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