Versa

A resource is a reference to a node or a literal in the data model. The actual form of the reference is left to the implementation, however, these can be thought of as the blank nodes allocated to the node or literal based on Simple entailment [SEMANTICS].

A node is reference to a named or unnamed node in the model.

A literal is reference to a literal in the model.

A statement represents an arc in the model.

A heterogeneous ordered collection of any data type (including other lists or sets). Duplicates are allowed.

A heterogeneous unordered collection of any data type (including other sets or lists), with no duplicate values. See the section on equality for a definition of how members of a set are computed to be equal.

A sequence of zero or more characters, as defined in the XML 1.0 recommendation. Versa strings are similar to XPath strings.

Versa numbers are the same as XPath numbers: positive or negative floating-point numbers, based on the rules and semantics for double precision, 64-bit numbers in IEEE 754.

Boolean types represent logical truth or falsehood. As such there are two boolean literals: true and false.

When any datatype is converted to a list or set, the results is a list or set of length one with that value as the only member.

When a list is converted to another data type (besides set) the first item in the list is converted to that data type. If the list is empty, the results are null. When a list is converted to a set it produces a set with the same entries as the list, except that if there are duplicate values, any equivalent values following the first are omitted (e.g. set(list(1,2,1)) = set(1,2))

When a set is converted to any data type it is first converted to a list, then the list conversions are applied. As sets are unordered it is not gaurenteed that two subsequent conversions to list will produce the same results. As an example, the following may not always be true string(list(1,2)) = string(list(1,2))

A node query is a query to retrieve a specific node from the scope. If the node specified exists in the scope, then the results of the query are the set containing that node. If the node does not exist in the scope, then the results are an empty set.

There are two different forms of resource query, the first is an absolute URI queryand is specified using the "<" and ">" tokens surronding the URI. In addition, an implementation may support the deprecated uri query of the form @"URI".

The second form of resource query is using a qname. The prefix of the qname is resolved using the set of in scope namespaces mappings (see the section below on variables and namespaces) and converted to a absolute URI query. If the specified prefix is not defined then the results of the query are the empty set.

The following are examples of node queries:

Note that the lexical rules of XML QNames may limit the situations in they may be used in Versa. For instance, if the URIs are UUIDs in URN form. The full form can always be used to express any valid URI.

Absolute URIs support the escaping of unicode characters. See the section on string escaping for more details.

Similar to node queries, literal queries return a list of zero or more literals from the scope. If the specified literal is not in the scope then the results are an empty set. A literal query allows you to specify a string value and an optinal language or datatype to match against.

As a shortcut, queries for boolean and number values can use the simplified syntax. The processor will convert the short-cut value into an appropriate literal (by the conversion rules) and use that for the query.

When used are arguments to function calls, literals are interpreted as literal values, not as queries. If you would like to pass the results of a literal query to a function, see the query method.

Below are some examples of literal queries.

4.6.2.1. String Escaping

The forward traversal operator matches patterns based on given sets of subjects and predicates. It returns a list of resulting objects. It takes the following form:

set-expression - set-expression -> filter-expression
        

The forward filter operator matches patterns based on given sets of subjects and predicates. In contrast to the forward traversal operator, it returns a list of the subjects that result from the patterns rather than the objects. It takes the following form:

set-expression |- set-expression -> filter-expression
        

In both cases the first set-expression is a evaluated to obtain list (cast if need be) which are the subjects of statements. Each of these resources is set as the context for evaluating the second set-expression, which is treated as a list of predicates(cast if need be). All statements in the model with these subjects and predicates are marked as candidate statements. The object of each of the candidate statements is evaluated as the context of the filter-expression.

In the case of forward traversal, if the result, after conversion to boolean type, of evaluating the filter-expression is true, the object is added to the list of results. In the case of forward filtering, if the result, after conversion to boolean type, of evaluating the filter-expression is true, the subject of the corresponding statement is added to the list of results.

Unless an ordering aggregate function (see below) is used, the order of the resulting elements in the list is undefined in Versa, and is determined by the underlying model.

The backward traversal operator is similar to the forward traversal operator, but it is used to match patterns using the inverses of predicates. A backward traversal expression takes the following form:

filter-expression <- set-expresion - set-expression
        

The backward filter operator is similar to the forward filter operator, but it is used to match patterns using the inverses of predicates. A backward filter expression takes the following form:

filter-expression <- set-expression -| set-expression
        

In both cases, the first set is a set of resources which are the objects of statements, the predicates of which are given by the resources in the second set expression. In the case of traversal, the results are a list of matching statements, and the subject of each statement is evaluated as the context of the boolean expression. If the result, after conversion to boolean type, is true, the subject is added to the list of results. Conversions are automatically applied, as with forward traversal expressions. In the case of filter, the results are the objects of the original statements.

Versa provides a set of special functions which are designed to be used within traversal operations to transform partial results within the context of the traversal.

4.7.3.1. sortq

sortq(set, expression [, vsort:number | vsort:string [, vsort:ascending | vsort:descending ] ])
         

Editor's note: Are there any others that cannot be expressed as operations on the result list? Grouping primitives, perhaps.

Existential expressions are away to all optimizers signal that ahe source expression is over the set of all resources in the model. In all four cases, the expression could be rewritten by addind all() as the missing expression. So the exitensial expression

 [ - rdf:type -> rdfs:Class ] 

is evaluated as

 all() - rdf:type -> rdfs:Class 

list(expression)
        

Convert the expression into a list.

set(expression)
        

Convert the expression into a set

boolean(expression)
        

Return the boolean value of the argument

string(expression)
        

Return the string value of the argument

literal(expression)
        

Convert the expression to a literal.

node(expression)
        

Create a resource. The expression is converted into a string, and that string is used to as a URI to query the model.

number(expression,[,datatype])
        

If a single argument is passed, then convert the expression to a number as defined above. If to arguments are passed, then the expression if converted to a string, and the underlying model is asked to convert this to a number based on the data type. If the underlying model does not support this then the conversion is completed assuming the datatype argument was not passed.

statement(expression)
        

Convert the expression into a statement.

all()
        

Returns a set of all resources in the model. This method should be used with care. For a subset of resources, use a pattern. In a traversal or filter use the wild card pattern instead.

distribute(list,
           query,
           [query, [...]])
        

distribute converts the first argument into a list. The second and subsequent arguments (the query arguments) are anonymous functions or function references. It uses each item in the list as the sole argument for evaluating each of the query arguments. The result is a list of lists; each entry in the outer list is a list containing the results from evaluating each of the query arguments in order using the Nth list item as context.

For example, the query:

distribute(["a", "ab"], &string-length, (! x  : concat("c-", $x)))
        

returns

[[1, "c-a"], [2, "c-ab"]]
        

The outer list is of length two because there are two items in the first argument. Each inner list has two items because there are that many query arguments.

map(function-reference, list1, [listn, [...]])
        

The first argument to map is a function-reference or an anonymous function which will be evaulated with an argument set computed from the context set. To compute the argument set, the ith item is taken from each list. These then form the arguments, in the order of the list epxressions, that are given to the function reference. The processes will be performed as many times as the length of the longst list. Shorter lists will be padded with "null" value.

The result are a list of values, as long as the longest item in the list from the list expression arguments.

As an example, the query:

map(&concat, ["A", "B", "C"], ["1", "2"])
        

Is equivilent to

[concat("A","2"), concat("B", "2"), concat("C",null)]
        

and will return a list of length 3:

["A1", "B2", "C"]
        

And the query:

map((! x : $x-h:formatted-name->*), h:principia-h:author->*)
        

Returns the formatted name of the author of the book identified as "h:principia", and thus in our sample model would return

["Isaac Newton"]
        

This is equivalent to the chained traversal expression

h:principia - h:author -> * - h:formatted-name -> *
        

filter(list, query, [query, [...]])
        

filter converts the first argument into a list (the source list). The second and following arguments are either function referenceas or anonymous functions. Each query is called once per item in the list with that item as the only argument. If the all queries return true, then the list item is added to the result set.

sort(list, conversion=&string, direction=$versa:ascendind )
        

The first argument is converted to a list or a set. The result is the list obtained by sorting according to the given criteria. The second parameter indicates the conversion function that should be applied to each item before sorting. It must be a function reference or a anonymous function.

The default is the string conversion function. The third parameter indicates the direction of sorting. The system variables versa:ascending and versa:descending are used to determine the direction. The default is ascending.

union(set, set)
        

Both arguments are converted to sets, and the result is a set consisting of all items that are in either argument set.

intersection(set, set)
        

Both arguments are converted to sets, and the result is a set consisting of all items that are in both argument sets.

difference(set, set)
        

Both arguments are converted to sets, and the result is a set consisting of items that are in he first set but not in the second (set difference).

join(list[, list, [...]])
        

Each argument is converted to a list, and the result is a list which consists of the concatenation of all the argument lists in order.

statements(subject,predicate,object,result-type = $versa:object-result)
        

The statements function is the functional equivilant of the traversa and filter operators with the caveats listed below. Each of the first three arguments is interpreted as follows (based on its type).

similar to the operators, the statements function allows the dot expression, and the traversal variables available as arguments. It should be noted though that since function arguments are evaulated at in the containing scope of the function, these need to be wrapped in anonymous functions to have the identical meaning of the operators. As an example, the following are equivilent:

  all() - eq($versa:subject,"http://foo.com") -> lt(.,13)

and

  statements(all(), (! : eq($versa:subject,"http://foo.com")), (! x : lt($x,13)))

It is an error to pass a function reference, or anonymous function, that requires more then 1 parameter. If the reference takes zero parameters, then it is called without params. If the reference takes a single argument, then it is passed dot.

add(number,number [,number2 ... ])
        

Converts all arguments into numbers and returns the result of adding all of the together.

sub(number ,number)
        

Converts all arguments into numbers and returns the result of subtracting the two..

mul(number,number [,number2 ... ])
        

Converts all arguments into numbers and returns the result of multiplying all of the together.

div(number ,number)
        

Converts all arguments into numbers and returns the result of dividing the two..

sum(list )
        

Converts the argument into a list, then returns the results of converting each argument to a number and adding them all together.

floor(number )
        

Returns the largest (closest to positive infinity) number that is not greater than the argument and that is an integer..

ceiling(number )
        

Returns the smallest (closest to negative infinity) number that is not less than the argument and that is an integer..

round(number )
        

Returns the number that is closest to the argument and that is an integer. If there are two such numbers, then the one that is closest to positive infinity is returned. If the argument is NaN, then NaN is returned. If the argument is positive infinity, then positive infinity is returned. If the argument is negative infinity, then negative infinity is returned. If the argument is positive zero, then positive zero is returned. If the argument is negative zero, then negative zero is returned. If the argument is less than zero, but greater than or equal to -0.5, then negative zero is returned.

length(list)
        

Converts the argument to a list and returns the number of items in the list. If the argument cannot be converted to a list, then null is returned.

string-length(string)
        

The number of characters in the string is returned. If the argument cannot be conterted into a string, then null is returned.

find-regex(string , regex,versa:ignore-case = false)
        

The regex string is interpreted as a POSIX Simple Regular Expression [PSRE] and the return value is the first index at which it is matched in the string. If the versa:ignore-case flag is evaulates to a boolean true, then the regular expression is matched without regard to the case of alphabetic characters. If there is no regular expression match at all, the return value is -1. If the first argument cannot be converted to a string, or the second cannot be converted to a string then null is returned. It is a runtime error if the regex is invalid.

concat(string, string2, [...]])
        

Each argument is converted to a string, and the result is a string which consists of the concatenation of all the arguments in order.

substring-before(string , string)
        

Convert all arguments to strings. Return the substring of the first argument that precedes the first occurrence of the second argument, or the empty string if the first argument does not contain the second.

substring-after(string, string)
        

Convert all arguments to strings. Return the substring of the first argument that succeeds the first occurrence of the second argument, or the empty string if the first argument does not contain the second.

canonical(literal)
        

Convert the literal into a string that is the canonical form of the literal. This assumes that the underlying model support data types and that the literal is datatypes. If not, then the string value of the literal is returned, or null if the argument is not a literal.

language(literal)
        

Return the language of the literal. If the literal is typed the results are null. If the parameter is not a literal, the results are null. If the argument is a literal without a language, the results are the emty string.

datatype(literal)
        

Return the datatype of the literal. If the literal is not typed or the argument is not a literal, then the null value is returned.

ground(constant)
        

Map the constant value into a resource in the datamodel. If the constant represents a URI, then return the node for this URI. If the resource is a literal, then return the literal for the constant. All other parameters result in null.

and(boolean[, boolean, [...]])
        

Return true if the boolean values of all the arguments are true.

or(boolean[, boolean, [...]])
        

Return true if the boolean value of one or more arguments are true

not(boolean)
        

If the boolean value of the argument is true, return false, otherwise return true.

is-resource(value)
        

Return true if the argument is a resource.

is-literal(value)
        

Return true if the argument is a literal.

is-node(value)
        

Return true if the argument is a node.

lt(number , number )
        

Return true if the first is less than the second (after both have been converted to numbers). Otherwise return false.

gt(number  , number)
        

Return true if the first is greater than the second (after both have been converted to numbers). Otherwise return false.

lte(number [ , number ])
        

Return true if the first is less than or equal the second (after both have been converted to numbers). Otherwise return false.

gte(number , number )
        

Return true if the first is greater than or equals the second (after both have been converted to numbers). Otherwise return false.

eq(expression , expression )
        

Return true if the first expression is equal the second expression.

neq(expression , expression)
        

Return true if the first expression is not equal the second expression.

member(list , value )
        

Return true if the value is a member of the list.

starts-with(string , string)
        

Return true if the string value of the first argument starts with the value of the second.

contains(string , string, ignore-case = false)
        

Return true if the string value of the second argument is a substring value of the first.