glob

README

glob
====
Noel Cower
v1.0, 2014-12-15

The 'glob' package is a simple package for doing shell glob-like pattern
matching against strings using wildcards.



Reference
---------

The following is a rudimentary intro the package's API. For more thorough
documentation, use godoc.

func Matches
~~~~~~~~~~~~

[source,go]
func Matches(pattern interface{}, str string) (bool, error)

Returns whether or not the given pattern, which may be a GlobPattern
or string (if a string, a new GlobPattern will be compiled as needed),
matches the given string str. May return an error.

This is a general purpose function that can be used if you don't plan to
reuse a pattern many times or can't guarantee you'll always use the same
pattern.



type GlobPattern
~~~~~~~~~~~~~~~~

[source,go]
----
type GlobPattern struct {
    // contains filtered or unexported fields
}
----

GlobPattern is a compiled, reusable glob pattern. Unlike when using Matches
above, GlobPattern's 'Matches' method does not result in on-the-fly compilation
of a GlobPattern for ever use.


func NewPattern
^^^^^^^^^^^^^^^

[source,go]
func NewPattern(pattern string) (*GlobPattern, error)

Attempts to compile the pattern string into a GlobPattern. If successful,
return the GlobPattern and nil, otherwise returns nil and an error.


func (*GlobPattern) Matches
^^^^^^^^^^^^^^^^^^^^^^^^^^^

[source,go]
func (p *GlobPattern) Matches(str string) bool

Returns whether the pattern 'p' matches the string 'str'. Does not return an
error.



License
-------

The glob package is distributed under the Boost Software License, Version 1.0.
See accompanying file link:COPYING[] or copy at
<http://www.boost.org/LICENSE_1_0.txt>.

[sidebar]
--
include::./COPYING[]
--

Documentation

Overview

Package glob provides rudimentary pattern matching functions using shell-like wildcards `*` and `?`.

Index

• Variables
• func Matches(pattern Pattern, str string) (matched bool, err error)
• type GlobPattern
  • func NewPattern(pattern string) (*GlobPattern, error)
  • func (p *GlobPattern) Matches(str string) bool
  • func (p *GlobPattern) String() string
• type Literal
  • func (l Literal) Matches(s string) bool
• type Pattern
• type PatternStr

Examples

• Matches
• NewPattern

Variables

var ErrInvalidGlobSequence = errors.New("* or ? may not follow *")

ErrInvalidGlobSequence is returned by NewPattern if the glob pattern contained any wildcard following an asterisk.

var ErrInvalidPatternType = errors.New("invalid pattern type")

ErrInvalidPatternType is returned by Matches if the given pattern type was neither a string nor a *GlobPattern.

var ErrPatternEmpty = errors.New("compiled glob pattern is empty")

ErrPatternEmpty is returned by NewPattern if the resulting pattern is empty.

var ErrPatternInvalid = errors.New("unable to compile glob pattern")

ErrPatternInvalid is returned by NewPattern if pattern compilation failed without an error.

Functions

func Matches

func Matches(pattern Pattern, str string) (matched bool, err error)

Matches returns whether the glob pattern matches str. If an error occurs (i.e., the pattern is somehow invalid), it will always return false and an error. Otherwise, if the pattern is valid, it will return true or false depending on whether it matches str and a nil error.

pattern may be either a *GlobPattern or a PatternStr. If it's a string, it will be parsed and compiled on demand.

If the pattern is neither a string nor a *GlobPattern, ErrInvalidPatternType will be the returned error.

If pattern is a string and an error is returned, it is any error that may be returned by NewPattern.

Example

var m bool
var err error

// Match
m, err = Matches(PatternStr("foo/bar/*/baz"), "foo/bar/qux/baz")

switch {
case err != nil:
	panic(err)
case m:
	fmt.Println("Matches!")
}

// No match
m, err = Matches(PatternStr("foo/bar/*/baz?"), "foo/bar/qux/baz")

switch {
case err != nil:
	panic(err)
case !m:
	fmt.Println("Doesn't match!")
}

Output:

Matches!
Doesn't match!

Types

type GlobPattern

type GlobPattern struct {
	// contains filtered or unexported fields
}

GlobPattern is a compiled glob pattern.

func NewPattern

func NewPattern(pattern string) (*GlobPattern, error)

NewPattern allocates a new GlobPattern based on pattern and returns it. Patterns consist of varying sequences of chars interspersed with wildcards -- either `*` or `?` to match 1 or more characters or a single character, respectively. Any character may be escaped with a backslash (\) to produce the same literal character in the string. Escaping any other character will yield the escaped character. Avoid escaping characters where possible, as this introduces additional complexity into the pattern.

Example

var p *GlobPattern
var err error

p, err = NewPattern("foo/bar/*/baz")
if err != nil {
	panic(err)
}

m := p.Matches("foo/bar/quz/baz")
if m {
	fmt.Println("Matches!")
}

m = p.Matches("foo/bar/")
if !m {
	fmt.Println("Doesn't match!")
}

Output:

Matches!
Doesn't match!

func (*GlobPattern) Matches

func (p *GlobPattern) Matches(str string) bool

Matches returns whether the glob pattern p matches str.

func (*GlobPattern) String

func (p *GlobPattern) String() string

String returns the pattern this GlobPattern was compiled with.

type Literal

type Literal string

Literal is a literal string that must match its input string.

func (Literal) Matches

func (l Literal) Matches(s string) bool

type Pattern

type Pattern interface {
	// contains filtered or unexported methods
}

Pattern is the common interface implemented by patterns under the glob package. Only PatternStr and GlobPattern implement this, which allows them to be recognized as patterns by Matches(). When in doubt, using the concrete GlobPattern is recommended.

type PatternStr

type PatternStr string

PatternStr is a convenience type for passing strings as patterns to the Matches function. The PatternStr is compiled on demand.