HOME


Contents

Rules & Phases Steps & Tokens Step head
Converters Flatteners Mappers


Tutorials

Hello, world! Data Access Starter Kit

Dap 0.1.7 Language Quick Tour

Dap provides an easy and powerful means for complex and extensive document rebuilds with dinamically resolved dependencies.

Dap language is rather "functional", than "imperative". That means, dap rules do not specify imperatively for each click event: "update Node1, Node2 and another dozen of nodes; hide Node765432 and show P elements inside DIV elements, having class .NodesToShow, slowly". Instead, any node's contetnt is defined as a "function" of its template markup and environment status of the place, it is inserted to. You needn't provide all the wirings to make nodes interact with each other. Dap rules simply specify a node's generation rule, like: "This node is built using variables A, B, X and may update variables A, X, Y, Z". And all dependencies are resolved by dap engine automatically. When any of A, or B, or X changed, the node rebuilds automatically. When the node changes any of A, X, Y, Z — all the dependent nodes are updated — automatically, too. No any additional wirings needed.

Such a "functional" way of document definition may appear pretty much different from what web-developers are used to. It might seem complicated and cumbersome when reading syntax specification, but when it comes to actual coding — it turns out to be quite easy and handy.

I'd recommend that you see the 'Hello, world' tutorial before getting into dap syntax details. That would help you keep track of what is it all about.

Rules and Phases

All dap rules consist of steps, steps consist of tokens, tokens consist of parts. Very simple:

rule ::=step{; step}
step ::=token{ token}
token::=[field][$status][:converter{,converter}][@alias][=value]

That is, steps within a rule are separated by a semicolon+space; header and tokens within a step — by a single space; multiple converters are separated by commas. All token parts are grammatically optional. Empty strings are valid names, but in many cases they are reserved and have special meaning.

A dap-enabled node may have none, any or both of the following rules, corresponding to the node life phase:

  • Data or Down phase: d-rule

    When a dap node is populated, its content is generated using its d-rule, and according to its status context and data context. Execution of d-rule of a node may change any particular entries of its contexts, and theese changes will be observable by the nodes's descendants and after-siblings.

  • User or Up phase: u-rule

    When a dap node is activated (usually, by a user-related event), its own u-rule and u-rules of its ancestors are executed, starting from the node and bubbling up. Changes made to status entries are automatically reflected in all dependent nodes, initiating rebuilds for the nodes whose content does depend on the changes made. Changes to data entries do not initiate updates, though their updated values may be used in rebuilds initiated by status updates.

Steps and Tokens

Each rule consists of one or more steps, wich are executed consequently on the rule run. A step consists of tokens. The first token of a step is the step's head; the rest are data tokens (or simply tokens). Data tokens define data involved in the step execution; step head specifies actions to perform on that data.

Zero or more data tokens may participate in execution of each step. A token is a structure, that defines a datapiece passed to a mapper. Data tokens are not just identifiers, but execution units wich provide some simple data manipulations, such as data binding, assignments and conversions. Token may reference a data entry, a status entry, or specify a literal value. Token also specifies conversion chain for the datapiece, and an alias, under wich the datapiece is fed to the mapper.

Each token may contain:

  • data entry reference
  • status reference
  • conversion chain
  • alias
  • literal value

Token parts are separated by their respective prefixes: $ (dollar sign) — for status entry reference, : (colon) — for conversion chain, @ (at sign) — for alias, = (equal sign) — for value. Data entry reference, if present, is not prefixed, but is placed as first part of a token. All token parts are optional, but their order is mandatory. Full token looks like:

data$status:converter1,converterN@alias=value

and its meaning is:

  1. read data entry from the node's data context, or take literal value if data entry is not specified or not present in the data context.
  2. store it as a status entry in the node's status context
  3. sequentially apply all the converters,
  4. provide the executed token with an alias.

Omitting any token parts modifies token behavior in a straightforward manner:

  • if no converts specified, datapiece is fed as is
  • if neither data entry nor literal value specified, the status entry's own value is taken
  • if no status entry specified, none is changed
  • if no alias provided, the result is named after the entry (or left anonymous, if none of those are specified).

A shortened form is allowed, in which status entry name is omitted, while the $ prefix is present, like: entry$. This form is equivalent to entry$entry (read value from a particular data entry and store it in a status entry with the same name). This shorthand is very common in dap, it helps keeping the code cleaner and encourages reasonable entry naming.

Setting and getting status entries

As can be seen from the token structure description above, a status variable's value can be set (by specifying a literal value or a source data entry) and can be read (by omitting both literal value and data entry reference).

Setting a status entry has different semantics for up and down phases:

  • at the down-phase, a new status entry is introduced in the node's scope of status context; should a one with the same name already exist in outer scopes, it is hid from the current scope
  • at the up-phase, the referenced entry is first searched in the context, then, if not found, created new.

Reading a status entry always assumes that it is present in the node's status context (has been already introduced — in the node's ancestors' d-rules, or in the current rule earlier), otherwise rule fails.

Converters

Converters allow to... yes, convert, the result of token execution. Converters only change the result, not the source of the value. This changed value is fed to the mapper, but not written back to the entry it was obtained from.

Dap core provides the following converters:

Custom converters may be defined in extension libraries.

Step head

Step head is the first token of a step. Step head itself doesn't fetch datapieces; it defines what to do with the rest of the token list. It has the same structure as an ordinary token, except that its data part specifies a dap mapper, and its value part specifies a token list flattener.

Flatteners

A flattener may be applied to the token list to convert the whole list into a single datum, wich is fed to the mapper instead of individual tokens of the step. Alias for the flattened datum is specified by the head's alias part.

In dap 0.1.7, there are two classes of flatteners: joiners and conveyors. Joiners treats the feed as a set of datapieces with equal semantics, and usually yields to some kind of 'sum' of them: numeric or textual or whatever. In contrast, conveyors treats the feed as a sequence of 'operators', which are sequentially applied to initial value.

Joiner flatteners

Dap core joiners are:

  • concat

    Concatenates values of all tokens into a single string

  • space

    Concatenates values by a single space

  • url

    Builds an URLEncoded query string. Anonymous tokens are appended unencoded.

  • ?, !

    ANY(returns first non-empty value from the token list) / LACK (returns true if at least one token is false/empty)

    In conjunction with ! converter, these flatteners become NONE / ALL respectively

  • eq, asc, dsc

    Check respectively for: equality, monotonous ascend or monotonous descend of the token list
    Equality check may be performed upon any data, whereas ascend and descend checks — only upon numbers.

  • Examples

    !=concat =abra @foo=cada @bar=bra
    abracadabra

    !=space =abra @foo=cada @bar=bra
    abra cada bra

    !=url =abra @foo=cada @bar=bra =hmaputra
    abra&foo=cada&bar=brahmaputra

    !=? @empty= @foo=cada @bar=bra
    cada

    ?=eq =abra @foo=cad @bar=abra
    false

    ?=eq =abra @bar=abra
    true

    ?=asc =-1 =7 =12 =13
    true

    ?=asc =-1 =7 =15 =13
    false

    ?=dsc =-1 =-7 =-12 =-13
    true

Conveyor flatteners

Conveyors allow to perform a series of parameterized transformations of a datum in a single rule step. Each token in the feed is treated as a binary operator. The first operand is the result of application of previous token (or initial value). Token alias gives the operator name, token value gives the second operand.

Conveyor operators may be of three kinds:

  • empty (anonymous token)
  • predefined (operator name is specified explicitly in conveyor definition)
  • default (operator, not defined explicitly in conveyor definition, instead its name is passed as a parameter to the conveyor's default handler, if present)

Dap core conveyors:
  • @

    Switch-case selector. Empty operator specifies the switch value, default operator specifies cases. If the case (a token alias) matches the switch, the token's value is added to output.

    One predefined operator, ! (exclamation sign), forces a value to be added to output regardless of the switch.

  • #

    Hash selector. Empty operator specifies a pool, implicit operators specify objects to be taken from that pool.

    Predefined operator ? prevents empty values from being output.

  • Examples

    Given two objects:

    TheRollingStones:{
    	vocal	:Mick Jagger
    	guitar	:[Keith Richards,Ron Wood]
    	bass	:Darryl Jones
    	drums	:Charlie Watts
    }
    
    and
    Metallica:{
    	vocal	:James Hetfield
    	guitar	:Kirk Hammett
    	bass	:Rob Trujillo
    	drums	:Lars Ulrich
    }
    

    these conveyors would yield:

    $role=guitar; $result=# $role@ TheRollingStones.guitar TheRollingStones.bass Metallica.guitar
    [[Keith Richards, Ron Wood], Kirk Hammett]

    $role=bass; $result=@ TheRollingStones@ $role
    [Darryl Jones]

    $role=violine; $result=@ TheRollingStones@ $role
    ['']

    $role=violine; $result=@ TheRollingStones@ $role@?
    []

Custom flatteners (both joiners and conveyors) can be defined in external libraries.


Mappers

Mappers to dap are what functions to javascript are. They take "arguments" and perform "actions". Dap mappers are unary — they deal with only one token at a time. Multiple tokens in a step are executed as a "for each token" sequence.

Since all mappers are unary, the following signature may be used for their description:

mapper @alias=value

Each token comes to a mapper as an @alias=value datapiece. Alias is specified by token's @alias part (or an entry name, or anonymous), and value is the result of token execution; it is also subject to conversions, if specified. If the token's alias is empty (like in =value, or data@, or data$status@:convert=value, etc.), the token is said anonymous. In some mappers, anonymous tokens have specialized meaning over named ones.

The basic dap core mappers are:

Entry-modifying mappers

Entry-modifying mappers are used to modify target's fields. The target may be a status entry, or the node's scope of data context.

Custom mappers can be defined in external libraries.


See also: