embeds/generate

This module exposes the internal/shared code for both embeds/files as well as embeds/env.

It exposes some common type aliases and functions, and provides a lower-level API to generate module files from a set of Definitions.

I recommend starting with the embeds/files and/or embeds/env modules first before diving into this one!

Types

Code

</>

Code represents the rendered string of some Gleam expression.

Because some expressions can’t be constants, you can also choose to print function bodies instead.

pub type Code {
  Skip
  GenerateError(String)
  Constant(String)
  FunctionBody(String)
}

Constructors

```
Skip
```
Skip generating code for this symbol.
```
GenerateError(String)
```
Codegen produced some error that should be reported to the user.
```
Constant(String)
```
Produce a constant definition in Gleam, like
```
pub const var_name = ...
```
```
FunctionBody(String)
```
Produce a zero-argument function definition in Gleam, like
```
pub fn var_name() {
    ...
}
```
You can use this constructor instead of Constant when your code contains anonymous functions, function calls, or other expressions that are not allowed inside of constants.

Data

</>

Data represents the contents of some file or other external source, and can either be UTF-8 Text, or Binary.

pub type Data {
  Text(String)
  Binary(BitArray)
}

Constructors

```
Text(String)
```
```
Binary(BitArray)
```

Definition

</>

A single codegen unit, potentially producing a single Code statement (so either a constant definition or a function.)

pub type Definition {
  Definition(
    name: String,
    read: fn() -> Result(Data, String),
    last_modified_seconds: Int,
    module: String,
    var_name: String,
  )
}

Constructors

```
Definition(
  name: String,
  read: fn() -> Result(Data, String),
  last_modified_seconds: Int,
  module: String,
  var_name: String,
)
```
Arguments
- name
  
  A human-identifyable name for this definition used in error messages. Usually the file path, or the name of the environment variable.
- read
  
  Files might get big, and definitions in general might be fetched from anywhere, so reading is deferred using this closure.
- last_modified_seconds
  
  A unix timestamp indicating the last modification time in seconds since Jan 01, 1970 for the source file of this definition.
  
  If a module only contains definitions that were modified before the module was last generated, generation will be skipped.
  
  You can savely just set this value to 0 if you don’t have a good value available.
- module
  
  The name of the module this definition belongs to. Note that no sanitization takes place, and module should be a valid Gleam module name.
  
  You can use to_gleam_module_name to turn a path or arbitrary string into a valid Gleam module path.
- var_name
  
  The name of the target constant or function name. Note that no sanitization takes place, and var_name should be a valid Gleam identifier.
  
  You can use to_gleam_identifier to turn an arbitrary string into a valid Gleam identifier.

Error

</>

the internal Error type returned by all embeds functions.

pub type Error {
  NotInsideGleamProject
  InvalidArgument(name: String, value: String, reason: String)
  CouldNotListFiles(path: String, FileError)
  CouldNotRead(name: String, message: String)
  DuplicateVarName(String, String)
  PrinterError(name: String, message: String)
  WriteError(path: String, FileError)
}

Constructors

```
NotInsideGleamProject
```
the current working directory is not a Gleam project, and has no gleam.toml file.

InvalidArgument(name: String, value: String, reason: String)

a command-line argument could not be parsed or is invalid.

```
CouldNotListFiles(path: String, FileError)
```
A simplifile error occurred while listing all files.
```
CouldNotRead(name: String, message: String)
```
An error occurred while calling the read function for a definition.
```
DuplicateVarName(String, String)
```
Multiple definitions would produce the same constant in the same module.
```
PrinterError(name: String, message: String)
```
The printer returned an error that should be reported.
```
WriteError(path: String, FileError)
```
A simplifile error occurred while writing to the output module file.

Constants

default_header

</>

pub const default_header: String

A simple module comment which is used as the header by the CLI

Functions

bits_to_data

</>

pub fn bits_to_data(bits: BitArray) -> Data

Try to convert a BitArray to Text first , returning Binary if the conversion fails.

data_to_bits

</>

pub fn data_to_bits(data: Data) -> BitArray

Convert some data back to a BitArray.

default_print

</>

pub fn default_print(name: String, data: Data) -> Code

convert data to code, by simply calling string.inspect/bit_array.inspect.

describe_error

</>

pub fn describe_error(err: Error) -> String

Turn an Error into a human-readable string.

describe_errors

</>

pub fn describe_errors(errs: List(Error)) -> String

Turn multiple erros into a human-readable string.

generate

</>

pub fn generate(
  defs: List(Definition),
  header: String,
  print: fn(String, Data) -> Code,
  force: Bool,
) -> Result(Nil, List(Error))

Generates module files based on a list of Definitions.

guard_gleam_project

</>

pub fn guard_gleam_project(
  f: fn() -> Result(a, List(Error)),
) -> Result(a, List(Error))

enforce that the current working directory is a gleam project (by checking a gleam.toml exists). Automatically called by generate, but you may wish to exit earlier. Designed to be used with use.

result_to_const

</>

pub fn result_to_const(result: Result(String, String)) -> Code

Helper function to convert a Result into either a Constant or GenerateError.

result_to_fn

</>

pub fn result_to_fn(result: Result(String, String)) -> Code

Helper function to convert a Result into either a FunctionBody or GenerateError.

skip_or_const

</>

pub fn skip_or_const(result: Result(String, Nil)) -> Code

Helper function to convert a Result into either a Constant or skip generating on error.

skip_or_fn

</>

pub fn skip_or_fn(result: Result(String, Nil)) -> Code

Helper function to convert a Result into either a FunctionBody or skip generating on error.

to_gleam_identifier

</>

pub fn to_gleam_identifier(str: String) -> String

Ensures the given string is a valid Gleam identifier by replacing invalid characters by underscores.

Empty strings return “empty”, numbers will be prefixed with “n”.

If the resulting variable name would be a reserved keyword, an additional underscore will be added at the end.

to_gleam_module_name

</>

pub fn to_gleam_module_name(path: String) -> String

Ensures a path is a valid Gleam module path, by making sure that every piece is a valid Gleam identifier.

Unix / and Windows \\ are both treated as module separators.

NOTE:The top-level module is not allowed to be called gleam, but this function does not enforce this!

Constructors

Constructors

Constructors

Arguments

Constructors