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