.. _reference: Reference manual ================ This reference manual is work in progress. .. _declaring-namespaces: Declaring namespaces -------------------- Namespace prefixes are declared as *global* variables, whose name is ``t4rns:prefix``, and whose value is the namespace URI. Note that literal values in TALES must start with the ``string:`` keyword. Note also that variable declaration are separated by semicolons. Example:: ... .. _node-list-operators: RDF Path BNF ------------ NB: For making this BNF less verbose, the slashes separating the tokens in the TALES expression are not represented. Note in particular that absolute paths (``AbsPath``) start with an empty token so that the TALES expression actually starts with a slash. :: RDFPath :- AbsPath | RelPath | CompoundPath AbsPath :- "" StartStep RelPath? RelPath :- Step+ DataOp? CompoundPath :- (AbsPath | RelPath) BinaryOp StartStep RelPath? StartStep :- Curie ("or" Curie)* Step :- XCurie ("or" XCurie)* | NodeOp Curie :- (Any standard CURIE) XCurie :- (Any standard or inverted (with ":-") CURIE) DataOp :- (see list below) NodeOp :- (see list below) BinaryOp :- (see list below) Operators --------- .. contents:: :local: any ^^^ :type: NodeOp :result: node list (1 node) :pre-condition: none Only keep the first node from the list. NB: except in a few cases, the order of the lists is not significant, so any may return different values on different rendering of the template. NB: if the node list is empty, any will cause an error rather than returning a single path. This allows to use it in conjunction with TAL's ``|`` operator. asInversePath ^^^^^^^^^^^^^ :type: DataOp :result: text :pre-condition: none Same as asPath, but appends ``:-`` after each CURIE. asPath ^^^^^^ :type: DataOp :result: text :pre-condition: none Tries to convert a node list into the corresponding path. This is useful with the question-mark syntax of TAL. Only URI-ref nodes, that can be expressed as CURIEs with the current namespaces, are included in the list. blanks ^^^^^^ :type: NodeOp :result: node list (only blank nodes) :pre-condition: none Only keeps the blank nodes from the node list. contains ^^^^^^^^ :type: BinaryOp :result: boolean :pre-condition: none Evaluates to *true* if the left hand node list and the right hand node list have at least one node in common. NB: although *intersect* would have seemed a more exact name, *contains* seems more suited to common uses of this operator, like:: tal:condition="some_node/rdf:type/contains/owl:Class" convert ^^^^^^^ :type: DataOp :result: *depends* (see below) :pre-condition: single literal Tries to convert the literal to a builtin data, according to its datatype. count ^^^^^ :type: DataOp :result: integer :pre-condition: none Counts the number of nodes in the node list. datatype ^^^^^^^^ :type: NodeOp :result: node list (0 or 1 uri-ref) :pre-condition: a single literal node Evaluates to the datatype, if any, of the literal. id ^^ :type: DataOp :result: text :pre-condition: a single node, blank or URI-ref Evaluates to the identifier part of the node, i.e. what would be used as the suffix of the CURIE. isBlank ^^^^^^^ :type: DataOp :result: boolean :pre-condition: a single node Evaluates to true if and only if the node is blank. isLiteral ^^^^^^^^^ :type: DataOp :result: boolean :pre-condition: a single node Evaluates to true if and only if the node is a literal. isURIRef ^^^^^^^^ :type: DataOp :result: boolean :pre-condition: a single node Evaluates to true if and only if the node is a URI-ref. iterList ^^^^^^^^ :type: NodeOp :result: node list (sorted) :pre-condition: a single node, well formed ``rdf:List`` Iter over the items of the ``rdf:List``. iterSeq ^^^^^^^ :type: NodeOp :result: node list (sorted) :pre-condition: a single node Iter over the ``rdf:li`` properties of the node. link ^^^^^ :type: NodeOp :result: single URIref :pre-condition: none Tries to extract form parameters to generate a URL applying the same template to the resource identified by this URI-ref. TODO: make the documentation clear about what happens for graph templates, resource templates without graph, resource remplates with graph literals ^^^^^^^^ :type: NodeOp :result: node list (only literals) :pre-condition: non Only keeps the literal nodes from the node list. n3 ^^ :type: DataOp :result: text :pre-condition: single node Evaluates to the N3 syntax for the node (useful for literals, that will render by default just as their value). ns ^^ :type: NodeOp :result: node list (single URI-ref node) :pre-condition: single node, URI-ref Evaluates to the namespace part of the URI-ref, as a node. Useful to check that two resources belong to the same namespace with ``r1/ns/contains/r2/ns``. renderWith ^^^^^^^^^^ :type: BinaryOp :result: text :pre-condition: the first operand must evaluate to a single node, the second operand must evaluate to a single URI-ref Retrieve the RHS resource, and use it as a template to render the LHS resource. NB: do not forget the TAL keyword ``structure`` whenever the invoked template produces HTML or XML tags, or those tags will be escaped and rendered as is. selectLang ^^^^^^^^^^ :type: NodeOp :result: node list (only literals) :pre-condition: none Tries to extract HTTP ``Accept-language`` information from the context, and select from the node list the literals that best match this directive. text ^^^^ :type: DataOp :result: text :pre-condition: single node, literal Evaluates to the value of the literal. uri ^^^ :type: DataOp :result: text :pre-condition: single node, URI-ref Evaluates to the URI of that node (usually, URI-ref nodes are rendered as CURIEs or within angle brackets). URIRefs ^^^^^^^ :type: NodeOp :result: node list (only uri-ref) :pre-condition: non Only keeps the URI-ref nodes from the node list. .. _context-variables: Context variables ----------------- graph ^^^^^ TODO: The RDF graph. It has an attribute ``size`` returning the number of triples. It is iterable (usable with ``tal:repeat``), and yields triples with attributes ``subject``, ``predicate``, ``object`` and ``s``, ``p``, ``o`` for short. Those attributes are nodes that can be used as any other node. .. _t4r-display: t4r:display ^^^^^^^^^^^ By default, a path evaluating to multiple nodes will display as one of those nodes; a path evaluating to no node will not display at all (see `why `:ref:). If ``t4r:display`` is set to ``string:strict``, then a path evaluating to *n* nodes with *n*\ ≠1 will display as the special string ``{n nodes}``. Although less usable, this makes debugging of templates more convenient. TODO