artisanal library Core

Artisanal: A polished CLI framework for Dart.

This library provides the core CLI experience, including:

  • Console for rich terminal output and interactive prompts.
  • Verbosity levels for controlling output detail.
  • Unified Terminal abstraction for raw mode and ANSI handling.

Functional Areas

  • I/O: Console provides a high-level API for writing to stdout/stderr, handling verbosity, and running tasks with status indicators.
  • Terminal: Terminal and StdioTerminal handle raw mode, cursor positioning, and input event decoding.
  • Styling: Style and Color provide a fluent API for terminal text formatting (Lip Gloss-inspired).

High-Level I/O

The Console class is the primary entry point for high-level CLI output. It supports:

  • Writing styled text with verbosity awareness.
  • Rendering DisplayComponents (tables, lists, panels).
  • Interactive prompts (confirm, select, input).
  • Task tracking with spinners and progress bars.

Verbosity and Logging

Verbosity levels allow users to control the amount of output produced by your CLI.

  • quiet: Only essential output.
  • normal: Standard output (default).
  • verbose: Detailed information for debugging.
  • debug: Maximum detail, including internal state.

Modular Exports

For specific functionality, you may want to import the modular libraries:

  • package:artisanal/args.dart: Command-line argument parsing and runners.
  • package:artisanal/style.dart: Full Lip Gloss-style styling system.
  • package:artisanal/tui.dart: Interactive TUI framework (Elm Architecture).
  • package:artisanal/bubbles.dart: Reusable interactive TUI components.
  • package:artisanal/uv.dart: Low-level cell-buffer rendering engine.

The Console class is the primary entry point for high-level CLI output. It supports:

  • Writing styled text with verbosity awareness.
  • Rendering DisplayComponents (tables, lists, panels).
  • Interactive prompts (confirm, select, input).
  • Task tracking with spinners and progress bars.

Verbosity levels allow users to control the amount of output produced by your CLI.

  • quiet: Only essential output.
  • normal: Standard output (default).
  • verbose: Detailed information for debugging.
  • debug: Maximum detail, including internal state.

Classes

Ansi Terminal
Unified ANSI escape sequence constants and utilities.
AnsiColor
An explicit ANSI color code (0-255).
BasicColor
A color specified as a hex string or ANSI string code.
Color Style
Abstract base class for terminal colors.
Colors
Semantic and named color presets.
Command<T> Core
Base command class for Artisanal-style CLI commands.
CommandRunner<T> Core
An Artisanal-inspired wrapper around package:args CommandRunner.
Components
Higher-level console UI components (Laravel-style).
Console Core
The main I/O helper for Artisanal-style console output.
Key
Represents a parsed keyboard input event.
Keys
Key constants and utilities for keyboard input handling.
KittyImage
Utilities for the Kitty Graphics Protocol.
Layout
Layout utilities for composing rendered blocks.
NullRenderer
A renderer that discards all output.
RawModeGuard
Guard object returned by Terminal.enableRawMode.
Renderer
Abstract interface for rendering styled output.
StdioTerminal
Standard terminal implementation using dart:io.
StringRenderer
A renderer that captures output to a string buffer.
StringTerminal
A terminal that captures output to a string buffer (for testing).
Style Style
Fluent, chainable style builder for terminal output.
Terminal Terminal
Abstract terminal interface for all terminal operations.
TerminalRenderer
A renderer that outputs to a terminal.
Validators
Built-in validators for input prompts using Acanthis.

Enums

ColorProfile
Color profile indicating terminal color capabilities.
KeyType
Types of keyboard input events.
TaskResult
Result of a task operation.
Verbosity
Verbosity levels for console output.

Extensions

DisplayComponentExtension on DisplayComponent
Extension to allow DisplayComponents to be written directly to a Console.
StyleConvenienceExtensions on Style
Convenience extensions for common semantic styles.

Properties

defaultRenderer ↔ Renderer
Gets the default renderer.
getter/setter pair

Functions

resetDefaultRenderer() → void
Resets the default renderer to a new TerminalRenderer.
styleRunes(String s, Style styler(int rune, int index)) → String
Styles individual runes in a string using a styler function.

Typedefs

ReadLine = String? Function()
Callback for reading a line of input.
SecretReader = String Function(String prompt, {String? fallback})
Callback for reading secret/password input without echo.
WriteLine = void Function(String line)
Callback for writing a complete line to output.
WriteRaw = void Function(String text)
Callback for writing raw text (without newline) to output.