embeds/env

embeds/env generates a Gleam module containing constants and zero-argument functions based on environment variables.

This module is intended to be run as a CLI tool during your build process:

gleam run -m embeds/env -- --help

The functions exposed in this module can also be used directly to support advanced use cases inside custom pre-build scripts.

Types

Options

</>

pub type Options {
  Options(
    module: String,
    header: String,
    parse: fn(String, String) -> generate.Code,
    prefix: String,
    regex: option.Option(regexp.Regexp),
  )
}

Constructors

```
Options(
  module: String,
  header: String,
  parse: fn(String, String) -> generate.Code,
  prefix: String,
  regex: option.Option(regexp.Regexp),
)
```
Arguments

module

Name of the module to generate.

Note that the module name is not sanitized, and should represent a valid Gleam module name. You can use generate.to_gleam_module_name to turn a path or arbitrary into a valid value.

header

The module header

prefix

Only environment variables matching this prefix will be included, and the prefix will be stripped from the variable name.

regex

Optional regex that needs to match the variable name after the prefix has been stripped. If a capture group exists, the first match will be used for the environment variable.

Parser

</>

A parser is just a function turning an environment variable into Code.

Custom parsers

type Environment {
    Development
    Testing
    Production
}

fn environemnt(value: String) -> Code {
    // you need to make sure the type constructors are available,
    // for example by adding them to the header!
    case value {
        "development" -> generate.Constant(string.inspect(Development))
        "production" -> generate.Constant(string.inspect(Production))
        "testing" -> generate.Constant(string.inspect(Testing))
        _ -> generate.GenerateError("Invalid Environment: " <> value)
    }
}

pub type Parser =
  fn(String) -> generate.Code

Values

bool

</>

pub fn bool(value: String) -> generate.Code

A parser for boolean flags

default_parse

</>

pub fn default_parse(key: String, value: String) -> generate.Code

A default parse function, converting environment variables into string constants.

float

</>

pub fn float(value: String) -> generate.Code

A parser for floating-point literals

generate

</>

pub fn generate(
  options: Options,
) -> Result(Nil, List(generate.Error))

Generate Gleam modules, containing constants for all found variables. Exported for easier integration with other build tools.

Example

import embeds/env
import embeds/generate
import gleam/option
import gleam/io

pub fn main() {
    let result = env.generate(env.Options(
        module: "build_env",
        header: generate.default_header,
        parse: env.default_parse,
        prefix: "BUILD_",
        regex: option.None,
    ))

    case result {
       Ok(Nil) -> Nil
       Error(errs) -> io.println_error(generate.describe_errors(errs))
    }
}

get_variables

</>

pub fn get_variables(
  module: String,
  prefix: String,
  regex: option.Option(regexp.Regexp),
) -> List(generate.Definition)

Get all variables from the environment matching a prefix and a regex, and convert them into definitions.

int

</>

pub fn int(value: String) -> generate.Code

A parser for integers literals

list

</>

pub fn list(
  item_parser: fn(String) -> generate.Code,
  separator: String,
) -> fn(String) -> generate.Code

A parser for lists. Common separators might be : or ,

main

</>

pub fn main() -> Nil

runs generate using command line arguments to fill out the arguments.

string

</>

pub fn string(value: String) -> generate.Code

A string parser, just passing through the value

typed_parse

</>

pub fn typed_parse(
  definitions: List(#(String, fn(String) -> generate.Code)),
) -> fn(String, String) -> generate.Code

A function taking a list of (key, parser) pairs, and turning them into a parse function to be used in Options.

This allows you to generate other types of variables, instead of just strings.

Example

let options = env.Options(
    module: "build_env",
    header: generate.default_header,
    prefix: "BUILD_",
    regex: option.None,
    parse: env.typed_parse([
        #("BUILD_ENV", string),
        #("BUILD_REVISION", int),
        #("BUILD_ENABLE_AWESOMENESS", bool)
    ]),
)

typed_parse_fallback

</>

pub fn typed_parse_fallback(
  definitions: List(#(String, fn(String) -> generate.Code)),
  fallback: fn(String, String) -> generate.Code,
) -> fn(String, String) -> generate.Code

A variant of typed_parse that takes an additional fallback function used when the variable is not found inside of definitions.

Using default_parse as the fallback is useful to include all variables not found in definitions as simple string constants.

Constructors

Arguments

Custom parsers

Example

Example