readme.md
1# glob.[go](https://golang.org)
2
3[![GoDoc][godoc-image]][godoc-url] [![Build Status][travis-image]][travis-url]
4
5> Go Globbing Library.
6
7## Install
8
9```shell
10 go get github.com/gobwas/glob
11```
12
13## Example
14
15```go
16
17package main
18
19import "github.com/gobwas/glob"
20
21func main() {
22 var g glob.Glob
23
24 // create simple glob
25 g = glob.MustCompile("*.github.com")
26 g.Match("api.github.com") // true
27
28 // quote meta characters and then create simple glob
29 g = glob.MustCompile(glob.QuoteMeta("*.github.com"))
30 g.Match("*.github.com") // true
31
32 // create new glob with set of delimiters as ["."]
33 g = glob.MustCompile("api.*.com", '.')
34 g.Match("api.github.com") // true
35 g.Match("api.gi.hub.com") // false
36
37 // create new glob with set of delimiters as ["."]
38 // but now with super wildcard
39 g = glob.MustCompile("api.**.com", '.')
40 g.Match("api.github.com") // true
41 g.Match("api.gi.hub.com") // true
42
43 // create glob with single symbol wildcard
44 g = glob.MustCompile("?at")
45 g.Match("cat") // true
46 g.Match("fat") // true
47 g.Match("at") // false
48
49 // create glob with single symbol wildcard and delimiters ['f']
50 g = glob.MustCompile("?at", 'f')
51 g.Match("cat") // true
52 g.Match("fat") // false
53 g.Match("at") // false
54
55 // create glob with character-list matchers
56 g = glob.MustCompile("[abc]at")
57 g.Match("cat") // true
58 g.Match("bat") // true
59 g.Match("fat") // false
60 g.Match("at") // false
61
62 // create glob with character-list matchers
63 g = glob.MustCompile("[!abc]at")
64 g.Match("cat") // false
65 g.Match("bat") // false
66 g.Match("fat") // true
67 g.Match("at") // false
68
69 // create glob with character-range matchers
70 g = glob.MustCompile("[a-c]at")
71 g.Match("cat") // true
72 g.Match("bat") // true
73 g.Match("fat") // false
74 g.Match("at") // false
75
76 // create glob with character-range matchers
77 g = glob.MustCompile("[!a-c]at")
78 g.Match("cat") // false
79 g.Match("bat") // false
80 g.Match("fat") // true
81 g.Match("at") // false
82
83 // create glob with pattern-alternatives list
84 g = glob.MustCompile("{cat,bat,[fr]at}")
85 g.Match("cat") // true
86 g.Match("bat") // true
87 g.Match("fat") // true
88 g.Match("rat") // true
89 g.Match("at") // false
90 g.Match("zat") // false
91}
92
93```
94
95## Performance
96
97This library is created for compile-once patterns. This means, that compilation could take time, but
98strings matching is done faster, than in case when always parsing template.
99
100If you will not use compiled `glob.Glob` object, and do `g := glob.MustCompile(pattern); g.Match(...)` every time, then your code will be much more slower.
101
102Run `go test -bench=.` from source root to see the benchmarks:
103
104Pattern | Fixture | Match | Speed (ns/op)
105--------|---------|-------|--------------
106`[a-z][!a-x]*cat*[h][!b]*eyes*` | `my cat has very bright eyes` | `true` | 432
107`[a-z][!a-x]*cat*[h][!b]*eyes*` | `my dog has very bright eyes` | `false` | 199
108`https://*.google.*` | `https://account.google.com` | `true` | 96
109`https://*.google.*` | `https://google.com` | `false` | 66
110`{https://*.google.*,*yandex.*,*yahoo.*,*mail.ru}` | `http://yahoo.com` | `true` | 163
111`{https://*.google.*,*yandex.*,*yahoo.*,*mail.ru}` | `http://google.com` | `false` | 197
112`{https://*gobwas.com,http://exclude.gobwas.com}` | `https://safe.gobwas.com` | `true` | 22
113`{https://*gobwas.com,http://exclude.gobwas.com}` | `http://safe.gobwas.com` | `false` | 24
114`abc*` | `abcdef` | `true` | 8.15
115`abc*` | `af` | `false` | 5.68
116`*def` | `abcdef` | `true` | 8.84
117`*def` | `af` | `false` | 5.74
118`ab*ef` | `abcdef` | `true` | 15.2
119`ab*ef` | `af` | `false` | 10.4
120
121The same things with `regexp` package:
122
123Pattern | Fixture | Match | Speed (ns/op)
124--------|---------|-------|--------------
125`^[a-z][^a-x].*cat.*[h][^b].*eyes.*$` | `my cat has very bright eyes` | `true` | 2553
126`^[a-z][^a-x].*cat.*[h][^b].*eyes.*$` | `my dog has very bright eyes` | `false` | 1383
127`^https:\/\/.*\.google\..*$` | `https://account.google.com` | `true` | 1205
128`^https:\/\/.*\.google\..*$` | `https://google.com` | `false` | 767
129`^(https:\/\/.*\.google\..*|.*yandex\..*|.*yahoo\..*|.*mail\.ru)$` | `http://yahoo.com` | `true` | 1435
130`^(https:\/\/.*\.google\..*|.*yandex\..*|.*yahoo\..*|.*mail\.ru)$` | `http://google.com` | `false` | 1674
131`^(https:\/\/.*gobwas\.com|http://exclude.gobwas.com)$` | `https://safe.gobwas.com` | `true` | 1039
132`^(https:\/\/.*gobwas\.com|http://exclude.gobwas.com)$` | `http://safe.gobwas.com` | `false` | 272
133`^abc.*$` | `abcdef` | `true` | 237
134`^abc.*$` | `af` | `false` | 100
135`^.*def$` | `abcdef` | `true` | 464
136`^.*def$` | `af` | `false` | 265
137`^ab.*ef$` | `abcdef` | `true` | 375
138`^ab.*ef$` | `af` | `false` | 145
139
140[godoc-image]: https://godoc.org/github.com/gobwas/glob?status.svg
141[godoc-url]: https://godoc.org/github.com/gobwas/glob
142[travis-image]: https://travis-ci.org/gobwas/glob.svg?branch=master
143[travis-url]: https://travis-ci.org/gobwas/glob
144
145## Syntax
146
147Syntax is inspired by [standard wildcards](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm),
148except that `**` is aka super-asterisk, that do not sensitive for separators.
