embeds - v1.1.0

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) -> Code,
    prefix: String,
    regex: Option(Regex),
  )
}

Constructors 

  • Options(
  module: String,
  header: String,
  parse: fn(String, String) -> Code,
  prefix: String,
  regex: Option(Regex),
)

    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) -> Code

Functions

bool

</> 
pub fn bool(value: String) -> Code

A parser for boolean flags

default_parse

</> 
pub fn default_parse(key: String, value: String) -> Code

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

float

</> 
pub fn float(value: String) -> Code

A parser for floating-point literals

generate

</> 
pub fn generate(options: Options) -> Result(Nil, List(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(Regex),
) -> List(Definition)

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

int

</> 
pub fn int(value: String) -> Code

A parser for integers literals

list

</> 
pub fn list(
  item_parser: fn(String) -> Code,
  separator: String,
) -> fn(String) -> 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) -> Code

A string parser, just passing through the value

typed_parse

</> 
pub fn typed_parse(
  definitions: List(#(String, fn(String) -> Code)),
) -> fn(String, String) -> 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) -> Code)),
  fallback: fn(String, String) -> Code,
) -> fn(String, String) -> 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.

✨ Search Document