mamba library

The public API for defining and executing Mamba command-line applications.

Mamba keeps command definition, validation, and execution separate:

  1. Commands register names, descriptions, inputs, and behavior.
  2. An Executor builds a CommandRegistry that organizes that data.
  3. A Parser reads the selected registry and decides whether an invocation is valid, producing typed values when it is.
  4. The executor selects the matching command and gives it parsed values, trailing arguments, and global context established by hooks.

See README.md for the complete input syntax, rendered help, and production and test setup guidance.

Classes

AccessorChoiceOption<T extends Enum>
AccessorDoubleOption
AccessorIntOption
AccessorListOption
AccessorOption
A value or a group of values inside an accessor tree.
AccessorPrimitiveOption<T>
AccessorStringOption
ArgParser
A class for taking a list of raw command line arguments and parsing out options and flags from them.
ArgResults
The results of parsing a series of command line arguments using ArgParser.parse.
BasicFormatter
BooleanFlag
CarapaceSpecConverter
Converts a typed registry record into a Carapace completion spec.
CarapaceSpecWriter
Writes a record-derived Carapace spec to the platform's spec directory.
Chalk
Chalk - A Library for printing styled text to the console using ANSI control sequences. Documentation of the ANSI code system: https://en.wikipedia.org/wiki/ANSI_escape_code . References with detailed explainations of the various color models included here: https://en.wikipedia.org/wiki/HSL_and_HSV and https://en.wikipedia.org/wiki/HWB_color_model The complete history of the X11 color names (later used in css/svg also) https://en.wikipedia.org/wiki/X11_color_names .
ChoiceOption<T extends Enum>
ChoicePositional<T extends Enum>
ChoiceVariadic<T extends Enum>
CliArgResults
Enhanced wrapper for ArgResults with Clix utilities
CliArgsHelper
Utility class for enhanced args functionality with Clix styling
CliColor
CLI Color System - Comprehensive terminal color management
CliConfig
Configuration manager for CLI applications
CliFormatter
CliIO
CliLogger
CliLogger - Main logging class with comprehensive CLI features
CliParser
Wrapper class that enhances the args package with Clix styling and utilities
CliStyle
CliStyle - Advanced text styling and visual effects
CliTestResult
Represents the result of executing a CLI command or test.
CliTestRunner
A utility class for running and testing CLI commands.
CliTestSummary
Summary of multiple test results
CliTheme
Clix
Main Clix class - Global access point for CLI operations
ClixDirectoryPicker
A directory browser using Clix line input rather than raw arrow keys.
ClixSelector
A numbered Clix selector that keeps input in the terminal's line mode.
Command
CommandHelp
The formatter and the registry an Executor resolved an invocation to.
CommandRegistry
CommandResolution
CompletionCommand
ConfigValue
Configuration value with validation and metadata
Confirm
Confirm Class - Yes/No confirmation prompt
ConsoleIO
CountFlag
Decimal
DefaultedAccessorOption<T>
DefaultedInput<T>
DefaultedOption<T>
DefaultedPositional<T>
DefaultedRepeatableOption<T>
DefaultValue<T>
DiscretionaryPositional<T>
DoubleOption
Executor
Flag<T>
GroupCommand
GroupHelp
A resolved help page supplied to a group that has no selected child.
HelpFormatter
The customization boundary for rendering a CommandRegistry as help text.
Input<T>
An identity-based, typed handle for a parsed command value.
InputDefinition
Metadata used by the parser, registry, help, and completion integrations.
IntOption
MambaBuiltInFlags
Reusable flag declarations supplied by Mamba.
MambaColors
MambaContext
Mutable state scoped to an executor and shared by all of its executions.
MambaContextBool
A bool value stored in MambaContext.
MambaContextDouble
A double value stored in MambaContext.
MambaContextInt
An int value stored in MambaContext.
MambaContextKey<T extends Object>
A typed identity token for a scalar value stored in MambaContext.
MambaContextString
A String value stored in MambaContext.
MambaContextValue<T extends Object>
A closed scalar value that can be stored in MambaContext.
MambaEnumValue
Opt in to exact enum-owned CLI choice spellings instead of Enum.name.
MambaExecutionError
MambaExecutionResult
MambaExecutor<T>
MambaFailureResult
MambaHelpFormatter
Renders a CommandRegistry as ANSI-styled command-line help text.
MambaReadContext
A read-only view of a MambaContext supplied to ordinary command hooks.
MambaSuccessResult
MandatoryPositional<T>
MultiSelect
MultiSpinner
MultiSpinner for managing multiple concurrent tasks
NormalPositional
NormalVariadic
Number
Option<T>
OptionalInput<T>
OptionalPositional<T>
PairChoiceOption<T extends Enum>
PairDoubleOption
PairedOptions<T extends Object>
A group whose members must either all be supplied or all be omitted.
PairedOptionsDefinition
PairIntOption
PairOption<T>
PairStringOption
ParsedInputs
ParsedValue<T>
Parser
Parses one command line into identity-keyed typed input values.
Password
Positional<T>
ProcessedStandardInput
Data read from the invocation's standard input.
Progress
Progress Class - Visual progress tracking bar
Prompt<T>
RegistryAccessor
RegistryAccessorGroup
RegistryAccessorValue
RegistryCommand
RegistryRecordConverter
Converts a typed registry description into an integration-specific artifact.
RepeatableChoiceOption<T extends Enum>
RepeatableDoubleOption
RepeatableIntOption
RepeatableOption<T>
RepeatableOptionDefinition
RepeatablePairDoubleOption
RepeatablePairIntOption
RepeatablePairOption<T>
RepeatablePairStringOption
RepeatableStringOption
RepeatedChoicePositional<T extends Enum>
RepeatedPositional<T>
RepeatedPositionalDefinition
RepeatedStringPositional
RequiredAccessorOption<T>
RequiredInput<T>
RequiredOption<T>
RequiredRepeatableOption<T>
Select
Select Class - Single selection menu prompt
SelectedOptions<T extends Object>
A named collection of pair options that resolves to a map of supplied values.
SingleOption<T>
Spinner
Spinner Class - Animated loading indicator
SpinnerTask
Individual task in MultiSpinner
StringOption
Table
TableColumn
ToBashCompletionConverter
Compiles a registry record into a portable Bash completion script.
ToFishCompletionConverter
Compiles a registry record into Fish complete declarations.
ToPowerShellCompletionConverter
Compiles a registry record into a native PowerShell argument completer.
ToZshCompletionConverter
Compiles a registry record into a native Zsh completion function.
ValidationRules
ValidationRules - Fluent builder for validatio /// Alpha Dash Rule - Letters, numbers, dashes, underscores only chains
Validator
Validator - S /// Alpha Dash Validation - Letters, numbers, dashes, underscores onlyatic validation methods collection
Variadic
YamlWriter
YAML Writer.
YamlWriterConfig
Configuration for YamlWriter.

Enums

ChalkAnsiColorSet
Color sets available for the basic ANSI colors 0 - 15. These match the colors I used for DartPad and VSCode also. There are versions for light mode, dark mode and high contrast mode.
ChalkOutputMode
Available output modes for the color and styled text. The default is ANSI output mode, setOutputMode() can be used on specific Chalk instances to change this. `Chalk.setDefaultOutputMode = true | false;' can be used to change the default for future construction of Chalk instances. The default is ChalkOutputMode.ansi
ChalkWhitespaceTreatment
CliIcons
Collection of predefined icons for CLI applications.
HintSymbol
Enum for hint symbols and separators
IndentLevel
LineSpacing
Enum for controlling spacing between lines in multi-line logging
LogLevel
MambaExecutionPhase
Padding
Enum for controlling padding inside background colors
PointStyle
ProgressStyle
Different styles for displaying progress bars
QuoteStyle
Style of quotes to use for string serialization.
RegistryValueKind
ShellCompletion
Spacing
Enum for controlling spacing between elements
SpinnerType
Types of animated symbols available for spinner animations
TableAlignment
Enum for table column text alignment options
TaskStatus
Status of individual tasks in multi-task operations
TreeSymbol

Extension Types

EntryDescriptionString
A yellow description for a help entry.
FormattedString
An ANSI-styled fragment that a help formatter can compose safely.
OptionalString
A styled help fragment enclosed in optional square brackets.
OrString
Joins mutually exclusive alternatives.
PairString
Joins members that must be supplied together.
RequiredString
A styled help fragment that must be supplied.
SectionTitleString
A green title for a help section.
SelectionString
Joins members that can be selected independently.

Extensions

ChalkX11 on Chalk
This extension class adds proper methods to Chalk for all of the standard X11/CSS/SVG color names for use by Chalk. This extension has the added advantage of providing code completion and type checking at coding/compile time. Using the dynamic color method cannot provide any coding/compile time checks because it works via a dynamic lookup at run time. Example of using this extension for Chalk: chalk.lightGoldenrodYellow.onCornflowerBlue(...) versus having to use the color (or css or x11) method to get a dynamic so you can use the dynamic lookups: chalk.color.lightGoldenrodYellow.onCornflowerBlue(...) Because of the dynamic lookup is not resolved until run time that method can be prone to errors which would not be detected until run time.
ClixSpinnerWork on Spinner
Runs work behind Clix's automatically started spinner.
PointStyleSymbol on PointStyle
RegistryPositionalCardinality on RegistryPositional

Constants

DUMP_HTML_INFO_OBJECTS → const bool

Properties

ansiColorDisabled → bool
Read only. Chalk does not look at it's value.
final
chalk ↔ Chalk
Default global instance of chalk used for base call. This can be set to a specific Chalk instance that would then serve as basis for all calls.
getter/setter pair
chalkUsedAnsiInclude → String
Read only, informational only. Name of the ansi include file used supports_ansi.dart is the default, or the dart.libary.io version supports_ansi_io.dart or the dart.library.js_interop version supports_ansi_web.dart.
final
dartSupportsAnsiColor → bool
Read only. Chalk does not use it's value although in some situation a user might use this to set the Chalk ansi color level (or something) I have left it here only for completeness. Within the common debug consoles this variable is essentially worthless because they return FALSE from both VSCode debug console and IntelliJ/Android Studio debug consoles. (This is because dart just checks for 'xterm' string being present in the 'TERM' environmental variable of the console..) See https://github.com/dart-lang/sdk/issues/31606 and https://github.com/dart-lang/sdk/issues/41770 for more info.
final

Functions

isClosedPipeFileSystemException(FileSystemException error) → bool
valueKindOf(InputDefinition input) → RegistryValueKind
One interpretation of an input's value across parsing and registry output.

Typedefs

ClixInput = Input
Clix's text prompt, named separately from Mamba's typed input declaration.
CompletionFileWriter = void Function(String path, String contents)
Receives a validated destination and the completion script generated for it.
ParsedArguments = (List<String>, ParsedInputs, List<String>, {bool help, bool version})
RegistryFlag = ({bool? defaultValue, String? description, bool hidden, String name, bool? negatable, String? short})
RegistryOption = ({List<String>? choices, String? defaultValue, String? description, bool hidden, num? max, num? min, String name, List<String>? pairedOptions, String? pattern, bool? repeatable, bool required, String? short, num? step, bool? unique, String valueType})
RegistryOptionGroup = ({List<String> members, bool required, bool single})
One group of related options: a paired set or a selected set.
RegistryPositional = ({List<String>? choices, String? defaultValue, String? description, String name, String? pattern, bool? repeatable, bool required, int? times})
RegistryRecord = ({List<RegistryAccessor>? accessors, List<RegistryCommand>? commands, Map<String, List<String>> conflicts, List<String>? defaultCommandPath, String description, List<RegistryFlag>? flags, String name, List<RegistryOptionGroup>? optionGroups, List<RegistryOption>? options, List<RegistryFlag>? persistentFlags, List<RegistryOption>? persistentOptions, List<RegistryPositional>? positionals, RegistryVariadic? variadic})
RegistryVariadic = ({List<String>? choices, String? description, String? pattern})
YAMLWriter = YamlWriter

Exceptions / Errors

ArgParserException
An exception thrown by ArgParser.
CliArgException
Custom exception for CLI argument parsing errors
CliConfigException
Exception thrown when configuration operations fail
MambaApplicationNameException
MambaCommandNotFoundException
MambaException
A recoverable failure that can be rendered to a user.
MambaIntegrationException
MambaParseException
MambaRegistryError
An unrecoverable error in a Mamba command-definition invariant.