GitHub

cli_output

API reference for cli_output.

How a CLI shows help, errors and its version (Effect's CliOutput).

A Formatter turns a HelpDoc or errors into text; a Presenter writes the runner's events (help, an invalid invocation, the version) to the console. Both have defaults; replace them with layer and layer_presenter. Without a formatter provided, the default one colors its output when TerminalCapabilities says the terminal can.

Values

AttributeTypeDescription
default_presenterPresenter

Types

TypeDefinitionDescription
Eventtype Event = Help | InvalidInvocation | Version
FlagSectionModetype FlagSectionMode = Literal['full', 'summary', 'none']

How help shows inherited or global flags: listed, as a pointer to the help of the command that declares them, or not at all.

Classes

Functions

default_formatter

default_formatter(*, colors=None, inherited_flags='full', global_flags='full') -> Formatter

The built-in formatter; colors defaults to whether stdout is a terminal and NO_COLOR is unset. inherited_flags and global_flags choose how a subcommand's help shows the shared flags of its ancestors and the global flags: listed ("full"), as a pointer to the declaring command's help ("summary") or not at all ("none"). The command declaring global flags always lists them.

ParameterTypeDescription
colorsbool | None = None
inherited_flagsFlagSectionMode = 'full'
global_flagsFlagSectionMode = 'full'

Returns Formatter

def default_formatter(
    *,
    colors: bool | None = None,
    inherited_flags: FlagSectionMode = "full",
    global_flags: FlagSectionMode = "full",
) -> Formatter:
    """The built-in formatter; ``colors`` defaults to whether stdout is a
    terminal and ``NO_COLOR`` is unset. ``inherited_flags`` and
    ``global_flags`` choose how a subcommand's help shows the shared flags of
    its ancestors and the global flags: listed (``"full"``), as a pointer to
    the declaring command's help (``"summary"``) or not at all (``"none"``).
    The command declaring global flags always lists them."""
    return _DefaultFormatter(
        _Colors(ansi.detect_colors() if colors is None else colors),
        _HelpOptions(inherited_flags, global_flags),
    )

resolve_formatter

resolve_formatter() -> Effect[Formatter]

The provided formatter, else the default one colored as the terminal's capabilities allow.

Returns Effect[Formatter]

def resolve_formatter() -> Effect[Formatter]:
    """The provided formatter, else the default one colored as the
    terminal's capabilities allow."""

    def body():
        provided = yield from service_option(CurrentFormatter)
        if isinstance(provided, Some):
            return provided.value
        capabilities = yield from TerminalCapabilities()
        return default_formatter(colors=capabilities.can_color)

    return gen(body)

layer

layer(formatter) -> Layer[CurrentFormatter]
ParameterTypeDescription
formatterFormatter

Returns Layer[CurrentFormatter]

def layer(formatter: Formatter) -> Layer[CurrentFormatter]:
    return layer_succeed(CurrentFormatter, formatter)

layer_presenter

layer_presenter(presenter) -> Layer[CurrentPresenter]
ParameterTypeDescription
presenterPresenter

Returns Layer[CurrentPresenter]

def layer_presenter(presenter: Presenter) -> Layer[CurrentPresenter]:
    return layer_succeed(CurrentPresenter, presenter)

display_width

display_width(text) -> int
ParameterTypeDescription
textstr

Returns int

def display_width(text: str) -> int:
    return sum(_grapheme_width(grapheme) for grapheme in _graphemes(strip_ansi(text)))