ali@0: <?xml version="1.0"?>
ali@0: <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
ali@0:                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
ali@0: [
ali@0: ]>
ali@0: <chapter id="implementation-defined-behaviour">
ali@0:   <title>Implementation Defined Behaviour</title>
ali@0: 
ali@0:   <para>
ali@0:     The specification of the XEXPR language is laid out in a W3C note of
ali@0:     <ulink url="http://www.w3.org/TR/2000/NOTE-xexpr-20001121">21 November
ali@0:     2000</ulink>. However, the specification leaves quite a bit of
ali@0:     information to be deduced from the examples and leaves other parts of
ali@0:     the language loosly specified. This chapter documents the way that
ali@0:     libxexpr implements the language and gives the rationale for each
ali@0:     decision taken.
ali@0:   </para>
ali@0: 
ali@0:   <sect1 id="idb-numbers">
ali@0:     <title>Numbers</title>
ali@0: 
ali@0:     <para>
ali@0:       Numbers are defined in pseudo-BNF as:
ali@0:       <programlisting>
ali@0: number         : whitespace sign simple-number whitespace
ali@0: 	       ;
ali@0: 
ali@0: whitespace     : [ \t\n]*
ali@0: 	       ;
ali@0: 
ali@0: sign           : [+-]?
ali@0: 	       ;
ali@0: 
ali@0: simple-number  : 0x[0-9A-Fa-f]+
ali@0: 	       | [0-9]+
ali@0: 	       | [0-9]+\.[0-9]+
ali@0: 	       | [0-9]+\.[0-9]+[eE][+-][0-9]+
ali@0: 	       ;<!--
ali@0:    --></programlisting>
ali@0:       that is: they have an optional leading sign and may be surrounded with
ali@0:       whitespace.
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-numbers-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0:         While negative numbers can be created using &lt;subtract&gt; without
ali@0: 	the need for any signs, this seems overly cumbersome.
ali@0:       </para>
ali@0: 
ali@0:       <para>
ali@0: 	The examples in the specification make it clear that where two numbers
ali@0: 	are seperated by a space, this should be parsed as just two numbers
ali@0: 	and not two numbers plus an interveening string which a strict reading
ali@0: 	of the specification would imply.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-bindings">
ali@0:     <title>Bindings</title>
ali@0: 
ali@0:     <para>
ali@0:       Bindings are parsed as integers, floats or strings in that order (ie.,
ali@0:       the first type that matches will be used). Thus the following pairs
ali@0:       of expressions are equivalent:
ali@0:       <programlisting>
ali@0: &lt;func x="+01 "/&gt;
ali@0: 
ali@0: &lt;func&gt;
ali@0:   &lt;define name="x"&gt;&lt;integer&gt;1&lt;/integer&gt;&lt;/define&gt;
ali@0: &lt;/func&gt;
ali@0: 
ali@0: &lt;func x=" 14.0e-1"/&gt;
ali@0: 
ali@0: &lt;func&gt;
ali@0:   &lt;define name="x"&gt;&lt;float&gt;1.4&lt;/float&gt;&lt;/define&gt;
ali@0: &lt;/func&gt;
ali@0: 
ali@0: &lt;func x="Hello "/&gt;
ali@0: 
ali@0: &lt;func&gt;
ali@0:   &lt;define name="x"&gt;&lt;string&gt;Hello &lt;/string&gt;&lt;/define&gt;
ali@0: &lt;/func&gt;<!--
ali@0:    --></programlisting>
ali@0:     </para>
ali@0:     <simplesect id="idb-bindings-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	This seems to satisfy the doctrine of least-surpise.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-pcdata">
ali@0:     <title>Parsing of PCDATA</title>
ali@0: 
ali@0:     <para>
ali@0:       When numbers and strings are mixed in PCDATA, any whitespace surrounding
ali@0:       the numbers is taken to be part of the numbers rather than the strings.
ali@0:       Thus the following two expressions are equivalent:
ali@0:       <programlisting>
ali@0: &lt;foo&gt;This is the 0xdeadbeef constant.&lt;/foo&gt;
ali@0: 
ali@0: &lt;foo&gt;
ali@0:   &lt;string&gt;This is the&lt;/string&gt;
ali@0:   &lt;integer&gt;0xdeadbeef&lt;/integer&gt;
ali@0:   &lt;string&gt;constant.&lt;/string&gt;
ali@0: &lt;/foo&gt;<!--
ali@0:    --></programlisting>
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-pcdata-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	This seems more consistent with spaces between numbers not being
ali@0: 	parsed as strings than the alternative.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-define">
ali@0:     <title>The &lt;define&gt; Function</title>
ali@0: 
ali@0:     <para>
ali@0:       The &lt;define&gt; function creates a new function in the environment in
ali@0:       which it is invoked. This is different than the &lt;set&gt; function
ali@0:       which will modify the definition of an existing function if such exists.
ali@0:       Only if no such function is defined in any of the active environments will
ali@0:       &lt;set&gt; create a new function (and then in the outermost, or global,
ali@0:       environment).
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-define-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	We know from the examples in the specification (eg., in
ali@0: 	<ulink url="http://www.w3.org/TR/xexpr/#id-0045">section 45</ulink>)
ali@0: 	that &lt;subtract&gt; changes the definition of its first argument
ali@0: 	in at least the grandfather environment. It makes sense that &lt;set&gt;
ali@0: 	should do the same. When we come to &lt;define&gt;, however, we
ali@0: 	know from <ulink url="http://www.w3.org/TR/xexpr/#id-0003">section
ali@0: 	3</ulink> that it is equivalent to an attribute on the parent element
ali@0: 	and so it makes sense that it should create a variable in the parent
ali@0: 	environment.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-get">
ali@0:     <title>The &lt;get&gt; Function</title>
ali@0: 
ali@0:     <para>
ali@0:       The following two expressions are equivalent:
ali@0:       <programlisting>
ali@0: &lt;get name="x"/&gt;
ali@0: &lt;get&gt;x&lt;/get&gt;<!--
ali@0:    --></programlisting>
ali@0:       The expression &lt;x/&gt; has the same effect except in the case of
ali@0:       &lt;add&gt; and &lt;subtract&gt; where these two expressions are
ali@0:       different:
ali@0:       <programlisting>
ali@0: &lt;add&gt;&lt;x/&gt;1&lt;/add&gt;
ali@0: &lt;add&gt;&lt;get&gt;x&lt;/get&gt;1&lt;/add&gt;<!--
ali@0:    --></programlisting>
ali@0:       The first changes the definition of &lt;x&gt;, the second does not.
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       Note that IDs are allowed to start with the dot (.) and hyphen (-)
ali@0:       characters which are not valid as the first character in XML tags.
ali@0:       Thus get must be used in the following:
ali@0:       <programlisting>
ali@0: &lt;expr&gt;
ali@0:   &lt;define name=".net"&gt;4.5.50709&lt;/define&gt;
ali@0:   &lt;print&gt;&lt;get&gt;.net&lt;/get&gt;&lt;/print&gt;
ali@0: &lt;/expr&gt;<!--
ali@0:    --></programlisting>
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       Since &lt;get&gt; returns a function definition (just like
ali@0:       &lt;define&gt;), it is possible to define functions of this type that
ali@0:       take arguments and even invoke them in a somewhat circuitous manner:
ali@0:       <programlisting>
ali@0: &lt;expr&gt;
ali@0:   &lt;define name=".product" args="a b c d"&gt;
ali@0:     &lt;add&gt;
ali@0:       &lt;multiply&gt;
ali@0:         &lt;a/&gt;
ali@0:         &lt;b/&gt;
ali@0:       &lt;/multiply&gt;
ali@0:       &lt;multiply&gt;
ali@0:         &lt;c/&gt;
ali@0:         &lt;d/&gt;
ali@0:       &lt;/multiply&gt;
ali@0:     &lt;/add&gt;
ali@0:   &lt;/define&gt;
ali@0: 
ali@0:   &lt;expr&gt;
ali@0:     &lt;define name="closure"/&gt;
ali@0:     &lt;set name="closure"&gt;
ali@0:       &lt;get&gt;.product&lt;/get&gt;
ali@0:     &lt;/set&gt;
ali@0:     &lt;closure&gt;1 2 3 4&lt;/closure&gt;
ali@0:   &lt;/expr&gt;
ali@0: &lt;/expr&gt;<!--
ali@0:    --></programlisting>
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-get-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	<ulink url="http://www.w3.org/TR/xexpr/#id-0014">Section 14</ulink>
ali@0: 	tells us that &lt;get&gt;x&lt;/get&gt; and &lt;x/&gt; have the same
ali@0: 	effect in most cases (and thus presumably not all cases) and it
ali@0: 	would seem surprising if &lt;get&gt; were not to insulate a
ali@0: 	function in this manner.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-arithmetic">
ali@0:     <title>Arithmetic Operators</title>
ali@0: 
ali@0:     <para>
ali@0:       The empty arithmetic operators (&lt;add/&gt;, &lt;subtract/&gt;,
ali@0:       &lt;multiply/&gt; and &lt;divide/&gt;) all evaluate to &lt;nil/&gt;.
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       The &lt;add&gt; and &lt;subtract&gt; operators change their first
ali@0:       argument in some circumstances as in this example from the specification:
ali@0:       <programlisting>
ali@0: &lt;while&gt;
ali@0:   &lt;gt&gt;&lt;x/&gt; 0&lt;/gt&gt;
ali@0:   &lt;expr&gt;
ali@0:     &lt;print newline="true">&lt;x/&gt;&lt;print&gt;
ali@0:     &lt;subtract&gt;&lt;x/&gt; 1&lt;/subtract&gt;
ali@0:   &lt;/expr&gt;
ali@0: &lt;/while&gt;<!--
ali@0:    --></programlisting>
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       In general, the first agument will be modified if it is a function
ali@0:       invocation that has no bindings and no arguments. Thus the following
ali@0:       will print 9:
ali@0:       <programlisting>
ali@0: &lt;define name="x"&gt;&lt;multiply&gt;2 3&lt;/multiply&gt;&lt;/define&gt;
ali@0: &lt;add&gt;&lt;x/&gt;3&lt;/add&gt;
ali@0: &lt;print&gt;&lt;x/&gt;&lt;/print&gt;<!--
ali@0:    --></programlisting>
ali@0:       whereas this will print 6:
ali@0:       <programlisting>
ali@0: &lt;define name="x"&gt;&lt;multiply&gt;2 3&lt;/multiply&gt;&lt;/define&gt;
ali@0: &lt;add&gt;&lt;x unused=""/&gt;3&lt;/add&gt;
ali@0: &lt;print&gt;&lt;x/&gt;&lt;/print&gt;<!--
ali@0:    --></programlisting>
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       Where arguments are modified, this occurs as the arguments are being
ali@0:       evaluated. Thus this expression:
ali@0:       <programlisting>
ali@0: &lt;add&gt;&lt;x/&gt;&lt;x/&gt;&lt;x/&gt;&lt;/add&gt;<!--
ali@0:    --></programlisting>
ali@0:       will multiply &lt;x&gt; by 4 rather than by 3.
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-arithmetic-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	The examples in the specification imply that &lt;add&gt; and
ali@0: 	&lt;subtract&gt; modify their first argument when it is a
ali@0: 	variable. The iterative example in
ali@0: 	<ulink url="http://www.w3.org/TR/xexpr/#id-0008">section 8</ulink>
ali@0: 	wouldn't work if &lt;multiply&gt; worked the same way (and the
ali@0: 	definition of &lt;2pi&gt; in <ulink
ali@0: 	url="http://www.w3.org/TR/xexpr/#id-0007">section 7</ulink> would
ali@0: 	not be expected to modify the definition of &lt;pi&gt; each time
ali@0: 	it is called). Note that this example is erroneous: IDs can't contain
ali@0: 	numbers.
ali@0:       </para>
ali@0: 
ali@0:       <para>
ali@0: 	It seems undesirable to modify functions that take arguments.
ali@0: 	Making the decision based on the invocation rather than the
ali@0: 	function definition makes expressions much easier to read.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-comparison">
ali@0:     <title>Comparison Functions</title>
ali@0: 
ali@0:     <para>
ali@0:       The empty comparison functions (&lt;eq/&gt;, &lt;neq/&gt;, &lt;leq/&gt;,
ali@0:       &lt;geq/&gt;, &lt;lt/&gt; and &lt;gt/&gt;) and comparison functions with
ali@0:       exactly one argument all evaluate to &lt;true/&gt;.
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       The ordered comparison functions (&lt;leq&gt;, &lt;geq&gt;, &lt;lt&gt;
ali@0:       and &lt;gt&gt;) act as if the equivalent mathematical operator was
ali@0:       inserted between their arguments. Thus:
ali@0:       <programlisting>
ali@0: &lt;lt&gt;
ali@0:   1 2 3
ali@0: &lt;/lt&gt;<!--
ali@0:    --></programlisting>
ali@0:       is equivalent to the mathematical expression:
ali@0:       <screen>1 &lt; 2 &lt; 3</screen>
ali@0:       and:
ali@0:       <programlisting>
ali@0: &lt;leq&gt;
ali@0:   1 2 3
ali@0: &lt;/leq&gt;<!--
ali@0:    --></programlisting>
ali@0:       is equivalent to the mathematical expression:
ali@0:       <screen>1 ≤ 2 ≤ 3</screen>
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       When comparing objects of different types:
ali@0:       <itemizedlist>
ali@0: 	<listitem>
ali@0: 	  Numbers will be implicitly cast between &lt;float&gt; and
ali@0: 	  &lt;integer&gt; where that involves no loss of precision
ali@0: 	</listitem>
ali@0: 	<listitem>
ali@0: 	  Strings will be compared byte-by-byte as UTF8 encoded strings
ali@0: 	</listitem>
ali@0: 	<listitem>
ali@0: 	  Functions will always be completely evaluated
ali@0: 	</listitem>
ali@0: 	<listitem>
ali@0: 	  Invocations of the constant functions are ordered as &lt;false/&gt;
ali@0: 	  &lt; &lt;nil/&gt; &lt; &lt;true/&gt;
ali@0: 	</listitem>
ali@0:       </itemizedlist>
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-comparison-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	The empty comparison functions equaluate to &lt;true&gt; by analogy
ali@0: 	with the comparison functions.
ali@0:       </para>
ali@0: 
ali@0:       <para>
ali@0: 	The ordering of the comparison functions is confused in the
ali@0: 	specification with the examples for &lt;lt&gt; and &lt;gt&gt; agreeing
ali@0: 	with libxexpr's behaviour and the examples for &lt;leq&gt; and
ali@0: 	&lt;geq&gt; doing the opposite. The choice was arbitary.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-redefining-builtins">
ali@0:     <title>Redefining Builtin Functions</title>
ali@0: 
ali@0:     <para>
ali@0:       Attempting to redefine a builtin function results in an error.
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-redefining-builtins-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	While this could be implemented, there is no mention of it in the
ali@0: 	specification and it would complicate the implementation with no
ali@0: 	obvious benefit.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: 
ali@0:   <sect1 id="idb-namespaces">
ali@0:     <title>Namespaces</title>
ali@0: 
ali@0:     <para>
ali@0:       libxexpr considers an element's namespace to be part of its name
ali@0:       and thus elements in a namespace other than the XEXPR namespace as
ali@0:       are always distinct from functions defined by XEXPR. In addition,
ali@0:       functions defined using &lt;define&gt; are defined in the
ali@0:       XEXPR namespace.
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       libxexpr provides hooks for extending the XEXPR language by allowing
ali@0:       handlers to be installed for other namespaces.
ali@0:     </para>
ali@0: 
ali@0:     <para>
ali@0:       Elements which are in no namespace are treated as if they were in the
ali@0:       XEXPR namespace.
ali@0:     </para>
ali@0: 
ali@0:     <simplesect id="idb-namespaces-rationale">
ali@0:       <title>Rationale</title>
ali@0: 
ali@0:       <para>
ali@0: 	Being able to extend the XEXPR language is vital for it to be useful
ali@0: 	and namespaces are the obvious way to do this.
ali@0:       </para>
ali@0:     </simplesect>
ali@0:   </sect1>
ali@0: </chapter>