embeds - v1.1.0

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, Data) -> Code,
    force: Bool,
  )
}

Constructors 

  • Options(
  sources: List(Source),
  header: String,
  print: fn(String, Data) -> 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(Int),
    filter: fn(Bool, String) -> Bool,
  )
}

Constructors 

  • Source(
  src: String,
  module: String,
  flatten: Flatten,
  max_depth: 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.

Functions

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(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(Definition), 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.

✨ Search Document