PathGlob v0.2.0

View Source PathGlob

Actions Status Module Version Hex Docs

PathGlob tests whether a file path matches a glob pattern, without touching the filesystem. It has the same semantics as Path.wildcard/2.

Path.wildcard/2 allows you to find all paths that match a certain glob pattern. If you only want to know whether a particular path matches a glob, then Path.wildcard/2 can be slow (depending on the glob), because it needs to traverse the filesystem.

PathGlob provides a PathGlob.match?/3 function to check a path against a glob without touching the filesystem. Internally, the glob pattern is compiled to a Regex and then checked via String.match?/2. If you want to compile the glob pattern ahead-of-time, you can use PathGlob.compile/2.

installation

 Installation

The package can be installed by adding path_glob to your list of dependencies in mix.exs:

def deps do
  [
    {:path_glob, "~> 0.1.1"}
  ]
end

compatibility

 Compatibility

The aim of this library is to closely match the behaviour of Path.wildcard/2, bugs and all. Internally, Path.wildcard/2 is implemented via Erlang’s filelib:wildcard/2.

There is an extensive test suite, and every assertion is checked against both Path.wildcard/2 and PathGlob.match?/3 to ensure compatibility.

Elixir >= 1.10 is supported. The CI currently runs against:

  • Elixir 1.10 / OTP 22
  • Elixir 1.11 / OTP 23
  • Elixir 1.12 / OTP 24

caveats

 Caveats

Some behaviour is not identical to Path.wildcard/2:

exceptions

 Exceptions

Certain weird inputs (e.g. fo{o) cause Path.wildcard/2 to raise an exception. A variety of different exceptions (ErlangError, CaseClauseError, MatchError, ...) may be raised.

PathGlob aims to always raise an exception on the same inputs as Path.wildcard/2, but it will always be an ArgumentError.

directory-traversal

 Directory traversal

Path.wildcard/2 has an undocumented feature for directory traversal in the glob. For example, a glob of /foo/bar/../a would return the path /foo/bar/../a, which is the same as /foo/a. There is logic to check that /foo/bar is actually a directory before traversing.

PathGlob implements this pattern, but because it doesn’t interact with the filesystem, it doesn’t check whether the pattern is actually valid in relation to the contents of the filesystem.

alternatives

 Alternatives

  • ex_minimatch is a port of a JavaScript library, and so doesn’t target compatibility with Path.wildcard/2. It also appears to be an abandoned project.

license

 License

PathGlob is released under the Apache License 2.0.