ohmyglob

README

ohmyglob

A minimal glob matching utility for Go.

Works internally by converting glob expressions into Regexps, which are then used to match strings.

Features

• Customisable separators
• * matches any number of characters, but not the separator
• ? matches any single character, but not the separator
• ! at the beginning of a pattern will negate the match
• \ escapes the next character – \\ is a literal backslash
• "Globstar" (**) matching
• Glob sets allow matching against a set of ordered globs, with precedence to later matches

Usage

import glob "github.com/obeattie/ohmyglob"

var g glob.Glob
var err error
var doesMatch bool

// Standard, with a wildcard
g, err = glob.Compile("foo/*/baz", glob.DefaultOptions)
doesMatch = g.MatchString("foo/bar/baz") // true!
doesMatch = g.MatchString("nope") // false!

// Globstar
g, err = glob.Compile("foo/**/baz", glob.DefaultOptions)
doesMatch = g.MatchString("foo/bar/bar/baz") // true!
doesMatch = g.MatchString("foo/baz") // true!

Documentation

Overview

Package ohmyglob provides a minimal glob matching utility.

Index

• Variables
• func EscapeGlobComponent(component string, options *Options) string
• func EscapeGlobString(gs string, options *Options) string
• type Glob
  • func Compile(pattern string, options *Options) (Glob, error)
• type GlobMatcher
• type GlobSet
  • func CompileGlobSet(patterns []string, options *Options) (GlobSet, error)
  • func NewGlobSet(globs []Glob) (GlobSet, error)
• type Options

Variables

var (
	// Logger is used to log trace-level info; logging is completely disabled by default but can be changed by replacing
	// this with a configured logger
	Logger log.LoggerInterface
	// Escaper is the character used to escape a meaningful character
	Escaper = '\\'
)

var DefaultOptions = &Options{
	Separator:    '/',
	MatchAtStart: true,
	MatchAtEnd:   true,
}

DefaultOptions are a default set of Options that uses a forward slash as a separator, and require a full match

Functions

func EscapeGlobComponent

func EscapeGlobComponent(component string, options *Options) string

EscapeGlobComponent returns an escaped version of the passed string, ensuring a literal match when used in a pattern.

func EscapeGlobString

func EscapeGlobString(gs string, options *Options) string

EscapeGlobString returns an escaped version of the passed string, ensuring a literal match of its components. As distinct to EscapeGlobComponent, it will not escape the separator

Types

type Glob

type Glob interface {
	GlobMatcher
	// String returns the pattern that was used to create the Glob
	String() string
	// IsNegative returns whether the pattern was negated (prefixed with !)
	IsNegative() bool
}

Glob is a single glob pattern; implements GlobMatcher. A Glob is immutable.

func Compile

func Compile(pattern string, options *Options) (Glob, error)

Compile parses the given glob pattern and convertes it to a Glob. If no options are given, the DefaultOptions are used.

type GlobMatcher

type GlobMatcher interface {
	// Match reports whether the Glob matches the byte slice b
	Match(b []byte) bool
	// MatchReader reports whether the Glob matches the text read by the RuneReader
	MatchReader(r io.RuneReader) bool
	// MatchString reports whether the Glob matches the string s
	MatchString(s string) bool
}

GlobMatcher is the basic interface of a Glob or GlobSet. It provides a Regexp-style interface for checking matches.

type GlobSet

type GlobSet interface {
	GlobMatcher
	// Globs returns the ordered Glob objects contained within the set
	Globs() []Glob
	// String returns the patterns used to create the GlobSet
	String() string
	// MatchingGlob returns the Glob that matches the specified pattern (or does not match, in the case of a negative
	// glob)
	MatchingGlob(b []byte) Glob
	// AllMatchingGlobs returns all Globs that match the specified pattern (or do not match, in the case of a negative
	// glob)
	AllMatchingGlobs(b []byte) []Glob
}

GlobSet represents an ordered set of Globs, and has the same matching capabilities as a Glob. Globbing is done in order, with later globs taking precedence over earlier globs in the set. A GlobSet is immutable.

func CompileGlobSet

func CompileGlobSet(patterns []string, options *Options) (GlobSet, error)

CompileGlobSet constructs a GlobSet from a slice of strings, which will be compiled individually to Globs.

func NewGlobSet

func NewGlobSet(globs []Glob) (GlobSet, error)

NewGlobSet constructs a GlobSet from a slice of Globs.

type Options

type Options struct {
	// The character used to split path components
	Separator rune
	// Set to false to allow any prefix before the glob match
	MatchAtStart bool
	// Set to false to allow any suffix after the glob match
	MatchAtEnd bool
}

Options modify the behaviour of Glob parsing