|
| 1 | +[](https://github.com/dart-lang/glob/actions/workflows/test-package.yml) |
| 2 | +[](https://pub.dev/packages/glob) |
| 3 | +[](https://pub.dev/packages/glob/publisher) |
| 4 | + |
| 5 | +`glob` is a file and directory globbing library that supports both checking |
| 6 | +whether a path matches a glob and listing all entities that match a glob. |
| 7 | + |
| 8 | +A "glob" is a pattern designed specifically to match files and directories. Most |
| 9 | +shells support globs natively. |
| 10 | + |
| 11 | +## Usage |
| 12 | + |
| 13 | +To construct a glob, just use `Glob()`. As with `RegExp`s, it's a good idea to |
| 14 | +keep around a glob if you'll be using it more than once so that it doesn't have |
| 15 | +to be compiled over and over. You can check whether a path matches the glob |
| 16 | +using `Glob.matches()`: |
| 17 | + |
| 18 | +```dart |
| 19 | +import 'package:glob/glob.dart'; |
| 20 | +
|
| 21 | +final dartFile = Glob("**.dart"); |
| 22 | +
|
| 23 | +// Print all command-line arguments that are Dart files. |
| 24 | +void main(List<String> arguments) { |
| 25 | + for (var argument in arguments) { |
| 26 | + if (dartFile.matches(argument)) print(argument); |
| 27 | + } |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +You can also list all files that match a glob using `Glob.list()` or |
| 32 | +`Glob.listSync()`: |
| 33 | + |
| 34 | +```dart |
| 35 | +import 'package:glob/glob.dart'; |
| 36 | +import 'package:glob/list_local_fs.dart'; |
| 37 | +
|
| 38 | +final dartFile = Glob("**.dart"); |
| 39 | +
|
| 40 | +// Recursively list all Dart files in the current directory. |
| 41 | +void main(List<String> arguments) { |
| 42 | + for (var entity in dartFile.listSync()) { |
| 43 | + print(entity.path); |
| 44 | + } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +## Syntax |
| 49 | + |
| 50 | +The glob syntax hews closely to the widely-known Bash glob syntax, with a few |
| 51 | +exceptions that are outlined below. |
| 52 | + |
| 53 | +In order to be as cross-platform and as close to the Bash syntax as possible, |
| 54 | +all globs use POSIX path syntax, including using `/` as a directory separator |
| 55 | +regardless of which platform they're on. This is true even for Windows roots; |
| 56 | +for example, a glob matching all files in the C drive would be `C:/*`. |
| 57 | + |
| 58 | +Globs are case-sensitive by default on Posix systems and browsers, and |
| 59 | +case-insensitive by default on Windows. |
| 60 | + |
| 61 | +### Match any characters in a filename: `*` |
| 62 | + |
| 63 | +The `*` character matches zero or more of any character other than `/`. This |
| 64 | +means that it can be used to match all files in a given directory that match a |
| 65 | +pattern without also matching files in a subdirectory. For example, `lib/*.dart` |
| 66 | +will match `lib/glob.dart` but not `lib/src/utils.dart`. |
| 67 | + |
| 68 | +### Match any characters across directories: `**` |
| 69 | + |
| 70 | +`**` is like `*`, but matches `/` as well. It's useful for matching files or |
| 71 | +listing directories recursively. For example, `lib/**.dart` will match both |
| 72 | +`lib/glob.dart` and `lib/src/utils.dart`. |
| 73 | + |
| 74 | +If `**` appears at the beginning of a glob, it won't match absolute paths or |
| 75 | +paths beginning with `../`. For example, `**.dart` won't match `/foo.dart`, |
| 76 | +although `/**.dart` will. This is to ensure that listing a bunch of paths and |
| 77 | +checking whether they match a glob produces the same results as listing that |
| 78 | +glob. In the previous example, `/foo.dart` wouldn't be listed for `**.dart`, so |
| 79 | +it shouldn't be matched by it either. |
| 80 | + |
| 81 | +This is an extension to Bash glob syntax that's widely supported by other glob |
| 82 | +implementations. |
| 83 | + |
| 84 | +### Match any single character: `?` |
| 85 | + |
| 86 | +The `?` character matches a single character other than `/`. Unlike `*`, it |
| 87 | +won't match any more or fewer than one character. For example, `test?.dart` will |
| 88 | +match `test1.dart` but not `test10.dart` or `test.dart`. |
| 89 | + |
| 90 | +### Match a range of characters: `[...]` |
| 91 | + |
| 92 | +The `[...]` construction matches one of several characters. It can contain |
| 93 | +individual characters, such as `[abc]`, in which case it will match any of those |
| 94 | +characters; it can contain ranges, such as `[a-zA-Z]`, in which case it will |
| 95 | +match any characters that fall within the range; or it can contain a mix of |
| 96 | +both. It will only ever match a single character. For example, |
| 97 | +`test[a-zA-Z_].dart` will match `testx.dart`, `testA.dart`, and `test_.dart`, |
| 98 | +but not `test-.dart`. |
| 99 | + |
| 100 | +If it starts with `^` or `!`, the construction will instead match all characters |
| 101 | +_not_ mentioned. For example, `test[^a-z].dart` will match `test1.dart` but not |
| 102 | +`testa.dart`. |
| 103 | + |
| 104 | +This construction never matches `/`. |
| 105 | + |
| 106 | +### Match one of several possibilities: `{...,...}` |
| 107 | + |
| 108 | +The `{...,...}` construction matches one of several options, each of which is a |
| 109 | +glob itself. For example, `lib/{*.dart,src/*}` matches `lib/glob.dart` and |
| 110 | +`lib/src/data.txt`. It can contain any number of options greater than one, and |
| 111 | +can even contain nested options. |
| 112 | + |
| 113 | +This is an extension to Bash glob syntax, although it is supported by other |
| 114 | +layers of Bash and is often used in conjunction with globs. |
| 115 | + |
| 116 | +### Escaping a character: `\` |
| 117 | + |
| 118 | +The `\` character can be used in any context to escape a character that would |
| 119 | +otherwise be semantically meaningful. For example, `\*.dart` matches `*.dart` |
| 120 | +but not `test.dart`. |
| 121 | + |
| 122 | +### Syntax errors |
| 123 | + |
| 124 | +Because they're used as part of the shell, almost all strings are valid Bash |
| 125 | +globs. This implementation is more picky, and performs some validation to ensure |
| 126 | +that globs are meaningful. For instance, unclosed `{` and `[` are disallowed. |
| 127 | + |
| 128 | +### Reserved syntax: `(...)` |
| 129 | + |
| 130 | +Parentheses are reserved in case this package adds support for Bash extended |
| 131 | +globbing in the future. For the time being, using them will throw an error |
| 132 | +unless they're escaped. |
0 commit comments