wild

README

wild

wild is a Go library for string matching with wildcard support. It aims to provide a high-performance yet feature-rich string matching tool. Compared to regular expressions, wild offers higher execution efficiency while supporting common matching features such as non-greedy matching and capture groups. In scenarios where the full power of regular expressions is unnecessary, wild demonstrates significant advantages.

wild provides two syntax modes: Simple Mode and Extended Mode.

Simple Mode

Simple Mode is the default mode of wild. It supports wildcards * and ?, similar to path matching:

• *: Matches zero or more characters.
• ?: Matches zero or one character.

Extended Mode

Extended Mode supports additional wildcards beyond those in Simple Mode:

• .: Matches any single character.
• +: Matches one or more characters.
• ? suffix: Indicates non-greedy matching, which can only be used with * or + (e.g., *? or +?).
• \: Escape character to remove the special meaning of the following character.

Syntax Features and Usage Notes

The syntax of wild is designed for simplicity and efficiency. Although some symbols resemble regular expressions, their semantics and usage differ significantly. Key considerations include:

• Wildcard Independence: In wild, wildcards like * and + are self-contained and do not depend on preceding characters. For example, a+ in wild means "a followed by one or more arbitrary characters", unlike regex where a+ matches consecutive a characters.
• Full-Match Behavior: wild always performs full-string matching, implicitly anchored at both the start (^) and end ($). For instance, abc does not match abcd, but abc* does. To match substrings (e.g., 1abc), use *abc*.
• Strict Parsing Rules:
  • Consecutive wildcards (e.g., .. or *+) are prohibited. Wildcards must be separated by at least one static character. Non-greedy operators (*? or +?) are treated as single wildcards.
  • The escape character \ can only negate the special meaning of the immediately following character. It cannot precede non-wildcard characters or appear as the last character in a pattern.
• UTF-8 Support: wild supports only UTF-8 encoded strings. Case-insensitive matching (via the CaseInsensitive option) follows Unicode lowercase conversion rules. Exceptions may occur, such as German SS being converted to ss instead of ß.

Installation

Ensure your Go environment is properly configured, then install wild using:

go get -u go.xrfang.cn/wild

Usage

package main

import "go.xrfang.cn/wild"

func main() {
    m := wild.MustCompile(`+\.log`, wild.Extended)
    fns, _ := filepath.Glob(filepath.Join("logs", "*.log"))
    for _, fn := range fns {
        if m.Match(filepath.Base(fn)) {
            fmt.Printf("match: %s; capture: %s\n", m.Capture(0), m.Capture(1))
        }
    }
}

The above example demonstrates basic features like compilation flags (Extended), capture groups (Capture), and more. Refer to the API documentation for additional utilities such as Match and MatchEx.

Performance Analysis

The following are performance test results for wild and regular expressions (using the standard library engine in Go) under different scenarios. The tests were conducted using Go's benchmarking tool, and statistical analysis was performed using the benchstat tool.

Compilation Phase

Execution Speed

Test Case	wild (ns/op)	Regular Expression (ns/op)	Performance Improvement
Compile/Wild	296.0 ± 16%	2401 ± 6%	87%
Compile/Wild#01	301.6 ± 11%	2256 ± 10%	86%
Compile/Wild#02	316.6 ± 10%	2908 ± 9%	88%

Memory Allocation

Test Case	wild (B/op)	Regular Expression (B/op)	Memory Savings
Compile/Wild	412.0	2906	86%
Compile/Wild#01	496.0	2906	83%
Compile/Wild#02	584.0	4117	86%

Number of Memory Allocations

Test Case	wild (allocs/op)	Regular Expression (allocs/op)	Reduction in Allocation Count
Compile/Wild	9	41	78%
Compile/Wild#01	9	41	78%
Compile/Wild#02	6	44	86%

Matching Phase

Execution Speed

Test Case	wild (ns/op)	Regular Expression (ns/op)	Performance Improvement
Match/Wild	112.8 ± 1%	153.9 ± 6%	27%
Match/Wild#01	41.62 ± 1%	56.30 ± 1%	26%
Match/Wild#02	91.04 ± 0%	124.9 ± 1%	27%

Memory Allocation

Neither wild nor Regular Expression allocate memory during the matching phase.

Documentation

Overview

Package wild provides a simple wildcard pattern matching implementation. It supports basic syntax ('?', '*') and extended mode with case-insensitive or non-greedy matching. The package also provides capture groups for wildcards.

Index

• func CaseInsensitive(m *Matcher)
• func Extended(m *Matcher)
• func Match(pattern, subject string, opts ...Option) (bool, error)
• func MatchEx(pattern, subject string, opts ...Option) (bool, error)
• type Matcher
  • func Compile(pattern string, opts ...Option) (*Matcher, error)
  • func MustCompile(pattern string, opts ...Option) *Matcher
  • func (m *Matcher) Capture(idx int) string
  • func (m *Matcher) CapturePos(idx int) (int, int)
  • func (m *Matcher) Captures() int
  • func (m Matcher) Dump(w io.Writer)
  • func (m *Matcher) Match(s string) (res bool)
  • func (m Matcher) String() string
• type Option

Functions

func CaseInsensitive

func CaseInsensitive(m *Matcher)

CaseInsensitive configures the Matcher to perform case-insensitive matching. When this option is applied, the Matcher will treat characters in the pattern and target string as case-insensitive (e.g., 'A' == 'a').

func Extended

func Extended(m *Matcher)

Extended enables extended matching mode. In extended mode, the Matcher supports additional features such as:

• '.' to match exactly one character
• '+' to match one or more characters
• append '?' to a pattern to make it non-greedy
• '\' to escape special characters that follows

Without using Extended, the matcher is in "simple" mode which only supports:

• '*' to match zero or more characters
• '?' to match zero or one character

func Match

func Match(pattern, subject string, opts ...Option) (bool, error)

Match compiles the given pattern and checks if the subject matches it. Parameters:

• pattern: The pattern string to be compiled into a Matcher.
• subject: The target string to be matched against the compiled pattern.
• opts: Optional configuration options for customizing the behavior of the Matcher.

Returns:

• A boolean indicating whether the subject matches the pattern.
• An error if the pattern compilation fails.

func MatchEx

func MatchEx(pattern, subject string, opts ...Option) (bool, error)

MatchEx is similar to Match, but it enables extended matching mode by default. See Extended for more details.

Types

type Matcher

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

Matcher represents a compiled wildcard pattern with matching rules and state. It contains compiled matching rules, case sensitivity flag, extended mode flag, capture group positions, and the current subject string being matched.

func Compile

func Compile(pattern string, opts ...Option) (*Matcher, error)

Compile compiles a wildcard pattern into a matcher object. Supports following syntax:

• '.' : match exactly one character (extended mode only)
• '?' : match zero or one character (greedy)
• '*' : match zero or more characters (greedy)
• '+' : match one or more characters (greedy, extended mode only)
• '*?' : match zero or more characters (non-greedy, extended mode only)
• '+?' : match one or more characters (non-greedy, extended mode only)
• '\\' : escape special characters (extended mode only)

Options:

• CaseInsensitive: enable case-insensitive matching
• Extended: enable extended mode to support:
• '.' operator for single character
• '+' quantifier for 1-or-more matches
• '\' escapes for special characters
• non-greedy modifiers ('?')

Validates pattern syntax and returns error for:

• invalid escape sequences (e.g., "\\a" where 'a' isn't special)
• dangling escape at pattern end
• invalid quantifier combinations (e.g., "x?+")
• using extended-mode operators (., +, escapes) without Extended

Capture groups are automatically numbered for each wildcard operator, with group 0 always being the full match.

func MustCompile

func MustCompile(pattern string, opts ...Option) *Matcher

MustCompile is a helper function that compiles a pattern into a Matcher. It wraps the Compile function and panics if the compilation fails.

This function is intended for use in situations where a failure to compile the pattern is considered a critical error, such as during application initialization. If you want to handle errors gracefully, use Compile instead.

func (*Matcher) Capture

func (m *Matcher) Capture(idx int) string

Capture returns the captured substring for the given group index. Index 0 returns the entire matched string, subsequent indices correspond to wildcard operators in the pattern.

func (*Matcher) CapturePos

func (m *Matcher) CapturePos(idx int) (int, int)

CapturePos returns the start and end byte positions of a capture group. Positions are [inclusive, exclusive) indices into the original string. Returns (-1, -1) for invalid indices or unmatched groups.

func (*Matcher) Captures

func (m *Matcher) Captures() int

Captures returns the total number of capture groups available. Always returns at least 1 (group 0 for full match). Count includes:

• Group 0: entire match
• Groups 1-N: each wildcard operator in pattern

Example: Pattern "a*?b+" returns 3 (full match, '*?' and '+')

func (Matcher) Dump

func (m Matcher) Dump(w io.Writer)

Dump writes detailed debugging information about the compiled pattern to the given writer.

Includes pattern string, case sensitivity, rule types (static/greedy/non-greedy), and quantifiers.

Example output:

   pattern: a*?b* (case insensitive)
   4 rules defined
     rule#0: subj=a (static)
     rule#1: verb=*; stop=b (non-greedy)
     rule#2: subj=b (static)
	 rune#3: verb=* (greedy)

func (*Matcher) Match

func (m *Matcher) Match(s string) (res bool)

Match attempts to match the input string against the compiled wildcard pattern. Returns true if the entire string matches the pattern rules, or false on any rule mismatch. Empty matcher matches any string.

func (Matcher) String

func (m Matcher) String() string

String returns the canonical string representation of the compiled pattern. Escapes special characters (., ?, *, +, \) in static text sections and reconstructs quantifiers.

type Option

type Option func(m *Matcher)

Option represents a functional option for configuring a Matcher. It is a function that takes a pointer to a Matcher and applies specific configuration settings to it.