[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset LABEL_ASK] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr::color]
[require linenoise]
[require struct::matrix]
[require textutil::adjust]
[require try]
[require cmdr::ask]
[titledesc [vset TITLE_ASK]]
[description]
[include parts/welcome.inc]

This package provides a few utility commands implementing a few simple
terminal-based interactions with the user.

[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::ask] [method string] [arg query] [opt [arg default]]]

When invoked this command prompts the user with [arg query] for a string.
If the [arg default] is specified and not the empty string it is also
shown as part of the prompt. Note that [arg default] defaults to the
empty string.

[para] The interactively entered string is returned as the result of the
command. The [arg default] is returned as the result if the user entered
an empty string and the [arg default] is not empty.

[list_begin arguments]
[arg_def string query] The prompt to show to the user before interaction begins.
[arg_def string default] The default to return if the user enters nothing.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::ask] [method string/extended] [arg query] [opt options...]]

This command is similar to [cmd {::cmdr::ask string}], except it allows for
more customization of the interaction through options.

[para] The accepted options are
[list_begin options]
[opt_def -history  boolean]   If [const true], save user input into [package linenoise]'s in-memory history. Default is [const false].
[opt_def -hidden   boolean]   If [const true], input is hidden. Default is [const false], visible echo.
[opt_def -complete cmdprefix] If not empty, installed as completion callback.
[opt_def -default  string]    If not empty the string to return if the user enters the empty string.
[list_end]

[list_begin arguments]
[arg_def string query] The prompt to show to the user before interaction begins.
[list_end]


[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::ask] [method string*] [arg query]]

Behaves like [cmd {::cmdr::ask string}] without a default, except that the user's
input is not echoed back to the terminal. This command is for the entry of hidden
strings, i.e. passwords, and the like.

[list_begin arguments]
[arg_def string query] The prompt to show to the user before interaction begins.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::ask] [method yn] [arg query] [opt [arg default]]]

When invoked this command prompts the user with [arg query] for a [emph boolean]
value/string. If the [arg default] is specified and not the empty string it is
also shown as part of the prompt. Note that [arg default] defaults to the empty
string.

[para] The interactively entered boolean is returned as the result of the command.
The [arg default] boolean is returned as the result if the user entered an empty
string and the [arg default] is not empty.

[para] Note that the command will not return until the user entered a valid
boolean value. Entering a non-boolean string causes the command to loop internally
and re-prompt.

[list_begin arguments]
[arg_def string query] The prompt to show to the user before interaction begins.
[arg_def string default] The default boolean to return if the user enters nothing.
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::ask] [method choose] [arg query] [arg choices] [opt [arg default]]

When invoked this command prompts the user with [arg query] for one of the
[arg choices], entered as string. Prompt and input happen on a single line.

[para] The interactively entered choice is returned as the result of the command.
The [arg default] choice is returned as the result if the user entered an empty
string and the [arg default] is not empty.

[para] Note that the command will not return until the user entered a valid
choice. Entering a non-choice causes the command to loop internally and re-prompt.
The user is supported in entry by an internal completion callback.

[list_begin arguments]
[arg_def string query] The prompt to show to the user before interaction begins.
[arg_def string default] The default boolean to return if the user enters nothing.
[list_end]


[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::ask] [method menu] [arg header] [arg prompt] [arg choices] [opt [arg default]]

Similar to [cmd {::cmdr::ask choice}], except that the [arg choices] are shown
as an enumerated menu, one per line, with a leading [arg header].

Furthermore the command accepts not only the choices as input, but also their
numeric indices in the menu. The result however is always the relevant chosen string.

[list_end]
[include parts/feedback.inc]
[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset LABEL_COLOR] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require cmdr::tty]
[require cmdr::color]
[titledesc [vset TITLE_COLOR]]
[description]
[include parts/welcome.inc]

This package provides a few utility commands implementing
the management of terminal colors.

[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

When invoked this command 

[para] The ... is returned as the result of the command.

[list_begin arguments]
[arg_def list list] ...
[list_end]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::color] [method ...] ...]

[list_end]
[include parts/feedback.inc]
[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset LABEL_PAGER] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require linenoise]
[require cmdr::tty]
[require cmdr::pager]
[titledesc [vset TITLE_PAGER]]
[description]
[include parts/welcome.inc]

This package provides a single utility command to manage the automatic
paging of long output, like [vset PROJECT]'s automatic help.

[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::pager] [method text]]

When invoked this command either simply prints the [arg text] to stdout,
or invokes an external pager application to manage the output.

[para] The pager is only invoked when

[list_begin enumerated]
[enum] Stdout is a terminal, and
[enum] The text does not fit into the height of the terminal, and
[enum] a pager application could be found.
[list_end]

[para] If any of the above conditions fail the text is simply printed.

[para] When the command comes to the third condition above it will look
for the pager specified in the environment variable [const PAGER] first,
and then [const less] and [const more], in this order.

[list_begin arguments]
[arg_def string text]
The text to print or page.
[list_end]

[para] The result of the command is the empty string.

[list_end]
[include parts/feedback.inc]
[manpage_end]

[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[manpage_begin [vset LABEL_TTY] [vset MAN_SECTION] [vset VERSION]]
[include parts/module.inc]
[require Tclx]
[require cmdr::tty]
[titledesc [vset TITLE_TTY]]
[description]
[include parts/welcome.inc]

This package provides a single utility command testing if the
[const stdout] [term channel] is a tty or not, and reporting
the result.

[section API]
[list_begin definitions]
[comment {- - -- --- ----- -------- -------------}]
[call [cmd ::cmdr::tty] [method stdout]]

When invoked this command returns a boolean value indicating
if the [const stdout] [term channel] is a tty ([const true]),
or not ([const false]).

[list_end]
[include parts/feedback.inc]
[manpage_end]

[include configuration.inc]
[vset TITLE_INTRO    "[vset PTITLE] - Introduction to the project"]
[vset TITLE_LICENSE  "[vset PTITLE] - License"			 ]
[vset TITLE_CHANGES  "[vset PTITLE] - Log of Changes"    	 ]
[vset TITLE_SOURCES  "[vset PTITLE] - How To Get The Sources"	 ]
[vset TITLE_INSTALL  "[vset PTITLE] - The Installer's Guide"	 ]
[vset TITLE_DEV      "[vset PTITLE] - The Developer's Guide"	 ]

[comment {- Custom documents & titles - - -- --- ----- --------}]
[vset TITLE_MAIN          "[vset PTITLE] - Main package and API"]
[vset TITLE_ACTOR         "[vset PTITLE] - (Internal) Base class for officers and privates"]
[vset TITLE_ASK           "[vset PTITLE] - Terminal-based simple user interactions"]
[vset TITLE_COLOR         "[vset PTITLE] - Terminal colors"]
[vset TITLE_CONFIG        "[vset PTITLE] - (Partially internal) Collection of parameters for privates"]
[vset TITLE_DEV_COMPLETE  "[vset PTITLE] - Internals of command line completion"]
[vset TITLE_DEV_DSL       "[vset PTITLE] - Internals of DSL handling"]
[vset TITLE_DEV_HF        "[vset PTITLE] - Writing custom help formats"]
[vset TITLE_DEV_VT        "[vset PTITLE] - Writing custom validation types"]
[vset TITLE_DSL           "[vset PTITLE] - Introduction to the Specification Language"]
[vset TITLE_DSL_OFFICER   "[vset PTITLE] - Officer Specification Language"]
[vset TITLE_DSL_PRIVATE   "[vset PTITLE] - Private Specification Language"]
[vset TITLE_DSL_PARAMETER "[vset PTITLE] - Parameter Specification Language"]
[vset TITLE_HELP          "[vset PTITLE] - (Internal) Utilities for help text formatting and setup"]
[vset TITLE_HELP_JSON     "[vset PTITLE] - Formatting help as JSON object"]
[vset TITLE_HELP_SQL      "[vset PTITLE] - Formatting help as series of SQL commands"]
[vset TITLE_HELP_TCL      "[vset PTITLE] - Formatting help as Tcl data structure"]
[vset TITLE_OFFICER       "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."]
[vset TITLE_PAGER         "[vset PTITLE] - Paging long output"]
[vset TITLE_PARAMETER     "[vset PTITLE] - (Partially internal) Command parameters"]
[vset TITLE_PRIVATE       "[vset PTITLE] - (Internal) Single command handling, options, and arguments"]
[vset TITLE_TTY           "[vset PTITLE] - Check if stdin is a tty, i.e. terminal"]
[vset TITLE_UTIL          "[vset PTITLE] - (Internal) General Utilities"]
[vset TITLE_VALIDATE      "[vset PTITLE] - Standard validation types for parameters"]
[vset TITLE_VCOMMON       "[vset PTITLE] - Utilities for Validation Types"]
[vset TITLE_FLOW          "[vset PTITLE] - Runtime Processing Flow"]

[comment {- Miscellanea ............. - - -- --- ----- --------}]
[vset LABEL_INTRO         [vset PROJECT]-introduction]
[vset LABEL_LICENSE       [vset PROJECT]-license]
[vset LABEL_CHANGES       [vset PROJECT]-changes]
[vset LABEL_SOURCES       [vset PROJECT]-howto-get-sources]
[vset LABEL_INSTALL       [vset PROJECT]-installation]
[vset LABEL_DEV           [vset PROJECT]_development]

[vset LABEL_MAIN          [vset PROJECT]]
[vset LABEL_ACTOR         [vset PROJECT]::actor]
[vset LABEL_ASK           [vset PROJECT]::ask]
[vset LABEL_COLOR         [vset PROJECT]::color]
[vset LABEL_CONFIG        [vset PROJECT]::config]
[vset LABEL_DEV_COMPLETE  [vset PROJECT]_dev~completion]
[vset LABEL_DEV_DSL       [vset PROJECT]_dev~dsl]
[vset LABEL_HELPFORMATS   [vset PROJECT]-user-helpformats]
[vset LABEL_VTYPES        [vset PROJECT]-user-vtypes]
[vset LABEL_DSL           [vset PROJECT]-spec-dsl]
[vset LABEL_DSL_OFFICER   [vset PROJECT]-spec-dsl-officer]
[vset LABEL_DSL_PARAMETER [vset PROJECT]-spec-dsl-parameter]
[vset LABEL_DSL_PRIVATE   [vset PROJECT]-spec-dsl-private]
[vset LABEL_HELP          [vset PROJECT]::help]
[vset LABEL_HELP_JSON     [vset PROJECT]::help::json]
[vset LABEL_HELP_SQL      [vset PROJECT]::help::sql]
[vset LABEL_HELP_TCL      [vset PROJECT]::help::tcl]
[vset LABEL_OFFICER       [vset PROJECT]::officer]
[vset LABEL_PAGER         [vset PROJECT]::pager]
[vset LABEL_PARAMETER     [vset PROJECT]::parameter]
[vset LABEL_PRIVATE       [vset PROJECT]::private]
[vset LABEL_TTY           [vset PROJECT]::tty]
[vset LABEL_UTIL          [vset PROJECT]::util]
[vset LABEL_VALIDATE      [vset PROJECT]::validate]
[vset LABEL_VCOMMON       [vset PROJECT]::validate::common]
[vset LABEL_FLOW          [vset PROJECT]-spec-flow]