cmdr
Check-in [67f83ccddb]
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:Another placeholder, for the DSL spec, and filled out actor reference
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 67f83ccddb0000d87987191582993a7f2fbcec02
User & Date: andreask 2013-11-05 00:40:43
Context
2013-11-05
05:55
Updated embedded documentation check-in: ca14a9b8c1 user: aku tags: trunk
00:40
Another placeholder, for the DSL spec, and filled out actor reference check-in: 67f83ccddb user: andreask tags: trunk
2013-11-04
22:45
Moved all title setup into definitions. check-in: d1574f44fb user: andreask tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to doc/cmdr_actor.man.

            1  +[comment {-*- tcl -*- doctools manpage}]
            2  +[include parts/definitions.inc]
            3  +[manpage_begin [vset PROJECT]_actor [vset MAN_SECTION] [vset VERSION]]
            4  +[include parts/module.inc]
            5  +[require cmdr::util]
            6  +[titledesc [vset TITLE_ACTOR]]
            7  +[description]
            8  +[include parts/welcome.inc]
            9  +
           10  +This internal package implements the base class containing functionality
           11  +common to [package cmdr::officer] and [package cmdr::private].
           12  +
           13  +--TODO-- Describe the common parts (common blocks, super chain, completion support, DSL support)
           14  +
           15  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           16  +[section {Class API}]
           17  +
           18  +The class API is not public. It is used internally by the framework
           19  +when parsing a command hierarchy specification to create the necessary
           20  +command instances.
           21  +
           22  +[para] It is described here for use by developers maintaining,
           23  +modifying and extending the framework itself. A user of the framework
           24  +has no need for it.
           25  +
           26  +[list_begin definitions]
           27  +[comment {- - -- --- ----- -------- -------------}]
           28  +[call [cmd ::cmdr::actor] [method new]]
           29  +
           30  +Create an auto-named instance of [class cmdr::actor].
           31  +[para] [emph {Not used}].
           32  +
           33  +[comment {- - -- --- ----- -------- -------------}]
           34  +[call [cmd ::cmdr::actor] [method create] [arg obj]]
           35  +
           36  +Create a new instance of [class cmdr::actor], named [arg obj].
           37  +
           38  +[list_end][comment definitions]
           39  +
           40  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
           41  +[section {Instance API}]
           42  +
           43  +Most of the instance API is not public.
           44  +
           45  +[para] It is described here for use by developers maintaining,
           46  +modifying and extending the framework itself. A user of the framework
           47  +has no need for it.
           48  +
           49  +[list_begin definitions]
           50  +[comment {- - -- --- ----- -------- -------------}]
           51  +[call [cmd <actor>] [method completions] [arg parse] [arg cmdlist]]
           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.
           57  +
           58  +[list_begin arguments]
           59  +[arg_def dict parse]
           60  +A dictionary holding the current completion state of a partial command
           61  +line.
           62  +
           63  +[para] -- TODO -- Describe the state fields and their meaning.
           64  +
           65  +[arg_def list cmdlist]
           66  +List of valid completions.
           67  +[list_end][comment arguments]
           68  +
           69  +[comment {- - -- --- ----- -------- -------------}]
           70  +[call [cmd <actor>] [method description]]
           71  +
           72  +This accessor method returns the human-readable description of the
           73  +actor.
           74  +
           75  +[comment {- - -- --- ----- -------- -------------}]
           76  +[call [cmd <actor>] [method description:] [arg text]]
           77  +
           78  +This method sets the description of the actor to the [arg text].
           79  +
           80  +[list_begin arguments]
           81  +[arg_def string text] The description to remember.
           82  +[list_end][comment {--- arguments --}]
           83  +
           84  +[comment {- - -- --- ----- -------- -------------}]
           85  +[call [cmd <actor>] [method dname]]
           86  +
           87  +This accessor method returns the display name of the actor.  This is
           88  +the [method name] of the actor prefixed with the contents of the
           89  +reserved common block [const *prefix*], set during command line
           90  +processing with the actual command path to reach the current actor.
           91  +
           92  +[comment {- - -- --- ----- -------- -------------}]
           93  +[call [cmd <actor>] [method do] [opt [arg word...]]]
           94  +
           95  +This method processes the command-line given as a list of words.  Here
           96  +in the bse class it does nothing. It is a virtual method expecting to
           97  +be redefined by the derived classes.
           98  +
           99  +[list_begin arguments]
          100  +[arg_def list word]
          101  +[list_end][comment {--- arguments --}]
          102  +
          103  +[comment {- - -- --- ----- -------- -------------}]
          104  +[call [cmd <actor>] [method documented]]
          105  +
          106  +This accessor method returns the "documented" flag of the actor.
          107  +
          108  +[comment {- - -- --- ----- -------- -------------}]
          109  +[call [cmd <actor>] [method exists] [arg key]]
          110  +
          111  +This method returns a boolean value indicating whether the common
          112  +block named by [arg key] exists in the actor and its parents
          113  +([const true]), or not ([const false]).
          114  +
          115  +[list_begin arguments]
          116  +[arg_def string key]
          117  +The name of the common block to check for.
          118  +[list_end][comment {--- arguments --}]
          119  +
          120  +[comment {- - -- --- ----- -------- -------------}]
          121  +[call [cmd <actor>] [method fullname]]
          122  +
          123  +This method returns the full name of the actor.
          124  +
          125  +This is the [method name] of the actor prefixed with the path to it in
          126  +the specification, i.e. the names of all actors in the chain of
          127  +supers.
          128  +
          129  +[comment {- - -- --- ----- -------- -------------}]
          130  +[call [cmd <actor>] [method get] [arg key]]
          131  +
          132  +This method returns the content of the common block named by
          133  +[arg key]. An error is thrown if the block is not known to the actor,
          134  +nor its parents.
          135  +
          136  +[list_begin arguments]
          137  +[arg_def string key]
          138  +The name of the common block to retrieve.
          139  +[list_end][comment {--- arguments --}]
          140  +
          141  +[comment {- - -- --- ----- -------- -------------}]
          142  +[call [cmd <actor>] [method help]]
          143  +
          144  +This accessor method returns the empty string. It is a virtual method
          145  +expecting to be redefined by the derived classes.
          146  +
          147  +[comment {- - -- --- ----- -------- -------------}]
          148  +[call [cmd <actor>] [method keys]]
          149  +
          150  +This accessor method returns a list of names for the set of common
          151  +blocks known to this actor, and all of its parents.
          152  +
          153  +[comment {- - -- --- ----- -------- -------------}]
          154  +[call [cmd <actor>] [method lappend] [arg key] [arg data]]
          155  +
          156  +This method extends the contents of the common block named
          157  +by [arg key] with [arg data].
          158  +
          159  +Conceptually this is a get/lappend/set operation, i.e. while the
          160  +existing block content is taken from the actor or its parents, the new
          161  +content is always stored in the actor.
          162  +
          163  +[list_begin arguments]
          164  +[arg_def string key]  The name of the common block to extend.
          165  +[arg_def any    data] The data to add to the block.
          166  +[list_end][comment {--- arguments --}]
          167  +
          168  +[comment {- - -- --- ----- -------- -------------}]
          169  +[call [cmd <actor>] [method match] [arg parse] [arg cmdlist]]
          170  +
          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.
          175  +
          176  +[list_begin arguments]
          177  +[arg_def dict parse]
          178  +A dictionary holding the current completion state of a partial command
          179  +line.
          180  +
          181  +[para] -- TODO -- Describe the state fields and their meaning.
          182  +
          183  +[arg_def list cmdlist]
          184  +List of possible completions.
          185  +[list_end][comment arguments]
          186  +
          187  +[comment {- - -- --- ----- -------- -------------}]
          188  +[call [cmd <actor>] [method name]]
          189  +
          190  +This accessor method returns the name of the actor.
          191  +
          192  +[comment {- - -- --- ----- -------- -------------}]
          193  +[call [cmd <actor>] [method name:] [arg name]]
          194  +
          195  +This method sets the name of the actor.
          196  +
          197  +[list_begin arguments]
          198  +[arg_def string name]
          199  +The name to remember.
          200  +[list_end][comment {--- arguments --}]
          201  +
          202  +[comment {- - -- --- ----- -------- -------------}]
          203  +[call [cmd <actor>] [method parse-line] [arg line]]
          204  +
          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.
          209  +
          210  +[list_begin arguments]
          211  +[arg_def string line]
          212  +The command line.
          213  +[list_end][comment {--- arguments --}]
          214  +
          215  +
          216  +[comment {- - -- --- ----- -------- -------------}]
          217  +[call [cmd <actor>] [method root]]
          218  +
          219  +This accessor method returns the root actor instance the actor belongs
          220  +to.
          221  +
          222  +[comment {- - -- --- ----- -------- -------------}]
          223  +[call [cmd <actor>] [method set] [arg key] [arg data]]
          224  +
          225  +This method sets the contents of the common block named by [arg key]
          226  +to [arg data]. If the block does not exist it is created. Otherwise
          227  +its existing content is written over.
          228  +
          229  +[list_begin arguments]
          230  +[arg_def string key]  The name of the common block to write.
          231  +[arg_def any    data] The data to store in the block.
          232  +[list_end][comment {--- arguments --}]
          233  +
          234  +[comment {- - -- --- ----- -------- -------------}]
          235  +[call [cmd <actor>] [method super]]
          236  +
          237  +This accessor method returns the parent actor instance.  For the root
          238  +of the tree this is the empty string.
          239  +
          240  +[comment {- - -- --- ----- -------- -------------}]
          241  +[call [cmd <actor>] [method super:] [arg obj]]
          242  +
          243  +This method links the actor to its parent actor.
          244  +
          245  +[list_begin arguments]
          246  +[arg_def cmdr::actor obj]
          247  +The parent actor instance to remember.
          248  +[list_end][comment {--- arguments --}]
          249  +
          250  +[comment {- - -- --- ----- -------- -------------}]
          251  +[call [cmd <actor>] [method undocumented]]
          252  +
          253  +This method marks the actor as undocumented.
          254  +
          255  +[comment {- - -- --- ----- -------- -------------}]
          256  +[call [cmd <actor>] [method unset] [arg key]]
          257  +
          258  +This method removes the common block named by [arg key]
          259  +from the actor. Note that definitions in parents are
          260  +not touched by this.
          261  +
          262  +[list_begin arguments]
          263  +[arg_def string key]  The name of the common block to remove.
          264  +[list_end][comment {--- arguments --}]
          265  +
          266  +[list_end][comment {-- definitions --}]
          267  +
          268  +
          269  +[comment @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@]
          270  +[section {Help Information}]
          271  +[include parts/help_structure.inc]
          272  +
          273  +[include parts/feedback.inc]
          274  +[manpage_end]

Added doc/cmdr_dsl.man.