gsh - v1.0.9

gsh

gsh is the core entry point for the Interactive Gleam Shell.

It acts as a development orchestrator, providing three main capabilities:

  1. Zero-Config Bootloader: Intercepts CLI arguments to dynamically boot host applications in the background (e.g., gleam run -m gsh -- my_app).
  2. Hot Code Swapping: Provides a compile command to manually rebuild the host project and trigger Erlang code:purge and code:load_file, hot-swapping live module updates without restarting the shell.
  3. Persistent REPL: A live-node interactive shell that maintains VM state, memoizes side effects, and safely handles runtime exceptions while toggling terminal raw mode to ensure clean I/O. It supports standard expression evaluation, lexical variable shadowing, and convenient top-level module syntax (fn, type) for rapid prototyping.

Types

ShellState

</>

Holds the persistent state of the shell session across evaluations. This state is passed recursively through the REPL loop to seamlessly inject historical context into each dynamically generated module.

pub type ShellState {
  ShellState(
    prompt_count: Int,
    bindings: List(binding.Binding),
    imports: List(String),
    types: List(#(String, String)),
    history: List(String),
    functions: List(#(String, String)),
    debug: Bool,
  )
}

Constructors 

  • ShellState(
  prompt_count: Int,
  bindings: List(binding.Binding),
  imports: List(String),
  types: List(#(String, String)),
  history: List(String),
  functions: List(#(String, String)),
  debug: Bool,
)

    Arguments

    prompt_count

    Increments on every REPL execution to guarantee uniquely named Erlang modules (e.g., gsh_eval_1, gsh_eval_2), preventing VM cache collisions.

    bindings

    Active let bindings. The shell intelligently drops older bindings only when all of their extracted variables have been fully shadowed.

    imports

    Active import statements. Checked sequentially to discard duplicates.

    types

    Custom type declarations. Stored as a tuple of #(Type_Name, Source_String). Redefining a type automatically prunes the old source to prevent compiler crashes.

    history

    The raw input strings of previously executed commands, used by the raw-mode editor for Arrow Up/Arrow Down traversal.

    functions

    Top-level fn definitions. Stored as a tuple of #(Function_Name, Source_String). When redefined, the old source string is strictly purged from the active state to satisfy the Gleam compiler’s unique-name constraints.

    debug

    Toggles verbose output for debugging the internal AST parsing and evaluation pipeline.

Values

main

</> 
pub fn main() -> Nil

The main entry point.

  1. Cleans up any orphaned evaluation files from previous crashed sessions.
  2. Intercepts trailing CLI arguments to boot background host applications.
  3. Injects a custom logger to prevent staircasing in background logs.
  4. Places the terminal into raw mode and starts the recursive REPL loop.
✨ Search Document