gavo.base.activetags module

Active tags are used in prepare and insert computed material into RD trees.

And, ok, we are dealing with elements here rather than tags, but I liked the name “active tags” much better, and there’s too much talk of elements in this source as it is.

The main tricky part with active tags is when they’re nested. In short, active tags are expanded even when within active tags. So, if you write:

<STREAM id="foo">
        <LOOP>
        </LOOP>
</STREAM>

foo contains not a loop element but whatever that spit out. In particular, macros within the loop are expanded not within some FEED element but within the RD.

There is a non-expanding version of STREAM, too, but that has to take special precautions.

class gavo.base.activetags.ActiveTag

Bases: object

A mixin for active tags.

This is usually mixed into structure.Structures or derivatives. It is also used as a sentinel to find all active tags below.

name_ = None

class gavo.base.activetags.Defaults(*args, **kwargs)

Bases: Structure

Defaults for macros.

In STREAMs and NXSTREAMs, DEFAULTS let you specify values filled into macros when a FEED doesn’t given them. Macro names are attribute names (or element names, if you insist), defaults are their values.

attrSeq = [<gavo.base.parsecontext.IdAttribute object>]

completedCallbacks = []

end_(ctx, name, value)

managedAttrs = {'id': <gavo.base.parsecontext.IdAttribute object>}

name_ = 'DEFAULTS'

start_(ctx, name, value)

value_(ctx, name, value)

class gavo.base.activetags.DelayedReplayBase(parent, **kwargs)

Bases: ReplayBase, GhostMixin

An base class for active tags wanting to replay streams from where the context is invisible.

These define a _replayer attribute that, when called, replays the stored events within the context at its end and to the parent.

This is what you want for the FEED and LOOP since they always work on the embedding element and, by virtue of being ghosts, cannot be copied. If the element embedding an event stream can be copied, this will almost certainly not do what you want.

attrSeq = [<gavo.base.complexattrs.StructListAttribute object>, <gavo.base.complexattrs.StructAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.complexattrs.StructListAttribute object>, <gavo.base.attrdef.BooleanAttribute object>, <gavo.base.parsecontext.ReferenceAttribute object>]

completedCallbacks = []

end_(ctx, name, value)

managedAttrs = {'EDIT': <gavo.base.complexattrs.StructListAttribute object>, 'PRUNE': <gavo.base.complexattrs.StructListAttribute object>, 'edits': <gavo.base.complexattrs.StructListAttribute object>, 'events': <gavo.base.complexattrs.StructAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'prunes': <gavo.base.complexattrs.StructListAttribute object>, 'reexpand': <gavo.base.attrdef.BooleanAttribute object>, 'source': <gavo.base.parsecontext.ReferenceAttribute object>}

class gavo.base.activetags.Edit(*args, **kwargs)

Bases: EmbeddedStream

an event stream targeted at editing other structures.

When replaying a stream in the presence of EDITs, the elements are are continually checked against ref. If an element matches, the children of edit will be played back into it.

attrSeq = [<gavo.base.complexattrs.StructAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.attrdef.ActionAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>]

completedCallbacks = []

managedAttrs = {'DEFAULTS': <gavo.base.complexattrs.StructAttribute object>, 'doc': <gavo.base.attrdef.UnicodeAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'passivate': <gavo.base.attrdef.ActionAttribute object>, 'ref': <gavo.base.attrdef.UnicodeAttribute object>}

name_ = 'EDIT'

onElementComplete()

refPat = re.compile('([A-Za-z_][A-Za-z0-9_]*)\\[([A-Za-z_][A-Za-z0-9_]*)\\]')

class gavo.base.activetags.EmbeddedStream(*args, **kwargs)

Bases: RecordingBase, Structure

An event stream as a child of another element.

attrSeq = [<gavo.base.complexattrs.StructAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.attrdef.ActionAttribute object>]

completedCallbacks = []

end_(ctx, name, value)

managedAttrs = {'DEFAULTS': <gavo.base.complexattrs.StructAttribute object>, 'doc': <gavo.base.attrdef.UnicodeAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'passivate': <gavo.base.attrdef.ActionAttribute object>}

name_ = 'events'

class gavo.base.activetags.EventStream(*args, **kwargs)

Bases: RecordingBase, GhostMixin, ActiveTag

An active tag that records events as they come in.

Their only direct effect is to leave a trace in the parser’s id map. The resulting event stream can be played back later.

attrSeq = [<gavo.base.complexattrs.StructAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>, <gavo.base.parsecontext.IdAttribute object>]

completedCallbacks = []

end_(ctx, name, value)

managedAttrs = {'DEFAULTS': <gavo.base.complexattrs.StructAttribute object>, 'doc': <gavo.base.attrdef.UnicodeAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>}

name_ = 'STREAM'

class gavo.base.activetags.GeneratorAttribute(name, **kwargs)

Bases: UnicodeAttribute

An attribute containing a generator working on the parse context.

feed(ctx, instance, literal)

class gavo.base.activetags.GhostMixin

Bases: StructCallbacks

A mixin to make a Structure ghostly.

Most active tags are “ghostly”, i.e., the do not (directly) show up in their parents. Therefore, as a part of the wrap-up of the new element, we raise an Ignore exception, which tells the Structure’s end_ method to not feed us to the parent.

onElementComplete()

class gavo.base.activetags.Loop(*args, **kwargs)

Bases: ReplayedEventsWithFreeAttributesBase

An active tag that replays a feed several times, each time with different values.

attrSeq = [<gavo.base.activetags.GeneratorAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>, <gavo.base.complexattrs.StructListAttribute object>, <gavo.base.complexattrs.StructAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>, <gavo.base.complexattrs.StructListAttribute object>, <gavo.base.attrdef.BooleanAttribute object>, <gavo.base.parsecontext.ReferenceAttribute object>]

completeElement(ctx)

completedCallbacks = []

managedAttrs = {'EDIT': <gavo.base.complexattrs.StructListAttribute object>, 'PRUNE': <gavo.base.complexattrs.StructListAttribute object>, 'codeItems': <gavo.base.activetags.GeneratorAttribute object>, 'csvItems': <gavo.base.attrdef.UnicodeAttribute object>, 'edits': <gavo.base.complexattrs.StructListAttribute object>, 'events': <gavo.base.complexattrs.StructAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'listItems': <gavo.base.attrdef.UnicodeAttribute object>, 'prunes': <gavo.base.complexattrs.StructListAttribute object>, 'reexpand': <gavo.base.attrdef.BooleanAttribute object>, 'source': <gavo.base.parsecontext.ReferenceAttribute object>}

maybeExpand(val)

name_ = 'LOOP'

class gavo.base.activetags.NonExpandedReplayedEvents(*args, **kwargs)

Bases: ReplayedEvents

A ReplayedEventStream that does not expand active tag macros.

You only want this when embedding a stream into another stream that could want to expand the embedded macros.

attrSeq = [<gavo.base.complexattrs.StructListAttribute object>, <gavo.base.complexattrs.StructAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.complexattrs.StructListAttribute object>, <gavo.base.attrdef.BooleanAttribute object>, <gavo.base.parsecontext.ReferenceAttribute object>]

completedCallbacks = []

managedAttrs = {'EDIT': <gavo.base.complexattrs.StructListAttribute object>, 'PRUNE': <gavo.base.complexattrs.StructListAttribute object>, 'edits': <gavo.base.complexattrs.StructListAttribute object>, 'events': <gavo.base.complexattrs.StructAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'prunes': <gavo.base.complexattrs.StructListAttribute object>, 'reexpand': <gavo.base.attrdef.BooleanAttribute object>, 'source': <gavo.base.parsecontext.ReferenceAttribute object>}

name_ = 'LFEED'

class gavo.base.activetags.Prune(parent, **kwargs)

Bases: ActiveTag, Structure

An active tag that lets you selectively delete children of the current object.

You give it regular expression-valued attributes; on the replay of the stream, matching items and their children will not be replayed.

If you give more than one attribute, the result will be a conjunction of the specified conditions.

This only works if the items to be matched are true XML attributes (i.e., not written as children).

For instance, the following will filter out all elements with a name of VERB from the stream:

<PRUNE name="VERB"/>

attrSeq = [<gavo.base.parsecontext.IdAttribute object>]

completedCallbacks = []

end_(ctx, name, value)

managedAttrs = {'id': <gavo.base.parsecontext.IdAttribute object>}

name_ = 'PRUNE'

value_(ctx, name, value)

class gavo.base.activetags.RawEventStream(*args, **kwargs)

Bases: EventStream

An event stream that records events, not expanding active tags.

Normal event streams expand embedded active tags in place. This is frequently what you want, but it means that you cannot, e.g., fill in loop variables through stream macros.

With non-expanded streams, you can do that:

<NXSTREAM id="cols">
        <LOOP listItems="\stuff">
                <events>
                        <column name="\item"/>
                </events>
        </LOOP>
</NXSTREAM>
<table id="foo">
        <FEED source="cols" stuff="x y"/>
</table>

Note that the normal innermost-only rule for macro expansions within active tags does not apply for NXSTREAMS. Macros expanded by a replayed NXSTREAM will be re-expanded by the next active tag that sees them (this is allow embedded active tags to use macros; you need to double-escape macros for them, of course).

ACTIVE_NOEXPAND = None

attrSeq = [<gavo.base.complexattrs.StructAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>, <gavo.base.parsecontext.IdAttribute object>]

completedCallbacks = []

managedAttrs = {'DEFAULTS': <gavo.base.complexattrs.StructAttribute object>, 'doc': <gavo.base.attrdef.UnicodeAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>}

name_ = 'NXSTREAM'

class gavo.base.activetags.RecordingBase(*args, **kwargs)

Bases: Structure

An “abstract base” for active tags doing event recording.

The recorded events are available in the events attribute.

attrSeq = [<gavo.base.complexattrs.StructAttribute object>, <gavo.base.attrdef.UnicodeAttribute object>, <gavo.base.parsecontext.IdAttribute object>]

completedCallbacks = []

end_(ctx, name, value)

feedEvent(ctx, type, name, value)

getEventSource()

returns an object suitable as event source in xmlstruct.

iterEvents()

returns an object suitable as event source in xmlstruct.

managedAttrs = {'DEFAULTS': <gavo.base.complexattrs.StructAttribute object>, 'doc': <gavo.base.attrdef.UnicodeAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>}

name_ = None

start_(ctx, name, value)

unexpandMacros()

undoes the marking of expanded values as expanded.

This is when, as with mixins, duplicate expansion of macros during replay is desired.

value_(ctx, name, value)

class gavo.base.activetags.ReplayBase(parent, **kwargs)

Bases: ActiveTag, Structure, StandardMacroMixin

An “abstract base” for active tags replaying streams.

attrSeq = [<gavo.base.complexattrs.StructListAttribute object>, <gavo.base.complexattrs.StructAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.complexattrs.StructListAttribute object>, <gavo.base.attrdef.BooleanAttribute object>, <gavo.base.parsecontext.ReferenceAttribute object>]

completedCallbacks = []

managedAttrs = {'EDIT': <gavo.base.complexattrs.StructListAttribute object>, 'PRUNE': <gavo.base.complexattrs.StructListAttribute object>, 'edits': <gavo.base.complexattrs.StructListAttribute object>, 'events': <gavo.base.complexattrs.StructAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'prunes': <gavo.base.complexattrs.StructListAttribute object>, 'reexpand': <gavo.base.attrdef.BooleanAttribute object>, 'source': <gavo.base.parsecontext.ReferenceAttribute object>}

name_ = None

replay(events, destination, ctx)

pushes the stored events into the destination structure.

While doing this, local macros are expanded unless we already receive the events from an active tag (e.g., nested streams and such).

class gavo.base.activetags.ReplayedEvents(*args, **kwargs)

Bases: ReplayedEventsWithFreeAttributesBase

An active tag that takes an event stream and replays the events, possibly filling variables.

This element supports arbitrary attributes with unicode values. These values are available as macros for replayed values.

attrSeq = [<gavo.base.complexattrs.StructListAttribute object>, <gavo.base.complexattrs.StructAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.complexattrs.StructListAttribute object>, <gavo.base.attrdef.BooleanAttribute object>, <gavo.base.parsecontext.ReferenceAttribute object>]

completeElement(ctx)

completedCallbacks = []

managedAttrs = {'EDIT': <gavo.base.complexattrs.StructListAttribute object>, 'PRUNE': <gavo.base.complexattrs.StructListAttribute object>, 'edits': <gavo.base.complexattrs.StructListAttribute object>, 'events': <gavo.base.complexattrs.StructAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'prunes': <gavo.base.complexattrs.StructListAttribute object>, 'reexpand': <gavo.base.attrdef.BooleanAttribute object>, 'source': <gavo.base.parsecontext.ReferenceAttribute object>}

name_ = 'FEED'

class gavo.base.activetags.ReplayedEventsWithFreeAttributesBase(*args, **kwargs)

Bases: DelayedReplayBase

An active tag that takes arbitrary attributes as macro definitions.

attrSeq = [<gavo.base.complexattrs.StructListAttribute object>, <gavo.base.complexattrs.StructAttribute object>, <gavo.base.parsecontext.IdAttribute object>, <gavo.base.complexattrs.StructListAttribute object>, <gavo.base.attrdef.BooleanAttribute object>, <gavo.base.parsecontext.ReferenceAttribute object>]

completeElement(ctx)

completedCallbacks = []

getAttribute(name)

Returns an attribute instance from name.

This function will raise a StructureError if no matching attribute definition is found.

managedAttrs = {'EDIT': <gavo.base.complexattrs.StructListAttribute object>, 'PRUNE': <gavo.base.complexattrs.StructListAttribute object>, 'edits': <gavo.base.complexattrs.StructListAttribute object>, 'events': <gavo.base.complexattrs.StructAttribute object>, 'id': <gavo.base.parsecontext.IdAttribute object>, 'prunes': <gavo.base.complexattrs.StructListAttribute object>, 'reexpand': <gavo.base.attrdef.BooleanAttribute object>, 'source': <gavo.base.parsecontext.ReferenceAttribute object>}

gavo.base.activetags.isActive(name)

gavo.base.activetags.registerActiveTag(activeTag)

declares activeTag as an active tag.

This is intended for active tags that might be defined one day outside of this module; at least as of DaCHS 2.0, there’s no such thing.