cmdr
Artifact Content
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2018 Conference, Houston/TX, US, Oct 15-19
Send your abstracts to tclconference@googlegroups.com
or submit via the online form by Aug 20.

Artifact b8481c4b9702e271eef26eb38492a42470263340:


[comment {-*- tcl -*- doctools manpage}]
[include parts/definitions.inc]
[vset VERSION 1]
[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 choose}], 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]