S-expressions

Locations

class binflakes.sexpr.location.TextLocationRange(filename, start_line, start_column, end_line, end_column)

Bases: object

Represents a range of locations in one input file, with both endpoints included.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.location.TextLocationSingle(filename, line, column)

Bases: object

Represents a single (filename, line, column) location in the input.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__sub__(other)

Returns a TextLocationRange corresponding to the range starting from the first single location (included) until the second single location (excluded).

__weakref__

list of weak references to the object (if defined)

Strings

binflakes.sexpr.string.escape_string(value)

Converts a string to its S-expression representation, adding quotes and escaping funny characters.

Symbols

class binflakes.sexpr.symbol.Symbol(name)

Bases: object

Represents an S-expression symbol.

__delattr__(name)

Attached to frozen classes as __delattr__.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setattr__(name, value)

Attached to frozen classes as __setattr__.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

Nodes

class binflakes.sexpr.nodes.AlternativesNode

Bases: object

A base for making node pseudo-classes that, when “created”, match the passed value to one of a given list of node subclasses and call the constructor of the matching one, if any.

If all involved node types are already defined on subclass creation, the list of supported node types can be set through the alternatives class attribute:

class MyAlternativesNode(AlternativesNode):
    alternatives = [
        MyNode,
        AnotherNode,
    ]

If one of the node types isn’t yet defined when a subclass is constructed, the node types can be set later through the set_alternatives class method:

class MyAlternativesNode(AlternativesNode):
    pass

class MyNode(...):
    ...

MyAlternativesNode.set_alternatives([
    MyNode,
    AnotherNode,
])

The alternatives specified must be mutually exclusive, as follows:

• There must be at most one alternative for each atom type.
• There must be at most one of the following:
  • A ListNode subtype.
  • Any number of FormNode subtypes, with distinct symbols.
• If any AlternativeNode subclass is specified in alternatives, it’s as if all alternatives of that class were specified directly in its place.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.nodes.ArrayNode(value, location=None)

Bases: binflakes.sexpr.nodes.AtomNode

Represents an array S-expression.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

value_type

alias of BinArray

class binflakes.sexpr.nodes.AtomNode(value, location=None)

Bases: binflakes.sexpr.nodes.Node

Represents a parsed atomic S-expression node (i.e. anything but a list). Abstract base class. Subclasses need to define value_type class attribute. No new direct subclasses should be defined by the user (all types need direct support from the base machinery), but the derived types can be arbitrarily subclassed further for extra methods.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.nodes.BoolNode(value, location=None)

Bases: binflakes.sexpr.nodes.AtomNode

Represents a bool S-expression.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

value_type

alias of bool

exception binflakes.sexpr.nodes.ConvertError

Bases: Exception

Raised by Node subclass constructors when given value cannot be represented as an instance of a given class.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.nodes.FormNode(value=NOTHING, location=None, symbol_location=None, **kwargs)

Bases: binflakes.sexpr.nodes.Node

An abstract base class for form nodes. Final subclasses need to set a symbol class attribute, define zero or more form arguments, and call the @form_node decorator on the class.

Constructs a FormNode instance from a value and location (where value is a list node, or a plain list), or directly from argument values:

AbcNode([Symbol('abc'), 123, 'def'], TextLocationRange(...))
AbcNode(my_arg=123, my_other_arg='def', location=...)

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__init__(value=NOTHING, location=None, symbol_location=None, **kwargs)

Constructs a FormNode instance from a value and location (where value is a list node, or a plain list), or directly from argument values:

AbcNode([Symbol('abc'), 123, 'def'], TextLocationRange(...))
AbcNode(my_arg=123, my_other_arg='def', location=...)

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

to_list()

Converts a parsed form back to a tuple of S-expressions it was made from.

class binflakes.sexpr.nodes.GenericListNode(value, location=None)

Bases: binflakes.sexpr.nodes.ListNode

Represents a generic list S-expression – items can be of any generic node type.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

item_type

alias of GenericNode

class binflakes.sexpr.nodes.GenericNode

Bases: binflakes.sexpr.nodes.AlternativesNode

A node pseudo-type representing any of the generic node types.

class binflakes.sexpr.nodes.IntNode(value, location=None)

Bases: binflakes.sexpr.nodes.AtomNode

Represents an int S-expression.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

value_type

alias of BinInt

class binflakes.sexpr.nodes.ListNode(value, location=None)

Bases: binflakes.sexpr.nodes.Node

Represents a uniform list S-expression. Abstract base class – should be subclassed with item_type class attribute set to the type of list items.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.nodes.NilNode(value=None, location=None)

Bases: binflakes.sexpr.nodes.AtomNode

Represents a nil S-expression.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.nodes.Node(value, location=None)

Bases: object

Represents a parsed S-expression node. Abstract base class. There are four immediately derived classes:

• AtomNode: represents atomic value nodes (everything except lists).
• ListNode: represents lists of values of uniform type.
• FormNode: represents forms – compound nodes represented in S-expression files by a list starting from a preset symbol and followed by pre-defined arguments of possibly non-uniform types.
• AlternativesNode: a pseudo-class representing an alternative of several disjoint node types. Cannot be instantiated – when constructor is called, the value is matched to one of the contained node type and an instance of the found type is returned instead.

This module provides a base class for every supported atom type, as well as a generic list type and alternatives type. These classes can be used to represent any S-expression and are returned by the reader. To create an S-expression based language, one can create a hierarchy of custom node subclasses and call the top node constructor on the generic tree returned by the reader – it will be resursively converted to the custom node set.

Converts a value to an instance of this class, recursively converting subnodes as necessary. The input value can be another compatible Node instance, or a bare Python value of the corresponding type.

Can be used to convert a bare Python value to a node tree, a generic node tree to a specific node tree, or a specific node tree back to a generic node tree.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__init__(value, location=None)

Converts a value to an instance of this class, recursively converting subnodes as necessary. The input value can be another compatible Node instance, or a bare Python value of the corresponding type.

Can be used to convert a bare Python value to a node tree, a generic node tree to a specific node tree, or a specific node tree back to a generic node tree.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.nodes.StringNode(value, location=None)

Bases: binflakes.sexpr.nodes.AtomNode

Represents a string S-expression.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

value_type

alias of str

class binflakes.sexpr.nodes.SymbolNode(value, location=None)

Bases: binflakes.sexpr.nodes.AtomNode

Represents a symbol S-expression.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

value_type

alias of Symbol

class binflakes.sexpr.nodes.WordNode(value, location=None)

Bases: binflakes.sexpr.nodes.AtomNode

Represents a word S-expression.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

value_type

alias of BinWord

binflakes.sexpr.nodes.form_arg(arg_type)

Defines a required form argument of a given node type.

binflakes.sexpr.nodes.form_node(cls)

A class decorator to finalize fully derived FormNode subclasses.

binflakes.sexpr.nodes.form_optional_arg(arg_type)

Defines an optional form argument of a given node type. If not passed, it is set to None. All optional arguments must come after all required arguments.

binflakes.sexpr.nodes.form_rest_arg(arg_type)

Defines a rest form argument. All form arguments not consumed by required and optional arguments will be converted to the given node type and gathered into a tuple. There can be at most one rest argument and it must be the last defined form argument.

Reader

exception binflakes.sexpr.read.ReadError

Bases: Exception

An exception class used for all problems noticed by the reader.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.read.Reader(filename)

Bases: object

A class for reading S-expressions and converting them to a node tree. Accepts the input line-by-line, yielding top-level S-expressions as they are recognized.

Initializes internal state. filename affects only the location tags that will be attached to nodes.

__init__(filename)

Initializes internal state. filename affects only the location tags that will be attached to nodes.

__weakref__

list of weak references to the object (if defined)

feed_line(line)

Feeds one line of input into the reader machine. This method is a generator that yields all top-level S-expressions that have been recognized on this line (including multi-line expressions whose last character is on this line).

finish()

Ensures the reader is in clean state (no unclosed S-expression is currently being parsed). Should be called after the last feed_line.

class binflakes.sexpr.read.StackEntryComment(start)

Bases: object

A reader stack entry representing a commented-out S-expression currently being parsed. start is the location of the opening comment sign.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.read.StackEntryList(start, items)

Bases: object

A reader stack entry representing a list currently being parsed. items are the items parsed so far, start is the location of the opening paren.

__ge__(other)

Automatically created by attrs.

__getstate__()

Automatically created by attrs.

__gt__(other)

Automatically created by attrs.

__le__(other)

Automatically created by attrs.

__lt__(other)

Automatically created by attrs.

__ne__(other)

Check equality and either forward a NotImplemented or return the result negated.

__repr__()

Automatically created by attrs.

__setstate__(state)

Automatically created by attrs.

__weakref__

list of weak references to the object (if defined)

class binflakes.sexpr.read.State

Bases: enum.Enum

Represents the reader state (between tokens, inside a string token, inside a BinArray token.

binflakes.sexpr.read.read_file(file, filename='<input>')

This is a generator that yields all top-level S-expression nodes from a given file object.

binflakes.sexpr.read.read_string(s, filename='<string>')

Reads all S-expressions from a given string and returns a list of nodes.