extras/globbing.h
changeset 573 01112353ffad
child 576 5da65f8e9a50
equal deleted inserted replaced
572:2728e1a3e75d 573:01112353ffad
       
     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.
       
    25  *
       
    26  * Unless otherwise stated, the rest of PhysicsFS falls under the GNU Lesser
       
    27  *  General Public License: http://www.gnu.org/licenses/lgpl.txt
       
    28  *
       
    29  *  \author Ryan C. Gordon.
       
    30  */
       
    31 
       
    32 
       
    33 /**
       
    34  * \fn char **PHYSFS_enumerateFilesWildcard(const char *dir, const char *wildcard, int caseSensitive)
       
    35  * \brief Get a file listing of a search path's directory.
       
    36  *
       
    37  * Matching directories are interpolated. That is, if "C:\mydir" is in the
       
    38  *  search path and contains a directory "savegames" that contains "x.sav",
       
    39  *  "y.Sav", and "z.txt", and there is also a "C:\userdir" in the search path
       
    40  *  that has a "savegames" subdirectory with "w.sav", then the following code:
       
    41  *
       
    42  * \code
       
    43  * char **rc = PHYSFS_enumerateFilesWildcard("savegames", "*.sav", 0);
       
    44  * char **i;
       
    45  *
       
    46  * for (i = rc; *i != NULL; i++)
       
    47  *     printf(" * We've got [%s].\n", *i);
       
    48  *
       
    49  * PHYSFS_freeList(rc);
       
    50  * \endcode
       
    51  *
       
    52  *  ...will print:
       
    53  *
       
    54  * \verbatim
       
    55  * We've got [x.sav].
       
    56  * We've got [y.Sav].
       
    57  * We've got [w.sav].\endverbatim
       
    58  *
       
    59  * Feel free to sort the list however you like. We only promise there will
       
    60  *  be no duplicates, but not what order the final list will come back in.
       
    61  *
       
    62  * Wildcard strings can use the '*' and '?' characters, currently.
       
    63  * Matches can be case-insensitive if you pass a zero for argument 3.
       
    64  *
       
    65  * Don't forget to call PHYSFS_freeList() with the return value from this
       
    66  *  function when you are done with it.
       
    67  *
       
    68  *    \param dir directory in platform-independent notation to enumerate.
       
    69  *   \return Null-terminated array of null-terminated strings.
       
    70  */
       
    71 __EXPORT__ char **PHYSFSEXT_enumerateFilesWildcard(const char *dir,
       
    72                                                    const char *wildcard,
       
    73                                                    int caseSensitive);
       
    74 
       
    75 /* end of globbing.h ... */
       
    76