[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

# cmdr::ask(n) 1 doc "Cmdr, a framework for command line parsing and dispatch"

## Name

cmdr::ask - Cmdr - Terminal-based simple user interactions

## Table Of Contents

## Synopsis

- package require cmdr::color
- package require linenoise
- package require struct::matrix
- package require textutil::adjust
- package require try
- package require cmdr::ask

- ::cmdr::ask string query ?default?
- ::cmdr::ask string/extended query ?options...?
- ::cmdr::ask string* query
- ::cmdr::ask yn query ?default?
- ::cmdr::ask choose query choices ?default?
- ::cmdr::ask menu header prompt choices ?default?

## Description

Welcome to the Cmdr project, written by Andreas Kupries.

For availability please read Cmdr - How To Get The Sources.

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

## API

::cmdr::ask string query ?default?

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

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

  string query

    The prompt to show to the user before interaction begins.

  string default

    The default to return if the user enters nothing.

::cmdr::ask string/extended query ?options...?

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

  The accepted options are

  -history boolean

    If true, save user input into linenoise's in-memory history. Default is false.

  -hidden boolean

    If true, input is hidden. Default is false, visible echo.

  -complete cmdprefix

    If not empty, installed as completion callback.

  -default string

    If not empty the string to return if the user enters the empty string.

  string query

    The prompt to show to the user before interaction begins.

::cmdr::ask string* query

  Behaves like ::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.

  string query

    The prompt to show to the user before interaction begins.

::cmdr::ask yn query ?default?

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

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

  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.

  string query

    The prompt to show to the user before interaction begins.

  string default

    The default boolean to return if the user enters nothing.

::cmdr::ask choose query choices ?default?

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

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

  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.

  string query

    The prompt to show to the user before interaction begins.

  string default

    The default boolean to return if the user enters nothing.

::cmdr::ask menu header prompt choices ?default?

  Similar to ::cmdr::ask choose, except that the choices are shown as an enumerated menu, one per line, with a leading 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.

## Bugs, Ideas, Feedback

Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Cmdr Tickets.

Please also report any ideas you may have for enhancements of either package(s) and/or documentation.

## Keywords

arguments, command hierarchy, command line completion, command line handling, command tree, editing command line, help for command line, hierarchy of commands, interactive command shell, optional arguments, options, parameters, processing command line, tree of commands

## Copyright

Copyright © 2013-2016 Andreas Kupries
Copyright © 2013-2016 Documentation, Andreas Kupries