Help:Extension:OttrParser/en

This extension provides a parsing of OTTR statements and a suitable generation of wikicode that implements an equivalent behavior for such statement in the MediaWiki. E.g., produce RDF triples based on semantic grouped templates for a consistent and simple instantiation of triple based information.

The Extension Page: Extension:OttrParser

General usage of the extension
Parse and replace OTTR text with wikicode are done via one of the following OTTR calls.

Important:  on every page there should only be ONE OTTR call  regardless of the variant of the call!

OTTR tag
Generating the wikicode for any OTTR code, the extension provides a html tag, that replaces itself while parsing with the wikicode adding the equivalent functionality.

&lt;ottr&gt; ... &lt;/ottr&gt;

The advantage of the html tag is that you can use the pipe character  and equal sign   inside the tags (in contrast to the parser function syntax). The disadvantage is the loss of the functionality of substitution thus the prevention of repeating extension/python calls.

Form attribute
When the attribute form is not empty, the extension does not add the Debug and Display-Wikicode part of the generated code in the output. This is mostly desired in form calls.

&lt;ottr form=True&gt; ... &lt;/ottr&gt;

OTTR Function
For Help:Substitution, the extension provides a parser function for templates.

Example Include something like this in your Template page:

The extension writes the safesubst call in the page, but surrounded with HTML-Comment characters. For re-running the parser delete all the generated code, except the safesubst call.

Appearance options
The extension adds to the generated code some highlighting and hints of the generated data and code. The display behavior of the individual parts can be global turned on and off with a switch from 0 to 1 and vis versa in the corresponding templates.

Template:ottr:DisplayOttr
Display the formulated OTTR call outside the editing mode can be useful on the rendered page. Both for instances and template definitions.

Example Appearance: OTTR-Definition: ex:Template1 [ ?arg1, ?arg2, ?arg3] :: { ottr:Triple (?arg1, ex:testPredicate, ex:testObject) , ottr:Triple (ex:testSubject, ?arg2, ex:testObject) , ottr:Triple (ex:testSubject, ex:testPredicate, ?arg3) }.

Template:ottr:DisplayFormHelp
For easy creating forms and instances, the extension adds a text part to each template, that let the user use them. The default page for a form is the same name as the template, but in the Form namespace. With the InputBox extension a button links to the new page with the automated content that fits to the defined template. If the default page for a form exists, the button disappears and a link to the generated form appears, that expects the name of a page for new instances.

Example Appearance of a button to create a form page: Form Info: The OTTR-Extension comes with an automated form creation, which simplifies the generation of instances of a template via input fields:

Example Appearance of a link to create an instance of the template:

Form Info: The OTTR Extension comes with an automated form creation, which simplifies the generation of instances of a template via input fields:


 * Create instance with form

Template:ottr:DebugOnOFF
The extension provides some (debug) information about generated instances. This includes the number of initialised triples, number of different used IRIs (an indication of the connectedness of the page), the max depth of OTTR-template calls and a list of all used OTTR-Templates and their number of calls.

Example Appearance: Debug Info:
 * Number Init Triples: 3
 * Number Used IRIs: 6
 * Max Depth: 2
 * Used Templates:
 * - ex:Template1: 1 - ottr:Triple: 3

Template:ottr:AllAnnotationsOnOff
The feature annotations from the OTTR-language are relevant for additional information about the template. So the first called template should get called. For ignoring such limitation and call every annotation of all called templates turn this ON. The extension uses the annotation also for specifying layout templates for a template (See here).

Template:ottr:DisplayTriplesOnOff
Include an inline ask query about the triples defined on this page. Needs sometimes more refreshes for displaying the table.

Example Appearance: Generated Triples: (Needs sometimes 2x refreshes)

Template:ottr:DisplayCode
Display the generated Wikicode for the instances or template on a page.

Example Appearance: Wikicode:

Prefixes and Comments
The extension uses prefixes from RDFs as namespaces of the wiki, e.g. the page of the IRI  lies in the xsd-namespace. Mapping now the prefix to the full IRI is done with a prefix expression, that contains the mapping information from prefix to the expanded URL. Because of organizational and clarity reasons, the extension wants to collect all Prefix information on one page. So, every occurrence of a prefix definition outside this particular page will give a warning, if the prefix is not defined on the prefix page already.

The default page for all prefixes is ottr:ottrPrefixes.

Syntax
The OTTR-syntax for prefixes is like the one in the turtle language. It starts with  and states then the prefix and the URL (in   and   signs) separated by a colon. It ends (like every OTTR statement) with a dot, e.g. @prefix xsd:.

Appearance
The displaying result depends on different preconditions: The prefix statement has no effect and no appearance.
 * The statement is on the prefix page:
 * 1) Prefix: xsd:
 * The statement is on another page and the prefix is not defined on the prefix page:
 * The statement is already on the prefix page:

Side Effects
On the Prefix page it produces also a subobject with the properties:
 * IRI
 * The complete URL without the  and.


 * Namespace
 * The prefix name.


 * Subobject-category
 * , for querying.

The Warning message produces like every error and warning box also a subobject of the subobject-category, containing the message and a simple error code.

Comments
Text declared as a comment is ignored by the parser.

The OTTR-syntax provides single- and multi-line  comments.

Template Definition
Writing an OTTR-Template, that can call other OTTR-Templates and produce at the end Triples, is one of the main usage parts of the extension. An OTTR-Template consists of a signature, containing the name of the template and the argument definitions, and the template hull. A template can have arguments with different options (parameter modifiers) and also a type restriction per argument is possible. Inside the template hull it states instance calls of other templates. An exception is a base template that maps it three input arguments to a triple representation (subject, predicate and object). In the OTTR-Language arguments are only passed via their position and not via a name reference, so the names of the arguments are only important for the usage of them inside the template.

An OTTR-Template must be on a page that is inside the Template-namespace and only one template per page is allowed. Other instances outside the template definition are ignored.

Syntax
The signature of a template consists of the template name (that must be equal to the page name, without the Template-Namspace) and the parameter declaration (arguments in the following). The arguments are inside square brackets and are separated by commas. The name of the argument starts with a. For additional parameter/argument features see the table below. The signature and the template hull is connected with double colons. The list of template calls inside the hull are surrounded with curly brackets  and separated by commas. Only the Base template is declared via the template hull:. Template calls inside a template are like the instantiation outside a template only with the difference, that there are arguments from a template signature allowed. The statement ends with a dot.

An example of a BASE Template and a template with 2 inner template calls: ottr:Triple[?subject, ?predicate, ?object] :: BASE. ex:Template_1[?arg1, ?arg2, ?arg3] :: { ottr:Triple(?arg1, ex:PredictateTest1, ?arg2), ottr:Triple(?arg1, ex:PredictateTest2, ?arg3) }.

Appearance
Apart from warnings, errors and OTTR display hints and information, a template definition does not produce any visible text. Display the input variables or other stuff use Layout Annotations, see here

Side Effects
The extension inserts wiki code such that a call from the template page with another OTTR statement produce the from the template declared triples and other template calls. It should check modifiers and restrictions and the execution of the inner template definition should depend on the result of the checks.

Instantiation
Instantiation of OTTR-Templates is the other main usage of the OTTR-language. A template instantiation is written on a normal page. But the syntax is the same for template calls inside templates and annotations.

Syntax
The template name to instantiate and the arguments surrounded by brackets, separated by commas  , and dot is needed for an instantiation. There are additional features for an instance described below, e.g. lists and list expands, none and blank arguments. ex:Template(ex:test, 4, "testString"@en).

Appearance
Besides debug information, hints and information, instances do not produce visible text by default. Added Layout Templates to a template can show the input of the template.

For instances some type depending on templates can produce some information requests to the user to establish the type dependencies. See here.

Side Effects
The idea of instances is to generate the triples from the called templates. So, the results are subobjects with the subobject-category. If errors or warnings occur also the categories.

List Features
OTTR comes with the functionality to handle a set of arguments in lists.

Define a List
Defining a list as an argument or as a default value is quite simple. Elements are surrounded by brackets  and separated by commas. A list can contain any normal input of the underlying position. (1,2,3,4) (ex:elem1, ex:elem2, ex:elem3) (4, ex:elem3, 5.6, false, "test") ((1,1),(1,2),(1,3))

List Expand
To use defined lists in a template, the OTTR-language provides an expand command. In front of a passed list argument, the list expand symbol (two pluses)  is needed for an expand. Furthermore, a list expander command is needed in front of the instance (separated by a vertical bar/pipe ). The three different list expander and their behavior are described in the table below. For every element the code produces an independent fold-out of the described template (repeat the template instantiation for each expand). Writing the list expand symbol inside a template hull, in front of an argument name is also valid, if the argument is a list. The empty list is. zipMin | ex:Template(++(1,2,3,4), ("a number","a symbol"), ++("one", "two", "three", "four")). The first and third argument is expanded. The second argument is passed as a normal argument to every instance in the fold-out. This example would produce 4 instances of the -template, e.g. ex:Template(1, ("a number","a symbol"), "one"). ex:Template(2, ("a number","a symbol"), "two"). ex:Template(3, ("a number","a symbol"), "three"). ex:Template(4, ("a number","a symbol"), "four").

The different list expander only produces different behavior, if there are more than one argument with a list expand symbol.

Blank Node
Using an IRI that is in every instance new generated and is not an argument can be a blank node. There are anonymous blank nodes and named blank nodes. Blank nodes with a name can be used in more than one position because it's the same reference name.

Syntax
Anonymous blank nodes are two square brackets.

A named blank node is an underscore followed by a colon and then the name, e.g..

Appearance
The blank nodes are represented by a name derived from the occurrence call execution path, so they appear inside the subobjects as a long name of page names and numbers. This is due to the idea, that every blank node should be the same in different refreshes and little changes.

Side Effects
The implementation differs from the OTTR description such that  and   do not refer to the same object. As described blank nodes are in this extension pages in the ottr:blank namespace, such that the names of the pages are derived by the execution path (template calls) of an instantiation. Not accepting Blank nodes as an argument can be done with the parameter mode "non-blank"

None Arg
Passing no value to a template means passing the none value. In the current OTTR-version the empty string is not a valid input (even if it is described differently on the website), so pass nothing needs to pass  or.

Syntax
The empty string is not valid. Write  or.

Side Effects
Internal the extension replaces it by the empty string. A template can behave different to a none input. The template can produce no template calls/instances if there is no optional parameter mode for the argument or can produce template calls, if it is present. If the argument/parameter has a default fall back constant, it uses this instead (completely ignoring the optional parameter mode).

The none argument is used in the list expander  for smaller lists.

OTTR-Literals
The OTTR-Languages accepts (in contrast to RDFs) different types of literals (and not only strings). These literals are integers (e.g. ), floats (e.g.   or  ), booleans  and normal strings with language tag or type hints (e.g. "mystring", "good morning"@en, "11-11-2011"@xsd:date). The mapping to the used IRIs for the types is described here.

The extension writes OTTR literals as strings with the type hint in the triple subobjects.

Automated Forms
The extension Page Forms provides user friendly forms that request the input of a template via normal input fields. An adequate form to a template needs information about the arguments of the template, like kind of best fitting input field and name. Also, adding relevant information for a qualified completion of a form, is important, because the named input field often do not display the requested input.

Because of the adaption of the template call via the OTTR parser, a form for OTTR-templates need to add additional arguments or call a template that inserts the arguments in an OTTR statement. The second variant is the chosen one in the extension implementation.

The OTTR Extension provides an automated form generation for a written template. It assumes the form for the template should have the same name as the template only in the Form-namespace. On the template page the parser generates a button 'Create Form' for generating such page. It automatically includes the needed code, and the user only has to click 'Create Page'. If the form page exists, the button disappears and a link to create a page with an instance of the form appears. The appearance of the whole Form Info Part on the template page can be turn off with an adaption of a Template. For a visual example and information see above.

Signatures
The OTTR-syntax accept a signature followed by a dot as a valid statement. Because there is no purpose in the mediawiki domain for this feature, the extension uses it to generate the form code for a template that has the same signature.

The derived information from the signature is used to generate the input field code for the different arguments and some information around it. It displays the existence of parameter modes and default values. Also, the requested type is shown. The parameters/arguments are ordered by their position and the name (without the ) is displayed in front of the corresponding input field.

The different parameter/argument modes are described by:
 * "?": optional argument,
 * "!": not a blank node ([] or _:example),
 * "DFLT": default value available

And are places in front of the input field.

The requested type is written after the input field if it is present in the signature. If a list is requested, the syntax of lists is described.

Input Types
Different requested types produce different input types for the input field supported by the page forms extension.

If no type restriction is added to the parameter, the default input form  is used.

Multi Instances
On one page you can add multiple instances with one form call. Simply by clicking on the "Add another instance"-button and filling the input fields.

Internally it satisfies the restriction of only one OTTR parser call per page.

Multi Templates
You can also add multiple instances from different templates with one form to a page. This is done by writing multiple signatures in the same OTTR call in the form page (all ending with a dot). In the same order the form will give the user the ability to add instances of any template that correlates to one of the present signatures. The number of different templates depend on how many template pages exists with the name, where X starts with 1.

If two or more signatures are present in the OTTR form call, none of them will have an empty instance by default when creating a new page.

Drawbacks of Using Forms
Currently it does not display the additional information from the parser to the instances, mainly because of the usage of &lt;noinclude&gt; tags.

Default Forms
The template name of the first signature in the form is used to add a default form to the form with the same name and an edit with form link appears on pages that are created with the form.

Example
The signature of the namedPizza example from above looks like the following:

Implementation Details
The mediawiki representations of the OTTR features are described TODO Help:Extension:OttrParser/ImplementationDetails.

You can change the Error and Warning box appearance by changing the template 'Template:ottr:ErrorMsg', maybe by simple calling a note template or other boxes.

Errors
If an internal unexpected Python Exception occurs the stack trace is printed out on the page.

There are several input errors, that are communicated to the user with a red Error box (the error code numbers are currently somewhat messy).

Warnings
There are several warnings, that are communicated to the user with a red Warning box.

Type Inferencing
Type checks added via type hint to strings and the types of parsed literals are done without the category feature (inside the extension code). Also the ottr:IRI check is also done and the List and NEList check.

The inferencing of types is currently not a feature of the semantic media wiki. The category inferencing comes close to the subClassOf feature and type relation. But to establish this connection to the different IRIs is not done via a simple wikicode on arbitrary pages. It needs the  on the page equal to the IRI or the Category equal to the Class name. If these pages are not the current page the extension writes the code on, it displays the user a request to add text to these pages. If the pages are not created, it displays a button that fills the edit page of a new page with the needed content. The wikicode for such behavior is written in the following templates:
 * Template:ax:SubClassOf
 * Template:ax:Type

So, it is recommended to use these templates, if the type restriction in other templates is necessarily.

The LUB type check checks if the written Category on the page is equal to the requested type (so it tries to not use the inferencing).

Task for the user
Before all checks the templates has code for checking, if the needed Code is already on such pages or not (by ask queries of the smw extension)

Type
The type relation is established by put the Category declaration on the normal page of the IRI inside the wiki. If the instance page name is equal to the IRI, the ax:Type template writes the Category silently. If not, it displays an instruction or a button for an easy creation of the page with the Category declaration per preload inside the edit field. For correct type checking add on page  tt:TypeTest1 :
 * Page does exist (tt:TypeTest1), but is not the current page:
 * Page does not exists:

SubClassOf
To establish the SubClassOf relation it is necessarily to get the SubCategory relationship, by adding the Category of the SubClass to the Category Page of the "ParentClass": Please add  to page Category:tt:testSubClass for correct type checking.
 * If the Category page of the ParentClass (tt:testSubClass) already exists such text occurs:
 * If the Category page does not exist:

Set Layout Template via Annotations
If a called annotation template lies in the Layout namespace, the extension adds some other arguments to the called annotation instance, that depend on the arguments of the defined template:
 * with the value 1
 * with the value equivalent to the number of arguments of the template.

And for every argument (X from 1 to ):
 * the name of the Xth parameter (defined in the template) with the question mark in front of it.
 * the passed value of the Xth argument.
 * 1 or 0 if the default value is used in the instance of the template.

For example, add an annotation with  with the template name as the first argument (here ex:mytemplate on the page Template:ex:mytemplate).

Ideas for Future Versions
A better type inferencing and type relation saving. Maybe also via subobjects but the hiearchy with the subClassOf relationship is not clear.

Knwon Problems

 * The SMW Extension does not accept special characters in the subobject like . Do not use them in string literals.
 * The nesting depth of templates can be limited in use, due to the execution/parsing depth of the wiki.