explode

README

go-explode

Tiny, zero-dependency Go library for performing brace expansion on a string expression.

Brace expansion defines a simple language for describing groups of alternating strings that "explode" into all combinations of these strings:

Groups are delimited by { and } and the alternations separated by ,. Whitespace around these symbols is not trimmed. Groups may be nested inside other groups to make the expansion recursive.

The result is ordered such that all expanded strings starting with a given substring in some group are generated before the next substring in the same group starts expanding. This appears to be the standard expansion ordering and is also the most intuitive when considering left- and rightmost groups more and less "significant", respectively (i.e. like numbers).

The idea of brace expansion originates form the shell languages and is probably best known from bash. Compared to the bash implementation, this one doesn't (currently) support escaping nor {1..3} style sequences.

While other implementations are easy to find (including in Go), this one is production ready by virtue of being polished, fully tested, and extremely fast: The algorithm is non-recursive and believed to be at least very close to optimal in terms of performance and memory usage.

Examples

• fi{nd,ne,sh} expands to [find, fine, fish]
• r{u,a}{,i}n expands to [run, ruin, ran, rain]
• s{{a,o}{il,lv},l{ee,o}p}ing expands to [sailing, salving, soiling, solving, sleeping, sloping]

Install

Command "go get" (legacy)

go get github.com/bisgardo/go-explode

Glide (legacy)

glide get github.com/bisgardo/go-explode

Command "go mod"

Coming soon.

Usage

The library exports the single function explode.String:

import "github.com/bisgardo/go-explode"

// ...

res, err := explode.String(expr)
if err != nil {
	// ...
}
for _, r := range res {
    fmt.Println(r)
}

See the included cmd for a slightly less trivial example.

Documentation

Index

• func String(expr string) ([]string, error)
• type Error
  • func (e Error) Error() string

Functions

func String

func String(expr string) ([]string, error)

String interprets a brace expansion expression and returns the list of expanded strings. The expansion is computed as combinations of substrings separated by ',' and grouped recursively by '{}' (see the README of this library for more details). The result is ordered such that all expanded strings starting with a given substring in some group are generated before the next substring in the same group starts expanding. Examples:

fi{nd,ne,sh}                -> [find, fine, fish]
r{u,a}{,i}n                 -> [run, ruin, ran, rain]
s{{a,o}{il,lv},l{ee,o}p}ing -> [sailing, salving, soiling, solving, sleeping, sloping]

An unmatched brace or a separator outside any brace pair is considered a syntax error. The function returns an appropriate Error immediately after such an error is encountered.

Types

type Error

type Error struct {
	// Location of the character which triggered the error.
	Pos int
	// Missing match character that it expected to find.
	// If the triggering character is a separator, then this is 0.
	Missing rune
}

Error is a syntax error of a brace expansion expression.

func (Error) Error

func (e Error) Error() string