Changeset 547

Show
Ignore:
Timestamp:
06/10/08 09:14:48 (6 months ago)
Author:
athomas
Message:

Lots of docstring updates.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • cly/trunk/cly/builder.py

    r527 r547  
    3232    """The base class for all grammar nodes. 
    3333 
    34     Constructor arguments are: 
    35  
    36     ``help=''``: string or callable returning a list of (key, help) tuples 
     34    :param help: 
     35        string or callable returning a list of (key, help) tuples 
    3736        A help string or a callable returning an iterable of (key, help) 
    3837        pairs. There is a useful class called Help which can be used for 
    3938        this purpose. 
    4039 
    41     ``name=None``: string 
     40    :param name: 
    4241        The name of the node. If ommitted the key used by the parent Node 
    4342        is used. The node name also defines the node path: 
    …… 
    5049    you find yourself using a particular pattern repeatedly. 
    5150 
    52     ``pattern=None``: regular expression string 
     51    :param pattern: 
    5352        The regular expression used to match user input. If not provided, 
    5453        the node name is used: 
    …… 
    5857        True 
    5958 
    60     ``separator=r'\s+|\s*$'``: regular expression string 
     59    :param separator: 
    6160        A regular expression used to match the text separating this node 
    6261        and the next. 
    6362 
    64     ``group=0``: integer 
     63    :param group: 
    6564        Nodes can be grouped together to provide visual cues. Groups are 
    6665        ordered ascending numerically. 
    6766 
    68     ``order=0``: integer 
     67    :param order: 
    6968        Within a group, nodes are normally ordered alphabetically. This can 
    7069        be overridden by setting this to a value other than 0. 
    7170 
    72     ``match_candidates=False``: boolean 
     71    :param match_candidates: 
    7372        The candidates() method returns a list of words that match at the 
    7473        current token, which are then used for completion, but can also be 
    …… 
    7877        files in the current directory). 
    7978 
    80     ``traversals=1``: integer 
     79    :param traversals: 
    8180        The number of times this node can match in any parse context. Alias 
    8281        nodes allow for multiple traversal. 
    …… 
    151150                continue 
    152151            if not isinstance(node, Node): 
    153                 raise InvalidAnonymousNode('Anonymous node is not a Node object') 
     152                raise InvalidAnonymousNode('"%r" must be a Node object' % node) 
    154153            # TODO Convert help to name instead of __anonymous_<n> 
    155154            node.name = '__anonymous_%i' % self.__anonymous_children 
    …… 
    458457    Constructor arguments: 
    459458 
    460     ``alias``: relative or absolute grammar path 
    461         Path to the aliased node. If the alias contains glob characters (``*`` 
    462         or ``?``) all matching nodes are aliased. 
     459    :param alias: 
     460        Relative or absolute path to the aliased node. If the alias contains 
     461        glob characters (``*`` or ``?``) all matching nodes are aliased. 
    463462 
    464463    >>> from cly.parser import Parser, Context 
    …… 
    670669        """Build a CLY Grammar from XML. 
    671670 
    672         ``xml``: string 
    673             XML source 
    674         ``extra_nodes``: dictionary 
     671        :param xml: 
     672            XML source as a string. 
     673        :param extra_nodes: 
    675674            Dictionary of Node subclasses. 
    676         ``extra_locals``: 
     675        :param extra_locals: 
    677676            Valid locals() when evaluating XML grammar node attributes. 
    678677 
    …… 
    771770 
    772771 
    773 def xml_lazy_attr_evaluator(attr, positional_args=None): 
     772def _xml_lazy_attr_evaluator(attr, positional_args=None): 
    774773    """Return a callable that lazily evaluates an expression. 
    775774 
    …… 
    815814 
    816815 
    817 def xml_boolean_type(value): 
     816def _xml_boolean_type(value): 
    818817    """Converter for boolean attributes.""" 
    819818    return str(value).lower() in ('true', '1', 'yes') 
    820819 
    821820 
    822 def xml_group_type(value): 
     821def _xml_group_type(value): 
    823822    """Parse a group="n" attribute.""" 
    824823    try: 
    …… 
    907906    default_attr_type_map = { 
    908907        'traversals': int, 
    909         'group': xml_group_type, 
     908        'group': _xml_group_type, 
    910909        'order': int, 
    911         'match_candidates': xml_boolean_type, 
    912         'with_context': xml_boolean_type, 
     910        'match_candidates': _xml_boolean_type, 
     911        'with_context': _xml_boolean_type, 
    913912        } 
    914913 
    …… 
    10101009                else: 
    10111010                    args = [] 
    1012                 v = xml_lazy_attr_evaluator(v, args) 
     1011                v = _xml_lazy_attr_evaluator(v, args) 
    10131012 
    10141013            attributes[k] = v 
    …… 
    10231022    Constructor arguments 
    10241023 
    1025     ``doc``: 
     1024    :param doc: 
    10261025        An iterable of two element tuples in the form ``(key, help)``. 
    10271026 

  • cly/trunk/cly/console.py

    r527 r547  
    520520    if width > term_width or expand_to_fit: 
    521521        scale = float(term_width) / width 
    522         widths = [int(w * scale) for w in widths] 
     522        widths = [max(1, int(w * scale)) for w in widths] 
    523523 
    524524    row_alt = -1 

  • cly/trunk/cly/extra.py

    r492 r547  
    77# 
    88 
    9 """Useful functions for use in conjunction with CLY.""" 
     9"""Useful functions for CLY.""" 
    1010 
    1111 

  • cly/trunk/cly/interactive.py

    r520 r547  
    1515customisable completion key, interactive help and more. 
    1616 
    17 Press ``?`` at any location to contextual help. 
     17Press ``?`` at any time to view contextual help. 
    1818""" 
    1919 
    …… 
    180180    Constructor arguments: 
    181181 
    182     ``parser``: ``Parser`` or ``Grammar`` object 
     182    :param parser: 
    183183        The parser/grammar to use for interaction. 
    184184 
    185     ``application='cly'``: string 
     185    :param application: 
    186186        The application name. Used to construct the history file name and 
    187187        prompt, if not provided. 
    188188 
    189     ``prompt=None``: string 
     189    :param prompt: 
    190190        The prompt. 
    191191 
    192     ``user_context=None``: `anything` 
     192    :param user_context: 
    193193        A user-specified object to pass to the parser. The parser builds each 
    194194        parse ``Context`` with this object, which in turn will deliver this 
    195195        object on to terminal nodes that have set ``with_context=True``. 
    196196 
    197     ``with_context=False``: `boolean` 
     197    :param with_context: 
    198198        Force current parser Context to be passed to all action nodes, unless 
    199199        they explicitly set the member variable ``with_context=False``. 
    200200 
    201     ``history_file=None``: `string` 
     201    :param history_file: 
    202202        Defaults to ``~/.<application>_history``. 
    203203 
    204     ``history_length=500``: `integer` 
     204    :param history_length: 
    205205        Lines of history to keep. 
     206 
     207    :param inhibit_exceptions: 
     208        As for :meth:`loop`. 
     209 
     210    :param with_backtrace: 
     211        As for :meth:`loop`. 
    206212    """ 
    207213 
    …… 
    235241        executed command. 
    236242 
    237         default_text 
     243        :param default_text: 
    238244            Text to insert into the input buffer prior to editing. 
    239245        """ 
    …… 
    261267        """Repeatedly read and execute commands from the user. 
    262268 
    263         inhibit_exceptions : boolean 
     269        :param inhibit_exceptions: 
    264270            Normally, ``interact_loop`` will pass exceptions back to the caller for 
    265271            handling. Setting this to ``True`` will cause an error message to 
    266272            be printed, but interaction will continue. 
    267273 
    268         with_backtrace : boolean 
     274        :param with_backtrace: 
    269275            Whether to print a full backtrace when ``inhibit_exceptions=True``. 
    270276 
    271         callback 
     277        :param callback: 
    272278            Called with the Interact object before each line is displayed. 
    273279        """ 
    …… 
    328334        self.input_driver.prompt = prompt 
    329335 
    330     prompt = property(_get_prompt, _set_prompt) 
     336    prompt = property(_get_prompt, _set_prompt, doc='Prompt. Can be set.') 
    331337 
    332338 

  • cly/trunk/cly/parser.py

    r520 r547  
    11# -*- coding: utf-8 -*- 
    22# 
    3 # Copyright (C) 2006-2007 Alec Thomas <alec@swapoff.org> 
     3# Copyright (C) 2006-2008 Alec Thomas <alec@swapoff.org> 
    44# 
    55# This software is licensed as described in the file COPYING, which 
    …… 
    77# 
    88 
    9 """CLY grammar and help parsers, and support classes.""" 
     9"""CLY parser classes.""" 
    1010 
    1111 
    …… 
    8888    """Represents the parsing context of a single command. 
    8989 
    90     The context contains all the information the parser needs to maintain 
    91     state while parsing the input command. 
     90    A parse context is created automatically when input is parsed. It contains all 
     91    the information needed to parse input tokens, including the current cursor 
     92    position in the input stream, the current node in the grammar, variables 
     93    collected and a history of nodes traversed. 
     94  
     95    Basic usage is:: 
     96  
     97      parser = Parser(grammar) 
     98      context = parser.parse('some input text') 
     99      print context.vars 
     100  
     101    If the input is invalid the context will have consumed as much input as 
     102    possible. The attributes ``parsed`` and ``remaining`` contain how much text has 
     103    been consumed and remains, respectively. 
     104 
    92105    """ 
    93106    def __init__(self, parser, command, user_context=None): 
    …… 
    229242 
    230243class Parser(object): 
    231     """Parse and execute CLY grammars.""" 
     244    """Parse and execute CLY grammars. 
     245     
     246    A grammar is simply a data structure. To actually utilise it one needs to bind 
     247    it to a ``Parser`` object and parse some input with it. The parser takes care 
     248    of creating a ``Context`` for each parse run, parsing the input, and executing 
     249    any callbacks. 
     250  
     251    .. note:: 
     252       *parser* in this context refers to parsing user input, *not* parsing CLY 
     253       grammars. 
     254    """ 
    232255    def __init__(self, grammar, user_context=None, with_user_context=False, 
    233256                 with_context=False):