cmdr
Check-in [65c018615d]
Not logged in
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Filled the officer documentation, and tweaked privates a bit.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 65c018615d1bbdd980b3237fa1c7b80c88878491
User & Date: andreask 2013-11-13 22:44:30
Original Comment: filled the officer documentation, and tweaked privates a bit.
Context
2013-11-13
23:33
Filled in the main package documentation (framework entrypoint) check-in: 5e924d81b9 user: andreask tags: trunk
22:44
Filled the officer documentation, and tweaked privates a bit. check-in: 65c018615d user: andreask tags: trunk
2013-11-05
05:55
Updated embedded documentation check-in: ca14a9b8c1 user: aku tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to doc/cmdr_officer.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[include parts/definitions.inc]
            3  +[manpage_begin [vset PROJECT]_officer [vset MAN_SECTION] [vset VERSION]]
            4  +[include parts/module.inc]
            5  +[require cmdr::util]
            6  +[titledesc [vset TITLE_OFFICER]]
            7  +[description]
            8  +[include parts/welcome.inc]
            9  +
           10  +This package implements [emph officers], the inner nodes of command
           11  +hierarchies.  Each officer can execute many actions, by delegating
           12  +them to their sub-ordinate actors, officers and privates.
           13  +
           14  +[para] This class is sub-class of [package cmdr::actor].
           15  +
           16  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           17  +[section {Class API}]
           18  +
           19  +The class API is not public. It is used internally by the framework
           20  +when parsing a command hierarchy specification to create the necessary
           21  +officer instances.
           22  +
           23  +[para] It is described here for use by developers maintaining,
           24  +modifying and extending the framework itself. A user of the framework
           25  +has no need for it.
           26  +
           27  +[list_begin definitions]
           28  +[comment {- - -- --- ----- -------- -------------}]
           29  +[call [cmd ::cmdr::officer] [method new] [arg super] [arg name] [arg actions]]
           30  +
           31  +Create an auto-named instance of [class cmdr::officer].
           32  +[para] [emph {Not used}].
           33  +
           34  +[comment {- - -- --- ----- -------- -------------}]
           35  +[call [cmd ::cmdr::officer] [method create] [arg obj] [arg super] [arg name] [arg actions]]
           36  +
           37  +Create a new instance of [class cmdr::officer], named [arg obj].
           38  +Used by the DSL processing parts of the framework to instantiate officers.
           39  +
           40  +[list_begin arguments]
           41  +[arg_def object super]
           42  +The instance command of the actor (officer actually) which contains the new officer.
           43  +
           44  +[arg_def string name]
           45  +The user-visible name of the command.
           46  +
           47  +[arg_def script actions]
           48  +The specification of the officer's subordinates.
           49  +Please read [term [vset TITLE_DSL]], section --TODO-- for the details.
           50  +
           51  +[list_end][comment arguments]
           52  +[list_end][comment definitions]
           53  +
           54  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           55  +[section {Instance API}]
           56  +
           57  +The instance API is not public. It is used internally by the framework
           58  +during the parsing of a command hierarchy specification to configure
           59  +the officer instances, and when processing a command line at runtime
           60  +to manage navigation of the hierarchy, word-completion, etc.
           61  +
           62  +[para] It is described here for use by developers maintaining,
           63  +modifying and extending the framework itself. A user of the framework
           64  +has no need for it.
           65  +
           66  +[list_begin definitions]
           67  +[comment {- - -- --- ----- -------- -------------}]
           68  +[call [cmd <officer>] [method children]]
           69  +
           70  +This method returns a list containing the instance commands of the
           71  +subordinate actors managed by this officer.
           72  +
           73  +See also method [method known] which returns a list of names.
           74  +
           75  +[comment {- - -- --- ----- -------- -------------}]
           76  +[call [cmd <officer>] [method complete] [arg line]]
           77  +
           78  +This hook-method for the main shell is responsible for computing the
           79  +set of completions for the entered [arg line].
           80  +
           81  +[list_begin arguments]
           82  +[arg_def string line]
           83  +The command line to complete.
           84  +[list_end][comment {--- arguments --}]
           85  +
           86  +[comment {- - -- --- ----- -------- -------------}]
           87  +[call [cmd <officer>] [method complete-words] [arg parse]]
           88  +
           89  +This method is given the completion state [arg parse] of a partial
           90  +command line and returns a list of strings which are the valid
           91  +completions at this point.
           92  +
           93  +[list_begin arguments]
           94  +[arg_def dict parse]
           95  +A dictionary holding the current completion state of a partial command
           96  +line.
           97  +
           98  +[para] -- TODO -- Describe the state fields and their meaning.
           99  +
          100  +[list_end][comment arguments]
          101  +
          102  +[comment {- - -- --- ----- -------- -------------}]
          103  +[call [cmd <officer>] [method continued] [arg line]]
          104  +
          105  +This hook-method for the main shell is responsible for the detection
          106  +of a continuation-line in the entered command [arg line]. It always
          107  +returns the boolean value [const false] as the main shell does not
          108  +support continuation lines.
          109  +
          110  +[list_begin arguments]
          111  +[arg_def list list]
          112  +[list_end][comment {--- arguments --}]
          113  +
          114  +[comment {- - -- --- ----- -------- -------------}]
          115  +[call [cmd <officer>] [method default]]
          116  +
          117  +This method returns the instance command of the subordinate to use
          118  +during command line processing if the first word does not specify a
          119  +known subordinate. An error is thrown if no such default was specified
          120  +for this officer. See also method [method hasdefault].
          121  +
          122  +[comment {- - -- --- ----- -------- -------------}]
          123  +[call [cmd <officer>] [method dispatch] [arg cmd]]
          124  +
          125  +This hook-method for the main shell is responsible for the recognition
          126  +and execution of the supported commands.
          127  +
          128  +[list_begin arguments]
          129  +[arg_def string cmd]
          130  +The command line containing the command to run.
          131  +[list_end][comment {--- arguments --}]
          132  +
          133  +[comment {- - -- --- ----- -------- -------------}]
          134  +[call [cmd <officer>] [method do] [opt [arg word]...]]
          135  +
          136  +This method parses the [arg word]s of the command line, matching them
          137  +to the sub-ordinates of the officer. When done without error it
          138  +recursively invokes the chosen sub-ordinate to continue processing.
          139  +
          140  +[para] This represents the "Dispatch" phase of command line processing.
          141  +
          142  +[list_begin arguments]
          143  +[arg_def string word]
          144  +The words of the command line to parse and match to parameters.
          145  +[list_end][comment arguments]
          146  +
          147  +[comment {- - -- --- ----- -------- -------------}]
          148  +[call [cmd <officer>] [method ehandler] [arg cmd]]
          149  +
          150  +This method specifies a command prefix to wrap around the parsing of
          151  +the command line for the officer, and the execution of its action.
          152  +
          153  +[list_begin arguments]
          154  +[arg_def cmd-prefix cmd]
          155  +A command prefix taking a single argument, a script. The command
          156  +prefix has to execute this script in its caller's context. The script
          157  +will parse words for the officer,m and perform its action. The command
          158  +prefix then has the responsbility to perform any custom cleanup action
          159  +required by the application using the framework to prevent leakage of
          160  +data between multiple commands executed one after the other (i.e. in
          161  +an interactive shell run by the framework).
          162  +[list_end][comment arguments]
          163  +
          164  +[comment {- - -- --- ----- -------- -------------}]
          165  +[call [cmd <officer>] [method exit]]
          166  +
          167  +This hook-method for the main shell returns a boolean value indicating
          168  +whether the main shell was stopped and has to exit ([const true]), or
          169  +not ([const false]).
          170  +
          171  +[comment {- - -- --- ----- -------- -------------}]
          172  +[call [cmd <officer>] [method extend] [arg path] [arg arguments] [arg action]]
          173  +
          174  +A convenience method to create a "private" command underneath this
          175  +officer, with the command name [arg path] (a list of names). Any
          176  +intermediate officers are created as needed. An error is thrown if any
          177  +of the intermediates already exist as a (non-extensible) private, or
          178  +if the last command already exists.
          179  +
          180  +[para] The arguments after the [arg path] match the constructor of
          181  +privates in number and semantics.
          182  +
          183  +[list_begin arguments]
          184  +[arg_def script path]
          185  +The list of names specifying the route from this officer to the new
          186  +private. The last element is the name of the private command, while
          187  +the preceding names specify the intermediate officers.
          188  +
          189  +[comment {--- TODO place into text block for inclusion --- see private - constructor}]
          190  +[arg_def script arguments]
          191  +The specification of the private's parameters.
          192  +Please read [term [vset TITLE_DSL]], section --TODO-- for the details.
          193  +
          194  +[arg_def cmd-prefix action]
          195  +The command prefix to invoke when this private is selected for
          196  +execution.  It takes a single argument, the instance command of the
          197  +hidden [package cmdr::config] container holding the private's
          198  +parameters. The result of the action, if there is any, is ignored by
          199  +the framework.
          200  +
          201  +[list_end][comment arguments]
          202  +
          203  +[comment {- - -- --- ----- -------- -------------}]
          204  +[call [cmd <officer>] [method has] [arg name]]
          205  +
          206  +This method returns a boolean value indicating if this officer has a
          207  +sub-ordinate of the given [arg name] ([const true]), or not
          208  +([const false]). See also method [method lookup].
          209  +
          210  +[list_begin arguments]
          211  +[arg_def string name] The name of the sub-ordinate to look for.
          212  +[list_end]
          213  +
          214  +[comment {- - -- --- ----- -------- -------------}]
          215  +[call [cmd <officer>] [method hasdefault]]
          216  +
          217  +This method returns a boolean value indicating if this officer has a
          218  +default sub-ordinate ([const true]), or not ([const false]). See also
          219  +method [method default].
          220  +
          221  +[comment {- - -- --- ----- -------- -------------}]
          222  +[call [cmd <officer>] [method help] [opt [arg prefix]]]
          223  +
          224  +This method returns the help information for the officer and its
          225  +subordinates. The [arg prefix], if specified provides the name of the
          226  +officer within the help data. It defaults to the empty string.
          227  +
          228  +The result of the command is a structure of the form
          229  +described in section [sectref {Help Information}].
          230  +
          231  +[list_begin arguments]
          232  +[arg_def string prefix]
          233  +The name to use for the officer within the generated help.
          234  +[list_end][comment arguments]
          235  +
          236  +
          237  +[comment {- - -- --- ----- -------- -------------}]
          238  +[call [cmd <officer>] [method known]]
          239  +
          240  +This method returns a list containing the names of the subordinate
          241  +actors managed by this officer.
          242  +
          243  +See also method [method children] which returns a list of instance
          244  +commands.
          245  +
          246  +See also method [method lookup] to map names to instance commands.
          247  +
          248  +[comment {- - -- --- ----- -------- -------------}]
          249  +[call [cmd <officer>] [method learn] [arg script]]
          250  +
          251  +This method takes a regular specification script and uses it to extend
          252  +the set of subordinates known to this officer. This is the same type
          253  +of script as used during construction, except here we dynamically
          254  +extend the officer.
          255  +
          256  +[list_begin arguments]
          257  +[arg_def script actions]
          258  +The specification of the officer's additional subordinates.
          259  +Please read [term [vset TITLE_DSL]], section --TODO-- for the details.
          260  +
          261  +[list_end][comment arguments]
          262  +
          263  +[comment {- - -- --- ----- -------- -------------}]
          264  +[call [cmd <officer>] [method lookup] [arg name]]
          265  +
          266  +This method returns the instance command of the sub-ordinate with the
          267  +given [arg name]. An error is thrown if such a sub-ordinate does not
          268  +exist. See also method [method has].
          269  +
          270  +[list_begin arguments]
          271  +[arg_def string name] The name of the sub-ordinate to look for.
          272  +[list_end]
          273  +
          274  +[comment {- - -- --- ----- -------- -------------}]
          275  +[call [cmd <officer>] [method prompt1]]
          276  +
          277  +This hook-method for the main shell returns the primary prompt string
          278  +to use.
          279  +
          280  +[comment {- - -- --- ----- -------- -------------}]
          281  +[call [cmd <officer>] [method prompt2]]
          282  +
          283  +This hook-method for the main shell returns the secondary prompt
          284  +string for use within a continuation. As the main shell does not
          285  +support continuation lines it should not be invoked ever, and thus
          286  +always throws an error should it be invoked.
          287  +
          288  +
          289  +[comment {- - -- --- ----- -------- -------------}]
          290  +[call [cmd <officer>] [method report] [arg what] [arg data]]
          291  +
          292  +This hook-method for the main shell is responsible for the reporting
          293  +of the command results.
          294  +
          295  +[para] Its result is the empty string.
          296  +
          297  +[list_begin arguments]
          298  +[arg_def enum what]
          299  +The result code of the command, one of [const ok], or [const fail].
          300  +
          301  +[arg_def any data]
          302  +The result of the command, or an error message in case of failure.
          303  +[list_end][comment {--- arguments --}]
          304  +
          305  +[list_end][comment definitions]
          306  +
          307  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
          308  +[section {Help Information}]
          309  +[include parts/help_structure.inc]
          310  +
          311  +[include parts/feedback.inc]
          312  +[manpage_end]

Changes to doc/cmdr_private.man.

     4      4   [include parts/module.inc]
     5      5   [require cmdr::util]
     6      6   [titledesc [vset TITLE_PRIVATE]]
     7      7   [description]
     8      8   [include parts/welcome.inc]
     9      9   
    10     10   This package implements [emph privates], the leaves of command
    11         -hierarchies.  While each private can execute only a single option they
           11  +hierarchies.  While each private can execute only a single action they
    12     12   have parameters, i.e. arguments and options with which to configure
    13     13   the behaviour of their action.
           14  +
           15  +[para] This class is sub-class of [package cmdr::actor].
    14     16   
    15     17   [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
    16     18   [section {Class API}]
    17     19   
    18     20   The class API is not public. It is used internally by the framework
    19     21   when parsing a command hierarchy specification to create the necessary
    20     22   private instances.
................................................................................
    34     36   [call [cmd ::cmdr::private] [method create] [arg obj] [arg super] [arg name] [arg arguments] [arg action]]
    35     37   
    36     38   Create a new instance of [class cmdr::private], named [arg obj].
    37     39   Used by the DSL processing parts of the framework to instantiate privates.
    38     40   
    39     41   [list_begin arguments]
    40     42   [arg_def object super]
    41         -The instance command of the actor (officer actually) which contain the private.
           43  +The instance command of the actor (officer actually) which contains the new private.
    42     44   
    43     45   [arg_def string name]
    44     46   The user-visible name of the command.
    45     47   
           48  +[comment {--- TODO place into text block for inclusion --- see officer - extend}]
    46     49   [arg_def script arguments]
    47     50   The specification of the private's parameters.
    48     51   Please read [term [vset TITLE_DSL]], section --TODO-- for the details.
    49     52   
    50     53   [arg_def cmd-prefix action]
    51     54   The command prefix to invoke when this private is selected for
    52     55   execution.  It takes a single argument, the instance command of the
................................................................................
    57     60   [list_end][comment arguments]
    58     61   [list_end][comment definitions]
    59     62   
    60     63   [comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
    61     64   [section {Instance API}]
    62     65   
    63     66   The instance API is not public. It is used internally by the framework
    64         -when during the processing of a command line at runtime
    65         -
    66         -parsing a command hierarchy specification to create the necessary
    67         -private instances.
           67  +during the parsing of a command hierarchy specification to configure
           68  +the private instances, and when processing a command line at
           69  +runtime to manage word-completion, etc.
    68     70   
    69     71   [para] It is described here for use by developers maintaining,
    70     72   modifying and extending the framework itself. A user of the framework
    71     73   has no need for it, although they have indirect access through
    72     74   parameters and their container.
    73     75   
    74     76   [list_begin definitions]