The dom.base module

Some general element types and some base classes for the quickly.dom elements.

Base classes

The following are base element classes for different languages.

class Document(*children, **attrs)

Bases: quickly.dom.element.Element

Base class for a full source document.

space_between = '\n\n'

concat_space(n, m)

Return the minimum whitespace to apply between these child nodes.

This method is called in the points() method, when calculating whitespace between two adjacent child nodes. By default, the value of the space_between attribute is returned. Reimplement this method to differentiate whitespacing based on the (type or contents of the) nodes.

class String(head, *children, **attrs)

Bases: quickly.dom.element.TextElement

Base class for a string element.

classmethod read_head(origin)

Return the value as computed from the specified origin Tokens.

The default implementation concatenates the text from all tokens.

write_head()

Return the textual output that represents our head value.

The default implementation just returns the head attribute, assuming it is text.

class Comment(head, *children, **attrs)

Bases: quickly.dom.element.TextElement

Base class for a comment element.

class SinglelineComment(head, *children, **attrs)

Bases: quickly.dom.base.Comment

Base class for a multiline comment element.

indent_override()

Returns 0 if this comment has at least three comment characters at the beginning.

If it is on a line on its own, the current indent will then be ignored.

class MultilineComment(head, *children, **attrs)

Bases: quickly.dom.base.Comment

Base class for a multiline comment element.

class BackslashCommand(head, *children, **attrs)

Bases: quickly.dom.element.TextElement

A command that starts with a backslash, like in LaTeX and LilyPond.

The backslash (\) is not in the head value.

classmethod check_head(head)

Return False if the head value starts with a backslash (\).

classmethod read_head(origin)

Strip the backslash of the origin token.

write_head()

Add the backslash on write-out.

Generic elements

These are generic elements, which are never created from transforming a sourcce, but may be used to alter the output of a DOM tree/document.

class Newline(*children, **attrs)

Bases: quickly.dom.element.Element

A Newline.

Not created from existing documents, but you can insert this node anywhere you want a newline in manually crafted documents.

head = ''

space_after = '\n'

class BlankLine(*children, **attrs)

Bases: quickly.dom.element.Element

A blank line.

Not created from existing documents, but you can insert this node anywhere you want a blank line in manually crafted documents.

head = ''

space_after = '\n\n'

class Line(*children, **attrs)

Bases: quickly.dom.element.Element

Container that prints the child nodes on one line with a space in between.

Not created from existing documents, but you can insert this node in a Document when you want some nodes to be on the same line, for example when you want to write a comment at the end of the preceding line instead of on a line of its own.

space_before = '\n'

space_after = '\n'

space_between = ' '

class Column(*children, **attrs)

Bases: quickly.dom.element.Element

Container that prints every child node on a new line.

Not created from existing documents, but you can insert this node in a Document when you want some nodes to be stacked vertically.

space_before = '\n'

space_after = '\n'

space_between = '\n'

class Text(head, *children, **attrs)

Bases: quickly.dom.element.TextElement

Generic text that is printed unmodified.

Special element

There is one “special” element.

class Unknown(*children, **attrs)

Bases: quickly.dom.element.HeadElement

Represents a document region that is not transformed.

This element can only occur in documents transformed from source. It is used to denote reqions that are not transformed, such as CSS style tags or attributes, or script tags, in Html documents containing LilyPond music.

Parce has fancy highlighting for those text fragments, but it makes no sense to try to transform those also to useful DOM nodes. So instead, we simply record the positions in the source document of these fragments using the first and the last token of such contexts that are not transformed.

Calling write_head() on this element results in an exception, because it does not know how it looks. But it knows the position in the document, because the first and the last untransformed tokens are in the origin.

Before you can write out a document containing Unknown elements fully out (e.g. using write() or write_indented()), you should replace those elements with e.g. Text elements that have the text such as it appears in the source document. This can be done using util.replace_unknown().

You can edit() documents with this element however, it will simply leave the unknown parts of the document as they are.

write_head()

Raise RuntimeError.

Language and Transform base/helper classes

class XmlLike

Bases: object

Mixin class for a language definition that bases on parce.lang.Xml.

Adds the comsume attribute to some lexicons, like comment and string, which makes transforming easier.

comment = XmlLike.comment

sqstring = XmlLike.sqstring

dqstring = XmlLike.dqstring

cdata = XmlLike.cdata

processing_instruction = XmlLike.processing_instruction

class Transform

Bases: parce.transform.Transform

Transform base class that keeps the origin tokens.

Provides the factory() method that creates the DOM node.

factory(element_class, head_origin, tail_origin=(), *children)

Create an Element, keeping its origin.

The head_origin and optionally tail_origin is an iterable of Token instances. All elements should be created using this method, so that it can be overridden for the case you don’t want to remember the origin.

class AdHocTransform

Bases: object

Transform mixin class that does not keep the origin tokens.

This is used to create pieces (nodes) of a LilyPond document from text, and then use that pieces to compose a larger Document or to edit an existing document. It is undesirable that origin tokens then would mistakenly be used as if they originated from the document that’s being edited.

factory(element_class, head_origin, tail_origin=(), *children)

Create an Item without keeping its origin.

The head_origin and optionally tail_origin is an iterable of Token instances. All items should be created using this method, so that it can be overridden for the case you don’t want to remember the origin.