embeds/files

embeds/files generates Gleam modules containing constants and zero-argument functions based on the contents of files.

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

gleam run -m embeds/files -- --help

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

Types

Flatten

</>

pub type Flatten {
  DontFlatten
  FlattenAll
  FlattenFirst(Int)
}

Constructors

```
DontFlatten
```
Don’t flatten. Every directory will generate another sub-module.
```
FlattenAll
```
Flatten all files, resulting in a single Gleam module
```
FlattenFirst(Int)
```
Only flatten the first N directory levels

Options

</>

pub type Options {
  Options(
    sources: List(Source),
    header: String,
    print: fn(String, generate.Data) -> generate.Code,
    force: Bool,
  )
}

Constructors

```
Options(
  sources: List(Source),
  header: String,
  print: fn(String, generate.Data) -> generate.Code,
  force: Bool,
)
```
Arguments

sources

A list of sources to scan for files. See the Source documentation for more info.

header

The header to place on the top of all modules

print

A printer is a function that turns a file into some Gleam code. You can use generate.default_print to produce String or BitArray literals.

force

If force is enabled, all modules will be regenerated, regardless of whether or not their timestamp has changed.

Source

</>

A Source, describing how to map a directory structure to Gleam module names.

pub type Source {
  Source(
    src: String,
    module: String,
    flatten: Flatten,
    max_depth: option.Option(Int),
    filter: fn(Bool, String) -> Bool,
  )
}

Constructors

```
Source(
  src: String,
  module: String,
  flatten: Flatten,
  max_depth: option.Option(Int),
  filter: fn(Bool, String) -> Bool,
)
```
Arguments

src

The source directory, where your asset files live.

module

The base name of the generated module.

The module name will be used as a base for all files in src, and nested directories will generate nested modules. (see flatten on how to tweak this) Multiple sources can re-use the same module name.

flatten

how many levels of directories to ignore before starting to group things into nested modules, which is sometimes useful to “skip” some diretories first.

max_depth

The maximum amount of levels to traverse before stopping looking for files. This setting is independent of flatten and will instead work based on the directory tree. A value of 0 means to only look at the given src directory. A None value represents no limit.

filter

A filter function called on file and directory names. If the function returns False, the directory or file will be skipped. Set to default_filter to filter out hidden files and directories.

The first argument is set to True if the given path is a directory.

Values

default_filter

</>

pub fn default_filter(is_dir: Bool, path: String) -> Bool

A default filter function to use inside sources. Filters out hidden files and directories.

generate

</>

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

Generate Gleam modules, containing constants for all found files, given the sources. Exported for easier integration with other build tools.

Example

import embeds/files
import embeds/generate
import gleam/option
import gleam/io

pub fn main() {
    let result = files.generate(files.Options(
        sources: [files.Source(
            src: "./assets",
            module: "assets",
            flatten: files.FlattenAll,
            max_depth: option.None,
            filter: files.default_filter,
        )],

        print: generate.default_print,
        header: generate.default_header,
        force: False,
    ))

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

get_files

</>

pub fn get_files(
  src: Source,
) -> Result(List(generate.Definition), simplifile.FileError)

Find all files inside a Source. You usually do not need to call this function yourself.

main

</>

pub fn main() -> Nil

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

Constructors

Constructors

Arguments

Constructors

Arguments

Example