globbing.h
1
2
/** \file globbing.h */
3
4
#include "physfs.h"
5
6
7
8
9
10
11
12
13
/**
* \mainpage PhysicsFS globbing
*
* This is an extension to PhysicsFS to let you search for files with basic
* wildcard matching, regardless of what sort of filesystem or archive they
* reside in. It does this by enumerating directories as needed and manually
* locating matching entries.
*
* Usage: Set up PhysicsFS as you normally would, then use
14
* PHYSFSEXT_enumerateFilesWildcard() when enumerating files. This is just
15
* like PHYSFS_enumerateFiles(), but it returns a subset that matches your
16
17
* wildcard pattern. You must call PHYSFSEXT_freeEnumeration() on the results,
* just PHYSFS_enumerateFiles() would do with PHYSFS_freeList().
18
19
20
21
22
23
24
25
*
* License: this code is public domain. I make no warranty that it is useful,
* correct, harmless, or environmentally safe.
*
* This particular file may be used however you like, including copying it
* verbatim into a closed-source project, exploiting it commercially, and
* removing any trace of my name from the source (although I hope you won't
* do that). I welcome enhancements and corrections to this file, but I do
26
27
* not require you to send me patches if you make changes. This code has
* NO WARRANTY.
29
* Unless otherwise stated, the rest of PhysicsFS falls under the zlib license.
30
* Please see LICENSE.txt in the source's "docs" directory.
31
32
33
34
35
36
37
*
* \author Ryan C. Gordon.
*/
/**
* \fn char **PHYSFS_enumerateFilesWildcard(const char *dir, const char *wildcard, int caseSensitive)
38
* \brief Get a file listing of a search path's directory, filtered with a wildcard pattern.
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
*
* Matching directories are interpolated. That is, if "C:\mydir" is in the
* search path and contains a directory "savegames" that contains "x.sav",
* "y.Sav", and "z.txt", and there is also a "C:\userdir" in the search path
* that has a "savegames" subdirectory with "w.sav", then the following code:
*
* \code
* char **rc = PHYSFS_enumerateFilesWildcard("savegames", "*.sav", 0);
* char **i;
*
* for (i = rc; *i != NULL; i++)
* printf(" * We've got [%s].\n", *i);
*
* PHYSFS_freeList(rc);
* \endcode
*
* ...will print:
*
* \verbatim
* We've got [x.sav].
* We've got [y.Sav].
* We've got [w.sav].\endverbatim
*
* Feel free to sort the list however you like. We only promise there will
* be no duplicates, but not what order the final list will come back in.
*
* Wildcard strings can use the '*' and '?' characters, currently.
* Matches can be case-insensitive if you pass a zero for argument 3.
*
68
69
70
71
* Don't forget to call PHYSFSEXT_freeEnumerator() with the return value from
* this function when you are done with it. As we use PhysicsFS's allocator
* for this list, you must free it before calling PHYSFS_deinit().
* Do not use PHYSFS_freeList() on the returned value!
72
73
*
* \param dir directory in platform-independent notation to enumerate.
74
75
76
* \param wildcard Wildcard pattern to use for filtering.
* \param caseSensitive Zero for case-insensitive matching,
* non-zero for case-sensitive.
77
* \return Null-terminated array of null-terminated strings.
78
79
*
* \sa PHYSFSEXT_freeEnumeration
81
PHYSFS_DECL char **PHYSFSEXT_enumerateFilesWildcard(const char *dir,
82
83
84
const char *wildcard,
int caseSensitive);
85
86
87
88
89
90
91
92
93
94
95
96
97
98
/**
* \fn void PHYSFSEXT_freeEnumeration(char **list)
* \brief Free data returned by PHYSFSEXT_enumerateFilesWildcard
*
* Conceptually, this works like PHYSFS_freeList(), but is used with data
* returned by PHYSFSEXT_enumerateFilesWildcard() only. Be sure to call this
* on any returned data from that function before
*
* \param list Pointer previously returned by
* PHYSFSEXT_enumerateFilesWildcard(). It is safe to pass a
* NULL here.
*
* \sa PHYSFSEXT_enumerateFilesWildcard
*/
99
PHYSFS_DECL void PHYSFSEXT_freeEnumeration(char **list);
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
/**
* \fn void PHYSFSEXT_enumerateFilesCallbackWildcard(const char *dir, const char *wildcard, int caseSensitive, PHYSFS_EnumFilesCallback c, void *d);
* \brief Get a file listing of a search path's directory, filtered with a wildcard pattern, using an application-defined callback.
*
* This function is equivalent to PHYSFSEXT_enumerateFilesWildcard(). It
* reports file listings, filtered by a wildcard pattern.
*
* Unlike PHYSFS_enumerateFiles(), this function does not return an array.
* Rather, it calls a function specified by the application once per
* element of the search path:
*
* \code
*
* static void printDir(void *data, const char *origdir, const char *fname)
* {
* printf(" * We've got [%s] in [%s].\n", fname, origdir);
* }
*
* // ...
* PHYSFS_enumerateFilesCallbackWildcard("savegames","*.sav",0,printDir,NULL);
* \endcode
*
* Items sent to the callback are not guaranteed to be in any order whatsoever.
* There is no sorting done at this level, and if you need that, you should
* probably use PHYSFS_enumerateFilesWildcard() instead, which guarantees
* alphabetical sorting. This form reports whatever is discovered in each
* archive before moving on to the next. Even within one archive, we can't
* guarantee what order it will discover data. <em>Any sorting you find in
* these callbacks is just pure luck. Do not rely on it.</em> As this walks
* the entire list of archives, you may receive duplicate filenames.
*
* Wildcard strings can use the '*' and '?' characters, currently.
* Matches can be case-insensitive if you pass a zero for argument 3.
*
* \param dir Directory, in platform-independent notation, to enumerate.
* \param wildcard Wildcard pattern to use for filtering.
* \param caseSensitive Zero for case-insensitive matching,
* non-zero for case-sensitive.
* \param c Callback function to notify about search path elements.
* \param d Application-defined data passed to callback. Can be NULL.
*
* \sa PHYSFS_EnumFilesCallback
* \sa PHYSFS_enumerateFiles
*/
146
PHYSFS_DECL void PHYSFSEXT_enumerateFilesCallbackWildcard(const char *dir,
147
148
149
150
151
const char *wildcard,
int caseSensitive,
PHYSFS_EnumFilesCallback c,
void *d);
152
/* end of globbing.h ... */