cmdr_dev~completion(n) 1.1 doc "Cmdr, a framework for command line parsing and dispatch"

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 rest of this section is a textual description of the UML sequence diagram shown above.

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. 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. 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. When the buffer is empty all commands are possible completions, as are all the commands of the default subordinate, if any was specified.

   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. 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. When the subordinate is again an officer, these rules here apply again.

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

   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.

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 rest of this section is a textual description of the UML sequence diagram shown above.

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. 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. 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. When the buffer is empty all commands are possible completions.

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