interpolate

README

Interpolate

A golang library for parameter expansion (like ${BLAH} or $BLAH) in strings from environment variables. An implementation of POSIX Parameter Expansion, plus some other basic operations that you'd expect in a shell scripting environment like bash.

Installation

go get -u github.com/buildkite/interpolate

Usage

package main

import (
  "github.com/buildkite/interpolate"
  "fmt"
)

func main() {
	env := interpolate.NewSliceEnv([]string{
		"HELLO_WORLD=🦀",
	})

	output, _ := interpolate.Interpolate(env, "Buildkite... ${HELLO_WORLD} ${ANOTHER_VAR:-🏖}")
	fmt.Println(output)
}

// Output: Buildkite... 🦀 🏖

Supported Expansions

${parameter} or $parameter

Use value. If parameter is set, then it shall be substituted; otherwise it will be blank

${parameter:-[word]}

Use default values. If parameter is unset or null, the expansion of word (or an empty string if word is omitted) shall be substituted; otherwise, the value of parameter shall be substituted.

${parameter-[word]}

Use default values when not set. If parameter is unset, the expansion of word (or an empty string if word is omitted) shall be substituted; otherwise, the value of parameter shall be substituted.

${parameter:[offset]}

Use the substring of parameter after offset. A negative offset must be separated from the colon with a space, and will select from the end of the string. If the value is out of bounds, an empty string will be substituted.

${parameter:[offset]:[length]}

Use the substring of parameter after offset of given length. A negative offset must be separated from the colon with a space, and will select from the end of the string. If the offset is out of bounds, an empty string will be substituted. If the length is greater than the length then the entire string will be returned.

${parameter:?[word]}

Indicate Error if Null or Unset. If parameter is unset or null, the expansion of word (or a message indicating it is unset if word is omitted) shall be returned as an error.

$$parameter or \$parameter or $${expression} or \${expression}

An escaped interpolation. Will not be interpolated, but will be unescaped by a call to interpolate.Interpolate()

License

Licensed under MIT license, in LICENSE.

Documentation

Index

• func Identifiers(str string) ([]string, error)
• func Interpolate(env Env, str string) (string, error)
• type EmptyValueExpansion
  • func (e EmptyValueExpansion) Expand(env Env) (string, error)
  • func (e EmptyValueExpansion) Identifiers() []string
• type Env
  • func NewMapEnv(env map[string]string) Env
  • func NewSliceEnv(env []string) Env
• type EscapedExpansion
  • func (e EscapedExpansion) Expand(Env) (string, error)
  • func (e EscapedExpansion) Identifiers() []string
• type Expansion
• type Expression
  • func (e Expression) Expand(env Env) (string, error)
  • func (e Expression) Identifiers() []string
• type ExpressionItem
  • func (i ExpressionItem) String() string
• type Parser
  • func NewParser(str string) *Parser
  • func (p *Parser) Parse() (Expression, error)
• type RequiredExpansion
  • func (e RequiredExpansion) Expand(env Env) (string, error)
  • func (e RequiredExpansion) Identifiers() []string
• type SubstringExpansion
  • func (e SubstringExpansion) Expand(env Env) (string, error)
  • func (e SubstringExpansion) Identifiers() []string
• type UnsetValueExpansion
  • func (e UnsetValueExpansion) Expand(env Env) (string, error)
  • func (e UnsetValueExpansion) Identifiers() []string
• type VariableExpansion
  • func (e VariableExpansion) Expand(env Env) (string, error)
  • func (e VariableExpansion) Identifiers() []string

Examples

• Interpolate

Functions

func Identifiers

func Identifiers(str string) ([]string, error)

Indentifiers parses the identifiers from any expansions in the provided string

func Interpolate

func Interpolate(env Env, str string) (string, error)

Interpolate takes a set of environment and interpolates it into the provided string using shell script expansions

Example

package main

import (
	"fmt"
	"log"

	"github.com/buildkite/interpolate"
)

func main() {
	env := interpolate.NewSliceEnv([]string{
		"HELLO_WORLD=🦀",
	})

	output, err := interpolate.Interpolate(env, "Buildkite... ${HELLO_WORLD} ${ANOTHER_VAR:-🏖}")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(output)

}

Output:

Buildkite... 🦀 🏖

Types

type EmptyValueExpansion

type EmptyValueExpansion struct {
	Identifier string
	Content    Expression
}

EmptyValueExpansion returns either the value of an env, or a default value if it's unset or null

func (EmptyValueExpansion) Expand

func (e EmptyValueExpansion) Expand(env Env) (string, error)

func (EmptyValueExpansion) Identifiers

func (e EmptyValueExpansion) Identifiers() []string

type Env

type Env interface {
	Get(key string) (string, bool)
}

func NewMapEnv

func NewMapEnv(env map[string]string) Env

Creates an Env from a map of environment variables

func NewSliceEnv

func NewSliceEnv(env []string) Env

Creates an Env from a slice of environment variables

type EscapedExpansion

type EscapedExpansion struct {
	// PotentialIdentifier is an identifier for the purpose of Identifiers,
	// but not for the purpose of Expand.
	PotentialIdentifier string
}

EscapedExpansion is an expansion that is delayed until later on (usually by a later process)

func (EscapedExpansion) Expand

func (e EscapedExpansion) Expand(Env) (string, error)

func (EscapedExpansion) Identifiers

func (e EscapedExpansion) Identifiers() []string

type Expansion

type Expansion interface {
	// Expand expands the expansion using variables from env.
	Expand(env Env) (string, error)

	// Identifiers returns any variable names referenced within the expansion.
	// Escaped expansions do something special and return identifiers
	// (starting with $) that *would* become referenced after a round of
	// unescaping.
	Identifiers() []string
}

An expansion is something that takes in ENV and returns a string or an error

type Expression

type Expression []ExpressionItem

Expression is a collection of either Text or Expansions

func (Expression) Expand

func (e Expression) Expand(env Env) (string, error)

func (Expression) Identifiers

func (e Expression) Identifiers() []string

type ExpressionItem

type ExpressionItem struct {
	Text string
	// -- or --
	Expansion Expansion
}

ExpressionItem models either an Expansion or Text. Either/Or, never both.

func (ExpressionItem) String

func (i ExpressionItem) String() string

type Parser

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

Parser takes a string and parses out a tree of structs that represent text and Expansions

func NewParser

func NewParser(str string) *Parser

NewParser returns a new instance of a Parser

func (*Parser) Parse

func (p *Parser) Parse() (Expression, error)

Parse expansions out of the internal text and return them as a tree of Expressions

type RequiredExpansion

type RequiredExpansion struct {
	Identifier string
	Message    Expression
}

RequiredExpansion returns an env value, or an error if it is unset

func (RequiredExpansion) Expand

func (e RequiredExpansion) Expand(env Env) (string, error)

func (RequiredExpansion) Identifiers

func (e RequiredExpansion) Identifiers() []string

type SubstringExpansion

type SubstringExpansion struct {
	Identifier string
	Offset     int
	Length     int
	HasLength  bool
}

SubstringExpansion returns a substring (or slice) of the env

func (SubstringExpansion) Expand

func (e SubstringExpansion) Expand(env Env) (string, error)

func (SubstringExpansion) Identifiers

func (e SubstringExpansion) Identifiers() []string

type UnsetValueExpansion

type UnsetValueExpansion struct {
	Identifier string
	Content    Expression
}

UnsetValueExpansion returns either the value of an env, or a default value if it's unset

func (UnsetValueExpansion) Expand

func (e UnsetValueExpansion) Expand(env Env) (string, error)

func (UnsetValueExpansion) Identifiers

func (e UnsetValueExpansion) Identifiers() []string

type VariableExpansion

type VariableExpansion struct {
	Identifier string
}

VariableExpansion represents either $VAR or ${VAR}, our simplest expansion

func (VariableExpansion) Expand

func (e VariableExpansion) Expand(env Env) (string, error)

func (VariableExpansion) Identifiers

func (e VariableExpansion) Identifiers() []string