Changeset 441

Show
Ignore:
Timestamp:
05/31/07 20:20:22 (2 years ago)
Author:
athomas
Message:

cly: More docs.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • cly/trunk/doc/developers-guide.rst

    r440 r441  
    88 
    99CLY allows developers to quickly and easily add interactive shell environments 
    10 to their programs, existing or new. 
     10to their applications, whether existing or new. 
    1111 
    1212It offers a simple syntax for defining grammars and a powerful interactive 
    …… 
    1919The developer defines their syntax using a hierarchy of objects. Syntactically, 
    2020child nodes are attached to their parent by ''calling'' the parent with the 
    21 children as positional or keyword arguments. Each positional argument is 
    22 treated as an `anonymous node` and thus should usually be reserved for terminal 
    23 nodes or nodes whose help will be explicitly overridden. The keyword of each 
    24 keyword argument is interpreted as the shell command at that position in the 
    25 grammar in addition to, unless overridden, the name of that child node. 
     21children as positional or keyword arguments. The actual key of each keyword 
     22argument is interpreted as the command at that position in the grammar.  
     23Additionally, unless overridden, it is treated as the name of that child node. 
     24Each positional argument is treated as an `anonymous node` and thus should 
     25usually be reserved for terminal nodes or nodes whose name, pattern and help 
     26will be explicitly overridden.  
    2627 
    2728Here is a simple example: 
    …… 
    4647  ONE_TWO := 'one_two' 
    4748 
     49Or, in more readable terms, this set of commands:: 
     50 
     51  one one_one 
     52  one one_two 
     53  two 
     54 
    4855Help! 
    4956~~~~~ 
    50 The first argument to every CLY grammar node **must** be a help string. This is 
    51 used to construct contextual help when a user presses `?`. 
    52  
    53 Context 
    54 ~~~~~~~ 
    55 Each command is parsed in a new context. The context stores state like 
    56 variables collected, number of traversals of nodes, etc. Mostly, it can be 
    57 ignored but is mentioned here for reference. 
     57The first argument to every CLY grammar node **must** be either a help string 
     58or a callable that returns an iterable of ``(key, help)`` tuples. This is used 
     59to construct contextual help when a user presses `?`. 
     60 
     61In the vast majority of cases a simple string, or possibly a pair, will be sufficient. 
     62For when it is not, the convenience class ``cly.parser.Help`` is available to 
     63construct help, either from a single pair: 
     64 
     65  .. code-block:: python 
     66 
     67    one=Node(Help.pair('one', 'Command 1')) 
     68 
     69or from a list of tuples: 
     70 
     71  .. code-block:: python 
     72 
     73    help = [('one', 'Command 1'), 
     74            ('1', 'Command 1')] 
     75 
     76    one=Node(Help(help), pattern=r'one|1') 
    5877 
    5978Types of Nodes 
    …… 
    6786 
    6887``Grammar`` 
    69     The root of the grammar. Contains all other nodes. 
     88    The root of the grammar. Contains all other nodes and acts purely as a 
     89    container and a match for the beginning of input. 
    7090 
    7191``Group`` 
    …… 
    80100 
    81101``Variable`` 
    82     Variable nodes insert their matching input into the ``vars`` of the 
    83     ``Context``, after being parsed by the ``parse()`` method. If the attribute 
    84     ``traversals != 1``, values are collected into a list rather than a scalar. 
    85     CLY includes a number of potentially useful ``Variable`` subclasses such as 
    86     ``URI``, ``Integer``, ``Float``, etc. 
     102    Variable nodes insert their matching input into the ``vars`` dictionary of 
     103    the ``Context``, after being parsed by the ``parse()`` method. If the 
     104    ``Variable`` attribute ``traversals`` is not 1, values are collected into a 
     105    list rather than a scalar.  CLY includes a number of potentially useful 
     106    ``Variable`` subclasses such as ``URI``, ``Integer``, ``Float``, etc. 
    87107 
    88108``Action`` 
    …… 
    90110    passes any ``vars`` parsed by previous ``Variable`` nodes through to the 
    91111    callback as arguments. 
     112 
     113Full details are available in the `API documentation`_. 
    92114 
    93115Node Attributes and Constructor Arguments 
    …… 
    127149most common of which is simply allowing optional nodes: 
    128150 
    129 .. code-block:: python 
    130  
    131   def add_host(hostname, ip, comment=''): 
    132     ... 
    133  
    134   # add <hostname> <ip> [<comment>] 
    135   add=Node('Add a host')( 
    136     hostname=Variable('Host name')( 
    137       ip=IP('IP address')( 
    138         action=Action('Add host', add_host), 
    139         # Optional comment 
    140         comment=Variable('Comment', pattern=r'.+')( 
    141           Alias('../../action'), 
     151  .. code-block:: python 
     152 
     153    def add_host(hostname, ip, comment=''): 
     154      ... 
     155 
     156    # add <hostname> <ip> [<comment>] 
     157    add=Node('Add a host')( 
     158      hostname=Variable('Host name')( 
     159        ip=IP('IP address')( 
     160          action=Action('Add host', add_host), 
     161          # Optional comment 
     162          comment=Variable('Comment', pattern=r'.+')( 
     163            Alias('../../action'), 
     164          ) 
    142165        ) 
    143       ) 
    144     ), 
    145   ) 
     166      ), 
     167    ) 
     168 
     169Which yields a syntax similar to: 
     170 
     171  .. code-block:: xml 
     172 
     173    add <hostname> <ip> [<comment>] 
    146174 
    147175A second use of aliases is importing an entire block of the grammar at the 
    148176current location. Convenient for allowing multiple optional branches: 
    149177 
    150 .. code-block:: python 
    151  
    152   def add_host(hostname, ip, comment=''): 
    153     ... 
    154  
    155   grammar = Grammar( 
    156     add=Node('Add a host')( 
    157       hostname=Variable('Host name')( 
    158         Action('Add host', add_host, valid=lambda context: 'ip' in context.vars), 
    159         ip=Node('IP address', traversals=0)( 
    160           ip=IP('IP address', traversals=0)( 
    161             Alias('../../../*') 
     178  .. code-block:: python 
     179 
     180    def add_host(hostname, ip, comment=''): 
     181      ... 
     182 
     183    grammar = Grammar( 
     184      add=Node('Add a host')( 
     185        hostname=Variable('Host name')( 
     186          Action('Add host', add_host, valid=lambda context: 'ip' in context.vars), 
     187          ip=Node('IP address', traversals=0)( 
     188            ip=IP('IP address', traversals=0)( 
     189              Alias('../../../*') 
     190            ), 
     191          ), 
     192          comment=Node('Comment')( 
     193            comment=String('Comment')( 
     194              Alias('../../../*') 
     195            ), 
    162196          ), 
    163197        ), 
    164         comment=Node('Comment')( 
    165           comment=String('Comment')( 
    166             Alias('../../../*') 
    167           ), 
    168         ), 
    169       ), 
    170     ), 
    171   ) 
    172  
    173 Which corresponds to something like this command syntax:: 
    174  
    175   add <hostname> ip <ip> [ip <ip> [ip <ip> ...]] [comment <comment>] 
     198      ), 
     199    ) 
     200 
     201Which corresponds to something like this command syntax: 
     202 
     203  .. code-block:: xml 
     204 
     205    add <hostname> ip <ip> [ip <ip> [ip <ip> ...]] [comment <comment>] 
     206 
     207Context 
     208~~~~~~~ 
     209Each command is parsed within a context. The context stores state information 
     210such as variables collected, number of traversals of nodes, cursor location, 
     211etc.  Mostly it can be ignored, but is mentioned here for reference. 
    176212 
    177213.. _API documentation: http://swapoff.org/cly/docs 

  • cly/trunk/doc/makedocs.py

    r419 r441  
    2222    } 
    2323 
    24   The directive requires the name of a language supported by SilverCity 
     24  The directive requires the name of a language supported by Pygments 
    2525  as its only argument.  All code in the indented block following 
    2626  the directive will be colourized.  Note that this directive is only