Python: module boopak.sparse

boopak.sparse | index boopak/sparse.py

`sparse: A module which implements simple S-expressions.
An S-expression is a string, or a parenthesized list of S-expressions.
In other words, good old Lisp-style expressions. This implementation
also allows named elements in lists (as well as the usual positional
elements).
The following are valid S-expressions:
string
()
(string)
(one two three)
(key=value key2=value2)
(list (containing a list) and ((another)))
(one two named=(inner (list) ()))
A string can containing special characters -- whitespace, quotes, equals,
parentheses -- if it is quoted. Single or double quotes can be used.
Inside a quoted string, quotes and backslashes should be escaped with
a backslash. So the following are also valid:
"quote " mark"
'single quote ' mark'
"smiley =o) clown"
Note that these three expressions are identical:
string
"string"
'string'
However, the following are not identical:
(string)
"(string)"
The former is a list containing one string; the latter is a string.
This module lets you convert the textual representation of an expression
into a structured representation -- a tree of Tree objects. (The subclasses
of Tree are List and ID, representing lists and strings.)
Classes:
Tree -- represents an S-expression
List -- subclass which represents a list expression
ID -- subclass which represents a string expression
Public functions:
parse() -- parse a string which contains exactly one S-expression
Internal classes:
AttrToken -- represents a named value encountered during parsing
ParseContext -- represents the state of an ongoing parse() operation`

Modules
`` |  |
StringIO | codecs |  |

Classes
`` |  | AttrToken ParseContext Tree ID List exceptions.Exception(exceptions.BaseException) ParseError
class AttrToken
`` | `AttrToken: represents a named value encountered during parsing. This is an internal class; it should not be used outside this module.`
| Methods defined here: __init__(self, key)
class ID(Tree)
`` | `ID: represents a string expression. ID(val) -- constructor The value that you pass to the constructor may be str or unicode. It becomes the ID's underlying string value, so it should not be quoted or escaped. For any str or unicode val, ID(val).as_string() == val`
| Methods defined here: __cmp__(self, other) __init__(self, id) __len__(self) as_boolean(self) as_float(self) as_integer(self) as_string(self) serialize(self) Methods inherited from Tree: __repr__(self)
class List(Tree)
`` | `List: represents a list expression. A list can contain positional entries and named values; it therefore acts as both an array and a dict. Array-style operations: len(l) l[int] l[int:int] l.append(tree) Dict-style operations: l.has_attr(key) l.get_attr(key) l.set_attr(key, tree) (The keys in these operations must be strings.) Positional (array) values and named (dict) values are separate. If l has no positional values, len(l) is zero, no matter how many named values it has. Contrariwise, l.get_attr() will never retrieve a positional value. List(val, val, ... key=val, key=val) -- constructor Construct a List with the given named and/or positional values. All values must be Trees. You can also construct a List from a Python list or dict, using the forms List(*list) or List(**dict).`
| Methods defined here: __contains__(self, it) __getitem__(self, key) __init__(self, *args, **attrs) __iter__(self) __len__(self) append(self, val) `append(val) -> None Add the Tree as the last positional entry.` get_attr(self, key) `get_attr(key) -> Tree Retrieve the named Tree which has the given key. If there is no entry with that key, returns None.` has_attr(self, key) `has_attr(key) -> bool Returns whether there is an entry with the given key.` serialize(self) set_attr(self, key, val) `set_attr(key, val) -> None Add the Tree val as a named entry, with the given key.` Methods inherited from Tree: __repr__(self) as_boolean(self) `as_boolean() -> bool Get the boolean value which this tree represents. The empty string is considered false, as are '0', 'no', or 'false'. Or really any string beginning with '0', 'n', 'N', 'f', or 'F'. Anything else is true. Raises ValueError if called on a List.` as_float(self) `as_float() -> float Get the float value which this tree represents. Raises ValueError if called on a List, or on a string which is not interpretable as a float.` as_integer(self) `as_integer() -> int or long Get the integer value which this tree represents. Raises ValueError if called on a List, or on a string which is not interpretable as an integer.` as_string(self) `as_string() -> str or unicode Get the string which this tree represents. (The result is not quoted or escaped; it is the underlying string value.) Raises ValueError if called on a List.`
class ParseContext
`` | `ParseContext: represents the state of an ongoing parse() operation. Parsing S-expressions is quite simple; we only need a stream of characters and the ability to look ahead by one. (Or, if you like, the ability to push one character back onto the stream.) Fields: fl -- a file-like object, from which characters are read. nextch -- if a character has been pushed back, it is here; if not, this is None. Constructor: ParseContext(fl) -- constructor`
| Methods defined here: __init__(self, fl) close(self) `close() -> None Shut down the parser, and close the underlying stream.` finalwhite(self) `finalwhite() -> None Ensure that there are no more expressions in the stream. Trailing whitespace is ignored. Raises ParseError on failure.` parseattr(self) `parseattr() -> Tree Parse the value part of a named value. The stream must be after the equals sign.` parseid(self) `parseid() -> ID or AttrToken Parse an unquoted string expression. The stream must be at the beginning of the expression.` parselist(self) `parselist() -> List Parse a parenthesized list expression. The stream must be at the beginning of the list contents, after the open parenthesis.` parsestring(self) `parsestring() -> ID Parse an quoted string expression. The stream must be at the beginning of the expression, before the initial quote.` parsetree(self) `parsetree() -> Tree or EndOfList or AttrToken Parse one expression from the stream, and return the Tree that represents it. Leading whitespace is ignored. EndOfList indicates that a closing parenthesis has been reached; an AttrToken instance indicates a named value such as x=y. These are not valid expressions on their own; they can only occur inside lists.`
class ParseError(exceptions.Exception)
`` | `ParseError: represents an error parsing string data into Trees.`
| Method resolution order: ParseError exceptions.Exception exceptions.BaseException __builtin__.object Data descriptors defined here: __weakref__ `list of weak references to the object (if defined)` Methods inherited from exceptions.Exception: __init__(...) `x.__init__(...) initializes x; see x.__class__.__doc__ for signature` Data and other attributes inherited from exceptions.Exception: __new__ = <built-in method __new__ of type object> `T.__new__(S, ...) -> a new object with type S, a subtype of T` Methods inherited from exceptions.BaseException: __delattr__(...) `x.__delattr__('name') <==> del x.name` __getattribute__(...) `x.__getattribute__('name') <==> x.name` __getitem__(...) `x.__getitem__(y) <==> x[y]` __getslice__(...) `x.__getslice__(i, j) <==> x[i:j] Use of negative indices is not supported.` __reduce__(...) __repr__(...) `x.__repr__() <==> repr(x)` __setattr__(...) `x.__setattr__('name', value) <==> x.name = value` __setstate__(...) __str__(...) `x.__str__() <==> str(x)` Data descriptors inherited from exceptions.BaseException: __dict__ args message `exception message`
class Tree
`` | `Tree: represents an S-expression. This is a virtual base class. Do not instantiate it; instead use the List or ID class.`
| Methods defined here: __repr__(self) as_boolean(self) `as_boolean() -> bool Get the boolean value which this tree represents. The empty string is considered false, as are '0', 'no', or 'false'. Or really any string beginning with '0', 'n', 'N', 'f', or 'F'. Anything else is true. Raises ValueError if called on a List.` as_float(self) `as_float() -> float Get the float value which this tree represents. Raises ValueError if called on a List, or on a string which is not interpretable as a float.` as_integer(self) `as_integer() -> int or long Get the integer value which this tree represents. Raises ValueError if called on a List, or on a string which is not interpretable as an integer.` as_string(self) `as_string() -> str or unicode Get the string which this tree represents. (The result is not quoted or escaped; it is the underlying string value.) Raises ValueError if called on a List.` serialize(self) `serialize() -> str or unicode Convert this tree into its textual representation. Strings will be quoted and escaped if necessary.`

Functions
`` |  | escaper = unicode_escape_encode(...) parse(val) `parse(val) -> Tree Parse a str or unicode value which contains *exactly one* S-expression. The value must contain one string (possibly quoted), or one parenthesized list. If the expression is ill-formed (unbalanced parentheses or quotes), this raises ParseError. Whitespace before or after the expression is ignored. Inside a list, whitespace separates expressions, but the amount is not significant. Note that parse('') raises ParseError, because it does not contain any expression.`

Data
`` |  | EndOfList = <object object>