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.
$$parameteror\$parameteror$${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
- type Env
- type EscapedExpansion
- type Expansion
- type Expression
- type ExpressionItem
- type Parser
- type RequiredExpansion
- type SubstringExpansion
- type UnsetValueExpansion
- type VariableExpansion
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Identifiers ¶
Indentifiers parses the identifiers from any expansions in the provided string
func Interpolate ¶
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) Identifiers ¶
func (e EmptyValueExpansion) Identifiers() []string
type Env ¶
func NewSliceEnv ¶
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) 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) Identifiers ¶
func (e Expression) Identifiers() []string
type ExpressionItem ¶
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 (*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) Identifiers ¶
func (e RequiredExpansion) Identifiers() []string
type SubstringExpansion ¶
SubstringExpansion returns a substring (or slice) of the env
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) Identifiers ¶
func (e UnsetValueExpansion) Identifiers() []string
type VariableExpansion ¶
type VariableExpansion struct {
Identifier string
}
VariableExpansion represents either $VAR or ${VAR}, our simplest expansion
func (VariableExpansion) Identifiers ¶
func (e VariableExpansion) Identifiers() []string
Source Files