Pattern language - epimorphics/dclib GitHub Wiki

Patterns are used to express computed values that can be bound to other variables (e.g. in a parameterized template) or given as the value of RDF properties (in a Resource map).

URI pattern:

"<http://example.com/{pattern}/{pattern}>"

If, after pattern substitution, this looks like a qname then any prefixes will be expanded.

Reverse property pattern:

"^<http://example.com/{pattern}/{pattern}>"

Literal pattern:

"I {pattern} am a literal"
"lang {pattern} string@en"
"non-lang string@@en"
"non-lang string\\@en"
"foo^^xsd:string"
"foo^^<http://example.com/literal>"
"not typed string\\^^rest of string"

Any of the special characters ('<', '>', '^', '{', '}') may be used in a plain string by means of the '' escape character. To put a '' in a JSON string you need "\" because \ is also used at the JSON level. So for example:

"\\<foo>"

is an plain literal "<foo>" not a URI resource.

The backslash escaping only applies to those special characters, in other cases it appears in the string as a \. This is useful when defining things like regular expressions.

The {pattern} parts of the above examples are all expressions which use jexl syntax, such as:

column
'string'
42
object.method(expr, ...)
fn(expr,expr,...)

In the simple cases there are Jexl expressions.

It is also possible to create Jexl scripts as a nested block:

"my { { statement; ... statement } } script"

Scripts are easy to write when using the YAML surface syntax.

The values which can be accessed in the expression are provided from:

• global context values
• the cell values from the current row of the input file
• values bound by can calling templates

In all cases the values are normally wrapped objects which support some useful method operations listed below.

The source value of a cell will be automatically coerced to numbers or dates if they syntactically look like the corresponding type. To override this use an explicit asString() call in the pattern. This processing follows the linked CSV conventions and supports:

• xsd:integer [0-9]+
• xsd:decimal [0-9]+\\.[0-9]+
• xsd:double [0-9]+(\\.[0-9]+)?[eE][-+]?[0-9]+(\\.[0-9]+)?
• xsd:dateTime
• xsd:date
• xsd:time
• xsd:gYearMonth

The expression evaluator can also handle raw java values. To extract the raw java value from a wrapped object use x.value. So, for example, to use arithmetic on a cell that looks like a number you would use a pattern such as {x.value + 1}.

Column names are normalized, fold to lower case, replace white space sequences and punctuation with "_".

Often source data has empty values for certain columns.

The default processing is that a missing value simply results in values derived from it being missed from the results, but the rest of the template still applies. For example, given data:

Then a template:

{
    "name" : "simple-skos",
    "@id" : "<{$base}{notation}>",
    "<rdf:type>" : "<skos:Concept>",
    "<skos:notation>" : "{notation}",
    "<dct:description>" : "{description}",
    "<skos:prefLabel>" : "{label}"
}

will generate output like:

<http://example.com/1>  a  skos:Concept ;
    skos:notation "1";
    skos:prefLabel "Entry 1;
    dct:description  "Description for 1" .

<http://example.com/2>  a  skos:Concept ;
    skos:notation "2";
    skos:prefLabel "Entry 2" .

Whereas if the notation value were missing then there would be no output for that row because the resource URI could not be constructed. For safety, if no template successfully generates applies to a given row then the whole process is deemed to have failed.

Using the required field you can force the template to explicitly test that a value is present for the given row before applying the template. So if description were required then the template would not apply to the second row in this example and the processing would fail unless there were any alternative template which did match.

If working with raw values (e.g. {'foo' + bar}) then the result will be converted to an RDF literal. For additional control over this there are two global functions:

Sometimes we need to test or access the RDF data already generated, for example when data has been fetched from a remote resource. This is only possible in the converter is working in non-streaming mode.

To help in this situation the following methods are supported (note that it is no longer necessary to further wrap the values using asRDFNode() to access these functions). In each case where a property values is required this may be given by a uri string, a qname string (using the prefixes defined for the conversion) or another value that is an RDF node.

As an example here is a (Yaml format) template which fetches OS district or county URIs and returns the corresponding County an rdf:value annotation:

name              : RDFNode processing test case
required          : ["id" ]
"@id"             : <{id.fetch()}>
<rdf:value>       : |
    { {
        var x = $root.asRDFNode();
        if (x.hasResourceValue('rdf:type','http://data.ordnancesurvey.co.uk/ontology/admingeo/County')) {
           return x
        } else {
           return x.getPropertyValue('http://data.ordnancesurvey.co.uk/ontology/admingeo/inCounty')
        }
    } }

It is possible to create small, reusable single-argument functions to reduce repetition in templates.

This is done by binding a variable to a pattern of the form:

{= expr; expr; ...; expr}

where the expressions are Jexel statements forming a script. These can refer to a variable $$ which will be passed in from when the function is applied. The value of the function application will be the value of the last expr or the value of any return statement.

To use this function then within a later pattern it can be called using:

{ f.apply(x) }

where f is the variable t which the function was bound and x is the value to be passed to the function. The environment visible to the function will be that in place at the time the function was created plus the calling argument $$.

For example:

name : Test emission of namespace URIs
type : Composite
bind : 
   - "$base" : "<http://example.com/test>"
   - "$ns" : "{= asResource($$).replaceAll('[#/]$','')}"
templates :
   - "@id" : "{$base}"
     "<rdf:type>"  : "<void:Dataset>"
     "<rdf:value2>" : "{$ns.apply('dct:')}"

This creates a reusable function ns which expands a namespace string to a URL for a vocabulary (with trailing # or / removed).