Extension API

This system has been designed with flexibility as well as extensibility in mind from the very get-go. On this page, the available API usable to define tags and thus AST-nodes as well as to intercept interpretation at runtime will be documented. Let's look at an abstract overview-diagram regarding the flow of data first:

Defining Tags

While a tag-definition may look deceptively simple at first glance, the possibilities it brings to the table cannot be overstated.

Code-Blocks are only available within the browser

The above represents the template provided in order to define a new tag, to be registered in and used with an instance of the Code-Blocks are only available within the browser. Immediately within the Code-Blocks are only available within the browser-constructor, the tag closing-type

Code-Blocks are only available within the browser

is to be defined, where self-closing tags may not bear any content and thereby will always receive a Code-Blocks are only available within the browser-list of Code-Blocks are only available within the browser; next up, a tag-priority

Code-Blocks are only available within the browser

will signal which definition to pick if a tag's name matched on multiple registered definitions, allowing the user to override built-in behavior (although not necessarily recommended) to any granularity. These already are the only properties required upfront, where name- and attribute- matching remain completely dynamic.

Matching Names

Due to the fact that names are not to be specified ahead of time, a tag-definition may handle patterns of arbitrary complexity, as is the case with Color Shorthands. Also, in general, tag- as well as attribute-names are case-insensitive. Once Code-Blocks are only available within the browser returned Code-Blocks are only available within the browser for one such given name, the tag-definition becomes a candidate within the list of possible handlers, from which the one of highest priority will prevail.

Creating Nodes

As soon as the system completed parsing the a tag in its entirety, including attributes as well as possibly some content, Code-Blocks are only available within the browser will be invoked (with the very same name matched upon earlier, for reference), whose responsibility it is to instantiate an AST-node, being a derivative of a Code-Blocks are only available within the browser:

Code-Blocks are only available within the browser

The base class already takes care of holding the Code-Blocks are only available within the browser, as well as optional lists of Code-Blocks are only available within the browser and Code-Blocks are only available within the browser (see Let-Bindings). This immediately implies that tags may implicitly define bindings or modify child-entries. While there are many pre-defined node-types available, users may also always define their own, handled via Interpreter-Interception.

Retrieving Attributes

The astute reader might have noticed that up until this point, no attributes have ever been defined anywhere - and for good reason: keeping a single source of truth, paired with flexibility. The Code-Blocks are only available within the browser, as passed into Code-Blocks are only available within the browser, handles access in a somewhat unusual, yet beautifully simplistic manner; let's take a look at its API first:

Code-Blocks are only available within the browser

There are two different types of attributes - Expressions as well as a sub-tree of Markup, both bound to an identifying Code-Blocks are only available within the browser, where a name can only ever depict one and the same type used as an internal representation of the data associated with it. Optional attributes are not required to be present in order for the construction of the corresponding tag to succeed, while their mandatory counterparts certainly are, failing parsing if absent; single values (nodes) may be null if omitted, while lists are always non-null, for convenience. When requiring an attribute as a list, this simply means that it may be specified more than once, and could possibly be bound using the spread-operator Code-Blocks are only available within the browser.

The above instantly implies the possibility of dynamic attributes like: Code-Blocks are only available within the browser, as follows:

Code-Blocks are only available within the browser

After Code-Blocks are only available within the browser responded with a result, the Code-Blocks are only available within the browser is internally checked for any unused attributes and, if any, will fail parsing, telling the user that they've specified unsupported (at least in their current attribute-constellation) names. This way, a tag can access attributes of exact types and names as desired, not having to take the burden of validation, without compromising on clarity when it comes to user-facing error-screens.

Lists of attributes are intentionally represented as an internal wrapper, due to the fact that they may be dynamically bound, using the spread-operator Code-Blocks are only available within the browser, which entails that the elements may not be known at parse-time; such a list is supposed to be stored inside the constructed node as-is, to be evaluated later during interpretation, using the concept of Interpreter-Interception; they are accessed by providing a reference to the interpreter, as follows:

Code-Blocks are only available within the browser

and

Code-Blocks are only available within the browser

Interpreter Interception

Many features require interception at the time of interpretation in order to be implemented; in fact, that's exactly how - for example - the Rainbow-Tag operates, by cancelling default processing of the elements it targets, while emitting its own colorized members into the final output.

Interception Lifecycle

Registering to be called for interception is again as simple as it gets: once the node as constructed by Code-Blocks are only available within the browser implements the following interface, it will be called when it itself is encountered, as well as for every of its children:

Code-Blocks are only available within the browser

The main point of control, Code-Blocks are only available within the browser, may result in one of the following signals:

Code-Blocks are only available within the browser

When instructing the interpreter to not process the current node, it will be skipped over in its entirety - including whichever children it may have contained. In order to only render said members partially, make use of the provided reference to the interpreter as to emit nodes manually; in most cases, processing will only be inhibited for terminal nodes though, which are then overridden by custom instances, emitted once again manually, while Code-Blocks are only available within the browser makes for a perfect way to keep a Code-Blocks are only available within the browser stack within the AST-node itself, handling state of the feature which leverages interception.

Let's look at an example of concurrent interceptors; even though per tag and thus per node, only at most a single interceptor may be registered at a time, there may be multiple interceptors in charge at any given depth. Due to this naturally arising mechanism, interceptors are kept on a stack, from which they are popped as soon as the scope of their corresponding tag ends; also, interceptors who registered first (outermost tags) always take precedence by being invoked first. A parent may skip a child's possibility of interception, such that it is not even called into; also, a child may skip a node which a parent did allow to process:

Code-Blocks are only available within the browser

• Code-Blocks are only available within the browser:
  • Calls interceptor Code-Blocks are only available within the browser: Code-Blocks are only available within the browser
  • Registers interceptor Code-Blocks are only available within the browser
• Code-Blocks are only available within the browser:
  • Calls interceptor Code-Blocks are only available within the browser: Code-Blocks are only available within the browser
  • Calls interceptor Code-Blocks are only available within the browser: Code-Blocks are only available within the browser
  • Registers interceptor Code-Blocks are only available within the browser
• Code-Blocks are only available within the browser:
  • Calls interceptor Code-Blocks are only available within the browser: Code-Blocks are only available within the browser
  • Calls interceptor Code-Blocks are only available within the browser: Code-Blocks are only available within the browser
  • Calls interceptor Code-Blocks are only available within the browser: Code-Blocks are only available within the browser
  • Calls Code-Blocks are only available within the browser of Code-Blocks are only available within the browser with Code-Blocks are only available within the browser
  • Calls Code-Blocks are only available within the browser of Code-Blocks are only available within the browser with Code-Blocks are only available within the browser
  • Does not register Code-Blocks are only available within the browser (as it skipped itself)

Interpreter Reference

With the lifecycle as described above in mind, an interceptor is now fully enabled to interpret expressions, introduce temporary variables, interpret markup subtrees, construct platform-specific components and emit to the output, all thanks to the provided interpreter-reference:

Code-Blocks are only available within the browser

Temporary Variables

In order to introduce temporary variables, update- and remove them again, there's an environment-accessor within the interpreter, providing a way to modify the temporary-variable-stack:

Code-Blocks are only available within the browser

When introducing variable-values which are modified by reference later on, as is the case with the Code-Blocks are only available within the browser-variable which the intrinsic Code-Blocks are only available within the browser attribute introduces, they should implement the following interface, as to allow the system to create a static copy to be used when snapshotting the environment for captures.

Code-Blocks are only available within the browser

In order to avoid having to make use of reflection whenever accessing members of objects within expressions with the member-operator, the following interface - if implemented on the object accessed into - is called first, as to directly access named fields; it also doubles as a means to define arbitrarily complex "getters".

Code-Blocks are only available within the browser

Creating/Modifying Components

Components, as created by invoking the Code-Blocks are only available within the browser with AST-nodes, may be modified to any degree using the platform-specific Code-Blocks are only available within the browser; next to modifying existing components, custom components may also be constructed from the ground up using nothing but their parameters, to be emitted directly later on. Learn more about this class over at the Platform-API.

Emitting To Output

When it comes to emitting intercepted or even custom elements to the final output, the following reference, as provided by the interpreter, allows for much flexibility:

Code-Blocks are only available within the browser