Bash.Builtin (Bash v0.6.0)

Copy Markdown View Source

Central registry for Bash builtin commands and reserved words.

This module provides:

  • List of reserved words (keywords)
  • List of all standard bash builtins
  • Map of implemented builtins to their modules
  • defbash macro for implementing builtins with streaming I/O

Reference: https://cgit.git.savannah.gnu.org/plain/bash.git/tree/builtins?h=bash-5.3

Implementing Builtins with defbash

Use use Bash.Builtin and the defbash macro to implement builtins with automatic streaming I/O through sinks:

defmodule Bash.Builtin.Echo do
  use Bash.Builtin

  defbash execute(args, state) do
    text = Enum.join(args, " ")
    puts(text)
    :ok
  end
end

I/O Functions

Inside defbash, the following functions are available:

  • puts(message) - Write to stdout with newline
  • write(data) - Write raw data to stdout
  • error(message) - Write to stderr with newline
  • gets() - Read a line from stdin
  • read(:all) - Read all stdin

State Updates

Use update_state/1 to request state changes:

defbash execute(args, state) do
  update_state(working_dir: "/new/path", env: %{"FOO" => "bar"})
  :ok
end

Return Values

  • :ok - Exit code 0
  • {:ok, n} - Exit code n
  • {:error, message} - Exit code 1, message to stderr

Summary

Functions

__using__(opts)

Sets up a module as a builtin implementation with streaming I/O.

all_builtins()

Returns the list of all bash builtins (implemented and unimplemented).

builtin?(name)

Check if a name is a builtin (implemented or not).

builtin_modules()

Returns the map of implemented builtins to their module implementations.

defbash(arg, list)

Define a builtin's execute function with streaming I/O support.

get_module(name)

Get the module for a builtin, if implemented.

implemented?(name)

Check if a builtin is implemented.

implemented_builtins()

Returns the list of implemented builtin names.

reserved_word?(name)

Check if a name is a reserved word.

reserved_words()

Returns the list of bash reserved words.

Functions

__using__(opts)

(macro)

Sets up a module as a builtin implementation with streaming I/O.

Example

defmodule Bash.Builtin.MyBuiltin do
  use Bash.Builtin

  defbash execute(args, state) do
    puts("Hello from builtin!")
    :ok
  end
end

all_builtins()

Returns the list of all bash builtins (implemented and unimplemented).

builtin?(name)

Check if a name is a builtin (implemented or not).

builtin_modules()

Returns the map of implemented builtins to their module implementations.

defbash(arg, list)

(macro)

Define a builtin's execute function with streaming I/O support.

The function receives:

  • args - List of string arguments
  • state - The session state map (with sinks, variables, etc.)

Inside the body, use:

  • puts/1 - Write line to stdout
  • write/1 - Write raw to stdout
  • error/1 - Write line to stderr
  • gets/0 - Read line from stdin
  • read/1 - Read from stdin
  • update_state/1 - Request state changes

Return values:

  • :ok - Success, exit code 0
  • {:ok, n} - Success, exit code n
  • {:error, message} - Failure, writes message to stderr

get_module(name)

Get the module for a builtin, if implemented.

implemented?(name)

Check if a builtin is implemented.

implemented_builtins()

Returns the list of implemented builtin names.

reserved_word?(name)

Check if a name is a reserved word.

reserved_words()

Returns the list of bash reserved words.