minimatch
一个最小化的匹配工具。
这是npm内部使用的匹配库。
它通过将glob表达式转换为JavaScript RegExp
对象来工作。
用法
// 混合模块,可以通过require()或import加载
import { minimatch } from 'minimatch'
// 或者:
const { minimatch } = require('minimatch')
minimatch('bar.foo', '*.foo') // true!
minimatch('bar.foo', '*.bar') // false!
minimatch('bar.foo', '*.+(bar|foo)', { debug: true }) // true,并且会输出调试信息!
特性
支持以下glob特性:
- 大括号展开
- 扩展的glob匹配
- "Globstar"
**
匹配 - Posix字符类,
如
[[:alpha:]]
,支持全范围的Unicode字符。例如,[[:alpha:]]
将匹配'é'
, 而[a-zA-Z]
则不会。不支持排序符号和集合匹配,所以[[=e=]]
将不会匹配'é'
,[[.ch.]]
在将ch
视为单个字符的语言环境中也不会匹配'ch'
。
参见:
man sh
man bash
模式匹配man 3 fnmatch
man 5 gitignore
Windows
请在glob表达式中只使用正斜杠。
尽管Windows使用 /
或 \
作为路径分隔符,但这个glob实现只使用 /
字符。
在glob表达式中,你必须只使用正斜杠。模式中的反斜杠将始终被解释为转义字符,而不是路径分隔符。
注意,在Windows上的路径中,\
或 /
都会被解释为路径分隔符,并会匹配glob表达式中的 /
。
所以在模式中始终使用 /
。
UNC路径
在Windows上,像 //?/c:/...
或 //ComputerName/Share/...
这样的UNC路径会被特殊处理。
- 以双斜杠开头后跟一些非斜杠字符的模式将保留其双斜杠。因此,像
//*
这样的模式将匹配//x
,但不匹配/x
。 - 以
//?/<驱动器字母>:
开头的模式不会将?
视为通配符。相反,它将被视为普通字符串。 - 以
//?/<驱动器字母>:/...
开头的模式将匹配以<驱动器字母>:/...
开头的文件路径,反之亦然, 就像//?/
不存在一样。这种行为仅在驱动器字母不区分大小写匹配时存在。 路径/模式的剩余部分会区分大小写进行比较,除非设置了nocase:true
。
注意,在文件路径参数中使用 \
字符作为路径分隔符来指定UNC路径总是允许的,
但在模式参数中只有在选项中设置了 windowsPathsNoEscape: true
时才允许。
Minimatch类
通过实例化 minimatch.Minimatch
类来创建minimatch对象。
var Minimatch = require('minimatch').Minimatch
var mm = new Minimatch(pattern, options)
属性
-
pattern
minimatch对象表示的原始模式。 -
options
传递给构造函数的选项。 -
set
一个二维数组,包含正则表达式或字符串表达式。 数组中的每一行对应一个大括号展开的模式。每行中的每个项对应一个单独的路径部分。 例如,模式{a,b/c}/d
会展开为一组如下的模式:[ [ a, d ] , [ b, c, d ] ]
如果模式的一部分没有任何"魔法"(即,它是像
"foo"
这样的东西,而不是fo*o?
), 那么它将保留为字符串,而不是转换为正则表达式。 -
regexp
由makeRe
方法创建。一个表示整个模式的单一正则表达式。 这在你希望以类似于启用了FNM_PATH
的fnmatch(3)
方式使用模式的情况下很有用。 -
negate
如果模式是否定的,则为true。 -
comment
如果模式是注释,则为true。 -
empty
如果模式是""
,则为true。
方法
-
makeRe()
如果需要,生成regexp
成员并返回它。如果模式无效,将返回false
。 -
match(fname)
如果文件名匹配模式,则返回true,否则返回false。 -
matchOne(fileArray, patternArray, partial)
接受一个以/
分割的文件名, 并将其与regExpSet
中的单行匹配。这个方法主要供内部使用, 但也暴露出来以便可以被需要避免过多文件系统调用的glob遍历器使用。 -
hasMagic()
如果解析后的模式包含任何魔法字符,则返回true。 如果所有比较器部分都是字符串字面量,则返回false。如果在构造函数上设置了magicalBraces
选项, 那么它会将否则不具有魔法的大括号展开视为魔法。如果未设置,那么像a{b,c}d
这样的模式将返回false
, 因为abd
和acd
都不包含任何特殊的glob字符。这并不意味着模式字符串可以作为字面文件名使用,因为它可能包含被转义的魔法glob字符。 例如,模式
\\*
或[*]
不会被认为具有魔法,因为匹配部分解析为字面字符串'*'
, 会匹配名为'*'
的路径,而不是'\\*'
或'[*]'
。minimatch.unescape()
方法 可用于移除转义字符。
所有其他方法都是内部方法,将根据需要调用。
minimatch(path, pattern, options)
主要导出。使用选项测试路径是否匹配模式。
var isJS = minimatch(file, '*.js', { matchBase: true })
minimatch.filter(pattern, options)
返回一个函数,该函数测试其提供的参数,适用于 Array.filter
。例如:
var javascripts = fileList.filter(minimatch.filter('*.js', { matchBase: true }))
minimatch.escape(pattern, options = {})
转义glob模式中的所有魔法字符,使其只匹配字面字符串
如果使用了windowsPathsNoEscape
选项,则字符会通过用[]
包裹来进行转义,因为包裹在字符类中的魔法字符只能被该确切字符满足。
斜杠(以及在windowsPathsNoEscape
模式下的反斜杠)无法被转义或取消转义。
minimatch.unescape(pattern, options = {})
取消对可能包含一些转义字符的glob字符串进行转义。
如果使用了windowsPathsNoEscape
选项,则会移除方括号转义,但不会移除反斜杠转义。例如,它会将字符串'[*]'
转换为*
,但不会将'\\*'
转换为'*'
,因为在windowsPathsNoEscape
模式下,\
是路径分隔符。
当未设置windowsPathsNoEscape
时,大括号转义和反斜杠转义都会被移除。
斜杠(以及在windowsPathsNoEscape
模式下的反斜杠)无法被转义或取消转义。
minimatch.match(list, pattern, options)
以fnmatch或glob的风格匹配文件列表。如果没有匹配项,且设置了options.nonull,则返回包含模式本身的列表。
var javascripts = minimatch.match(fileList, '*.js', { matchBase: true })
minimatch.makeRe(pattern, options)
根据模式创建一个正则表达式对象。
选项
所有选项默认为false
。
debug
向stderr输出大量信息。
nobrace
不展开{a,b}
和{1..3}
这样的大括号集合。
noglobstar
禁用**
匹配多个文件夹名。
dot
允许模式匹配以句点开头的文件名,即使模式在该位置没有明确的句点。
注意,默认情况下,a/**/b
将不会匹配a/.d/b
,除非设置了dot
。
noext
禁用+(a|b)
这样的"extglob"风格模式。
nocase
执行不区分大小写的匹配。
nocaseMagicOnly
当与{nocase: true}
一起使用时,创建不区分大小写的正则表达式,但保持字符串匹配部分不变。单独使用时没有效果。
当使用其他形式的不区分大小写匹配时,或者原始字符串表示在其他方面有用时,这个选项很有用。
nonull
当minimatch.match
找不到匹配项时,如果设置了此选项,则返回包含模式本身的列表。未设置时,如果没有匹配项,则返回空列表。
magicalBraces
这只影响Minimatch.hasMagic
方法的结果。
如果模式包含大括号展开,如a{b,c}d
,但没有其他魔法字符,那么Minimatch.hasMagic()
方法默认会返回false
。设置此选项后,它会对大括号展开以及其他魔法glob字符返回true
。
matchBase
如果设置,则不包含斜杠的模式将在路径包含斜杠时与路径的基名进行匹配。例如,a?b
会匹配路径/xyz/123/acb
,但不会匹配/xyz/acb/123
。
nocomment
抑制将模式开头的#
视为注释的行为。
nonegate
抑制将开头的!
字符视为否定的行为。
flipNegate
对否定表达式返回与未否定时相同的结果。(即,匹配时为true,不匹配时为false。)
partial
将部分路径与模式进行比较。只要路径的现有部分不与模式矛盾,就会被视为匹配。这在应用程序中很有用,当你遍历文件夹结构,还没有完整路径,但想确保不会进入永远无法匹配的路径。
例如:
minimatch('/a/b', '/a/*/c/d', { partial: true }) // true,可能是 /a/b/c/d
minimatch('/a/b', '/**/d', { partial: true }) // true,可能是 /a/b/.../d
minimatch('/x/y/z', '/a/**/z', { partial: true }) // false,因为 x !== a
windowsPathsNoEscape
仅将\\
用作路径分隔符,而不作为转义字符。如果设置,模式中的所有\\
字符都会被替换为/
。注意,这使得无法匹配包含字面glob模式字符的路径,但允许匹配在Windows平台上使用path.join()
和path.resolve()
构造的模式,模仿早期版本在Windows上的(有bug的!)行为。请谨慎使用,并注意关于Windows路径的警告。
出于遗留原因,如果options.allowWindowsEscape
设置为精确值false
,也会设置此选项。
windowsNoMagicRoot
当模式以UNC路径或驱动器字母开头,并且在nocase:true
模式下,不将模式的根部分转换为不区分大小写的正则表达式,而是将它们保留为字符串。
当平台为win32
且设置了nocase:true
时,这是默认行为。
preserveMultipleSlashes
默认情况下,多个/
字符(除了UNC路径开头的//
,见上文"UNC路径")被视为单个/
。
也就是说,像a///b
这样的模式会匹配文件路径a/b
。
设置preserveMultipleSlashes: true
来抑制这种行为。
optimizationLevel
一个数字,表示在解析和使用模式进行匹配之前应对其进行优化的级别。
当设置了noglobstar
时,globstar部分**
总是被转换为*
,多个相邻的**
部分会被转换为单个**
(即,a/**/**/b
会被视为a/**/b
,因为在所有情况下它们是等价的)。
-
0
- 不进行进一步更改。在这种模式下,.
和..
在模式中保持不变,意味着它们在测试路径字符串中也必须出现在相同位置。例如,像a/*/../c
这样的模式将匹配字符串a/b/../c
,但不匹配字符串a/c
。 -
1
- (默认) 移除双点..
跟随非**
、.
、..
或空''
模式部分的情况。例如,模式./a/b/../*
将转换为./a/*
,因此它会匹配路径字符串./a/c
,但不匹配路径字符串./a/b/../c
。模式中的点和空路径部分会被保留。 -
2
(或更高)- 更激进的优化,适用于文件遍历场景:- 移除双点
..
跟随非**
、.
或空''
模式部分的情况。在安全的情况下,移除模式中的空和.
部分(即,除了最后位置、第一位置,或以/
开头的模式的第二个位置,因为这可能表示Windows上的UNC路径)。 - 将包含
<pre>/**/../<p>/<rest>
的模式转换为等效的<pre>/{..,**}/<p>/<rest>
,其中<p>
是非.
、..
、**
或空''
的模式部分。 - 去重存在
**
部分的模式,如果它不是最后的路径部分,并且其他部分相同。例如,{a/**/b,a/b}
变为a/**/b
,因为**
可以匹配空路径部分。 - 去重一个模式包含
*
,而另一个在相同位置包含非点、非**
、.
、..
或''
的模式。例如,a/{*,x}/b
变为a/*/b
,因为*
可以匹配x
。
虽然这些优化提高了文件遍历用例(如glob)的性能(这也是本模块存在的原因),但在某些情况下,它可能无法匹配优化级别1或0本应匹配的字面字符串。
具体来说,虽然
Minimatch.match()
方法会以相同的方式优化文件路径字符串,从而得到相同的匹配结果,但除非先使用minimatch.levelTwoFileOptimize()
或类似方法处理路径字符串,否则使用Minimatch.makeRe()
提供的正则表达式进行测试时会失败。 - 移除双点
平台
当设置为win32
时,将触发所有Windows特定行为(对UNC路径的特殊处理,以及在文件路径比较中将\
视为分隔符)。
默认值为process.platform
的值。
与其他fnmatch/glob实现的比较
虽然严格遵守现有标准是一个值得追求的目标,但minimatch和其他实现之间存在一些差异。有些是有意为之,有些则是不可避免的。
如果模式以!
字符开头,则它被否定。设置nonegate
标志可以抑制这种行为,并将开头的!
字符视为普通字符。如果你希望模式以负向扩展glob模式(如!(a|B)
)开头,这可能是相关的。模式开头的多个!
字符将多次否定该模式。
如果模式以#
开头,则它被视为注释,不会匹配任何内容。使用\#
可以匹配行首的字面#
,或设置nocomment
标志来抑制这种行为。
默认支持双星号**
,除非设置了noglobstar
标志。这种支持方式类似于bsdglob和bash 4.1,其中**
仅在作为路径部分的唯一内容时才具有特殊意义。也就是说,a/**/b
会匹配a/x/y/b
,但a/**b
不会。
如果转义的模式没有匹配项,并且设置了nonull
标志,则minimatch.match返回原始提供的模式,而不是解释字符转义。例如,minimatch.match([], "\\*a\\?")
将返回"\\*a\\?"
而不是"*a?"
。这类似于在bash中设置nullglob
选项,但它不会解析转义的模式字符。
如果未禁用大括号展开,则在对glob模式进行任何其他解释之前执行展开。因此,像+(a|{b),c)}
这样在bash或zsh中无效的模式,会首先展开为+(a|b)
和+(a|c)
的集合,然后检查这些模式的有效性。由于这两个是有效的,因此继续进行匹配。
否定的扩展glob模式尽可能接近Bash语义处理,但某些否定扩展glob的情况在JavaScript正则表达式中极难表达。特别是,在bash中,否定模式<start>!(<pattern>*|)*
将匹配任何不以<start><pattern>
开头的内容。然而,<start>!(<pattern>*)*
_会_匹配以<start><pattern>
开头的路径,因为空字符串可以匹配否定部分。在这个库中,<start>!(<pattern>*|)*
将_不_匹配任何以<start>
开头的模式,这是由于正则表达式和bash路径展开在精确考虑哪些模式为"贪婪"方面存在差异。这可能是可以修复的,但会增加复杂性和性能成本,权衡下来似乎不值得追求。
注意,libc中的fnmatch(3)
是一个非常简单的字符串比较匹配器,不会对斜杠做任何特殊处理。这个库设计用于glob搜索和文件遍历,因此对/
进行了特殊处理。因此,在这个库中,foo*
不会匹配foo/bar
,尽管在fnmatch(3)
中会匹配。