| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
| <book> |
| <title>XPath 2.0 Processor User Manual</title> |
| |
| <chapter id="Introduction"> |
| <title>Introduction</title> |
| |
| <para>What is PsychohPath? PsychoPath is a XPath 2.0 XML Schema Aware |
| processor. It is nearly fully compliant to the XPath 2.0 test suite. It is |
| a library that does not require eclipse to be used. Known adopters of |
| PsychoPath include the Xerces-J project for XML Schemas 1.1 assertion |
| support.</para> |
| |
| <para>PsychoPath is the only known open-source java XPath 2.0 processor |
| that is fully schema aware. SAXON HE only supports the core functionality. |
| XML Schema awarness provides tighter static checking, and can be used to |
| help determine if certain operations can or should occur on an XML node. |
| For a detailed description of the PsychoPath's design please see the |
| <ulink url="/PsychoPathXPathProcessor/Design">design</ulink> |
| document.</para> |
| |
| <section id="Getting_PsychoPath"> |
| <title>Getting PsychoPath</title> |
| |
| <para>Currently there is no standalone build of PsychoPath. However, you |
| can download the <ulink |
| url="http://download.eclipse.org/webtools/downloads/drops/R3.1/R-3.1-20090616035105/">WTP |
| WST 3.1</ulink> zip file, and use the |
| org.eclipse.wst.xml.xpath2.processor.jar file. This jar has no |
| dependencies on eclipse, and will work as a standard jar file. If you |
| are using an OSGI container, then this is treated as a standard OSGI |
| bundle.</para> |
| |
| <tip> |
| <title>PsychoPath 1.1M1</title> |
| |
| <para>PsychoPath 1.1M1 is also available to <ulink |
| url="http://download.eclipse.org/webtools/downloads/drops/R3.2/S-3.2M1b-20090814143519/">download</ulink>. |
| 1.1M1 passes 96% of the XPath 2.0 test suite.</para> |
| </tip> |
| |
| <para>Additional dependencies you currently need are:</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>IBM ICU 4.0 or greater</para> |
| </listitem> |
| |
| <listitem> |
| <para>Xerces 2.8.0 or greater</para> |
| </listitem> |
| |
| <listitem> |
| <para>JavaCup 0.10 or greater.</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>If using eclipse, these are all available from the Orbit project. |
| Others can find the necessary jars from their respective project |
| pages.</para> |
| </section> |
| </chapter> |
| |
| <chapter id="How_to_feed_Psychopath_XPath_expressions"> |
| <title>Using PsychoPath XPath 2.0 API</title> |
| |
| <para>Since PsychoPath has been implemented as an external library and not |
| as a complete program, in order to use it, it needs to be accessed from |
| inside another program. To process XPath 2.0 expressions using PsychoPath |
| from another programs one needs to go through the following |
| process:</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>Load the XML document</para> |
| </listitem> |
| |
| <listitem> |
| <para>Optionally validate the XML document</para> |
| </listitem> |
| |
| <listitem> |
| <para>Initialize static and dynamic context in respect to the document |
| root</para> |
| </listitem> |
| |
| <listitem> |
| <para>Parse the XPath 2.0 expression</para> |
| </listitem> |
| |
| <listitem> |
| <para>Statically verify the XPath 2.0 expression</para> |
| </listitem> |
| |
| <listitem> |
| <para>Evaluate the XPath 2.0 expression in respect to the XML |
| document</para> |
| </listitem> |
| </orderedlist> |
| |
| <para>To give a better idea of how this process actually works, we’ll go |
| through an example of processing and evaluating the string expression |
| “Hello World!”. In this example the XML document that we load is called |
| “XPexample.xml”.</para> |
| |
| <section id="Non-Schema_Aware"> |
| <title>Non-Schema Aware</title> |
| |
| <programlisting>/** |
| * First load and optionally validate the XML document |
| */ |
| // Create an InputStream from the XML document |
| InputStream is = new FileInputStream(“XPexample.xml”); |
| |
| // Initializing the Xerces DOM loader. |
| DOMLoader loader = new XercesLoader(); |
| |
| // Optionally set flag to validate XML document loader.setvalidating(validate); |
| // Loads the XML document and stores the DOM root |
| Document doc = loader.load(is); |
| |
| /** |
| * Dynamic contexts must be initialised to defaults |
| * dependent on the XML Schema. |
| */ |
| |
| // Extracting the schema from DOM root of Xpexpression.xml. |
| ElementPSVI rootPSVI = (ElementPSVI)doc.getDocumentElement(); |
| XSModel schema = rootPSVI.getSchemaInformation(); |
| |
| // Initialising the DynamicContext. |
| DynamicContext dc = new DefaultDynamicContext(schema, doc); |
| |
| // Register the namespaces of the XPath 2.0 predefined datatypes |
| dc.addnamespace(“xs”,”[http://www.w3.org/2001/XMLSchema http://www.w3.org/2001/XMLSchema]”); |
| |
| // Register the XPath 2.0 standard functions |
| dc.addfunctionlibrary(new FnFunctionLibrary()); |
| dc.addfunctionlibrary(new XSCtrLibrary()); |
| |
| /** |
| * Parsing the XPath 2.0 expression into an AST representation |
| */ |
| // Initialises PsychoPath’s supplied parser. |
| XPathParser xpp = new JflexCupParser(); |
| |
| // Parses the XPath expression. |
| XPath xp = xpp.parse(xpath); |
| /** |
| * Static check the AST to verift structural validity of |
| * XPath 2.0 expression |
| */ |
| |
| // Initializing StaticChecker. |
| StaticChecker namecheck = new StaticNameResolver(sc); |
| |
| // Static Checking the Xpath expression ’Hello World!’ namecheck.check(xp); |
| /** |
| * Evaluate the XPath 2.0 expression |
| */ |
| |
| // Initializing the evaluator with DynamicContext and the name |
| // of the XML document XPexample.xml as parameters. |
| Evaluator eval = new DefaultEvaluator(dc, doc); |
| |
| // Evaluates the XPath 2.0 expression, storing the result |
| // in the ResultSequence |
| ResultSequence rs = eval.evaluate(xp); |
| </programlisting> |
| </section> |
| |
| <section id="Schema_Aware"> |
| <title>Schema Aware</title> |
| |
| <para></para> |
| |
| <programlisting>/** |
| * First load and optionally validate the XML document |
| */ |
| |
| SchemaFactory schemaFactory = new XMLSchemaFactory(); |
| URL schemaURL = new File("XPexample.xsd").toURL(); |
| Schema jaxpschema = schemaFactory.newSchema(schemaURL); |
| |
| // Create an InputStream from the XML document |
| InputStream is = new FileInputStream(“XPexample.xml”); |
| |
| // Initializing the Xerces DOM loader. |
| DOMLoader loader = new XercesLoader(jaxpschema); |
| |
| // Optionally set flag to validate XML document loader.setvalidating(validate); |
| // Loads the XML document and stores the DOM root |
| Document doc = loader.load(is); |
| |
| /** |
| * Dynamic contexts must be initialised to defaults |
| * dependent on the XML Schema. |
| */ |
| |
| // Initialising the DynamicContext. |
| DynamicContext dc = new DefaultDynamicContext(jaxpschema, doc); |
| |
| // Register the namespaces of the XPath 2.0 predefined datatypes |
| dc.addnamespace(“xs”,”[http://www.w3.org/2001/XMLSchema http://www.w3.org/2001/XMLSchema]”); |
| |
| // Register the XPath 2.0 standard functions |
| dc.addfunctionlibrary(new FnFunctionLibrary()); |
| dc.addfunctionlibrary(new XSCtrLibrary()); |
| |
| /** |
| * Parsing the XPath 2.0 expression into an AST representation |
| */ |
| // Initialises PsychoPath’s supplied parser. |
| XPathParser xpp = new JflexCupParser(); |
| |
| // Parses the XPath expression. |
| XPath xp = xpp.parse(xpath); |
| |
| /** |
| * Static check the AST to verift structural validity of |
| * XPath 2.0 expression |
| */ |
| |
| // Initilising StaticChecker. |
| StaticChecker namecheck = new StaticNameResolver(sc); |
| |
| // Static Checking the Xpath expression ’Hello World!’ namecheck.check(xp); |
| /** |
| * Evaluate the XPath 2.0 expression |
| */ |
| |
| // Initialising the evaluator with DynamicContext and the name |
| // of the XML document XPexample.xml as parameters. |
| Evaluator eval = new DefaultEvaluator(dc, doc); |
| |
| // Evaluates the XPath 2.0 expression, storing the result |
| // in the ResultSequence |
| ResultSequence rs = eval.evaluate(xp); |
| </programlisting> |
| |
| <para>XPath 2.0 defines everything to be a sequence of items, including |
| the arguments to expressions and the result of operations. Thus, the |
| overall result of an XPath expression evaluation is also a sequence of |
| items. PsychoPath uses the class ResultSequence as a Collections wrapper |
| to store these sequences and therefore, the result of an evaluation is |
| of this type also. The ResultSequence consists of zero or more items; an |
| item may be a node or a simple-value. “Hello World!” is an example of a |
| single value with length 1. A general sequence could be written as (“a”, |
| “s”, “d”, “f”).</para> |
| |
| <para>Extraction of certain items from the ResultSequence class is |
| described below, with details of the different operations that one might |
| apply on the ResultSequence. Consider that ’rs’ is the ResultSequence, |
| then:</para> |
| |
| <para></para> |
| |
| <programlisting>// Will return the number of elements in the sequence, in this |
| // case of ’Hello World!’ expression size = 1. |
| rs.size(); |
| |
| // Will return the n’th element in the sequence, in this case of |
| // ’Hello World!’, if n = 1, then it will return |
| // XSString of “Hello World!”, but if n = 2, it will return |
| // Empty Result. |
| rs.get(n); |
| |
| //Will return true if the sequence is empty. |
| rs.empty(); |
| |
| // Will return the first element of the sequence, |
| // in this example it will return XSString of “Hello World!” |
| rs.first() |
| </programlisting> |
| |
| <para>However, all the items extracted will be of the type’s base class |
| AnyType and need to be casted into its actual subtype.</para> |
| |
| <para>Certain operations always return a particular type and using this |
| knowledge, the extracted item can be immediately casted. In our example |
| “Hello World!” returns a string (easily known as it is inside the quotes |
| ’ ’ ), so this can safely be casted as such:</para> |
| |
| <para><programlisting>XSString xsstring = XSString)(rs.first());</programlisting>The |
| actual result can now be extracted from this XSString in the following |
| manner: <programlisting>String str = xsstring.value();</programlisting></para> |
| |
| <para>The details of how to cast extracted items from AnyType into their |
| actual subtypes with examples is in the next section on How to use each |
| production in the grammar.</para> |
| |
| <para>However, if the expected return type is unknown or multiple types |
| are possible, the types hierarchy can be traversed in a breadth first |
| manner making use of the Java instanceof operator to ascertain the |
| actual type. </para> |
| </section> |
| |
| <section id="How_to_use_the_XPath_2.0_grammar_with_PsychoPath"> |
| <title>How to use the XPath 2.0 grammar with PsychoPath</title> |
| |
| <para>In this section we will try to give you an overview of the XPath |
| 2.0 grammar in general and how each production in the grammar should be |
| used with PsychoPath. For the formal specifications, see the W3C |
| web-site for XPath 2.0 specification <ulink |
| url="http://www.w3.org/TR/xpath20">http://www.w3.org/TR/xpath20</ulink>.</para> |
| |
| <section id="Constants"> |
| <title>Constants</title> |
| |
| <para>String literals are written as “Hello” or ‘Hello’. In each case |
| the opposite kind of quotation mark can be used within the string: ‘He |
| said “Hello” ’ or “London is a big city”. To feed PsychoPath, “ ‘Hello |
| World!’ ”or “ “Hello World!” ” can be used to feed it with strings. |
| Remember that the ResultSequence returns AnyType so since a string is |
| being expected as the result, first it has to be casted in the code |
| like this: <programlisting>XSString xsstring = (XSString)(rs.first());</programlisting> |
| Numeric constants follow the Java rules for decimal literals: for |
| example, 4 or 4.67; a negative number can be written as -3.05. The |
| numeric literal is taken as a double precision floating point number |
| if it uses scientific notation (e.g. 1.0e7), as a fixed point decimal |
| if it includes a decimal point, or as an integer otherwise. When |
| extracting number literals from the ResultSequence, possible types to |
| be returned include <emphasis role="italic">XSDecima''l (e.g. : |
| xs:decimal: 4.67),''XSInteger ''(e.g. : xs:integer: 4) or |
| ''XSDouble</emphasis> (e.g. : xs:double 1e0). All of which need to be |
| cast in the same manner as stated before: from AnyType to their |
| corresponding types.</para> |
| |
| <para>There are no boolean constants as such: <emphasis |
| role="italic">true, false</emphasis> instead the function calls |
| <emphasis role="bold">true()</emphasis> and <emphasis |
| role="bold">false()</emphasis> are used.</para> |
| |
| <para>Constants of other data types can be written using constructors. |
| These look like function calls but require a string literal as their |
| argument. For example, <emphasis |
| role="bold">xs:float(“10.7”)</emphasis> produces a single-precision |
| floating point number.</para> |
| </section> |
| |
| <section id="Path_expressions"> |
| <title>Path expressions</title> |
| |
| <para>A path expression is a sequence of steps separated by the |
| <emphasis role="bold">/''' or '''//</emphasis> operator. For example, |
| <emphasis role="bold">../@desc</emphasis> selects the desc attribute |
| of the parent of the context node.</para> |
| |
| <para>In XPath 2.0, path expressions have been generalized so that any |
| expression can be used as an operand of <emphasis |
| role="bold">/</emphasis>, (both on the left and the right), as long as |
| its value is a sequence of nodes. For example, it is possible to use a |
| union expression (in parentheses) or a call to the id() |
| function.</para> |
| |
| <para>In practice, it only makes sense to use expressions on the right |
| of <emphasis role="bold">"/"</emphasis> if they depend on the context |
| item. It is legal to write $x/$y provided both $x and $y are sequences |
| of nodes, but the result is exactly the same as writing <emphasis |
| role="bold"> <emphasis role="italic">./$y</emphasis> |
| </emphasis>.</para> |
| |
| <para>Note that the expressions <emphasis role="bold">./$X</emphasis> |
| or <emphasis role="bold">$X/.</emphasis> can be used to remove |
| duplicates from <emphasis role="bold">$X</emphasis> and sort the |
| results into document order.</para> |
| |
| <para>The operator <emphasis role="bold">//</emphasis> is an |
| abbreviation for <emphasis |
| role="bold">/descendant-or-self::node()</emphasis>. An expression of |
| the form <emphasis role="bold">/E</emphasis> is shorthand for |
| <emphasis role="bold">root(.)/E</emphasis>, and the expression |
| <emphasis role="bold">/''' on its own is shorthand for |
| '''root(.)</emphasis>.</para> |
| </section> |
| |
| <section id="Axis_steps"> |
| <title>Axis steps</title> |
| |
| <para>The basic primitive for accessing a source document is the axis |
| step. Axis steps may be combined into path expressions using the path |
| operators "/" and "//", and they may be filtered using filter |
| expressions in the same way as the result of any other |
| expression.</para> |
| |
| <para>An axis step has the basic form axis::node-test, and selects |
| nodes on a given axis that satisfy the node-test. The axes available |
| are:</para> |
| |
| <orderedlist> |
| <listitem> |
| <para>element: age</para> |
| </listitem> |
| |
| <listitem> |
| <para>element: age</para> |
| </listitem> |
| </orderedlist> |
| |
| <para>The rest of the axes act in the same manner.</para> |
| </section> |
| |
| <section id="Set_difference.2C_intersection_and_Union"> |
| <title>Set difference, intersection and Union</title> |
| |
| <para>The expression E1 except E2 selects all nodes that are in E1 |
| unless they are also in E2. Both expressions must return sequences of |
| nodes. The results are returned in document order. For example, @* |
| except @note returns all attributes except the note attribute. The |
| expression E1 intersect E2 selects all nodes that are in both E1 and |
| E2. Both expressions must return sequences of nodes. The results are |
| returned in document order. The expression E1 union E2 selects all |
| nodes that are in either E1 or E2 or both. Both expressions must |
| return sequences of nodes. The results are returned in document order. |
| A complete example of the above expression would be as follows. |
| Consider an XML document which looks like this:</para> |
| |
| <programlisting><nodes> |
| <a> |
| <connecteda>A</connecteda> |
| <connecteda>B</connecteda> |
| <connecteda>C</connecteda> |
| </a> |
| <b> |
| <connectedb>B</connectedb> |
| <connectedb>C</connectedb> |
| <connectedb>D</connectedb> |
| </b> |
| </nodes> |
| </programlisting> |
| |
| <para>Then an example of each of the expressions would be:</para> |
| |
| <para><programlisting>data(/a/*) union data(/b/*)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:string: A</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:string: B</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:string: C</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:string: D</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>data(/a/*) intersect data(/b/*)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:string: B</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:string: C</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>data(/a/*) except data(/b/*)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:string: D</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| |
| <section id="Arithmetic_Expressions"> |
| <title>Arithmetic Expressions</title> |
| |
| <section id="Unary"> |
| <title>Unary</title> |
| |
| <para>minus and plus: The unary minus operator changes the sign of a |
| number. For example -1 is minus one, and -1e0 is the double value |
| negative -1.</para> |
| </section> |
| |
| <section id="Multiplication_and_Division:"> |
| <title>Multiplication and Division:</title> |
| |
| <para>The operator * multiplies two numbers. If the operands are of |
| different types, XPath 2.0 specifications say that one of them is |
| promoted to the type of the other. The result is the same type as |
| the operands after promotion.</para> |
| |
| <para>The operator div divides two numbers. Dividing two integers |
| produces a double; in other cases the result is the same type as the |
| operands.</para> |
| |
| <para>The operator idiv performs integer division. For example, the |
| result of 10 idiv 3 is 3.</para> |
| |
| <para>The mod operator returns the modulus (or remainder) after |
| division.</para> |
| |
| <para>The operators * and div may also be used to multiply or divide |
| a range by a number.</para> |
| |
| <para>For example, <emphasis role="italic">(1 idiv 1 to |
| 3)</emphasis> returns the result: <emphasis |
| role="italic">xs:integer: 1, xs:integer: 2, xs:integer: |
| 3</emphasis></para> |
| </section> |
| |
| <section id="Addition_and_Subtraction:"> |
| <title>Addition and Subtraction:</title> |
| |
| <para>The operators <emphasis role="bold">+</emphasis> and <emphasis |
| role="italic">'-'</emphasis> perform addition and subtraction of |
| numbers, in the usual way. Once again, if the operands are of |
| different types, XPath 2.0 specifications say one of them is |
| promoted but numeric type promotion is currently unsupported by |
| PsychoPath. The result is of the same type as the operands.</para> |
| |
| <para>Examples of above would be:</para> |
| |
| <para><programlisting> -(5 + 7)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:integer: -12</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>-xs:float(’1.23’)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:float: -1.23</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>-xs:double(’1.23’)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:double: -1.23</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>(+5 - +7)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:integer: -2</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>(1 to 5 div 0 )</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <itemizedlist> |
| <listitem> |
| <para>FAIL (division by zero!)</para> |
| </listitem> |
| </itemizedlist> |
| |
| <para><programlisting>5*6*10*5*96 div 20 div 3 div 1</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:decimal: 2400.0</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>31 mod 15</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:integer: 1</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| </section> |
| |
| <section id="Range_expressions"> |
| <title>Range expressions</title> |
| |
| <para>The expression E1 to E2 returns a sequence of integers. For |
| example, 1 to 5 returns the sequence 1, 2, 3, 4, 5. This is useful in |
| for expressions, for example the first five nodes of a node sequence |
| can be processed by writing for $i in 1 to 5 return (//x) <ulink |
| url="$i">$i</ulink>. Another example:</para> |
| |
| <para><programlisting>(1+1 to 10)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:integer: 2</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 3</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 4</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 5</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 6</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 7</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 8</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 9</para> |
| </listitem> |
| |
| <listitem> |
| <para>xs:integer: 10</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| |
| <section id="Comparisons"> |
| <title>Comparisons</title> |
| |
| <para>The simplest comparison operators are <emphasis |
| role="bold">eq</emphasis>, <emphasis role="bold">ne</emphasis>, |
| <emphasis role="bold">lt</emphasis>, <emphasis |
| role="bold">le</emphasis>, <emphasis role="bold">gt</emphasis>, |
| <emphasis role="bold">ge</emphasis>. These compare two atomic values |
| of the same type, for example two integers, two dates, or two strings. |
| (Collation hasn’t been implemented in current version of PsychoPath). |
| If the operands are not atomic values, an error is raised.</para> |
| |
| <para>The operators <emphasis role="bold">=''', </emphasis>!=' |
| <emphasis role="italic">, '</emphasis><=' <emphasis role="italic">, |
| '</emphasis>> <emphasis role="bold">, '''<</emphasis>, and |
| <emphasis role="bold">>=</emphasis> can compare arbitrary |
| sequences. The result is true if any pair of items from the two |
| sequences has the specified relationship, for example <emphasis |
| role="italic">$A = $B</emphasis> is true if there is an item in |
| <emphasis role="italic">$A</emphasis> that is equal to some item in |
| <emphasis role="italic">$B</emphasis>.</para> |
| |
| <para>The operators <emphasis role="bold">is</emphasis> and <emphasis |
| role="bold">isnot</emphasis> test whether the operands represent the |
| same (identical) node. For example, <emphasis role="italic">title |
| <ulink url="1">1</ulink> is * <ulink url="@note">@note</ulink> <ulink |
| url="1">1</ulink> </emphasis> is true if the first title child is the |
| first child element that has a <emphasis |
| role="italic">@note</emphasis> attribute. If either operand is an |
| empty sequence the result is an empty sequence (which will usually be |
| treated as false).</para> |
| |
| <para>The operators <emphasis role="bold"><<</emphasis> and |
| <emphasis role="bold">>></emphasis> test whether one node |
| precedes or follows another in document order. Consider this XML |
| document:</para> |
| |
| <programlisting><book> |
| <title>Being a Dog Is a Full-Time Job</title> |
| <author>Charles M. Schulz</author> |
| <character> |
| <name>Snoopy</name> |
| <friend-of>Peppermint Patty</friend-of> |
| <since>1950-10-04</since> |
| <age>2</age> |
| <qualification>extroverted beagle</qualification> |
| </character> |
| <character> |
| <name>Peppermint Patty</name> |
| <since>1966-08-22>/since> |
| <age>4</age> |
| <qualification>bold, brash and tomboyish</qualification> |
| </character> |
| </book> |
| </programlisting> |
| |
| <para>Example:</para> |
| |
| <para><programlisting>book/character name="Snoopy" << book/character Patty" </programlisting></para> |
| |
| <para><emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:boolean: true</para> |
| </listitem> |
| </orderedlist> |
| |
| <para>book/character <ulink url="name="Peppermint">Patty"</ulink> |
| << book/character <ulink |
| url="name="Snoopy"">name="Snoopy"</ulink> <emphasis |
| role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:boolean: false</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| |
| <section id="Conditional_Expressions"> |
| <title>Conditional Expressions</title> |
| |
| <para>XPath 2.0 allows a conditional expression of the form <emphasis |
| role="italic">if ( E1 ) then E2 else E3</emphasis>. For example, |
| <emphasis role="italic">if (@discount) then @discount else |
| 0</emphasis> returns the value of the discount attribute if it is |
| present, or zero otherwise.</para> |
| </section> |
| |
| <section id="Quantified_Expressions"> |
| <title>Quantified Expressions</title> |
| |
| <para>The expression <emphasis role="italic">some $x in E1 satisfies |
| E2</emphasis> returns true if there is an item in the sequence E1 for |
| which the effective boolean value of E2 is true. Note that E2 must use |
| the range variable <emphasis role="italic">$x</emphasis> to refer to |
| the item being tested; it does not become the context item. For |
| example, <emphasis role="italic">some $x in @* satisfies $x eq |
| ""</emphasis> is true if the context item is an element that has at |
| least one zero-length attribute value.</para> |
| |
| <para>Similarly, the expression <emphasis role="italic">every $x in E1 |
| satisfies E2</emphasis> returns true if every item in the sequence |
| given by E1 satisfies the condition.</para> |
| </section> |
| |
| <section id="And.2C_Or_Expressions"> |
| <title>And, Or Expressions</title> |
| |
| <para>The expression <emphasis role="italic">E1 and E2</emphasis> |
| returns true if the effective boolean values of E1 and E2 are both |
| true. The expression <emphasis role="italic">E1 or E2</emphasis> |
| returns true if the effective boolean values of either or both of E1 |
| and E2 are true.</para> |
| |
| <para><programlisting> (for a truth table) 1 and 1</programlisting></para> |
| |
| <para><emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:boolean: true</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>1 and 0</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:boolean: false</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>1 or 0</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:boolean: true</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>0 or 1</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:boolean: true</para> |
| </listitem> |
| </orderedlist> |
| |
| <para></para> |
| </section> |
| |
| <section id="SequenceType_Matching_Expressions"> |
| <title>SequenceType Matching Expressions</title> |
| |
| <para>The rules for SequenceType matching compare the actual type of a |
| value with an expected type. These rules are a subset of the formal |
| rules that match a value with an expected type defined in XQuery 1.0 |
| and XPath 2.0 Formal Semantics <ulink |
| url="http://www.w3.org/TR/xpath20/#XQueryFormalSemantics">http://www.w3.org/TR/xpath20/#XQueryFormalSemantics</ulink>, |
| because the Formal Semantics must be able to match a value with any |
| XML Schema type, whereas the rules below only match values against |
| those types expressible by the SequenceType syntax.</para> |
| |
| <para>Some of the rules for SequenceType matching require determining |
| whether a given type name is the same as or derived from an expected |
| type name. The given type name may be "known" (defined in the in-scope |
| schema definitions), or "unknown" (not defined in the in-scope schema |
| definitions). An unknown type name might be encountered, for example, |
| if a source document has been validated using a schema that was not |
| imported into the static context. In this case, an implementation is |
| allowed (but is not required) to provide an implementation-dependent |
| mechanism for determining whether the unknown type name is derived |
| from the expected type name. For example, an implementation might |
| maintain a data dictionary containing information about type |
| hierarchies. consider the following XML document:</para> |
| |
| <programlisting><sorbo> |
| <is>elite</is> |
| <!-- life sux --> |
| </sorbo> |
| </programlisting> |
| |
| <para>Then, the following are some example of SequenceType |
| matchings:</para> |
| |
| <para><programlisting> element({*})</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>element: sorbo</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>element(elite)</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>Empty results</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>sorbo/comment()</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>comment: life sux</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>data(/sorbo/comment())</programlisting></para> |
| |
| <para> <emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>xs:string: life sux</para> |
| </listitem> |
| </orderedlist> |
| |
| <para><programlisting>sorbo/node()</programlisting></para> |
| |
| <para><emphasis role="bold">result:</emphasis></para> |
| |
| <orderedlist> |
| <listitem> |
| <para>text:</para> |
| </listitem> |
| |
| <listitem> |
| <para>element: is</para> |
| </listitem> |
| |
| <listitem> |
| <para>comment: life sux</para> |
| </listitem> |
| |
| <listitem> |
| <para>text:</para> |
| </listitem> |
| </orderedlist> |
| |
| <para></para> |
| </section> |
| </section> |
| </chapter> |
| |
| <chapter id="How_to_use_XPath_2.0_functions_with_PsychoPath"> |
| <title>How to use XPath 2.0 functions with PsychoPath</title> |
| |
| <para>The aim of this section is to give the user an overview of the |
| available XPath 2.0 functions that are implemented in PsychoPath. For the |
| formal specifications, see the W3C web-site for XPath 2.0 functions and |
| operators <ulink |
| url="http://www.w3.org/TR/xpath-functions/">http://www.w3.org/TR/xpath-functions/</ulink>.</para> |
| |
| <section id="Accessors"> |
| <title>Accessors</title> |
| |
| <para>In order for PsychoPath to operate on instances of the XPath 2.0 |
| data model, the model must expose the properties of the items it |
| contains. It does this by defining a family of accessor functions. These |
| functions are not available to users or applications to call directly. |
| Instead, they are descriptions of the information that an implementation |
| of the model must expose to applications.</para> |
| |
| <para>data(‘string’)</para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XSString)rs.first()).stringvalue(); |
| println(n);</programlisting></para> |
| |
| <para>In order to get the result of ‘string’</para> |
| </section> |
| |
| <section id="Constructor_Functions"> |
| <title>Constructor Functions</title> |
| |
| <para><programlisting>xs:dateTime("2002-02-01T10:00:00+06:00")</programlisting></para> |
| |
| <para>From within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XSDateTime)rs.first()).stringvalue(); println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘2002-02-01T04:00:00Z’</para> |
| </section> |
| |
| <section id="Functions_on_Numeric_Values"> |
| <title>Functions on Numeric Values</title> |
| |
| <para><programlisting>ceiling(xs:float(‘10.4’))</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>float n = ((XSFloat)rs.first()).floatvalue(); |
| println(n);</programlisting></para> |
| |
| <para>In order to get the result of ‘11.0’</para> |
| </section> |
| |
| <section id="Functions_to_Assemble_and_Disassemble_Strings"> |
| <title>Functions to Assemble and Disassemble Strings</title> |
| |
| <para><programlisting>codepoints-to-string(0111)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XSString)rs.first()).stringvalue(); |
| println(n);</source></programlisting></para> |
| |
| <para>In order to get the result of ‘o’</para> |
| </section> |
| |
| <section id="Compare_and_Other_Functions_on_String_Values"> |
| <title>Compare and Other Functions on String Values</title> |
| |
| <para><programlisting>concat(‘un’, ‘grateful’)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XSString)rs.first()).stringvalue(); |
| println(n);</programlisting></para> |
| |
| <para>In order to get the result of ‘ungrateful’</para> |
| </section> |
| |
| <section id="Functions_Based_on_Substring_Matching"> |
| <title>Functions Based on Substring Matching</title> |
| |
| <para><programlisting>contains("abc", "edf")</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>boolean n = ((XSBoolean)rs.first()).value(); |
| println(n);</programlisting></para> |
| |
| <para>In order to get the result of ‘false’</para> |
| </section> |
| |
| <section id="String_Functions_that_Use_Pattern_Matching"> |
| <title>String Functions that Use Pattern Matching</title> |
| |
| <para><programlisting>matches(‘abcd’, ‘abcd’)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>boolean n = ((XSBoolean)rs.first()).value(); |
| println(n);</programlisting></para> |
| |
| <para>In order to get the result of ‘true’</para> |
| </section> |
| |
| <section id="Functions_on_Boolean_Values"> |
| <title>Functions on Boolean Values</title> |
| |
| <para><programlisting>not(true())</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>boolean n = ((XSBoolean)rs.first()).value(); |
| println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘false’</para> |
| </section> |
| |
| <section id="Component_Extraction_Functions_on_Durations.2C_Dates_and_Times"> |
| <title>Component Extraction Functions on Durations, Dates and |
| Times</title> |
| |
| <para><programlisting>timezone-from-time(xs:time("13:20:00+05:00"))</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XDTDayTimeDuration)rs.first()).stringvalue(); |
| println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘PT5H’</para> |
| </section> |
| |
| <section id="Functions_Related_to_QNames"> |
| <title>Functions Related to QNames</title> |
| |
| <para><programlisting>local-name-from-QName(QName(‘ <ulink |
| url="http://www.example.com/example">http://www.example.com/example</ulink>’, ‘person’))</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XSNCName)rs.first()).stringvalue(); |
| println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘person’</para> |
| </section> |
| |
| <section id="Functions_on_Nodes"> |
| <title>Functions on Nodes</title> |
| |
| <para></para> |
| |
| <section id="General_Functions_on_Sequences"> |
| <title>General Functions on Sequences</title> |
| |
| <para><programlisting>remove((‘s’,‘o’,‘m’,‘e’,‘t’,‘h’,‘i’,‘n’,‘g’), 6)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <programlisting>for (Iterator iter = rs.iterator(); iter.hasNext();) { |
| Object item = iter.next(); |
| String n = ((XSString)item).stringvalue(); |
| print(n + " "); |
| } println(""); |
| </programlisting> |
| |
| <para>in order to get the result of ‘s o m e t i n g’</para> |
| </section> |
| |
| <section id="Functions_That_Test_the_Cardinality_of_Sequences"> |
| <title>Functions That Test the Cardinality of Sequences</title> |
| |
| <para><programlisting>one-or-more((1,2,3,4,5))</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <programlisting>for (Iterator iter = rs.iterator(); iter.hasNext();) { |
| Object item = iter.next(); |
| int n = ((XSInteger)item).intvalue(); |
| print(n + " "); |
| } println(""); |
| </programlisting> |
| |
| <para>in order to get the result of ‘1 2 3 4 5’</para> |
| </section> |
| |
| <section id="Deep-Equal.2C_Aggregate_Functions.2C_and_Functions_that_Generate_Sequences"> |
| <title>Deep-Equal, Aggregate Functions, and Functions that Generate |
| Sequences</title> |
| |
| <para><programlisting>avg((3,4,5))</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>double avg = ((XSDouble)rs.first()).doublevalue(); |
| println(avg);</programlisting></para> |
| |
| <para>in order to get the result of ‘4.0’</para> |
| </section> |
| |
| <section id="Context_Functions"> |
| <title>Context Functions</title> |
| |
| <para><programlisting>(10 to 20) = 2</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>int pos = ((XSInteger)rs.first()).intvalue(); println(pos);</programlisting></para> |
| |
| <para>in order to get the result of ‘11’</para> |
| </section> |
| </section> |
| </chapter> |
| |
| <chapter id="How_to_use_XPath_2.0_operators_with_PsychoPath"> |
| <title>How to use XPath 2.0 operators with PsychoPath</title> |
| |
| <para>The aim of this section is to give the user an overview of the |
| available XPath 2.0 operators that are implemented in PsychoPath. For the |
| formal specifications, see the W3C web-site for XPath 2.0 functions and |
| operators <ulink |
| url="http://www.w3.org/TR/xpath-functions/">http://www.w3.org/TR/xpath-functions/</ulink>.</para> |
| |
| <para></para> |
| |
| <section id="Operators_on_Numeric_Values"> |
| <title>Operators on Numeric Values</title> |
| |
| <para><programlisting>xs:integer(4) + xs:integer(3)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>Integer n = ((XSInteger)rs.first()).integervalue(); |
| println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘7’</para> |
| </section> |
| |
| <section id="Comparison_of_Numeric_Values"> |
| <title>Comparison of Numeric Values</title> |
| |
| <para><programlisting>xs:decimal(3.3) = xs:decimal(6.6)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>boolean n = ((XSBoolean)rs.first()).value(); println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘false’</para> |
| </section> |
| |
| <section id="Operators_on_Boolean_Values"> |
| <title>Operators on Boolean Values</title> |
| |
| <para><programlisting>xs:boolean(’true’) gt xs:boolean(’false’)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>boolean n = ((XSBoolean)rs.first()).value(); println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘true’</para> |
| </section> |
| |
| <section id="Comparisons_of_Duration.2C_Date_and_Time_Values"> |
| <title>Comparisons of Duration, Date and Time Values</title> |
| |
| <para><programlisting>xs:time("23:00:00+06:00") lt xs:time("12:00:00-06:00")</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>boolean n = ((XSBoolean)rs.first()).value(); |
| println(n);</programlisting></para> |
| |
| <para>in order to get the result of ‘true’</para> |
| </section> |
| |
| <section id="Arithmetic_Functions_on_Durations"> |
| <title>Arithmetic Functions on Durations</title> |
| |
| <para><programlisting>multiply-dayTimeDuration(xs:dayTimeDuration("PT2H10M"), 2.1)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XDTDayTimeDuration)rs.first()).stringvalue(); |
| println(n);</programlisting></para> |
| |
| <para>which returns a xdt:dayTimeDuration value corresponding to 4 hours |
| and 33 minutes ‘PT4H33M’</para> |
| </section> |
| |
| <section id="Arithmetic_Functions_Dates_and_Times"> |
| <title>Arithmetic Functions Dates and Times</title> |
| |
| <para><programlisting>add-yearMonthDuration-to-dateTime( xs:dateTime("2000-10-30T11:12:00"), xdt:yearMonthDuration("P1Y2M"))</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>String n = ((XSDateTime)rs.first()).stringvalue(); |
| println(n);</programlisting></para> |
| |
| <para>which returns an xs:dateTime value corresponding to the lexical |
| representation ‘2001-12-30T11:12:00’</para> |
| </section> |
| |
| <section id="Operators_Related_to_QNames_And_Nodes"> |
| <title>Operators Related to QNames And Nodes</title> |
| |
| <para><programlisting>xs:QName(’ao’) eq xs:QName(’ao’)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>boolean n = ((XSBoolean)rs.first()).value(); |
| println(n);</programlisting></para> |
| |
| <para>which returns the result of ‘true’</para> |
| </section> |
| |
| <section id="Union.2C_Intersection_and_Except"> |
| <title>Union, Intersection and Except</title> |
| |
| <para><programlisting>union($seq2, $seq3)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <programlisting>for (Iterator iter = rs.iterator(); iter.hasNext();) { |
| Object item = iter.next(); |
| String n = ((XSString)item).stringvalue(); |
| print(n + ", "); |
| } |
| println(""); |
| </programlisting> |
| |
| <para> </para> |
| |
| <para>which returns the sequence consisting of $item1, $item2, |
| $item3.</para> |
| |
| <para></para> |
| </section> |
| |
| <section id="Operators_that_Generate_Sequences"> |
| <title>Operators that Generate Sequences</title> |
| |
| <para><programlisting>(1 to 3)</programlisting></para> |
| |
| <para>from within a Java application, in order to extract the result |
| from the result sequence, one would have to use this code:</para> |
| |
| <para><programlisting>int n = (XSInteger)rs.first()).stringvalue(); |
| println(n);</programlisting></para> |
| |
| <para>which returns the sequence consisting of 1, 2, 3.</para> |
| </section> |
| </chapter> |
| </book> |
