Changeset 438

Show
Ignore:
Timestamp:
05/27/07 22:35:06 (2 years ago)
Author:
athomas
Message:

cly: Fixed a couple of residual restructuring bugs. Documentation updates.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • cly/trunk/cly/interactive.py

    r434 r438  
    270270             *args, **kwargs): 
    271271    """Start an interactive session with the given grammar or parser object.""" 
    272     interact = Interact(grammar, *args, **kwargs) 
     272    interact = Interact(grammar_or_parser, *args, **kwargs) 
    273273    interact.loop(inhibit_exceptions=inhibit_exceptions, 
    274274                  with_backtrace=with_backtrace) 

  • cly/trunk/cly/parser.py

    r434 r438  
    1212__all__ = ['HelpParser', 'Context', 'Parser'] 
    1313__docformat__ = 'restructuredtext en' 
     14 
     15 
     16from cly.exceptions import * 
    1417 
    1518 

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

    r437 r438  
    11CLY Developer's Guide 
    22===================== 
     3 
     4.. contents:: 
    35 
    46Overview 
    …… 
    5658Types of Nodes 
    5759~~~~~~~~~~~~~~ 
    58 CLY includes a whole set of builtin node types, which can be broken down into 
     60CLY includes a whole suite of builtin node types, which can be broken down into 
    5961the following groups: 
    6062 
    …… 
    116118 
    117119For details on what attributes are available for each node class, refer to the 
    118 API documentation. 
     120`API documentation`_. 
    119121 
    120122Optional Branches 
    …… 
    131133  # add <hostname> <ip> [<comment>] 
    132134  add=Node('Add a host')( 
    133       hostname=Variable('Host name')( 
    134           ip=IP('IP address')( 
    135               action=Action('Add host', add_host), 
    136               # Optional comment 
    137               comment=Variable('Comment', pattern=r'.+')( 
    138                   Alias('../../action'), 
    139               ) 
    140           ) 
    141       ), 
     135    hostname=Variable('Host name')( 
     136      ip=IP('IP address')( 
     137        action=Action('Add host', add_host), 
     138        # Optional comment 
     139        comment=Variable('Comment', pattern=r'.+')( 
     140          Alias('../../action'), 
     141        ) 
     142      ) 
     143    ), 
    142144  ) 
    143145 
    144 A second useful situation is aliasing another entire block of the grammar at 
    145 the current location: 
     146A second use of aliases is importing an entire block of the grammar at the 
     147current location. Convenient for allowing multiple optional branches: 
    146148 
    147149.. code-block:: python 
    148150 
     151  def add_host(hostname, ip, comment=''): 
     152    ... 
    149153 
     154  grammar = Grammar( 
     155    add=Node('Add a host')( 
     156      hostname=Variable('Host name')( 
     157        Action('Add host', add_host, valid=lambda context: 'ip' in context.vars), 
     158        Traversals(0)( 
     159        ip=Node('IP address', traversals=0)( 
     160          ip=IP('IP address', traversals=0)( 
     161            Alias('../../../*') 
     162          ), 
     163        ), 
     164        comment=Node('Comment')( 
     165          comment=String('Comment')( 
     166            Alias('../../../*') 
     167          ), 
     168        ), 
     169      ), 
     170    ), 
     171  ) 
     172 
     173.. _API documentation: http://swapoff.org/cly/docs 

  • cly/trunk/doc/tutorial.rst

    r423 r438  
    1313 
    1414For the purposes of this tutorial I will implement a basic "shell", with the 
    15 commands ``ls``, ``cat`` and ``quit``. ``ls`` and ``cat`` will have full tab completion 
    16 of files and directories by the end of the tutorial. 
     15commands ``cat`` and ``quit``. ``cat`` will have full tab completion of files 
     16and directories. 
    1717 
    1818Step One - Fundamentals 
    …… 
    2626 
    2727    from cly import * 
    28     from cly.interactive import Interact 
    29  
    30 The second import introduces the Interact_ class. This class requires only one 
    31 argument, the CLY grammar that represents your interface. 
    32  
    33 The first module imported contains the core API of CLY. Some of the more useful 
    34 classes it includes are ``Context``, ``Node``, ``Alias``, ``Variable``, ``Action``, 
    35 ``Help`` and ``Parser``. 
    3628 
    3729Step Two - Interaction 
    3830---------------------- 
    3931 
    40 Making your program interactive is as simple as constructing an ``Interact`` 
    41 object and calling its ``interact_loop()`` method. 
    42  
    43 .. code-block:: python 
    44  
    45     from cly import * 
    46     from cly.interactive import Interact 
     32Making your program interactive is as simple as calling the ``interact()`` 
     33function with a grammar: 
     34 
     35.. code-block:: python 
     36 
     37    from cly import * 
    4738 
    4839    grammar = Grammar() 
    49     interact = Interact(grammar) 
    50     interact.interact_loop() 
    51  
    52 This calls ``interact_loop()`` with an empty grammar, which won't do much but 
     40    interact(grammar) 
     41 
     42This calls ``interact()`` with an empty grammar, which won't do much but 
    5343will actually allow interaction. 
    5444 
    …… 
    6252    import sys 
    6353    from cly import * 
    64     from cly.interactive import Interact 
    65  
    66     def do_quit(): 
    67         sys.exit(0) 
    68  
    69  
    70     grammar = Grammar( 
    71         quit=Node('Quit')( 
    72             Action('Quit', do_quit), 
    73         ), 
    74     ) 
    75  
    76     interact = Interact(grammar) 
    77     interact.interact_loop() 
     54 
     55    def do_quit(): 
     56        sys.exit(0) 
     57 
     58 
     59    grammar = Grammar( 
     60        quit=Node('Quit')( 
     61            Action('Quit', do_quit), 
     62        ), 
     63    ) 
     64 
     65    interact(grammar) 
    7866 
    7967**Note:** The apparent redundancy of having two *Quit* nodes is explained 
    …… 
    10593    import sys 
    10694    from cly import * 
    107     from cly.interactive import Interact 
    10895 
    10996    def do_quit(): 
    …… 
    124111    ) 
    125112 
    126     interact = Interact(grammar) 
    127     interact.interact_loop() 
     113    interact(grammar) 
    128114 
    129115Step Five - Recursion 
    …… 
    137123    import sys 
    138124    from cly import * 
    139     from cly.interactive import Interact 
    140125 
    141126    def do_quit(): 
    …… 
    158143    ) 
    159144 
    160     interact = Interact(grammar) 
    161     interact.interact_loop() 
     145    interact(grammar) 
    162146 
    163147Each ``Node`` has a ``traversals`` member which specifies the number of times that 
    …… 
    183167    import sys 
    184168    from cly import * 
    185     from cly.variables import File 
    186     from cly.interactive import Interact 
    187169 
    188170    def do_quit(): 
    …… 
    205187    ) 
    206188 
    207     interact = Interact(grammar) 
    208     interact.interact_loop() 
     189    interact(grammar) 
    209190 
    210191Variables can be used to not only validate input, but parse it into a useful 
    …… 
    220201behaviour of your command line applications. 
    221202 
    222 .. _Interact: http://swapoff.org/cly/docs/cly.interactive 
    223203.. _other features: http://swapoff.org/cly/docs