glob 1.1.7

glob is a file and directory globbing library that supports both checking whether a path matches a glob and listing all entities that match a glob.

A "glob" is a pattern designed specifically to match files and directories. Most shells support globs natively.

Usage #

To construct a glob, just use new Glob(). As with RegExps, it's a good idea to keep around a glob if you'll be using it more than once so that it doesn't have to be compiled over and over. You can check whether a path matches the glob using Glob.matches():

import 'package:glob/glob.dart';

final dartFile = new Glob("**.dart");

// Print all command-line arguments that are Dart files.
void main(List<String> arguments) {
  for (var argument in arguments) {
    if (dartFile.matches(argument)) print(argument);
  }
}

You can also list all files that match a glob using Glob.list() or Glob.listSync():

import 'package:glob/glob.dart';

final dartFile = new Glob("**.dart");

// Recursively list all Dart files in the current directory.
void main(List<String> arguments) {
  for (var entity in dartFile.listSync()) {
    print(entity.path);
  }
}

Syntax #

The glob syntax hews closely to the widely-known Bash glob syntax, with a few exceptions that are outlined below.

In order to be as cross-platform and as close to the Bash syntax as possible, all globs use POSIX path syntax, including using / as a directory separator regardless of which platform they're on. This is true even for Windows roots; for example, a glob matching all files in the C drive would be C:/*.

Globs are case-sensitive by default on Posix systems and browsers, and case-insensitive by default on Windows.

Match any characters in a filename: *

The * character matches zero or more of any character other than /. This means that it can be used to match all files in a given directory that match a pattern without also matching files in a subdirectory. For example, lib/*.dart will match lib/glob.dart but not lib/src/utils.dart.

Match any characters across directories: **

** is like *, but matches / as well. It's useful for matching files or listing directories recursively. For example, lib/**.dart will match both lib/glob.dart and lib/src/utils.dart.

If ** appears at the beginning of a glob, it won't match absolute paths or paths beginning with ../. For example, **.dart won't match /foo.dart, although /**.dart will. This is to ensure that listing a bunch of paths and checking whether they match a glob produces the same results as listing that glob. In the previous example, /foo.dart wouldn't be listed for **.dart, so it shouldn't be matched by it either.

This is an extension to Bash glob syntax that's widely supported by other glob implementations.

Match any single character: ?

The ? character matches a single character other than /. Unlike *, it won't match any more or fewer than one character. For example, test?.dart will match test1.dart but not test10.dart or test.dart.

Match a range of characters: [...]

The [...] construction matches one of several characters. It can contain individual characters, such as [abc], in which case it will match any of those characters; it can contain ranges, such as [a-zA-Z], in which case it will match any characters that fall within the range; or it can contain a mix of both. It will only ever match a single character. For example, test[a-zA-Z_].dart will match testx.dart, testA.dart, and test_.dart, but not test-.dart.

If it starts with ^ or !, the construction will instead match all characters not mentioned. For example, test[^a-z].dart will match test1.dart but not testa.dart.

This construction never matches /.

Match one of several possibilities: {...,...}

The {...,...} construction matches one of several options, each of which is a glob itself. For example, lib/{*.dart,src/*} matches lib/glob.dart and lib/src/data.txt. It can contain any number of options greater than one, and can even contain nested options.

This is an extension to Bash glob syntax, although it is supported by other layers of Bash and is often used in conjunction with globs.

Escaping a character: \

The \ character can be used in any context to escape a character that would otherwise be semantically meaningful. For example, \*.dart matches *.dart but not test.dart.

Syntax errors #

Because they're used as part of the shell, almost all strings are valid Bash globs. This implementation is more picky, and performs some validation to ensure that globs are meaningful. For instance, unclosed { and [ are disallowed.

Reserved syntax: (...)

Parentheses are reserved in case this package adds support for Bash extended globbing in the future. For the time being, using them will throw an error unless they're escaped.

1.1.7 #

  • Set max SDK version to <3.0.0, and adjust other dependencies.

1.1.6 #

  • Improve support for Dart 2 runtime semantics.

1.1.5 #

  • Declare support for async 2.0.0.

  • Require Dart 1.23.0.

1.1.4 #

  • Throw an exception when listing globs whose initial paths don't exist in case-insensitive mode. This matches the case-sensitive behavior.

1.1.3 #

  • Support string_scanner 1.0.0.

1.1.2 #

  • Fix all strong mode errors and warnings.

1.1.1 #

  • Fix a bug where listing an absolute glob with caseInsensitive: false failed.

1.1.0 #

  • Add a caseSensitive named parameter to new Glob() that controls whether the glob is case-sensitive. This defaults to false on Windows and true elsewhere.

    Matching case-insensitively on Windows is a behavioral change, but since it more closely matches the semantics of Windows paths it's considered a bug fix rather than a breaking change.

1.0.5 #

  • Narrow the dependency on path. Previously, this allowed versions that didn't support all the functionality this package needs.

  • Upgrade to the new test runner.

1.0.4 #

  • Added overlooked collection dependency.

1.0.3 #

  • Fix a bug where Glob.list() and Glob.listSync() would incorrectly throw exceptions when a directory didn't exist on the filesystem.

1.0.2 #

  • Fixed Glob.list() on Windows.

1.0.1 #

  • Fix several analyzer warnings.

  • Fix the tests on Windows.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  glob: ^1.1.7

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:glob/glob.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
97
Health:
Code health derived from static analysis. [more]
90
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
53
Overall:
Weighted score of the above. [more]
86
Learn more about scoring.

We analyzed this package on Sep 17, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, other

Primary library: package:glob/glob.dart with components: io.

Health suggestions

Fix lib/src/ast.dart. (-3.45 points)

Analysis of lib/src/ast.dart reported 7 hints, including:

line 65 col 60: Use = to separate a named parameter from its default value.

line 203 col 31: Use = to separate a named parameter from its default value.

line 221 col 52: Use = to separate a named parameter from its default value.

line 258 col 34: Use = to separate a named parameter from its default value.

line 279 col 70: Use = to separate a named parameter from its default value.

Fix lib/src/list_tree.dart. (-3.45 points)

Analysis of lib/src/list_tree.dart reported 7 hints, including:

line 171 col 63: Use = to separate a named parameter from its default value.

line 193 col 65: Use = to separate a named parameter from its default value.

line 313 col 62: Use = to separate a named parameter from its default value.

line 340 col 7: Future results in async function bodies must be awaited or marked unawaited using package:pedantic.

line 362 col 7: Future results in async function bodies must be awaited or marked unawaited using package:pedantic.

Fix lib/src/parser.dart. (-1.99 points)

Analysis of lib/src/parser.dart reported 4 hints:

line 25 col 62: Use = to separate a named parameter from its default value.

line 35 col 46: Use = to separate a named parameter from its default value.

line 53 col 37: Use = to separate a named parameter from its default value.

line 155 col 40: Use = to separate a named parameter from its default value.

Fix lib/glob.dart. (-1.49 points)

Analysis of lib/glob.dart reported 3 hints:

line 102 col 41: Use = to separate a named parameter from its default value.

line 123 col 63: Use = to separate a named parameter from its default value.

line 144 col 65: Use = to separate a named parameter from its default value.

Maintenance suggestions

The package description is too short. (-20 points)

Add more detail to the description field of pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.

Package is getting outdated. (-16.71 points)

The package was last published 60 weeks ago.

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and glob.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.23.0 <3.0.0
async >=1.2.0 <3.0.0 2.3.0
collection ^1.1.0 1.14.12
path ^1.3.0 1.6.4
string_scanner >=0.1.0 <2.0.0 1.0.5
Transitive dependencies
charcode 1.1.2
meta 1.1.7
source_span 1.5.5
term_glyph 1.1.0
Dev dependencies
test >=0.12.0 <2.0.0
test_descriptor ^1.0.0