Modules, Imports, and Testing

Modules and Files

• Every Gleam source file is a module
• The module name comes from the file path relative to src/
  • src/myapp/utils.gleam becomes the module myapp/utils
• import myapp/utils makes the module's func available as utils.func
• import myapp/utils.{my_fn} imports my_fn unqualified so you can call it without a prefix
• Standard library modules follow the same convention: import gleam/list, import gleam/dict, import gleam/string
  • Circular imports are not allowed

This Lesson

• src/modules/types.gleam contains shared type definitions
• src/modules/logic.gleam contains pure functions over those types
• src/modules.gleam is the entry point that wires them together

Public and Private Definitions

• Every function and type in Gleam is private by default
• Adding pub makes it accessible from other modules

pub type Status {
  Active
  Done
}

pub type Todo {
  Todo(title: String, status: Status)
}

• pub type Status exports the type and its constructors (Active, Done)
  • Other modules can create Active or Done values
• pub type Todo exports the record type and its constructor
  • Other modules can write Todo(title: "...", status: Active)
• Omit pub and the type is invisible outside the file

pub fn display_status(status: Status) -> String {
  case status {
    Active -> "[ ]"
    Done -> "[x]"
  }
}

• Use private functions for implementation details that callers should not depend on directly
  • E.g., have a public entry point and a private function to do the recursion

Opaque Types

• An opaque type makes the type name public but hides its constructors
• Other modules can hold a value of the type but cannot create or inspect it directly
  • They must use the functions the module provides

pub opaque type Counter {
  Counter(value: Int)
}

pub fn new() -> Counter { Counter(0) }
pub fn increment(c: Counter) -> Counter { Counter(c.value + 1) }
pub fn decrement(c: Counter) -> Counter {
  case c.value > 0 {
    True -> Counter(c.value - 1)
    False -> c
  }
}
pub fn value(c: Counter) -> Int { c.value }

• Counter is visible to other modules
• Counter(42) is not: only new() can create a Counter
• Common use: collections that enforce invariants
  • Sorted lists, non-empty lists, validated email addresses, etc.

Organising by Layer

• The logic module contains pure functions that take and return plain data:

pub fn add_task(tasks: List(types.Todo), title: String) -> List(types.Todo) {
  [types.Todo(title, types.Active), ..tasks]
}

• add_task has no side effects: list in, list out
  • Easy to test: call it, inspect the result
• It uses types.Todo and types.Active because modules/types is imported at the top of the file
• Prepending with [new_item, ..existing] is idiomatic: it runs in constant time

pub fn render(tasks: List(types.Todo)) -> String {
  tasks
  |> list.index_map(fn(task, i) {
    let num = int.to_string(i + 1) <> ". "
    let status = types.display_status(task.status)
    num <> status <> " " <> task.title
  })
  |> string.join("\n")
}

• render is also pure: List(Todo) in, String out
• list.index_map(fn(i, task) { ... }) maps with a zero-based index
  • Like Python's enumerate
• string.join("\n") concatenates lines with a newline separator
• Returning a String instead of printing keeps this function in the logic layer
  • The caller decides how to display it
• The three-layer structure:
  • types.gleam: data definitions only, no logic
  • logic.gleam: pure functions over the types, no IO imports
  • Entry point: calls logic functions and handles side effects

Testing with gleeunit

• Gleam's test runner is gleeunit
• Tests live in test/ in files named *_test.gleam

pub fn add_task_test() {
  let result = logic.add_task([], "write tests")
  result
  |> should.equal([types.Todo("write tests", types.Active)])
}

pub fn render_single_test() {
  let tasks = [types.Todo("learn Gleam", types.Active)]
  logic.render(tasks)
  |> should.equal("1. [ ] learn Gleam")
}

• Every function ending in _test runs automatically
• should.equal(expected) asserts the piped value equals expected
• should.be_ok and should.be_error check Result values
• gleam test runs all tests, gleam test --module foo_test runs one file

Type Aliases

• type MyAlias = SomeOtherType creates a readable name for an existing type.

pub type Filename = String
pub type Hash = String
pub type FileMap = dict.Dict(Hash, List(Filename))

• Filename and String are identical to the compiler; one is just more descriptive
• Unlike opaque types, aliases do not hide constructors
• Use them to make function signatures communicate intent: fn group(files: List(#(Filename, Hash))) -> FileMap is clearer than fn group(files: List(#(String, String))) -> dict.Dict(String, List(String))

Check Understanding

Exercises