src/unison/physfs-1.1.1/extras/globbing.h

   1 /** \file globbing.h */
   2
   3 /**
   4  * \mainpage PhysicsFS globbing
   5  *
   6  * This is an extension to PhysicsFS to let you search for files with basic
   7  *  wildcard matching, regardless of what sort of filesystem or archive they
   8  *  reside in. It does this by enumerating directories as needed and manually
   9  *  locating matching entries.
  10  *
  11  * Usage: Set up PhysicsFS as you normally would, then use
  12  *  PHYSFSEXT_enumerateFilesPattern() when enumerating files. This is just
  13  *  like PHYSFS_enumerateFiles(), but it returns a subset that matches your
  14  *  wildcard pattern. You must call PHYSFS_freeList() on the results, just
  15  *  like you would with PHYSFS_enumerateFiles().
  16  *
  17  * License: this code is public domain. I make no warranty that it is useful,
  18  *  correct, harmless, or environmentally safe.
  19  *
  20  * This particular file may be used however you like, including copying it
  21  *  verbatim into a closed-source project, exploiting it commercially, and
  22  *  removing any trace of my name from the source (although I hope you won't
  23  *  do that). I welcome enhancements and corrections to this file, but I do
  24  *  not require you to send me patches if you make changes. This code has
  25  *  NO WARRANTY.
  26  *
  27  * Unless otherwise stated, the rest of PhysicsFS falls under the zlib license.
  28  *  Please see LICENSE.txt in the root of the source tree.
  29  *
  30  *  \author Ryan C. Gordon.
  31  */
  32
  33
  34 /**
  35  * \fn char **PHYSFS_enumerateFilesWildcard(const char *dir, const char *wildcard, int caseSensitive)
  36  * \brief Get a file listing of a search path's directory.
  37  *
  38  * Matching directories are interpolated. That is, if "C:\mydir" is in the
  39  *  search path and contains a directory "savegames" that contains "x.sav",
  40  *  "y.Sav", and "z.txt", and there is also a "C:\userdir" in the search path
  41  *  that has a "savegames" subdirectory with "w.sav", then the following code:
  42  *
  43  * \code
  44  * char **rc = PHYSFS_enumerateFilesWildcard("savegames", "*.sav", 0);
  45  * char **i;
  46  *
  47  * for (i = rc; *i != NULL; i++)
  48  *     printf(" * We've got [%s].\n", *i);
  49  *
  50  * PHYSFS_freeList(rc);
  51  * \endcode
  52  *
  53  *  ...will print:
  54  *
  55  * \verbatim
  56  * We've got [x.sav].
  57  * We've got [y.Sav].
  58  * We've got [w.sav].\endverbatim
  59  *
  60  * Feel free to sort the list however you like. We only promise there will
  61  *  be no duplicates, but not what order the final list will come back in.
  62  *
  63  * Wildcard strings can use the '*' and '?' characters, currently.
  64  * Matches can be case-insensitive if you pass a zero for argument 3.
  65  *
  66  * Don't forget to call PHYSFS_freeList() with the return value from this
  67  *  function when you are done with it.
  68  *
  69  *    \param dir directory in platform-independent notation to enumerate.
  70  *   \return Null-terminated array of null-terminated strings.
  71  */
  72 __EXPORT__ char **PHYSFSEXT_enumerateFilesWildcard(const char *dir,
  73                                                    const char *wildcard,
  74                                                    int caseSensitive);
  75
  76 /* end of globbing.h ... */
  77