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#
| Attribute | Type | Description |
|---|---|---|
default_presenter | Presenter |
Types#
| Type | Definition | Description |
|---|---|---|
Event | type Event = Help | InvalidInvocation | Version | |
FlagSectionMode | type 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') -> FormatterThe 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.
| Parameter | Type | Description |
|---|---|---|
colors | bool | None = None | |
inherited_flags | FlagSectionMode = 'full' | |
global_flags | FlagSectionMode = '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]| Parameter | Type | Description |
|---|---|---|
formatter | Formatter |
Returns Layer[CurrentFormatter]
def layer(formatter: Formatter) -> Layer[CurrentFormatter]:
return layer_succeed(CurrentFormatter, formatter)layer_presenter#
layer_presenter(presenter) -> Layer[CurrentPresenter]| Parameter | Type | Description |
|---|---|---|
presenter | Presenter |
Returns Layer[CurrentPresenter]
def layer_presenter(presenter: Presenter) -> Layer[CurrentPresenter]:
return layer_succeed(CurrentPresenter, presenter)display_width#
display_width(text) -> int| Parameter | Type | Description |
|---|---|---|
text | str |
Returns int
def display_width(text: str) -> int:
return sum(_grapheme_width(grapheme) for grapheme in _graphemes(strip_ansi(text)))