ADDED doc/cmdr_dev_completion.man Index: doc/cmdr_dev_completion.man ================================================================== --- /dev/null +++ doc/cmdr_dev_completion.man @@ -0,0 +1,24 @@ +[comment {-*- tcl -*- doctools manpage}] +[include parts/definitions.inc] +[manpage_begin [vset PROJECT]_completion [vset MAN_SECTION] [vset VERSION]] +[include parts/module.inc] +[require cmdr] +[titledesc [vset TITLE_DEV_COMPLETE]] +[description] +[include parts/welcome.inc] + +This internal document provides an overview on how the framework +performs command-line completion in both the main and mini shells, +referencing all the relevant methods and describing the data +structures in use. + +[para] For more information about other internals of the framework +please read [term [vset TITLE_DEV]]. + +[section {Code Overview}] [include parts/completion_methods.inc] +[section {Parse State}] [include parts/completion_state.inc] +[section {Main Shell Operation}] [include parts/completion_main.inc] +[section {Mini Shell Operation}] [include parts/completion_mini.inc] + +[include parts/feedback.inc] +[manpage_end] Index: doc/cmdr_howto_development.man ================================================================== --- doc/cmdr_howto_development.man +++ doc/cmdr_howto_development.man @@ -57,54 +57,57 @@ [vset PTITLE] (currently) does not have demonstrations, nor examples. [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Directory structure}] -Explain the physical layout (directory structure). +The directory structure of the sources is as explained below: [list_begin definitions] - [include parts/layout_standard.inc] -[def [file actor.tcl]] == Package [package cmdr::actor]. -[def [file cmdr.tcl]] == Package [package cmdr]. -[def [file config.tcl]] == Package [package cmdr::config]. -[def [file help.tcl]] == Package [package cmdr::help]. -[def [file help_json.tcl]] == Package [package cmdr::help::json]. -[def [file help_sql.tcl]] == Package [package cmdr::help::sql]. -[def [file officer.tcl]] == Package [package cmdr::officer]. -[def [file parameter.tcl]] == Package [package cmdr::parameter]. -[def [file private.tcl]] == Package [package cmdr::private]. -[def [file util.tcl]] == Package [package cmdr::util]. -[def [file validate.tcl]] == Package [package cmdr::validate]. -[def [file vcommon.tcl]] == Package [package cmdr::validate::common]. - +[def [file actor.tcl]] Package [package cmdr::actor]. +[def [file cmdr.tcl]] Package [package cmdr]. +[def [file config.tcl]] Package [package cmdr::config]. +[def [file help.tcl]] Package [package cmdr::help]. +[def [file help_json.tcl]] Package [package cmdr::help::json]. +[def [file help_sql.tcl]] Package [package cmdr::help::sql]. +[def [file officer.tcl]] Package [package cmdr::officer]. +[def [file parameter.tcl]] Package [package cmdr::parameter]. +[def [file private.tcl]] Package [package cmdr::private]. +[def [file util.tcl]] Package [package cmdr::util]. +[def [file validate.tcl]] Package [package cmdr::validate]. +[def [file vcommon.tcl]] Package [package cmdr::validate::common]. [list_end] +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Extended Build Actions}] - [include parts/build-dev.inc] [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [section {Architecture & Concepts}] -The following sections explain - -[list_begin enumerated] -[enum] the internal architecture and package dependencies. -[enum] the internal data structures. -[enum] important operation sequences (UML SD). -[list_end] - -[subsection {System Architecture}] [include parts/architecture.inc] -[comment { @EDIT Package dependencies (diagram) }] - -[subsection {Data structures}] -[comment { @EDIT Explain data structures }] - -[subsection {Operation Sequences}] -[comment { @EDIT Explain operation sequences }] - + +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] +[section {Validation Types}] + +Everything said in the public document [term [vset TITLE_DEV_VT]] +applies to the standard validation types of the framework (as listed +in [term [vset TITLE_VALIDATE]]) as well. + +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] +[section {Help Formats}] + +Everything said in the public document [term [vset TITLE_DEV_HF]] +applies to the standard help formats of the framework (as listed in +[term [vset TITLE_HELP_STD]]) as well. + +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] +[section {Command Line Completion}] + +The document [term [vset TITLE_DEV_COMPLETE]] describes the inner +workings of the command line completion provided by the framework. + +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@] [include parts/related.inc] [include parts/feedback.inc] [manpage_end] DELETED doc/complete.man Index: doc/complete.man ================================================================== --- doc/complete.man +++ /dev/null @@ -1,208 +0,0 @@ -[comment {-*- tcl -*- doctools manpage}] -[include parts/definitions.inc] -[manpage_begin [vset PROJECT] [vset MAN_SECTION] [vset VERSION]] -[include parts/module.inc] -[require cmdr] -[titledesc [vset TITLE_COMPLETE]] -[description] -[include parts/welcome.inc] - -This internal document describes how the framework performs -command-line completion, in both main and mini shells, plus the -relevant data structures and methods. - -[para] For more information about the framework's internals please -read [term [vset TITLE_DEV]]. - -[comment {************************************************************}] -[section {Main Shell}] - -[package cmdr::officer] implements the [term {main shell}]. - -[para] This shell accepts the names of all sub-ordinate commands known -to the officer as commands. - -[para] It may additional accept a hard-wired command [cmd .exit], -depending on the parse state (see flag [const doexit]). - - -[para] The main shell's repl core calls on the instance method -[method complete] for command-line completion. - -[para] This method uses the standard [method parse-line] method of its -own [package cmdr::actor] base-class to get the standard parsing -structure used within the framework and then delegates to the instance -method [method complete-words]. - -[para] Note: The details of the state structure generated by -[method parse-line] and then taken by [method complete-words] are -explained in section [sectref {Parse State}]. Read it before trying to -follow the rules. - -[para] [method complete-words] then applies the following rules: - - -[list_begin enumerated] - -[enum] In case of syntax error return an empty list (no completion). - -[enum] For an empty command line return all commands, and all commands - known to the default subordinate, if any. - -[enum] If the [term {current word}] (as per [const at]) is not the - last word, treat it as the name of the sub-ordinate command - responsible for handling the remaining words and delegate - completion to it, advancing the current word as needed. - -[para] No completion is done if the word does not yield a command to - delegate to (unknown or ambigous). If a default command is known - this case will delegate to that. - -[para] When recursing in this way the subordinate command will see - "[const doexit] == [const false]". - -[para] If the subordinate is again an officer it will proceed - using this same set of rules. A [term private] on the other - hand has its own set of rules, explained below. - -[enum] If the [term {current word}] is the last word on the command - line then completion is done using the set of commands known - to the officer and its default sub-ordinate, if any. - - No recursion takes place. -[list_end] - -[para] When the recursion described above enters a [term private] -command the recursion ends and all remaining arguments are processed -to determine the set of parameters responsible for completion of the -last word. - -[para] This is similar to the argument parsing done ... todo ... - - -[comment { @ EDIT: --- todo --- sequence diagram main shell completion }] - - -[comment {************************************************************}] -[section {Mini Shell}] - -[package cmdr::config] implements the [term {mini shell}]. - -[para] This shell accepts the [term system] names of all parameters -held by the config instance as commands, all taking a single value as -their argument, the string value of the parameter indicated by the -command name itself. - -[para] It additional accepts five hard-wired commands to control exit -conditions and access to help. - -These commands all start with a [const .] and do not take any -arguments at all. They are, in alphabetical order, [const .cancel], -[const .exit], [const .help] [const .ok], and [const .run]. - -[para] The mini shell's repl core calls on the instance method -[method complete] for command-line completion. - -[para] This method uses the standard [method parse-line] method of the -[package cmdr::actor] base-class of the context (a -[package cmdr::private] instance) to get the standard parsing -structure used within the framework and then delegates to the instance -method [method complete-repl]. - -[para] [method complete-rel] then applies the following rules: - -[list_begin enumerated] - -[enum] In case of syntax error return an empty list (no completion). - -[enum] For an empty command line return all commands. - -[enum] For a partial single word return all matching commands. - -[enum] For a command containing more than two words no further - completion is possible, return an empty list. - -[enum] After a full single word delegate completion to the - [package cmdr::parameter] instance indicated by the - first word and return its results. The relevant - method is [method complete-words]. - -[para] No completion is done if the first word does not yield - a parameter to delegate to (unknown or ambigous), or - if it is a presence option, which does not take an argument. - -[para] The parameter essentially only extracts the word to complete - from the state structure and then delegates to the validation - type (method [method complete]) for actual completion. - -[list_end] - -[para] Note: The details of the state structure generated by -[method parse-line] and then taken by [method complete-repl] are -explained in section [sectref {Parse State}]. - -[comment { @ EDIT: --- todo --- sequence diagram mini shell completion }] - - -[comment {************************************************************}] -[section {Parse State}] - -The state structure used by all methods relevant to command line -completion is a dictionary containing the six keys list below. - -Its only generator is method [method parse-line] of base-class -[package cmdr::actor], all others parts of the system then only read -and manipulate it. - -[list_begin definitions] -[def [const ok]] -A boolean flag. [const true] indicates that the [const line] parsed -sucessfully into words. [const false] indicates a syntax error. - -[para] The framework expects basic shell syntax with space-separated -words using single- and double-quotes for words containing whitespace -themselves. Note that complex syntax like variable- and -command-substitutions are not allowed. - -[def [const line]] -A copy of the unparsed command line. - -[def [const words]] - -The command [const line] parsed into the bare words. The data is not -valid if [const ok] indicates a parsing error. This is not a list of -strings, but actually a list of tokens. - -[para] Each token is a list of four elements containing, in the order -below: - -[list_begin enumerated] -[enum] Type of the token (implicitly specifies found quoting). -[enum] Start index of token in [const line] including quoting. -[enum] End index of token in [const line], including quoting. -[enum] The string value of the token, with escapes fully resolved. - I.e. the actual word. -[list_end] - -[para] Note: If [const line] ended in trailing whitespace the last -element of this list will be an empty string representing the word -started by the user, yet still empty. - -[def [const nwords]] -The number of element in [const words]. The data is not valid if -[const ok] indicates a parsing error. - -[def [const at]] -The index of the [term {current word}] in [const words] currently -considered by the completion code. Initially [const 0] this advances -as the completion code works through the prefix to determine the -context for the completion of the last word. - -[def [const doexit]] -A boolean flag. Indicates if the pseudo-command [cmd .exit] is active -([const true]), or not. Initially [const true]. - -[list_end] - -[include parts/feedback.inc] -[manpage_end] ADDED doc/figures/dsl_umlsequence.inc Index: doc/figures/dsl_umlsequence.inc ================================================================== --- /dev/null +++ doc/figures/dsl_umlsequence.inc @@ -0,0 +1,80 @@ +# -*- tcl -*- tcl.tk//DSL diagram//EN//1.0 +## ==================================================================== +## UML sequence diagram DSL, assembly level. + +# Should have a grid parameter the others are based on. + +set boxheight [10 mm] +set boxwidth [30 mm] +set movelength [10 mm] + +proc actor {code n {w {}}} { + global $code + if {$w eq ""} { + upvar 1 boxwidth bw + set w $bw + } + box "$n" width $w + group { down ; line } + move to [by [5 mm] e] + set $code [last line end] + return +} + +proc skip {code} { + global $code + group { down ; line from [set $code] } + set $code [last line end] + return +} + +proc action {code args} { + global $code a$code + box fillcolor white {*}$args with north at [set $code] width [3 mm] height [10 mm] + set $code [last box south] + set a$code [last box] + return +} + +proc label {code text} { + global a$code + text text $text with sw at [[set a$code] ne] + return +} + +proc call-up {from to label} { + global a$from a$to + arrow from [[set a$from] w] to [[set a$to] e] stroke 2 + text $label with sw at [[last arrow end] by [2 mm] e] + return +} + +proc call-down {from to label} { + global a$from a$to + arrow from [[set a$from] e] to [[set a$to] w] stroke 2 + text $label with se at [[last arrow end] by [2 mm] w] + return +} + +proc return-down {from to label} { + global a$from a$to + arrow from [[set a$from] e] to [[set a$to] w] dotted + text $label with sw at [[last arrow start] by [2 mm] e] + return +} + +proc return-up {from to label} { + global a$from a$to + arrow from [[set a$from] w] to [[set a$to] e] dotted + text $label with se at [[last arrow start] by [2 mm] w] + return +} + +proc stop {code} { + global $code + skip $code + circle with center at [set $code] radius [1 mm] fillcolor black + return +} + +## ==================================================================== ADDED doc/figures/main-shell.dia Index: doc/figures/main-shell.dia ================================================================== --- /dev/null +++ doc/figures/main-shell.dia @@ -0,0 +1,93 @@ +# -*- tcl -*- tcl.tk//DSL diagram//EN//1.0 +## DSL for uml sequences. Draft. + +source [file join [file dirname [file normalize [info script]]] dsl_umlsequence.inc] + +## ==================================================================== + +actor kn "known" [20 mm] +actor kv "kinetcl::Valid" +actor cb "BASE" [20 mm] +actor cv "kinetcl_validate" [35 mm] +actor cf "framesync" [25 mm] +actor co "context" [20 mm] + +action cf +label cf can-sync-with(node) +action cv +call-up cf cv "invoke" +action kv +call-up cv kv "invoke" +action kn +call-up kv kn "dict exists" + +action kn +action kv +return-down kn kv true + +skip cb +action cb +call-down kv cb "@mark" + +skip co +action co +call-down cb co "save handle" + +action co +action cb +return-up co cb "" +action kv +return-up cb kv "" + +action kv +action cv dashed fillcolor {} +action cv dashed fillcolor {} +action cv +return-down kv cv "TCL_OK" +action co +call-down cv co "get handle" +action co +action cv +return-up co cv "handle" + +action cv +action cf dashed fillcolor {} +action cf dashed fillcolor {} +action cf dashed fillcolor {} +action cf dashed fillcolor {} +action cf +return-down cv cf "TCL_OK, handle" + +# sync heights... + +skip co +skip cb +skip cb +skip cb +skip kv +skip kv +skip kn +skip kn +skip kn +skip kn +stop co +stop cb +stop cf +stop cv +stop kv +stop kn + +# close timelines + +line \ + from [$kn by [10 mm] w] \ + to [$co by [10 mm] e] + +# outside annotation ... need symbolic locations. + +set p [[0.5 between [2nd box ne] [3rd box nw]] by [5 mm] n] +line dashed \ + from $p \ + to [[$p | $cb] by [5 mm] down] +text text C with w at [last line start] +text text Tcl with e at [last line start] ADDED doc/figures/mini-shell.dia Index: doc/figures/mini-shell.dia ================================================================== --- /dev/null +++ doc/figures/mini-shell.dia @@ -0,0 +1,93 @@ +# -*- tcl -*- tcl.tk//DSL diagram//EN//1.0 +## DSL for uml sequences. Draft. + +source [file join [file dirname [file normalize [info script]]] dsl_umlsequence.inc] + +## ==================================================================== + +actor kn "known" [20 mm] +actor kv "kinetcl::Valid" +actor cb "BASE" [20 mm] +actor cv "kinetcl_validate" [35 mm] +actor cf "framesync" [25 mm] +actor co "context" [20 mm] + +action cf +label cf can-sync-with(node) +action cv +call-up cf cv "invoke" +action kv +call-up cv kv "invoke" +action kn +call-up kv kn "dict exists" + +action kn +action kv +return-down kn kv true + +skip cb +action cb +call-down kv cb "@mark" + +skip co +action co +call-down cb co "save handle" + +action co +action cb +return-up co cb "" +action kv +return-up cb kv "" + +action kv +action cv dashed fillcolor {} +action cv dashed fillcolor {} +action cv +return-down kv cv "TCL_OK" +action co +call-down cv co "get handle" +action co +action cv +return-up co cv "handle" + +action cv +action cf dashed fillcolor {} +action cf dashed fillcolor {} +action cf dashed fillcolor {} +action cf dashed fillcolor {} +action cf +return-down cv cf "TCL_OK, handle" + +# sync heights... + +skip co +skip cb +skip cb +skip cb +skip kv +skip kv +skip kn +skip kn +skip kn +skip kn +stop co +stop cb +stop cf +stop cv +stop kv +stop kn + +# close timelines + +line \ + from [$kn by [10 mm] w] \ + to [$co by [10 mm] e] + +# outside annotation ... need symbolic locations. + +set p [[0.5 between [2nd box ne] [3rd box nw]] by [5 mm] n] +line dashed \ + from $p \ + to [[$p | $cb] by [5 mm] down] +text text C with w at [last line start] +text text Tcl with e at [last line start] ADDED doc/parts/completion_main.inc Index: doc/parts/completion_main.inc ================================================================== --- /dev/null +++ doc/parts/completion_main.inc @@ -0,0 +1,108 @@ + +[comment ==============================================================] +[subsection Overview] + +The [term {main shell}] is fully implemented within the package +[package cmdr::officer], while its command-line completion also +reaches into the packages [package cmdr::private], +[package cmdr::config], and [package cmdr::parameter]. + +The purpose of this shell is interactive access to the commands of an +officer. Which implies, for the toplevel officer, access to the entire +command hierarchy. + +[para] To this end this shell accepts the names of all subordinate +commands known to the officer as commands. + +[para] It may additional accept a hard-wired command [cmd .exit], +depending on the parse state (see flag [const doexit]). + + +[comment ==============================================================] +[subsection {Sequencing and Rules}] + +This section is in essence the textual description of an UML sequence +diagram. + +[para] Note that the state structure used by this code and referenced +in the text is explained in section [sectref {Parse State}]. + +[list_begin enumerated] + +[enum] The main shell's core read-eval-print-loop calls on the +instance method [method complete] for command-line completion, +providing the text of the buffer to complete at the end). + +[enum] The method [package cmdr::actor]::[method parse-line] is called +on first, to get a parse of the buffer. This parse is then delegated +to the instance method [method complete-words] to perform the bulk of +the work. + +[para] Note: The officer instance has access to [method parse-line] +because it is a derived class of [package cmdr::actor]. + +[enum] The implementation of method [method complete-words] applies +the rules below: + +[list_begin enumerated] + +[enum] If the buffer was not properly parsed (i.e. the state indicates +a syntax error), the list of completions is empty. + +[enum] When the buffer is empty all commands are possible completions, +as are all the commands of the default subordinate, if any was +specified. + +[enum] If the [term {current word}] (as per [const at]) is the last +word (per [const nwords]) on the command line then completion is done +using the set of commands known to the officer and its default +subordinate, if any. + +[enum] For a [term {current word}] which is not the last, i.e. at the +beginning or in the middle of the command line instead, then this word +is the name of the subordinate object responsible for handling the +remaining words. + +[para] No completion is done however if the current word does not +yield a subordinate to delegate to (i.e. unknown or ambigous). If a +default command is known this case will delegate to this subordinate, +as a last attempt. + +[para] When a subordinate was found the system advances the current +word, resets the [const doexit] flag, and lastly invokes the method +[method complete-words] of the sub-ordinate. + +[enum] When the subordinate is again an [term officer], these rules +here apply again. + +[enum] A [term private] however will delegate to the embedded +[package cmdr::config] instance, again using the method +[method complete-words]. + +[enum] This method processes the remaining words similar to how the +command line is parsed at runtime to match words to parameters, to +know at the end which (set of) parameter(s) governs the last word. + +[para] For [term options] the last word may be partial name of a flag, +or it may be the partial argument to an option. + +In case of the first the set of completions is the set of all flags +with the word as its prefix. + +In case of the second the completion delegates to the parameter +governing the flag, if there is any, which in turn delegates to its +associated validation type. + +[para] For [term inputs] the system essentially steps through a +non-deterministic finite automaton to find all the parameters which +may govern the current word. Completion is done as the union of the +completion done by the individual parameters. + +[para] Note that the automaton and its results can be precomputed, +this happens in the internal method [method CompletionGraph]. + +[list_end] + +[list_end] + +[comment { @ EDIT: --- todo --- sequence diagram main shell completion }] ADDED doc/parts/completion_methods.inc Index: doc/parts/completion_methods.inc ================================================================== --- /dev/null +++ doc/parts/completion_methods.inc @@ -0,0 +1,78 @@ + +The methods relevant to command-line completion can be found in four +packages/classes, namely: + +[list_begin definitions] +[def [package cmdr::actor]] + [list_begin definitions] + [def [method parse-line]] + Takes a command-line and returns an initial parse structure as + described in section [sectref {Parse State}] + + [def [method completions]] + [def [method match]] + [list_end] + +[def [package cmdr::config]] + [list_begin definitions] + [def [method complete]] + Hook method, entrypoint for the mini-shell. + + Takes the buffer to complete and returns the list of completions, + which may be empty. + + Uses the workhorse method below and the [package cmdr::actor] + methods. + + [def [method complete-repl]] + Main work method taking a parse structure and returning the list + of completions. More details about it (and the mini-shell) can be + found in section [sectref {Mini Shell Operation}]. + + [def [method complete-words]] + Main work method for completion from the main shell, invoked by + the [package cmdr::private] instance having to complete words. + + [list_end] + +[def [package cmdr::officer]] + [list_begin definitions] + [def [method complete]] + + Hook method, entrypoint for the main shell. + + Takes the buffer to complete and returns the list of completions, + which may be empty. + + Uses the workhorse method below and the [package cmdr::actor] + methods. + + [def [method complete-words]] + Main work method taking a parse structure and returning the list + of completions. More details about it (and the main shell) can be + found in section [sectref {Main Shell Operation}]. + + [para] Can recurse to the same method of other officers, and + private instances. + + [list_end] + +[def [package cmdr::parameter]] + [list_begin definitions] + [def [method complete-words]] + Main work method when reaching a parameter. + + Simply delegates the work to the method [method complete] of the + validation type associated with the parameter. + [list_end] + +[def [package cmdr::private]] + [list_begin definitions] + [def [method complete-words]] + Main work method when reaching a private while recursing through + the command hierarchy from officers. + + Delegates to the [package cmdr::config] method of the same name. + + [list_end] +[list_end] ADDED doc/parts/completion_mini.inc Index: doc/parts/completion_mini.inc ================================================================== --- /dev/null +++ doc/parts/completion_mini.inc @@ -0,0 +1,84 @@ + +[comment ==============================================================] +[subsection Overview] + +The [term {mini shell}] and its command-line completion is fully +implemented within the package [package cmdr::config]. + +The purpose of this shell is the interactive entry of the parameters +for a [term private]. + +[para] To this end this shell accepts the [term system] names of all +parameters held by the config instance as commands, plus five +hard-wired commands to control exit conditions and access to help. + +[para] The parameter commands all take single value as their argument, +the string value to set. + +The sole exception to this are [term {presence options}] which do not +take any argument. + +[para] Similarly none of the hardwired commands take an +argument. Their names all start with a [const .]. They are, in +alphabetical order, [const .cancel], [const .exit], [const .help] +[const .ok], and [const .run]. + +[comment ==============================================================] +[subsection {Sequencing and Rules}] + +This section is in essence the textual description of an UML sequence +diagram. + +[para] Note that the state structure used by this code and referenced +in the text is explained in section [sectref {Parse State}]. + +[list_begin enumerated] + +[enum] The mini shell's core read-eval-print-loop calls on the +instance method [method complete] for command-line completion, +providing the text of the buffer to complete at the end). + +[enum] The method [package cmdr::actor]::[method parse-line] is called +on first, to get a parse of the buffer. This parse is then delegated +to the instance method [method complete-repl] to perform the bulk of +the work. + +[para] Note: The config instance has access to [method parse-line] +through its internal [const context] command, which is an alias of the +[package cmdr::private] instance the configuration belongs to. This +class is derived from [package cmdr::actor]. + +[enum] The implementation of method [method complete-repl] applies the +rules below: + +[list_begin enumerated] +[enum] If the buffer was not properly parsed (i.e. the state indicates +a syntax error), the list of completions is empty. + +[enum] When the buffer is empty all commands are possible completions. + +[enum] When the buffer contains more than three words the list of +completions is empty, as all valid mini-shell commands consist of at +most two words. + +[enum] A buffer containing a single word contain a partial command +name and the list of completions is the set of commands having this +word as prefix. + +[enum] A buffer containing two words contains a command name and a +partial argument. Completion is delegated to the parameter (method +[package cmdr::parameter]::[method complete-words]) indicated by the +command name, and through it to the associated validation type. + +[para] No completion is done however if the first word does not yield +a parameter to delegate to (i.e. unknown or ambigous), or if it is a +presence option, which does not take an argument. + +[para] The hardwired commands fall here implicitly under unknown +parameter. + +[list_end] +[list_end] + +[comment { @ EDIT: --- todo --- sequence diagram mini shell completion }] + ADDED doc/parts/completion_state.inc Index: doc/parts/completion_state.inc ================================================================== --- /dev/null +++ doc/parts/completion_state.inc @@ -0,0 +1,57 @@ + +The state structure used by all methods relevant to command line +completion is a dictionary containing the six keys listed below. + +The only generator for this structure is method [method parse-line] of +the base-class [package cmdr::actor]. All others parts of the system +then only read and manipulate it. + +[list_begin definitions] +[def [const ok]] +A boolean flag. Indicates if the [const line] parsed sucessfully into +words ([const true]), or not ([const false], syntax error). + +[para] The framework expects basic shell syntax with space-separated +words using single- and double-quotes for words containing whitespace +themselves. Note that complex syntax like variable- and +command-substitutions are not allowed. + +[def [const line]] +A copy of the unparsed command line. + +[def [const words]] + +The command [const line] parsed into the bare words. The data is not +valid if [const ok] indicates a parsing error. This is not a list of +strings, but actually a list of tokens. + +[para] Each token is a list of four elements containing, in the order +below: + +[list_begin enumerated] +[enum] Type of the token (implicitly specifies found quoting). +[enum] Start index of token in [const line] including quoting. +[enum] End index of token in [const line], including quoting. +[enum] The string value of the token, with escapes fully resolved. + I.e. the actual word. +[list_end] + +[para] Note: If [const line] ended in trailing whitespace the last +element of this list will be an empty string representing the word +started by the user, yet still empty. + +[def [const nwords]] +The number of element in [const words]. The data is not valid if +[const ok] indicates a parsing error. + +[def [const at]] +The index of the [term {current word}] in [const words] currently +considered by the completion code. Initially [const 0] this advances +as the completion code works through the prefix to determine the +context for the completion of the last word. + +[def [const doexit]] +A boolean flag. Indicates if the pseudo-command [cmd .exit] is active +([const true]), or not. Initially [const true]. + +[list_end] Index: doc/parts/definitions.inc ================================================================== --- doc/parts/definitions.inc +++ doc/parts/definitions.inc @@ -5,25 +5,27 @@ [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_CONFIG "[vset PTITLE] - (Partially internal) Collection of parameters for privates"] -[vset TITLE_DEV_HF "[vset PTITLE] - Writing custom help formats"] -[vset TITLE_DEV_VT "[vset PTITLE] - Writing custom validation types"] +[vset TITLE_MAIN "[vset PTITLE] - Main package and API"] +[vset TITLE_ACTOR "[vset PTITLE] - (Internal) Base class for officers and privates"] +[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_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_OFFICER "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."] -[vset TITLE_PARAMETER "[vset PTITLE] - (Partially internal) Command parameters"] -[vset TITLE_PRIVATE "[vset PTITLE] - (Internal) Single command handling, options, and arguments"] -[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_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_STD "[vset PTITLE] - Standard help formats of the framework"] +[vset TITLE_HELP_SQL "[vset PTITLE] - Formatting help as series of SQL commands"] +[vset TITLE_OFFICER "[vset PTITLE] - (Internal) Aggregation of multiple commands for dispatch."] +[vset TITLE_PARAMETER "[vset PTITLE] - (Partially internal) Command parameters"] +[vset TITLE_PRIVATE "[vset PTITLE] - (Internal) Single command handling, options, and arguments"] +[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"] [comment {- Miscellanea ............. - - -- --- ----- --------}] ADDED embedded/man/files/cmdr_dev_completion.n Index: embedded/man/files/cmdr_dev_completion.n ================================================================== --- /dev/null +++ embedded/man/files/cmdr_dev_completion.n @@ -0,0 +1,569 @@ +'\" +'\" Generated from file 'cmdr_dev_completion\&.man' by tcllib/doctools with format 'nroff' +'\" Copyright (c) 2013 Andreas Kupries +'\" Copyright (c) 2013 Documentation, Andreas Kupries +'\" +'\" The definitions below are for supplemental macros used in Tcl/Tk +'\" manual entries. +'\" +'\" .AP type name in/out ?indent? +'\" Start paragraph describing an argument to a library procedure. +'\" type is type of argument (int, etc.), in/out is either "in", "out", +'\" or "in/out" to describe whether procedure reads or modifies arg, +'\" and indent is equivalent to second arg of .IP (shouldn't ever be +'\" needed; use .AS below instead) +'\" +'\" .AS ?type? ?name? +'\" Give maximum sizes of arguments for setting tab stops. Type and +'\" name are examples of largest possible arguments that will be passed +'\" to .AP later. If args are omitted, default tab stops are used. +'\" +'\" .BS +'\" Start box enclosure. From here until next .BE, everything will be +'\" enclosed in one large box. +'\" +'\" .BE +'\" End of box enclosure. +'\" +'\" .CS +'\" Begin code excerpt. +'\" +'\" .CE +'\" End code excerpt. +'\" +'\" .VS ?version? ?br? +'\" Begin vertical sidebar, for use in marking newly-changed parts +'\" of man pages. The first argument is ignored and used for recording +'\" the version when the .VS was added, so that the sidebars can be +'\" found and removed when they reach a certain age. If another argument +'\" is present, then a line break is forced before starting the sidebar. +'\" +'\" .VE +'\" End of vertical sidebar. +'\" +'\" .DS +'\" Begin an indented unfilled display. +'\" +'\" .DE +'\" End of indented unfilled display. +'\" +'\" .SO +'\" Start of list of standard options for a Tk widget. The +'\" options follow on successive lines, in four columns separated +'\" by tabs. +'\" +'\" .SE +'\" End of list of standard options for a Tk widget. +'\" +'\" .OP cmdName dbName dbClass +'\" Start of description of a specific option. cmdName gives the +'\" option's name as specified in the class command, dbName gives +'\" the option's name in the option database, and dbClass gives +'\" the option's class in the option database. +'\" +'\" .UL arg1 arg2 +'\" Print arg1 underlined, then print arg2 normally. +'\" +'\" RCS: @(#) $Id: man.macros,v 1.1 2009/01/30 04:56:47 andreas_kupries Exp $ +'\" +'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. +.if t .wh -1.3i ^B +.nr ^l \n(.l +.ad b +'\" # Start an argument description +.de AP +.ie !"\\$4"" .TP \\$4 +.el \{\ +. ie !"\\$2"" .TP \\n()Cu +. el .TP 15 +.\} +.ta \\n()Au \\n()Bu +.ie !"\\$3"" \{\ +\&\\$1 \\fI\\$2\\fP (\\$3) +.\".b +.\} +.el \{\ +.br +.ie !"\\$2"" \{\ +\&\\$1 \\fI\\$2\\fP +.\} +.el \{\ +\&\\fI\\$1\\fP +.\} +.\} +.. +'\" # define tabbing values for .AP +.de AS +.nr )A 10n +.if !"\\$1"" .nr )A \\w'\\$1'u+3n +.nr )B \\n()Au+15n +.\" +.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n +.nr )C \\n()Bu+\\w'(in/out)'u+2n +.. +.AS Tcl_Interp Tcl_CreateInterp in/out +'\" # BS - start boxed text +'\" # ^y = starting y location +'\" # ^b = 1 +.de BS +.br +.mk ^y +.nr ^b 1u +.if n .nf +.if n .ti 0 +.if n \l'\\n(.lu\(ul' +.if n .fi +.. +'\" # BE - end boxed text (draw box now) +.de BE +.nf +.ti 0 +.mk ^t +.ie n \l'\\n(^lu\(ul' +.el \{\ +.\" Draw four-sided box normally, but don't draw top of +.\" box if the box started on an earlier page. +.ie !\\n(^b-1 \{\ +\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.el \}\ +\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' +.\} +.\} +.fi +.br +.nr ^b 0 +.. +'\" # VS - start vertical sidebar +'\" # ^Y = starting y location +'\" # ^v = 1 (for troff; for nroff this doesn't matter) +.de VS +.if !"\\$2"" .br +.mk ^Y +.ie n 'mc \s12\(br\s0 +.el .nr ^v 1u +.. +'\" # VE - end of vertical sidebar +.de VE +.ie n 'mc +.el \{\ +.ev 2 +.nf +.ti 0 +.mk ^t +\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' +.sp -1 +.fi +.ev +.\} +.nr ^v 0 +.. +'\" # Special macro to handle page bottom: finish off current +'\" # box/sidebar if in box/sidebar mode, then invoked standard +'\" # page bottom macro. +.de ^B +.ev 2 +'ti 0 +'nf +.mk ^t +.if \\n(^b \{\ +.\" Draw three-sided box if this is the box's first page, +.\" draw two sides but no top otherwise. +.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c +.\} +.if \\n(^v \{\ +.nr ^x \\n(^tu+1v-\\n(^Yu +\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c +.\} +.bp +'fi +.ev +.if \\n(^b \{\ +.mk ^y +.nr ^b 2 +.\} +.if \\n(^v \{\ +.mk ^Y +.\} +.. +'\" # DS - begin display +.de DS +.RS +.nf +.sp +.. +'\" # DE - end display +.de DE +.fi +.RE +.sp +.. +'\" # SO - start of list of standard options +.de SO +.SH "STANDARD OPTIONS" +.LP +.nf +.ta 4c 8c 12c +.ft B +.. +'\" # SE - end of list of standard options +.de SE +.fi +.ft R +.LP +See the \\fBoptions\\fR manual entry for details on the standard options. +.. +'\" # OP - start of full description for a single option +.de OP +.LP +.nf +.ta 4c +Command-Line Name: \\fB\\$1\\fR +Database Name: \\fB\\$2\\fR +Database Class: \\fB\\$3\\fR +.fi +.IP +.. +'\" # CS - begin code excerpt +.de CS +.RS +.nf +.ta .25i .5i .75i 1i +.. +'\" # CE - end code excerpt +.de CE +.fi +.RE +.. +.de UL +\\$1\l'|0\(ul'\\$2 +.. +.TH "cmdr_completion" n 0 doc "Cmdr, a framework for command line parsing and dispatch" +.BS +.SH NAME +cmdr_completion \- Cmdr - Internals of command line completion +.SH SYNOPSIS +package require \fBcmdr \fR +.sp +.BE +.SH DESCRIPTION +.PP +Welcome to the Cmdr project, written by Andreas Kupries\&. +.PP +For availability please read \fICmdr - How To Get The Sources\fR\&. +.PP +This internal document provides an overview on how the framework +performs command-line completion in both the main and mini shells, +referencing all the relevant methods and describing the data +structures in use\&. +.PP +For more information about other internals of the framework +please read \fICmdr - The Developer's Guide\fR\&. +.SH "CODE OVERVIEW" +The methods relevant to command-line completion can be found in four +packages/classes, namely: +.TP +\fBcmdr::actor\fR +.RS +.TP +\fBparse-line\fR +Takes a command-line and returns an initial parse structure as +described in section \fBParse State\fR +.TP +\fBcompletions\fR +.TP +\fBmatch\fR +.RE +.TP +\fBcmdr::config\fR +.RS +.TP +\fBcomplete\fR +Hook method, entrypoint for the mini-shell\&. +Takes the buffer to complete and returns the list of completions, +which may be empty\&. +Uses the workhorse method below and the \fBcmdr::actor\fR +methods\&. +.TP +\fBcomplete-repl\fR +Main work method taking a parse structure and returning the list +of completions\&. More details about it (and the mini-shell) can be +found in section \fBMini Shell Operation\fR\&. +.TP +\fBcomplete-words\fR +Main work method for completion from the main shell, invoked by +the \fBcmdr::private\fR instance having to complete words\&. +.RE +.TP +\fBcmdr::officer\fR +.RS +.TP +\fBcomplete\fR +Hook method, entrypoint for the main shell\&. +Takes the buffer to complete and returns the list of completions, +which may be empty\&. +Uses the workhorse method below and the \fBcmdr::actor\fR +methods\&. +.TP +\fBcomplete-words\fR +Main work method taking a parse structure and returning the list +of completions\&. More details about it (and the main shell) can be +found in section \fBMain Shell Operation\fR\&. +.sp +Can recurse to the same method of other officers, and +private instances\&. +.RE +.TP +\fBcmdr::parameter\fR +.RS +.TP +\fBcomplete-words\fR +Main work method when reaching a parameter\&. +Simply delegates the work to the method \fBcomplete\fR of the +validation type associated with the parameter\&. +.RE +.TP +\fBcmdr::private\fR +.RS +.TP +\fBcomplete-words\fR +Main work method when reaching a private while recursing through +the command hierarchy from officers\&. +Delegates to the \fBcmdr::config\fR method of the same name\&. +.RE +.PP +.SH "PARSE STATE" +The state structure used by all methods relevant to command line +completion is a dictionary containing the six keys listed below\&. +The only generator for this structure is method \fBparse-line\fR of +the base-class \fBcmdr::actor\fR\&. All others parts of the system +then only read and manipulate it\&. +.TP +\fBok\fR +A boolean flag\&. Indicates if the \fBline\fR parsed sucessfully into +words (\fBtrue\fR), or not (\fBfalse\fR, syntax error)\&. +.sp +The framework expects basic shell syntax with space-separated +words using single- and double-quotes for words containing whitespace +themselves\&. Note that complex syntax like variable- and +command-substitutions are not allowed\&. +.TP +\fBline\fR +A copy of the unparsed command line\&. +.TP +\fBwords\fR +The command \fBline\fR parsed into the bare words\&. The data is not +valid if \fBok\fR indicates a parsing error\&. This is not a list of +strings, but actually a list of tokens\&. +.sp +Each token is a list of four elements containing, in the order +below: +.RS +.IP [1] +Type of the token (implicitly specifies found quoting)\&. +.IP [2] +Start index of token in \fBline\fR including quoting\&. +.IP [3] +End index of token in \fBline\fR, including quoting\&. +.IP [4] +The string value of the token, with escapes fully resolved\&. +I\&.e\&. the actual word\&. +.RE +.sp +Note: If \fBline\fR ended in trailing whitespace the last +element of this list will be an empty string representing the word +started by the user, yet still empty\&. +.TP +\fBnwords\fR +The number of element in \fBwords\fR\&. The data is not valid if +\fBok\fR indicates a parsing error\&. +.TP +\fBat\fR +The index of the \fIcurrent word\fR in \fBwords\fR currently +considered by the completion code\&. Initially \fB0\fR this advances +as the completion code works through the prefix to determine the +context for the completion of the last word\&. +.TP +\fBdoexit\fR +A boolean flag\&. Indicates if the pseudo-command \fB\&.exit\fR is active +(\fBtrue\fR), or not\&. Initially \fBtrue\fR\&. +.PP +.SH "MAIN SHELL OPERATION" +.SS OVERVIEW +The \fImain shell\fR is fully implemented within the package +\fBcmdr::officer\fR, while its command-line completion also +reaches into the packages \fBcmdr::private\fR, +\fBcmdr::config\fR, and \fBcmdr::parameter\fR\&. +The purpose of this shell is interactive access to the commands of an +officer\&. Which implies, for the toplevel officer, access to the entire +command hierarchy\&. +.PP +To this end this shell accepts the names of all subordinate +commands known to the officer as commands\&. +.PP +It may additional accept a hard-wired command \fB\&.exit\fR, +depending on the parse state (see flag \fBdoexit\fR)\&. +.SS "SEQUENCING AND RULES" +This section is in essence the textual description of an UML sequence +diagram\&. +.PP +Note that the state structure used by this code and referenced +in the text is explained in section \fBParse State\fR\&. +.IP [1] +The main shell's core read-eval-print-loop calls on the +instance method \fBcomplete\fR for command-line completion, +providing the text of the buffer to complete at the end)\&. +.IP [2] +The method \fBcmdr::actor\fR::\fBparse-line\fR is called +on first, to get a parse of the buffer\&. This parse is then delegated +to the instance method \fBcomplete-words\fR to perform the bulk of +the work\&. +.sp +Note: The officer instance has access to \fBparse-line\fR +because it is a derived class of \fBcmdr::actor\fR\&. +.IP [3] +The implementation of method \fBcomplete-words\fR applies +the rules below: +.RS +.IP [1] +If the buffer was not properly parsed (i\&.e\&. the state indicates +a syntax error), the list of completions is empty\&. +.IP [2] +When the buffer is empty all commands are possible completions, +as are all the commands of the default subordinate, if any was +specified\&. +.IP [3] +If the \fIcurrent word\fR (as per \fBat\fR) is the last +word (per \fBnwords\fR) on the command line then completion is done +using the set of commands known to the officer and its default +subordinate, if any\&. +.IP [4] +For a \fIcurrent word\fR which is not the last, i\&.e\&. at the +beginning or in the middle of the command line instead, then this word +is the name of the subordinate object responsible for handling the +remaining words\&. +.sp +No completion is done however if the current word does not +yield a subordinate to delegate to (i\&.e\&. unknown or ambigous)\&. If a +default command is known this case will delegate to this subordinate, +as a last attempt\&. +.sp +When a subordinate was found the system advances the current +word, resets the \fBdoexit\fR flag, and lastly invokes the method +\fBcomplete-words\fR of the sub-ordinate\&. +.IP [5] +When the subordinate is again an \fIofficer\fR, these rules +here apply again\&. +.IP [6] +A \fIprivate\fR however will delegate to the embedded +\fBcmdr::config\fR instance, again using the method +\fBcomplete-words\fR\&. +.IP [7] +This method processes the remaining words similar to how the +command line is parsed at runtime to match words to parameters, to +know at the end which (set of) parameter(s) governs the last word\&. +.sp +For \fIoptions\fR the last word may be partial name of a flag, +or it may be the partial argument to an option\&. +In case of the first the set of completions is the set of all flags +with the word as its prefix\&. +In case of the second the completion delegates to the parameter +governing the flag, if there is any, which in turn delegates to its +associated validation type\&. +.sp +For \fIinputs\fR the system essentially steps through a +non-deterministic finite automaton to find all the parameters which +may govern the current word\&. Completion is done as the union of the +completion done by the individual parameters\&. +.sp +Note that the automaton and its results can be precomputed, +this happens in the internal method \fBCompletionGraph\fR\&. +.RE +.PP +.SH "MINI SHELL OPERATION" +.SS OVERVIEW +The \fImini shell\fR and its command-line completion is fully +implemented within the package \fBcmdr::config\fR\&. +The purpose of this shell is the interactive entry of the parameters +for a \fIprivate\fR\&. +.PP +To this end this shell accepts the \fIsystem\fR names of all +parameters held by the config instance as commands, plus five +hard-wired commands to control exit conditions and access to help\&. +.PP +The parameter commands all take single value as their argument, +the string value to set\&. +The sole exception to this are \fIpresence options\fR which do not +take any argument\&. +.PP +Similarly none of the hardwired commands take an +argument\&. Their names all start with a \fB\&.\fR\&. They are, in +alphabetical order, \fB\&.cancel\fR, \fB\&.exit\fR, \fB\&.help\fR \fB\&.ok\fR, and \fB\&.run\fR\&. +.SS "SEQUENCING AND RULES" +This section is in essence the textual description of an UML sequence +diagram\&. +.PP +Note that the state structure used by this code and referenced +in the text is explained in section \fBParse State\fR\&. +.IP [1] +The mini shell's core read-eval-print-loop calls on the +instance method \fBcomplete\fR for command-line completion, +providing the text of the buffer to complete at the end)\&. +.IP [2] +The method \fBcmdr::actor\fR::\fBparse-line\fR is called +on first, to get a parse of the buffer\&. This parse is then delegated +to the instance method \fBcomplete-repl\fR to perform the bulk of +the work\&. +.sp +Note: The config instance has access to \fBparse-line\fR +through its internal \fBcontext\fR command, which is an alias of the +\fBcmdr::private\fR instance the configuration belongs to\&. This +class is derived from \fBcmdr::actor\fR\&. +.IP [3] +The implementation of method \fBcomplete-repl\fR applies the +rules below: +.RS +.IP [1] +If the buffer was not properly parsed (i\&.e\&. the state indicates +a syntax error), the list of completions is empty\&. +.IP [2] +When the buffer is empty all commands are possible completions\&. +.IP [3] +When the buffer contains more than three words the list of +completions is empty, as all valid mini-shell commands consist of at +most two words\&. +.IP [4] +A buffer containing a single word contain a partial command +name and the list of completions is the set of commands having this +word as prefix\&. +.IP [5] +A buffer containing two words contains a command name and a +partial argument\&. Completion is delegated to the parameter (method +\fBcmdr::parameter\fR::\fBcomplete-words\fR) indicated by the +command name, and through it to the associated validation type\&. +.sp +No completion is done however if the first word does not yield +a parameter to delegate to (i\&.e\&. unknown or ambigous), or if it is a +presence option, which does not take an argument\&. +.sp +The hardwired commands fall here implicitly under unknown +parameter\&. +.RE +.PP +.SH "BUGS, IDEAS, FEEDBACK" +Both the package(s) and this documentation will undoubtedly contain +bugs and other problems\&. +Please report such at +\fICmdr Tickets\fR [https:/core\&.tcl\&.tk/akupries/cmdr]\&. +.PP +Please also report any ideas you may have for enhancements of +either package(s) and/or documentation\&. +.SH 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 +.SH COPYRIGHT +.nf +Copyright (c) 2013 Andreas Kupries +Copyright (c) 2013 Documentation, Andreas Kupries + +.fi Index: embedded/man/files/cmdr_howto_development.n ================================================================== --- embedded/man/files/cmdr_howto_development.n +++ embedded/man/files/cmdr_howto_development.n @@ -283,11 +283,11 @@ package in favor of the external application\&. .PP .SH "DEMONSTRATION/EXAMPLE APPLICATIONS" Cmdr (currently) does not have demonstrations, nor examples\&. .SH "DIRECTORY STRUCTURE" -Explain the physical layout (directory structure)\&. +The directory structure of the sources is as explained below: .TP "\fIbuild\&.tcl\fR" The main file of the \fBkettle\fR-based build-system\&. .TP "\fIdoc/\fR" @@ -320,44 +320,44 @@ .sp Based on the \fBtcltest\fR package distributed with the Tcl core\&. .TP "\fIactor\&.tcl\fR" -== Package \fBcmdr::actor\fR\&. +Package \fBcmdr::actor\fR\&. .TP "\fIcmdr\&.tcl\fR" -== Package \fBcmdr\fR\&. +Package \fBcmdr\fR\&. .TP "\fIconfig\&.tcl\fR" -== Package \fBcmdr::config\fR\&. +Package \fBcmdr::config\fR\&. .TP "\fIhelp\&.tcl\fR" -== Package \fBcmdr::help\fR\&. +Package \fBcmdr::help\fR\&. .TP "\fIhelp_json\&.tcl\fR" -== Package \fBcmdr::help::json\fR\&. +Package \fBcmdr::help::json\fR\&. .TP "\fIhelp_sql\&.tcl\fR" -== Package \fBcmdr::help::sql\fR\&. +Package \fBcmdr::help::sql\fR\&. .TP "\fIofficer\&.tcl\fR" -== Package \fBcmdr::officer\fR\&. +Package \fBcmdr::officer\fR\&. .TP "\fIparameter\&.tcl\fR" -== Package \fBcmdr::parameter\fR\&. +Package \fBcmdr::parameter\fR\&. .TP "\fIprivate\&.tcl\fR" -== Package \fBcmdr::private\fR\&. +Package \fBcmdr::private\fR\&. .TP "\fIutil\&.tcl\fR" -== Package \fBcmdr::util\fR\&. +Package \fBcmdr::util\fR\&. .TP "\fIvalidate\&.tcl\fR" -== Package \fBcmdr::validate\fR\&. +Package \fBcmdr::validate\fR\&. .TP "\fIvcommon\&.tcl\fR" -== Package \fBcmdr::validate::common\fR\&. +Package \fBcmdr::validate::common\fR\&. .PP .SH "EXTENDED BUILD ACTIONS" Our build-system is based on \fBkettle\fR, as already explained in the \fICmdr - The Installer's Guide\fR\&. Beyond the targets useful for installation it also provides targets aiding developers and @@ -407,19 +407,10 @@ % /path/to/cmdr/build\&.tcl test --log .CE .PP .SH "ARCHITECTURE & CONCEPTS" -The following sections explain -.IP [1] -the internal architecture and package dependencies\&. -.IP [2] -the internal data structures\&. -.IP [3] -important operation sequences (UML SD)\&. -.PP -.SS "SYSTEM ARCHITECTURE" .PP All packages in the framework belong to one of three layers, as shown below: .PP .PS @@ -476,12 +467,21 @@ the complexity of the diagram below a few direct dependencies on \fBcmdr::util\fR were omitted where indirectly present through other dependencies (i\&.e\&. through \fBcmdr::help\fR): .PP IMAGE: pkg_dependencies -.SS "DATA STRUCTURES" -.SS "OPERATION SEQUENCES" +.SH "VALIDATION TYPES" +Everything said in the public document \fICmdr - Writing custom validation types\fR +applies to the standard validation types of the framework (as listed +in \fICmdr - Standard validation types for parameters\fR) as well\&. +.SH "HELP FORMATS" +Everything said in the public document \fICmdr - Writing custom help formats\fR +applies to the standard help formats of the framework (as listed in +\fICmdr - Standard help formats of the framework\fR) as well\&. +.SH "COMMAND LINE COMPLETION" +The document \fICmdr - Internals of command line completion\fR describes the inner +workings of the command line completion provided by the framework\&. .SH "RELATED DOCUMENTS" .IP [1] \fICmdr - Introduction to the project\fR .IP [2] \fICmdr - License\fR Index: embedded/man/index.n ================================================================== --- embedded/man/index.n +++ embedded/man/index.n @@ -280,10 +280,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -352,10 +355,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -424,10 +430,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -496,10 +505,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -568,10 +580,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -640,10 +655,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -712,10 +730,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -784,10 +805,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -856,10 +880,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -928,10 +955,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -1000,10 +1030,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -1072,10 +1105,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -1144,10 +1180,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR @@ -1216,10 +1255,13 @@ \fBfiles/cmdr_vcommon\&.n\fR cmdr::validate::common .TP \fBfiles/cmdr_changes\&.n\fR cmdr_changes +.TP +\fBfiles/cmdr_dev_completion\&.n\fR +cmdr_completion .TP \fBfiles/cmdr_howto_development\&.n\fR cmdr_development .TP \fBfiles/cmdr_dsl\&.n\fR Index: embedded/man/toc.n ================================================================== --- embedded/man/toc.n +++ embedded/man/toc.n @@ -279,10 +279,13 @@ \fIfiles/cmdr_vcommon\&.n\fR: Cmdr - Utilities for Validation Types .TP \fBcmdr_changes\fR \fIfiles/cmdr_changes\&.n\fR: Cmdr - Log of Changes .TP +\fBcmdr_completion\fR +\fIfiles/cmdr_dev_completion\&.n\fR: Cmdr - Internals of command line completion +.TP \fBcmdr_development\fR \fIfiles/cmdr_howto_development\&.n\fR: Cmdr - The Developer's Guide .TP \fBcmdr_dsl\fR \fIfiles/cmdr_dsl\&.n\fR: Cmdr - Introduction to the Specification Language ADDED embedded/www/doc/files/cmdr_dev_completion.html Index: embedded/www/doc/files/cmdr_dev_completion.html ================================================================== --- /dev/null +++ embedded/www/doc/files/cmdr_dev_completion.html @@ -0,0 +1,418 @@ + + +cmdr_completion - Cmdr, a framework for command line parsing and dispatch + + + + + +
+
[ + Home +| Main Table Of Contents +| Table Of Contents +| Keyword Index + ]
+

cmdr_completion(n) 0 doc "Cmdr, a framework for command line parsing and dispatch"

+

Name

+

cmdr_completion - Cmdr - Internals of command line completion

+
+ +

Synopsis

+
+
    +
  • package require cmdr
    • +
+
+
+

Description

+

Welcome to the Cmdr project, written by Andreas Kupries.

+

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

+

This internal document provides an overview on how the framework +performs command-line completion in both the main and mini shells, +referencing all the relevant methods and describing the data +structures in use.

+

For more information about other internals of the framework +please read Cmdr - The Developer's Guide.

+
+

Code Overview

+

The methods relevant to command-line completion can be found in four +packages/classes, namely:

+
+
cmdr::actor
+
+ +
parse-line
+

Takes a command-line and returns an initial parse structure as + described in section Parse State

+
completions
+
+
match
+
+
+
cmdr::config
+
+ +
complete
+

Hook method, entrypoint for the mini-shell. + Takes the buffer to complete and returns the list of completions, + which may be empty. + Uses the workhorse method below and the cmdr::actor + methods.

+
complete-repl
+

Main work method taking a parse structure and returning the list + of completions. More details about it (and the mini-shell) can be + found in section Mini Shell Operation.

+
complete-words
+

Main work method for completion from the main shell, invoked by + the cmdr::private instance having to complete words.

+
+
cmdr::officer
+
+ +
complete
+

Hook method, entrypoint for the main shell. + Takes the buffer to complete and returns the list of completions, + which may be empty. + Uses the workhorse method below and the cmdr::actor + methods.

+
complete-words
+

Main work method taking a parse structure and returning the list + of completions. More details about it (and the main shell) can be + found in section Main Shell Operation.

+

Can recurse to the same method of other officers, and + private instances.

+
+
cmdr::parameter
+
+ +
complete-words
+

Main work method when reaching a parameter. + Simply delegates the work to the method complete of the + validation type associated with the parameter.

+
+
cmdr::private
+
+ +
complete-words
+

Main work method when reaching a private while recursing through + the command hierarchy from officers. + Delegates to the cmdr::config method of the same name.

+
+
+
+

Parse State

+

The state structure used by all methods relevant to command line +completion is a dictionary containing the six keys listed below. +The only generator for this structure is method parse-line of +the base-class cmdr::actor. All others parts of the system +then only read and manipulate it.

+
+
ok
+

A boolean flag. Indicates if the line parsed sucessfully into +words (true), or not (false, syntax error).

+

The framework expects basic shell syntax with space-separated +words using single- and double-quotes for words containing whitespace +themselves. Note that complex syntax like variable- and +command-substitutions are not allowed.

+
line
+

A copy of the unparsed command line.

+
words
+

The command line parsed into the bare words. The data is not +valid if ok indicates a parsing error. This is not a list of +strings, but actually a list of tokens.

+

Each token is a list of four elements containing, in the order +below:

+
    +

  1. Type of the token (implicitly specifies found quoting).

    2. +

  2. Start index of token in line including quoting.

    3. +

  3. End index of token in line, including quoting.

    4. +

  4. The string value of the token, with escapes fully resolved. + I.e. the actual word.

    5. +
+

Note: If line ended in trailing whitespace the last +element of this list will be an empty string representing the word +started by the user, yet still empty.

+
nwords
+

The number of element in words. The data is not valid if +ok indicates a parsing error.

+
at
+

The index of the current word in words currently +considered by the completion code. Initially 0 this advances +as the completion code works through the prefix to determine the +context for the completion of the last word.

+
doexit
+

A boolean flag. Indicates if the pseudo-command .exit is active +(true), or not. Initially true.

+
+
+

Main Shell Operation

+

Overview

+

The main shell is fully implemented within the package +cmdr::officer, while its command-line completion also +reaches into the packages cmdr::private, +cmdr::config, and cmdr::parameter. +The purpose of this shell is interactive access to the commands of an +officer. Which implies, for the toplevel officer, access to the entire +command hierarchy.

+

To this end this shell accepts the names of all subordinate +commands known to the officer as commands.

+

It may additional accept a hard-wired command .exit, +depending on the parse state (see flag doexit).

+
+

Sequencing and Rules

+

This section is in essence the textual description of an UML sequence +diagram.

+

Note that the state structure used by this code and referenced +in the text is explained in section Parse State.

+
    +

  1. The main shell's core read-eval-print-loop calls on the +instance method complete for command-line completion, +providing the text of the buffer to complete at the end).

    2. +

  2. The method cmdr::actor::parse-line is called +on first, to get a parse of the buffer. This parse is then delegated +to the instance method complete-words to perform the bulk of +the work.

    +

    Note: The officer instance has access to parse-line +because it is a derived class of cmdr::actor.

    3. +

  3. The implementation of method complete-words applies +the rules below:

    +
      +

    1. If the buffer was not properly parsed (i.e. the state indicates +a syntax error), the list of completions is empty.

      2. +

    2. When the buffer is empty all commands are possible completions, +as are all the commands of the default subordinate, if any was +specified.

      3. +

    3. If the current word (as per at) is the last +word (per nwords) on the command line then completion is done +using the set of commands known to the officer and its default +subordinate, if any.

      4. +

    4. For a current word which is not the last, i.e. at the +beginning or in the middle of the command line instead, then this word +is the name of the subordinate object responsible for handling the +remaining words.

      +

      No completion is done however if the current word does not +yield a subordinate to delegate to (i.e. unknown or ambigous). If a +default command is known this case will delegate to this subordinate, +as a last attempt.

      +

      When a subordinate was found the system advances the current +word, resets the doexit flag, and lastly invokes the method +complete-words of the sub-ordinate.

      5. +

    5. When the subordinate is again an officer, these rules +here apply again.

      6. +

    6. A private however will delegate to the embedded +cmdr::config instance, again using the method +complete-words.

      7. +

    7. This method processes the remaining words similar to how the +command line is parsed at runtime to match words to parameters, to +know at the end which (set of) parameter(s) governs the last word.

      +

      For options the last word may be partial name of a flag, +or it may be the partial argument to an option. +In case of the first the set of completions is the set of all flags +with the word as its prefix. +In case of the second the completion delegates to the parameter +governing the flag, if there is any, which in turn delegates to its +associated validation type.

      +

      For inputs the system essentially steps through a +non-deterministic finite automaton to find all the parameters which +may govern the current word. Completion is done as the union of the +completion done by the individual parameters.

      +

      Note that the automaton and its results can be precomputed, +this happens in the internal method CompletionGraph.

      8. +
    +
    4. +
+
+
+

Mini Shell Operation

+

Overview

+

The mini shell and its command-line completion is fully +implemented within the package cmdr::config. +The purpose of this shell is the interactive entry of the parameters +for a private.

+

To this end this shell accepts the system names of all +parameters held by the config instance as commands, plus five +hard-wired commands to control exit conditions and access to help.

+

The parameter commands all take single value as their argument, +the string value to set. +The sole exception to this are presence options which do not +take any argument.

+

Similarly none of the hardwired commands take an +argument. Their names all start with a .. They are, in +alphabetical order, .cancel, .exit, .help +.ok, and .run.

+
+

Sequencing and Rules

+

This section is in essence the textual description of an UML sequence +diagram.

+

Note that the state structure used by this code and referenced +in the text is explained in section Parse State.

+
    +

  1. The mini shell's core read-eval-print-loop calls on the +instance method complete for command-line completion, +providing the text of the buffer to complete at the end).

    2. +

  2. The method cmdr::actor::parse-line is called +on first, to get a parse of the buffer. This parse is then delegated +to the instance method complete-repl to perform the bulk of +the work.

    +

    Note: The config instance has access to parse-line +through its internal context command, which is an alias of the +cmdr::private instance the configuration belongs to. This +class is derived from cmdr::actor.

    3. +

  3. The implementation of method complete-repl applies the +rules below:

    +
      +

    1. If the buffer was not properly parsed (i.e. the state indicates +a syntax error), the list of completions is empty.

      2. +

    2. When the buffer is empty all commands are possible completions.

      3. +

    3. When the buffer contains more than three words the list of +completions is empty, as all valid mini-shell commands consist of at +most two words.

      4. +

    4. A buffer containing a single word contain a partial command +name and the list of completions is the set of commands having this +word as prefix.

      5. +

    5. A buffer containing two words contains a command name and a +partial argument. Completion is delegated to the parameter (method +cmdr::parameter::complete-words) indicated by the +command name, and through it to the associated validation type.

      +

      No completion is done however if the first word does not yield +a parameter to delegate to (i.e. unknown or ambigous), or if it is a +presence option, which does not take an argument.

      +

      The hardwired commands fall here implicitly under unknown +parameter.

      6. +
    +
    4. +
+
+
+

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.

+
+ + +
Index: embedded/www/doc/files/cmdr_howto_development.html ================================================================== --- embedded/www/doc/files/cmdr_howto_development.html +++ embedded/www/doc/files/cmdr_howto_development.html @@ -115,19 +115,16 @@
  • Description
  • Development Tools
  • Demonstration/Example Applications
  • Directory structure
  • Extended Build Actions
    • -
  • Architecture & Concepts - -
    • -
  • Related Documents
    • -
  • Bugs, Ideas, Feedback
    • +
  • Architecture & Concepts
    • +
  • Validation Types
    • +
  • Help Formats
    • +
  • Command Line Completion
    • +
  • Related Documents
    • +
  • Bugs, Ideas, Feedback
  • Keywords
  • Copyright

    • Description

    @@ -165,11 +162,11 @@

    Demonstration/Example Applications

    Cmdr (currently) does not have demonstrations, nor examples.

    Directory structure

    -

    Explain the physical layout (directory structure).

    +

    The directory structure of the sources is as explained below:

    "build.tcl"

    The main file of the kettle-based build-system.

    "doc/"

    Main directory for all documentation.

    @@ -192,33 +189,33 @@
    "tests/"

    Main directory for the test-suite.

    Based on the tcltest package distributed with the Tcl core.

    "actor.tcl"
    -

    == Package cmdr::actor.

    +

    Package cmdr::actor.

    "cmdr.tcl"
    -

    == Package cmdr.

    +

    Package cmdr.

    "config.tcl"
    -

    == Package cmdr::config.

    +

    Package cmdr::config.

    "help.tcl"
    -

    == Package cmdr::help.

    +

    Package cmdr::help.

    "help_json.tcl"
    -

    == Package cmdr::help::json.

    +

    Package cmdr::help::json.

    "help_sql.tcl"
    -

    == Package cmdr::help::sql.

    +

    Package cmdr::help::sql.

    "officer.tcl"
    -

    == Package cmdr::officer.

    +

    Package cmdr::officer.

    "parameter.tcl"
    -

    == Package cmdr::parameter.

    +

    Package cmdr::parameter.

    "private.tcl"
    -

    == Package cmdr::private.

    +

    Package cmdr::private.

    "util.tcl"
    -

    == Package cmdr::util.

    +

    Package cmdr::util.

    "validate.tcl"
    -

    == Package cmdr::validate.

    +

    Package cmdr::validate.

    "vcommon.tcl"
    -

    == Package cmdr::validate::common.

    +

    Package cmdr::validate::common.

    Extended Build Actions

    Our build-system is based on kettle, as already explained in the Cmdr - The Installer's Guide. Beyond the targets useful for @@ -258,17 +255,10 @@

    Architecture & Concepts

    -

    The following sections explain

    -
      -

    1. the internal architecture and package dependencies.

      2. -

    2. the internal data structures.

      3. -

    3. important operation sequences (UML SD).

      4. -
    -

    System Architecture

    All packages in the framework belong to one of three layers, as shown below:

    architecture

    Note that:

      @@ -292,26 +282,35 @@ the complexity of the diagram below a few direct dependencies on cmdr::util were omitted where indirectly present through other dependencies (i.e. through cmdr::help):

      pkg_dependencies

    -

    Data structures

    +

    Validation Types

    +

    Everything said in the public document Cmdr - Writing custom validation types +applies to the standard validation types of the framework (as listed +in Cmdr - Standard validation types for parameters) as well.

    +
    +

    Help Formats

    +

    Everything said in the public document Cmdr - Writing custom help formats +applies to the standard help formats of the framework (as listed in +Cmdr - Standard help formats of the framework) as well.

    -

    Operation Sequences

    +

    Command Line Completion

    +

    The document Cmdr - Internals of command line completion describes the inner +workings of the command line completion provided by the framework.

    -
    -

    Related Documents

    + -

    Bugs, Ideas, Feedback

    +

    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 Index: embedded/www/doc/toc.html ================================================================== --- embedded/www/doc/toc.html +++ embedded/www/doc/toc.html @@ -64,46 +64,50 @@ cmdr_changes Cmdr - Log of Changes +cmdr_completion +Cmdr - Internals of command line completion + + cmdr_development Cmdr - The Developer's Guide - + cmdr_dsl Cmdr - Introduction to the Specification Language - + cmdr_dsl_officer Cmdr - Officer Specification Language - + cmdr_dsl_parameter Cmdr - Parameter Specification Language - + cmdr_dsl_private Cmdr - Private Specification Language - + cmdr_howto_get_sources Cmdr - How To Get The Sources - + cmdr_installation Cmdr - The Installer's Guide - + cmdr_introduction Cmdr - Introduction to the project - + cmdr_license Cmdr - License - + cmdr_vtypes Cmdr - Writing custom validation types

    Index: embedded/www/index.html ================================================================== --- embedded/www/index.html +++ embedded/www/index.html @@ -20,95 +20,95 @@ Keywords: A arguments - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Keywords: C command hierarchy - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes command line completion - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes command line handling - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes command tree - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Keywords: E editing command line - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Keywords: H help for command line - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes hierarchy of commands - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Keywords: I interactive command shell - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Keywords: O optional arguments - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes options - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Keywords: P parameters - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes processing command line - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Keywords: T tree of commands - cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes + cmdr · cmdr::actor · cmdr::config · cmdr::help · cmdr::help::json · cmdr::help::sql · cmdr::officer · cmdr::parameter · cmdr::private · cmdr::util · cmdr::validate · cmdr::validate::common · cmdr_changes · cmdr_completion · cmdr_development · cmdr_dsl · cmdr_dsl_officer · cmdr_dsl_parameter · cmdr_dsl_private · cmdr_howto_get_sources · cmdr_installation · cmdr_introduction · cmdr_license · cmdr_vtypes Index: embedded/www/toc.html ================================================================== --- embedded/www/toc.html +++ embedded/www/toc.html @@ -64,46 +64,50 @@ cmdr_changes Cmdr - Log of Changes +cmdr_completion +Cmdr - Internals of command line completion + + cmdr_development Cmdr - The Developer's Guide - + cmdr_dsl Cmdr - Introduction to the Specification Language - + cmdr_dsl_officer Cmdr - Officer Specification Language - + cmdr_dsl_parameter Cmdr - Parameter Specification Language - + cmdr_dsl_private Cmdr - Private Specification Language - + cmdr_howto_get_sources Cmdr - How To Get The Sources - + cmdr_installation Cmdr - The Installer's Guide - + cmdr_introduction Cmdr - Introduction to the project - + cmdr_license Cmdr - License - + cmdr_vtypes Cmdr - Writing custom validation types