1# Interpolate
 2
 3[![Build Status](https://github.com/mfridman/interpolate/actions/workflows/ci.yaml/badge.svg)](https://github.com/mfridman/interpolate/actions/workflows/ci.yaml)
 4[![Go Reference](https://pkg.go.dev/badge/github.com/mfridman/interpolate.svg)](https://pkg.go.dev/github.com/mfridman/interpolate)
 5[![Go Report Card](https://goreportcard.com/badge/github.com/mfridman/interpolate)](https://goreportcard.com/report/github.com/mfridman/interpolate)
 6
 7A Go library for parameter expansion (like `${NAME}` or `$NAME`) in strings from environment
 8variables. An implementation of [POSIX Parameter
 9Expansion](http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_02),
10plus some other basic operations that you'd expect in a shell scripting environment [like
11bash](https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html).
12
13## Installation
14
15```
16go get github.com/mfridman/interpolate@latest
17```
18
19## Usage
20
21```go
22package main
23
24import (
25  "github.com/mfridman/interpolate"
26  "fmt"
27)
28
29func main() {
30  env := interpolate.NewSliceEnv([]string{
31    "NAME=James",
32  })
33
34  output, _ := interpolate.Interpolate(env, "Hello... ${NAME} welcome to the ${ANOTHER_VAR:-🏖}")
35
36  fmt.Println(output)
37  // Output: Hello... James welcome to the 🏖
38}
39```
40
41## Supported Expansions
42
43- `${parameter}` or `$parameter`
44
45  - **Use value.** If parameter is set, then it shall be substituted; otherwise, it will be blank
46
47- `${parameter:-[word]}`
48
49  - **Use default values.** If parameter is unset or null, the expansion of word (or an empty string
50    if word is omitted) shall be substituted; otherwise, the value of parameter shall be
51    substituted.
52
53- `${parameter-[word]}`
54
55  - **Use default values when not set.** If parameter is unset, the expansion of word (or an empty
56    string if word is omitted) shall be substituted; otherwise, the value of parameter shall be
57    substituted.
58
59- `${parameter:[offset]}`
60
61  - **Use the substring of parameter after offset.** A negative offset must be separated from the
62    colon with a space, and will select from the end of the string. If the value is out of bounds,
63    an empty string will be substituted.
64
65- `${parameter:[offset]:[length]}`
66
67  - **Use the substring of parameter after offset of given length.** A negative offset must be
68    separated from the colon with a space, and will select from the end of the string. If the offset
69    is out of bounds, an empty string will be substituted. If the length is greater than the length
70    then the entire string will be returned.
71
72- `${parameter:?[word]}`
73  - **Indicate Error if Null or Unset.** If parameter is unset or null, the expansion of word (or a
74    message indicating it is unset if word is omitted) shall be returned as an error.
75
76## Prior work
77
78This repository is a fork of [buildkite/interpolate](https://github.com/buildkite/interpolate). I'd
79like to thank the authors of that library for their work. I've forked it to make some changes that I
80needed for my own use cases, and to make it easier to maintain. I've also added some tests and
81documentation.
82
83## License
84
85Licensed under MIT license, in `LICENSE`.