Etch — A Gleam TUI Backend Library

Etch is a powerful terminal user interface (TUI) backend library for Gleam, designed to help you build rich, interactive terminal applications with ease. It provides a comprehensive set of tools for managing terminal output, handling events, and styling text, with no third-party dependencies.

This project was inspired by crossterm.

Features

Terminal Control

Raw Mode: Enter and exit raw mode for direct terminal control
Alternative Screen: Switch between main and alternative screen buffers
Window Management: Get and set terminal dimensions
Screen Clearing: Clear the screen or specific portions with various options
Line Wrapping: Enable or disable line wrapping
Scrolling: Scroll the terminal content up or down

Cursor Management

Positioning: Move cursor to specific positions or relative offsets
Visibility: Show or hide the cursor
Position Saving: Save and restore cursor positions
Styling: Set cursor style (block, underscore, bar) with blinking options

Input Handling

Keyboard Input: Capture and parse keyboard input with modifiers
Mouse Support: Handle mouse input (clicks, drags, scrolls)
Focus Management: Detect focus gain/loss event
Window Resizing: Respond to terminal resize event
Keyboard Enhancement: Support for progressive keyboard enhancement flags

Text Styling

Colors: Full color support including:
- Standard colors (black, red, green, etc.)
- Bright variants
- 256 ANSI colors
- True RGB colors
Attributes: Text styling with bold, dim, italic, underline, blinking, and inverse
Style Management: Save and apply complex styles (foreground, background, attributes)

Command System

Queue System: Batch and flush terminal commands efficiently
Comprehensive Commands: Wide range of commands for all terminal operations
Immediate Execution: Execute commands without queueing

Input Handling and Terminal Raw Mode

These features are target specific. Add corresponding packages: gleam add etch_erlang or gleam add etch_javascript. Refer to their documentation to use these features properly and check examples.

Getting Started

Here’s a basic template to get you started with Etch:

import etch/command
import etch/style
import etch/stdout.{type Queue, execute, flush, queue}

pub fn main() {
  // Execute `Commands`
  execute([
    command.EnterAlternateScreen,
    command.HideCursor,
    command.Clear(terminal.All)
  ])

  // Queue `Commands`
  let q = Queue([
    command.SetForegroundColor(style.Red),
    command.SetBackgroundColor(style.Black),
  ])
  let text = "Styled text"
  let q = queue(q, [command.Println(text)])
  
  // Flush queued `Commands`
  flush(q)
}

Examples

Check out the examples in the examples/, examples_erlang/ and examples_javascript directories for more advanced usage:

hello_world.gleam: Basic text rendering and centering
events.gleam: Comprehensive event handling
snake.gleam: Simple game implementation
styles.gleam: Advanced text styling techniques

To run examples use this command:

gleam run -m examples/{example_name}

To run target specific examples cd into a target directory

cd examples_erlang # or cd examples_javascript
gleam run -m {example_name}

Documentation

For detailed API documentation, see the documentation for the Etch package.

Building and Shipping Your App

Before building your application I suggest you to look at the benchmarks.

See this awesome article: Packaging a Gleam app into a single executable. In short, there are multiple ways to build your app into a single executable:

JavaScript target

Bun

Build your application:
```
gleam build
```
Compile it using bun

bun build --compile --outfile=bundle build/dev/javascript/<project_name>/<project_name>.mjs --footer="main();"

You will get an executable file in your project’s root directory.

Node and Deno

Refer to the article above for more information.

Erlang target

Gleescript

Add gleescript to your project:
```
gleam add --dev gleescript
```
Build your application:
```
gleam build
gleam run -m gleescript
```

You will get an executable file in your project’s root directory. Users must have Erlang installed in order to run your executable.

Burrito

Create new mix project

mix new my_app

Add MixGleam to your project: See Installation
Add Burrito: See Quick start
Add etch

# in mix.exs
# ...
  defp deps do
    [
      # ...
      {:etch, "~> 1.4.0"},
      # ...
    ]
  end
# ...

Build your application:
```
mix
```

You will get an executable file in build directory. Unlike gleescript, burrito does not require Erlang to be installed to run your application.

Contributing.

Feel free to open issues and make pull requests.

Authors

Egor Kurtashkin — project owner and creator.

License

This project is licensed under MIT License. See LICENSE file for details.