Gleamgen

A package for generating clean, type-checked, and formatted Gleam code!

Key Features

• Type safety: ensure generated code is type safe using phantom types (including support for functions, custom types, and all builtin operators)
• Simple escape hatches with the dynamic version of functions (generating code is by nature dynamic)
• Automatically fix errors or clean up code. For example gleamgen automatically:
  • removes unused imports
  • inlines anonymous functions when appropriate,
  • simplifies blocks, and combines equivalent case branches
• Generate code in existing files (combines with existing imports and definitions)

Installation

gleam add gleamgen

Example

import gleam/io
import gleam/list
import gleam/string
import gleamgen/expression
import gleamgen/expression/block
import gleamgen/function
import gleamgen/import_
import gleamgen/module
import gleamgen/module/definition
import gleamgen/parameter
import gleamgen/render
import gleamgen/type_

pub fn generate() {
  let mod = {
    use imported_io <- module.with_import(import_.new(["gleam", "io"]))
    use imported_string <- module.with_import(import_.new(["gleam", "string"]))

    // module_used is of type Expression(String)
    use module_used <- module.with_constant(
      definition.new("module_used"),
      expression.string("Gleamgen"),
    )

    use greeter <- module.with_function(
      definition.new("greeter"),
      function.new1(
        param1: parameter.new("greeting", type_.string),
        // we have said that greeter returns a string, so handler returning anything
        // else would be a type error
        returns: type_.string,
        handler: fn(greeting) {
          greeting
          |> expression.concat_string(expression.string(" from "))
          // trying to concatenate any other type would be a compilation error
          |> expression.concat_string(module_used)
        },
      ),
    )

    // Let's pick a greeting that we will use inside the generated code
    let assert [outer_greeting, ..] =
      list.shuffle([
        expression.string("Howdy"),
        expression.string("Hello"),
        expression.call2(
          // If this is not the selected greeting, gleam/string will not be
          // imported in the final code
          import_.value_of_type(
            imported_string,
            "repeat",
            type_.reference(string.repeat),
          ),
          expression.string("Hi"),
          expression.int(5),
        ),
      ])

    use _main <- module.with_function(
      definition.new("main") |> definition.with_publicity(True),
      function.new0(type_.nil, fn() {
        use greeting <- block.with_let_declaration(
          "greeting",
          expression.call1(greeter, outer_greeting),
        )
        expression.call1(
          // reference the actual io.println function to get the name and
          // the type signature
          import_.value_of_type(
            imported_io,
            "println",
            type_.reference(io.println),
          ),
          greeting,
        )
      }),
    )

    module.eof()
  }

  mod
  |> module.render(render.default_context())
  |> render.to_string()
}

This will generate something like:

import gleam/io

const module_used = "Gleamgen"

fn greeter(greeting: String) -> String {
  greeting <> " from " <> module_used
}

pub fn main() -> Nil {
  let greeting = greeter("Hello")
  io.println(greeting)
}

To get started, check out the getting started guide, the docs, and the examples folder.