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

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

## Name

cmdr::parameter - Cmdr - (Partially internal) Command parameters

## Table Of Contents

## Synopsis

- package require cmdr::parameter

- ::cmdr::parameter new config order cmdline required defered name description spec
- ::cmdr::parameter create obj config order cmdline required defered name description spec
- <parameter> accept x
- <parameter> cmdline
- <parameter> code
- <parameter> complete-words parse
- <parameter> config word...
- <parameter> default
- <parameter> defered
- <parameter> description ?detail?
- <parameter> documented
- <parameter> dontinteract
- <parameter> flag
- <parameter> forget
- <parameter> generator
- <parameter> hasdefault
- <parameter> help
- <parameter> interactive
- <parameter> interact ?prompt?
- <parameter> isbool
- <parameter> is type
- <parameter> label
- <parameter> list
- <parameter> locker
- <parameter> lock reason
- <parameter> name
- <parameter> nopromote
- <parameter> options
- <parameter> ordered
- <parameter> presence
- <parameter> primary option
- <parameter> process detail queue
- <parameter> prompt
- <parameter> required
- <parameter> reset ?cleanup?
- <parameter> self
- <parameter> set?
- <parameter> setq queue
- <parameter> set value
- <parameter> string
- <parameter> threshold: n
- <parameter> threshold
- <parameter> type
- <parameter> undefined!
- <parameter> validator
- <parameter> value
- <parameter> when-complete
- <parameter> when-set

## Description

Welcome to the Cmdr project, written by Andreas Kupries.

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

This package implements parameters, collections of which (see cmdr::config) serve as the configuration of privates (see cmdr::private).

## Class API

The class API is not public. It is used internally by the framework when parsing a command hierarchy specification to create the necessary parameter instances.

It is described here for use by developers maintaining, modifying and extending the framework itself. A user of the framework has no need for it.

::cmdr::parameter new config order cmdline required defered name description spec

  Create an auto-named instance of cmdr::parameter.

  Not used.

::cmdr::parameter create obj config order cmdline required defered name description spec

  Create a new instance of cmdr::parameter, named obj. Used by the DSL processing parts of the framework to instantiate parameters.

  string obj

    The (command) name of the new parameter instance.

  cmdr::config config

    The instance command of the cmdr::config instance holding the parameter.

  boolean order

    Flag. Parameter is specified by order (true: argument), or name (false: option).

  boolean cmdline

    Flag. Parameter is visible on the command line (true: option, or argument), or not (false: state).

  boolean required

    Flag. Parameter is must be specified by the user at runtime (true), or not (false).

  boolean defered

    Flag. The internal representation is computed on-demand (true), or in the completion phase (false).

  string name

    Internal name of the parameter. Also the name used in the help, if not overridden by a label declaration (in spec).

  string description

    Human-readable help text for the parameter.

  script spec

    Tcl-script specifying the parameter in detail. Please read Cmdr - Parameter Specification Language for the details.

## Instance API

Most of the instance API is not public.

It is described here for use by developers maintaining, modifying and extending the framework itself. A user of the framework has no need for it.

<parameter> accept x

  This method validates the string value x against the validation type of the parameter and returns a boolean value indicating success (true), or not (false). The internal representation of x is not kept but released immediately. The parameter itself is not changed either. This is used during runtime by the 'test'-based processing of optional arguments.

  string x
<parameter> cmdline

  This accessor method returns the "cmdline" flag set during parameter construction. A result of true indicates that the parameter is visible on the command line (option, or argument), and otherwise (false) hidden (state).

<parameter> code

  This method returns a string encoding the flags "required" and "list". The mapping is as follows:

  +

    required, scalar

  ?

    optional, scalar

  +*

    required, list

  ?*

    optional, list.

<parameter> complete-words parse

  This method is part of the main shell command line completion. For the details of its workings please read Cmdr - Internals of command line completion.

  Given the completion state parse of a partial command line it returns a list of strings which are the valid completions at this point, for the parameter.

  dict parse

    A dictionary holding the current completion state of a partial command line.

<parameter> config word...

  This method either returns the cmdr::config instance containing the parameter, or the result of applying the words to that config instance. It is through this method that any script with access to a single parameter instance of a private will have access to all its parameters.

  string word...

    The method and its arguments to apply to the config instance holding the parameter. If none are specified the method self is implied, causing the return of the config instance itself.

<parameter> default

  This method returns the default value set by the parameter's specification, or the empty string.

<parameter> defered

  This accessor method returns the "defered" flag set during parameter construction. A result of true indicates that the parameter's internal representation is computed on-demand, and otherwise (false) during the completion phase.

<parameter> description ?detail?

  This method returns the parameter's help text. If the detail is specified and the name of an automatic option controlled by this parameter its implicit description is returned instead of the description of its primary.

  string detail

    Optional. The name of a automatic option controlled by the parameter.

<parameter> documented

  This accessor method returns the "documented" flag of the parameter. A value of true indicates that the parameter should be included in generated help, otherwise not.

<parameter> dontinteract

  This method disables interactive entry of the parameter's value for one time. I.e. after the information was used (see method value) the flag automatically resets. The result of the method is the empty string.

<parameter> flag

  This method returns the text of the primary flag of the parameter, including leading dashes.

<parameter> forget

  This method releases the internal representation of the parameter's value, if it has any. See also method reset for a stronger form.

<parameter> generator

  This method returns the "generate" command prefix callback, if it was set, and an empty list otherwise.

<parameter> hasdefault

  This method returns a boolean flag indicating if the parameter's specification declared a default value for it (true), or not (false).

<parameter> help

  This method returns the help information for the parameter. Note that this method does not check the "documented" flag of the parameter. That is the responsibility of the caller. The result of the command is a structure of the form described in section Help Information.

<parameter> interactive

  This method returns the "interactive" flag of the parameter. A result of true indicates that the parameter's string representation has to be queried interactively if no value was specified at runtime.

<parameter> interact ?prompt?

  This method interactively queries the string representation of the parameter from the user. If no prompt is specified the parameter's prompt from the specification is used. See also method prompt. The interaction takes the "list"-ness of the parameter into account. Note that the entered string(s) is/are validated and invalid information is rejected.

  string prompt

    Optional. The prompt to use for the interaction.

<parameter> isbool

  This method returns a boolean value indicating if the parameter uses the standard validation type "boolean" (true) or not (false). The parts of the parameter responsible for processing option arguments use this information to invoke the hard-wired special cases for this type, or not.

<parameter> is type

  This method returns a boolean value indicating if the parameter is of the specified type (true) or not (false).

  string type

    The type to check the parameter against. Recognized values are

    argument
    option
    state
<parameter> label

  This method returns the human-readable name of the parameter, for use in help. If not specifically overridden by the parameter's specification this is the same as the internal name (See method name).

<parameter> list

  This accessor method returns the "list" flag of the parameter. A value of true indicates that the parameter's value is a list, otherwise a scalar.

<parameter> locker

  This accessor method returns the string set by method lock below, or the empty string if lock was not used. Note: This information is reset by method reset, but not by forget.

<parameter> lock reason

  This method locks the parameter against modification by the methods set and setq, and remembers the reason for it. The reason is expected to be the name of another parameter whose use disallows the use of this one. Note: Such a lock is reset by method reset, but not by forget.

  string reason

    The name of the parameter locking this one against further modification.

<parameter> name

  This method returns the internal name of the parameter.

<parameter> nopromote

  This method returns the state of the non-promotion flag of the parameter.

<parameter> options

  This method returns the list of option flags recognized by the parameter.

<parameter> ordered

  This accessor method returns the "order" flag set during parameter construction. A result of true indicates that the parameter is specified by order at runtime (argument), and otherwise (false) by name (option).

<parameter> presence

  This method returns a boolean value indicating if the option parameter is set as presence-option (true) or not (false). The parts of the parameter responsible for processing option arguments use this information to invoke the hard-wired special cases for presence, or not.

<parameter> primary option

  This method returns a boolean value indicating if the named option is the primary option of this parameter (true), or not (false). An error will be thrown if the named option is not controlled by the parameter.

  string option

    The name of the option to check.

<parameter> process detail queue

  This method extracts the value of the parameter from the command line. A presence option takes nothing, whereas an isbool option takes the first value in the queue, if it is a proper boolean, and defaults to true if not. Any other argument or option takes the first value in queue.

  string detail

    The name of the parameter, or the option flag referencing it.

  struct::queue queue

    The queue instance holding the words of the command line not yet processed by the system.

<parameter> prompt

  This method returns the prompt string used by the parameter for interactive entry. If not overridden by the parameter's specification this defaults to a string derived from the internal name of the parameter, i.e. "Enter name:".

<parameter> required

  This accessor method returns the "required" flag set during parameter construction. A result of true indicates that the parameter must be specified by the user at runtime, and otherwise may be left unspecified (false).

<parameter> reset ?cleanup?

  This method sets the parameter into the initial state where it has neither string nor internal representation, nor is it locked. This is a stronger form of forget.

  boolean cleanup
<parameter> self

  This method returns the parameter instance itself.

<parameter> set?

  This accessor method returns a boolean value indicating if the parameter was given a string representation at runtime (true), or not (false).

<parameter> setq queue

  This method sets the first element of the queue as the value of the parameter. For a "list" parameter all elements of the queue are taken as the new value of the parameter. This is not quite analogous to method set below. They behave the same for scalar parameters, and differ for "list" parameters.

  stack::queue queue

    The queue instance holding the words of the command line not yet processed.

<parameter> set value

  This method sets the value as the new string representation of the parameter. For a "list" parameter the string representation is extended with the value. This action triggers the execution of the "when-set" callback. A previously existing internal representation is forgotten (See forget).

  string value

    The new value of the parameter, or an extension of the existing value.

<parameter> string

  This accessor method returns the string representation of the parameter. If such was not set an error will be thrown (See method undefined!).

<parameter> threshold: n

  This method specifies the minimum number of words needed after the optional argument parameter for it to accept the current word for itself. Parameters which are not optional arguments ignore this method. The result of the method is the empty string.

  integer n

    The acceptance threshold for the parameter.

<parameter> threshold

  This method returns the threshold set on the parameter. An empty string indicates a parameter without threshold. A value of -1 indicates that the optional argument accepts based on validation (See method accept) instead of using a threshold.

<parameter> type

  This accessor method returns the type of the parameter, one of argument, option, or state. See also method is for type-checking.

<parameter> undefined!

  This method explicitly throws a "parameter undefined" error for this parameter.

<parameter> validator

  This method returns the "validate" command prefix callback (i.e. the parameter's validation type).

<parameter> value

  This accessor method returns the internal representation of the parameter. If necessary the data is computed from the parameter's string representation, "default" value, or "generate" callback. An error is thrown if the value could not be determined. (See method undefined!). If the value is newly computed the action triggers the execution of the "when-complete" callback.

  A parameter asked for its internal representation goes through the following steps to deliver the value:

  1. If the internal representation is already known, simply deliver it as is. In other words, the result of the following steps is cached, and the steps are run only once.

  2. If the internal representation has been declared as undefined already, simply error out (again). This is still part of caching the result generated by the following steps.

  3. If the parameter has a string representation use the parameter's validation type to convert it to the proper internal representation, and return it.

  4. If interactive entry is possible (per the parameter's specification) perform the interaction. This saves the entered data as string representation which is then validated as per the previous step. Aborting the interaction leaves the parameter as undefined (which is thrown as error).

  5. If a generate callback exists use it to obtain the internal representation, and return it.

  6. If a default value exists make it the internal representation, and return it.

     Side note: As the parameter DSL only allows the declaration of one of default or generate only one of these steps can trigger.

  7. If the parameter is optional use the empty string as the internal representation and return it.

     Note that this rule should never trigger as the parameter DSL enforces that optional parameters always have one of default or generate.

  8. Leave the parameter is undefined and fail (throw an error).

<parameter> when-complete

  This method returns the "when-complete" command prefix callback, if it was set, and an empty list otherwise.

<parameter> when-set

  This method returns the "when-set" command prefix callback, if it was set, and an empty list otherwise.

## Help Information

The help information generated for parameters is a dictionary containing the keys below:

cmdline

  Output of method cmdline.

code

  Output of method code.

default

  Output of method default.

defered

  Output of method defered.

description

  Output of method description.

documented

  Output of method documented.

flags

  A dictionary mapping flag names to flag types, i.e. primary, alias, or inverted.

generator

  Output of method generator.

interactive

  Output of method interactive.

isbool

  Output of method isbool.

label

  Output of method label.

list

  Output of method list.

ordered

  Output of method ordered.

presence

  Output of method presence.

prompt

  Output of method prompt.

required

  Output of method required.

threshold

  Output of method threshold.

type

  Output of method type.

validator

  Output of method validator.

## 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