Standard library · Encoding and data

encoding/envfile

Reading and writing .env files, with variable substitution.

import encoding.envfile

On this page

Types
Functions

A .env file holds a program's environment variables, one KEY=value per line. This package skips blank lines and # comments, accepts export before a key, strips the quotes, and keeps the keys in order.

Parse substitutes references such as ${HOST} from the same file; ParseRaw leaves them alone. The operating system's own environment variables are not read; for those see the env package.

Types

`Doc`

struct Doc

The contents of an env file.

Name	Type	Description
`m`	`collections.OrderedMap`	The keys and values, in order.
`flags`	`Vector`	For each key, whether its value takes substitution; single quotes turn it off.

encoding-envfile-Parse.salam

import encoding.envfile
import encoding.encerr

func main:
    text := "# settings\nHOST=localhost\nPORT=8080\nexport NAME=\"hello world\"\nURL=http://${HOST}:${PORT}/\n"
    mut doc := envfile.Parse(text)
    println envfile.Len(doc), envfile.Keys(doc)
    println envfile.Get(doc, "NAME"), envfile.Has(doc, "DEBUG"), envfile.GetOr(doc, "DEBUG", "false")
    println envfile.KeyAt(doc, 0), envfile.ValueAt(doc, 1)
    println envfile.Get(doc, "URL")
    raw := envfile.ParseRaw(text)
    println envfile.Get(raw, "URL"), envfile.RefNames(raw)
    mut base := envfile.New()
    expanded := envfile.ExpandDoc(raw, base)
    println envfile.Get(expanded, "URL")
    println envfile.Expand("${HOST}/api", doc, base), envfile.RefNamesIn("$A and ${B}")
    envfile.Set(doc, "DEBUG", "true")
    println envfile.Remove(doc, "URL")
    println envfile.Format(doc)
    println envfile.FormatExport(base) == "", envfile.Quote("a b")
    mut other := envfile.Parse("PORT=9090\nMODE=prod\n")
    envfile.MergeInto(doc, other)
    println envfile.Get(doc, "PORT"), envfile.Get(doc, "MODE")
    mut e := encerr.NoError()
    _ := envfile.ParseStrict("=no key\n", e)
    println encerr.IsError(e), envfile.Valid("A=1\n")
    println envfile.ParseScalar(`"a\tb"`), envfile.ParseScalarEx("x ; comment", true)
    envfile.Free(doc)
    envfile.Free(raw)
    envfile.Free(base)
    envfile.Free(expanded)
    envfile.Free(other)
end

Output4 ["HOST", "PORT", "NAME", "URL"] hello world false false HOST 8080 http://localhost:8080/ http://${HOST}:${PORT}/ ["HOST", "PORT"] http://localhost:8080/ localhost/api ["A", "B"] true HOST=localhost PORT=8080 NAME="hello world" DEBUG=true true "a b" 9090 prod true true a b x

Functions

`Quote`

func Quote(v: str): str

Puts a value in double quotes when it needs them.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Format`

func Format(d &: Doc): str

Turns the document back into env file text.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`FormatExport`

func FormatExport(d &: Doc): str

Like Format, with export before each line, for a shell.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`New`

func New(): Doc

An empty document.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Len`

func Len(d &: Doc): int

The number of keys.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Has`

func Has(d &: Doc, key: str): bool

True when the key is there.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Get`

func Get(d &: Doc, key: str): str

A key's value, or an empty string when it is absent.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`GetOr`

func GetOr(d &: Doc, key: str, def: str): str

A key's value, or the default.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Set`

func Set(d &: Doc, key: str, val: str)

Sets a key's value; a new key goes on the end.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Remove`

func Remove(d &: Doc, key: str): bool

Removes a key and says whether it was there.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`KeyAt`

func KeyAt(d &: Doc, i: int): str

Key number i.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`ValueAt`

func ValueAt(d &: Doc, i: int): str

Value number i.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Keys`

func Keys(d &: Doc): Vector<str>

The keys, in order.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`MergeInto`

func MergeInto(dst &: Doc, src &: Doc)

Pours the keys of src into dst, replacing any that are already there.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Free`

func Free(d &: Doc)

Releases the document's memory.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`ParseRaw`

func ParseRaw(text: str): Doc

Reads a file without substituting the references.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Parse`

func Parse(text: str): Doc

Reads a file and substitutes the references.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`ParseStrict`

func ParseStrict(text: str, err &: encerr.EncodingError): Doc

Like Parse, but a malformed line is an error and err is filled in.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Valid`

func Valid(text: str): bool

True when every line is well formed.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`ParseScalar`

func ParseScalar(raw: str): str

Reads a single value, as on the right of an =: it strips the quotes and the escapes.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`ParseScalarEx`

func ParseScalarEx(raw: str, semi: bool): str

Like ParseScalar; when semi is true, ; starts a comment as well as #.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`ExpandDoc`

func ExpandDoc(d &: Doc, base &: Doc): Doc

Builds a new document with the references substituted. Names are looked up in the document first and then in base.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`Expand`

func Expand(raw: str, d &: Doc, base &: Doc): str

Substitutes the references in a string from the document and base.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`RefNames`

func RefNames(d &: Doc): Vector<str>

The names of the variables the document's values refer to.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam

`RefNamesIn`

func RefNamesIn(raw: str): Vector<str>

The names of the variables referred to in a string, in both the $A and the ${A} form.

The example for this item is shown with the ones above: encoding-envfile-Parse.salam