cmdr
Check-in [f7695638e8]
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 tclconference@googlegroups.com
or submit via the online form by Sep 9.

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

Overview
Comment:Added back-references from packages to the devguide for command-line completion.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:f7695638e8793475076778f273ce448939beeb46
User & Date: andreask 2013-11-27 18:25:48
Context
2013-11-27
19:23
Extended information about help formats and how to write them. Documented the DSL "section" command. check-in: f30dbe0098 user: andreask tags: trunk
18:25
Added back-references from packages to the devguide for command-line completion. check-in: f7695638e8 user: andreask tags: trunk
07:55
Continued the dev-guide in general, and completion internals in particular. Added draft diagram code for sequence diagrams. Snarfed from my 2012 kinetcl paper. Has to be modded for the completions. Todo: Document standard help formats, and how to write formats. Todo: Back-reference from the package docs to the completion internals. check-in: 5a6408a944 user: aku tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to doc/cmdr_actor.man.

    46     46   modifying and extending the framework itself. A user of the framework
    47     47   has no need for it.
    48     48   
    49     49   [list_begin definitions]
    50     50   [comment {- - -- --- ----- -------- -------------}]
    51     51   [call [cmd <actor>] [method completions] [arg parse] [arg cmdlist]]
    52     52   
    53         -This method is given the completion state [arg parse] of a partial
    54         -command line and a list of completions at the end of the line. It
    55         -returns a list of strings which are the valid completions of the whole
    56         -line, properly quoted.
           53  +This method is part of command line completion. For the details of
           54  +its workings please read [term [vset TITLE_DEV_COMPLETE]].
           55  +
           56  +[para] Given the completion state [arg parse] of a partial command
           57  +line and a list of completions at the end of the line it returns a
           58  +list of strings which are the valid completions of the whole line,
           59  +properly quoted.
    57     60   
    58     61   [list_begin arguments]
    59     62   [arg_def dict parse]
    60     63   A dictionary holding the current completion state of a partial command
    61     64   line.
    62     65   
    63         -[para] -- TODO -- Describe the state fields and their meaning.
    64         -
    65     66   [arg_def list cmdlist]
    66     67   List of valid completions.
    67     68   [list_end][comment arguments]
    68     69   
    69     70   [comment {- - -- --- ----- -------- -------------}]
    70     71   [call [cmd <actor>] [method description]]
    71     72   
................................................................................
   164    165   [arg_def string key]  The name of the common block to extend.
   165    166   [arg_def any    data] The data to add to the block.
   166    167   [list_end][comment {--- arguments --}]
   167    168   
   168    169   [comment {- - -- --- ----- -------- -------------}]
   169    170   [call [cmd <actor>] [method match] [arg parse] [arg cmdlist]]
   170    171   
   171         -This method is given the completion state [arg parse] of a partial
   172         -command line and a list of possible completions. The result is a list
   173         -of valid completions, filtered against the current word in the command
   174         -line.
          172  +This method is part of command line completion. For the details of
          173  +its workings please read [term [vset TITLE_DEV_COMPLETE]].
          174  +
          175  +[para] Given the completion state [arg parse] of a partial command
          176  +line and a list of possible completions it returns a list of valid
          177  +completions, filtered against the current word in the command line.
   175    178   
   176    179   [list_begin arguments]
   177    180   [arg_def dict parse]
   178    181   A dictionary holding the current completion state of a partial command
   179    182   line.
   180    183   
   181         -[para] -- TODO -- Describe the state fields and their meaning.
   182         -
   183    184   [arg_def list cmdlist]
   184    185   List of possible completions.
   185    186   [list_end][comment arguments]
   186    187   
   187    188   [comment {- - -- --- ----- -------- -------------}]
   188    189   [call [cmd <actor>] [method name]]
   189    190   
................................................................................
   198    199   [arg_def string name]
   199    200   The name to remember.
   200    201   [list_end][comment {--- arguments --}]
   201    202   
   202    203   [comment {- - -- --- ----- -------- -------------}]
   203    204   [call [cmd <actor>] [method parse-line] [arg line]]
   204    205   
   205         -This method is the main helper to begin command completion. Given the
   206         -entered command [arg line] it parses it into words and returns a parse
   207         -structure as is taken by all other methods taking part in command
   208         -completion.
          206  +This method is part of command line completion. For the details of
          207  +its workings please read [term [vset TITLE_DEV_COMPLETE]].
          208  +
          209  +[para] Is the main helper to begin command completion. Given the
          210  +entered command [arg line] it parses it into words and returns a
          211  +parse structure as is taken by all other methods taking part in
          212  +command completion.
   209    213   
   210    214   [list_begin arguments]
   211    215   [arg_def string line]
   212    216   The command line.
   213    217   [list_end][comment {--- arguments --}]
   214         -
   215    218   
   216    219   [comment {- - -- --- ----- -------- -------------}]
   217    220   [call [cmd <actor>] [method root]]
   218    221   
   219    222   This accessor method returns the root actor instance the actor belongs
   220    223   to.
   221    224   

Changes to doc/cmdr_config.man.

   115    115   
   116    116   This method returns a list of parameter names,
   117    117   for the parameters which are arguments.
   118    118   
   119    119   [comment {- - -- --- ----- -------- -------------}]
   120    120   [call [cmd <config>] [method complete] [arg line]]
   121    121   
   122         -This hook-method for the mini-shell is responsible
   123         -for computing the set of completions for the
   124         -entered [arg line].
          122  +This method is part of the mini shell command line
          123  +completion. For the details of its workings please read
          124  +[term [vset TITLE_DEV_COMPLETE]].
          125  +
          126  +[para] This hook-method, the entrypoint for the repl
          127  +is responsible for computing the set of completions
          128  +for the entered [arg line].
   125    129   
   126    130   [list_begin arguments]
   127    131   [arg_def string line]
   128    132   The command line to complete.
   129    133   [list_end][comment {--- arguments --}]
   130    134   
   131    135   [comment {- - -- --- ----- -------- -------------}]
   132    136   [call [cmd <config>] [method complete-repl] [arg parse]]
   133    137   
   134         -This internal method is used by the hook-method [method complete]
   135         -for the mini-shell, see above. It is given the completion
   136         -state [arg parse] of a partial command line and returns a
   137         -list of strings which are the valid completions at this point.
          138  +This internal method is part of the mini shell command line
          139  +completion. For the details of its workings please read
          140  +[term [vset TITLE_DEV_COMPLETE]].
          141  +
          142  +[para] It is used by the hook-method [method complete] (see above).
          143  +Given the completion state [arg parse] of a partial command
          144  +line it returns a list of strings which are the valid
          145  +completions at this point.
   138    146   
   139    147   [list_begin arguments]
   140    148   [arg_def dict parse]
   141    149   A dictionary holding the current completion state of a partial command
   142    150   line.
   143         -
   144         -[para] -- TODO -- Describe the state fields and their meaning.
   145    151   [list_end][comment {--- arguments --}]
   146    152   
   147    153   [comment {- - -- --- ----- -------- -------------}]
   148    154   [call [cmd <config>] [method complete-words] [arg parse]]
   149    155   
   150         -This method is given the completion state [arg parse] of a partial
   151         -command line and returns a list of strings which are the valid
          156  +This method is part of the main shell command line
          157  +completion. For the details of its workings please read
          158  +[term [vset TITLE_DEV_COMPLETE]].
          159  +
          160  +[para] Given the completion state [arg parse] of a partial
          161  +command line it returns a list of strings which are the valid
   152    162   completions at this point.
   153    163   
   154    164   [list_begin arguments]
   155    165   [arg_def dict parse]
   156    166   A dictionary holding the current completion state of a partial command
   157    167   line.
   158         -
   159         -[para] -- TODO -- Describe the state fields and their meaning.
   160    168   [list_end][comment {--- arguments --}]
   161    169   
   162    170   [comment {- - -- --- ----- -------- -------------}]
   163    171   [call [cmd <config>] [method continued] [arg line]]
   164    172   
   165    173   This hook-method for the mini-shell is responsible for the detection
   166    174   of a continuation-line in the entered command [arg line]. It always

Changes to doc/cmdr_officer.man.

    82     82   [arg_def string line]
    83     83   The command line to complete.
    84     84   [list_end][comment {--- arguments --}]
    85     85   
    86     86   [comment {- - -- --- ----- -------- -------------}]
    87     87   [call [cmd <officer>] [method complete-words] [arg parse]]
    88     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
           89  +This method is part of the main shell command line
           90  +completion. For the details of its workings please read
           91  +[term [vset TITLE_DEV_COMPLETE]].
           92  +
           93  +[para] Given the completion state [arg parse] of a partial
           94  +command line it returns a list of strings which are the valid
    91     95   completions at this point.
    92     96   
    93     97   [list_begin arguments]
    94     98   [arg_def dict parse]
    95     99   A dictionary holding the current completion state of a partial command
    96    100   line.
    97         -
    98         -[para] -- TODO -- Describe the state fields and their meaning.
    99         -
   100    101   [list_end][comment arguments]
   101    102   
   102    103   [comment {- - -- --- ----- -------- -------------}]
   103    104   [call [cmd <officer>] [method continued] [arg line]]
   104    105   
   105    106   This hook-method for the main shell is responsible for the detection
   106    107   of a continuation-line in the entered command [arg line]. It always

Changes to doc/cmdr_parameter.man.

   128    128   [def [const +*]] required, list
   129    129   [def [const ?*]] optional, list.
   130    130   [list_end]
   131    131   
   132    132   [comment {- - -- --- ----- -------- -------------}]
   133    133   [call [cmd <parameter>] [method complete-words] [arg parse]]
   134    134   
   135         -This method is given the completion state [arg parse] of a partial
   136         -command line and returns a list of strings which are the valid
          135  +This method is part of the main shell command line
          136  +completion. For the details of its workings please read
          137  +[term [vset TITLE_DEV_COMPLETE]].
          138  +
          139  +[para] Given the completion state [arg parse] of a partial
          140  +command line it returns a list of strings which are the valid
   137    141   completions at this point, for the parameter.
   138    142   
   139    143   [list_begin arguments]
   140    144   [arg_def dict parse]
   141    145   A dictionary holding the current completion state of a partial command
   142    146   line.
   143         -[para] --TODO-- Describe the state fields and their meaning.
   144    147   [list_end][comment {--- arguments --}]
   145    148   
   146    149   [comment {- - -- --- ----- -------- -------------}]
   147    150   [call [cmd <parameter>] [method config] [arg word...]]
   148    151   
   149    152   This method either returns the [package cmdr::config] instance
   150    153   containing the parameter, or the result of applying the words to that config

Changes to doc/cmdr_private.man.

    73     73   has no need for it, although they have indirect access through
    74     74   parameters and their container.
    75     75   
    76     76   [list_begin definitions]
    77     77   [comment {- - -- --- ----- -------- -------------}]
    78     78   [call [cmd <private>] [method complete-words] [arg parse]]
    79     79   
    80         -This method is given the completion state [arg parse] of a partial
    81         -command line and returns a list of strings which are the valid
           80  +This method is part of the main shell command line
           81  +completion. For the details of its workings please read
           82  +[term [vset TITLE_DEV_COMPLETE]].
           83  +
           84  +[para] Given the completion state [arg parse] of a partial
           85  +command line it returns a list of strings which are the valid
    82     86   completions at this point.
    83     87   
    84     88   [list_begin arguments]
    85     89   [arg_def dict parse]
    86     90   A dictionary holding the current completion state of a partial command
    87     91   line.
    88         -
    89         -[para] -- TODO -- Describe the state fields and their meaning.
    90         -
    91     92   [list_end][comment arguments]
    92     93   
    93     94   [comment {- - -- --- ----- -------- -------------}]
    94     95   [call [cmd <private>] [method do] [opt [arg word]...]]
    95     96   
    96     97   This method parses the [arg word]s of the command line, matching them
    97     98   to the parameters of the private, be they arguments, or options. When

Changes to doc/parts/completion_main.inc.

   101    101   [para] Note that the automaton and its results can be precomputed,
   102    102   this happens in the internal method [method CompletionGraph].
   103    103   
   104    104   [list_end]
   105    105   
   106    106   [list_end]
   107    107   
   108         -[comment { @ EDIT: --- todo --- sequence diagram main shell completion }]
          108  +[comment { @EDIT: --- todo --- sequence diagram main shell completion }]

Changes to doc/parts/completion_mini.inc.

    76     76   
    77     77   [para] The hardwired commands fall here implicitly under unknown
    78     78   parameter.
    79     79   
    80     80   [list_end]
    81     81   [list_end]
    82     82   
    83         -[comment { @ EDIT: --- todo --- sequence diagram mini shell completion }]
           83  +[comment { @EDIT: --- todo --- sequence diagram mini shell completion }]
    84     84