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
AccessorPrimitiveOption<T>
AccessorStringOption
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>
Command
CommandRegistry
CommandResolution
CompletionCommand
CountFlag
DefaultedAccessorOption<T>
DefaultedInput<T>
DefaultedOption<T>
DefaultedPositional<T>
DefaultedRepeatableOption<T>
DefaultValue<T>
DiscretionaryPositional<T>
DoubleOption
Executor
Flag<T>
GroupCommand
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
Declarations Mamba uses for its built-in flags.
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.
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>
NormalPositional
NormalVariadic
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.
Positional<T>
ProcessedStandardInput
RegistryAccessor
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>
SelectedOptions<T extends Object>
A named collection of pair options that resolves to a map of supplied values.
SingleOption<T>
StringOption
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.
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
MambaExecutionPhase
QuoteStyle
Style of quotes to use for string serialization.
ShellCompletion

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.

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

Typedefs

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})
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, 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? defaultValue, String? description, String? pattern})
YAMLWriter = YamlWriter

Exceptions / Errors

MambaCommandNotFoundException
MambaException
A recoverable failure that can be rendered to a user.
MambaIntegrationException
MambaParseException
MambaRegistryError
An unrecoverable error in a Mamba command-definition invariant.