<?xml version="1.0"?>

<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"

[

]>

<chapter id="implementation-defined-behaviour">

  <title>Implementation Defined Behaviour</title>

  <para>

    The specification of the XEXPR language is laid out in a W3C note of

    <ulink url="http://www.w3.org/TR/2000/NOTE-xexpr-20001121">21 November

    2000</ulink>. However, the specification leaves quite a bit of

    information to be deduced from the examples and leaves other parts of

    the language loosly specified. This chapter documents the way that

    libxexpr implements the language and gives the rationale for each

    decision taken.

  </para>

  <sect1 id="idb-numbers">

    <title>Numbers</title>

    <para>

      Numbers are defined in pseudo-BNF as:

      <programlisting>

number         : whitespace sign simple-number whitespace

	       ;

whitespace     : [ \t\n]*

	       ;

sign           : [+-]?

	       ;

simple-number  : 0x[0-9A-Fa-f]+

	       | [0-9]+

	       | [0-9]+\.[0-9]+

	       | [0-9]+\.[0-9]+[eE][+-][0-9]+

	       ;<!--

   --></programlisting>

      that is: they have an optional leading sign and may be surrounded with

      whitespace.

    </para>

    <simplesect id="idb-numbers-rationale">

      <title>Rationale</title>

      <para>

        While negative numbers can be created using <subtract> without

	the need for any signs, this seems overly cumbersome.

      </para>

      <para>

	The examples in the specification make it clear that where two numbers

	are seperated by a space, this should be parsed as just two numbers

	and not two numbers plus an interveening string which a strict reading

	of the specification would imply.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-bindings">

    <title>Bindings</title>

    <para>

      Bindings are parsed as integers, floats or strings in that order (ie.,

      the first type that matches will be used). Thus the following pairs

      of expressions are equivalent:

      <programlisting>

<func x="+01 "/>

<func>

  <define name="x"><integer>1</integer></define>

</func>

<func x=" 14.0e-1"/>

<func>

  <define name="x"><float>1.4</float></define>

</func>

<func x="Hello "/>

<func>

  <define name="x"><string>Hello </string></define>

&lt;/func&gt;<!--

   --></programlisting>

    </para>

    <simplesect id="idb-bindings-rationale">

      <title>Rationale</title>

      <para>

	This seems to satisfy the doctrine of least-surpise.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-pcdata">

    <title>Parsing of PCDATA</title>

    <para>

      When numbers and strings are mixed in PCDATA, any whitespace surrounding

      the numbers is taken to be part of the numbers rather than the strings.

      Thus the following two expressions are equivalent:

      <programlisting>

<foo>This is the 0xdeadbeef constant.</foo>

<foo>

  <string>This is the</string>

  <integer>0xdeadbeef</integer>

  <string>constant.</string>

&lt;/foo&gt;<!--

   --></programlisting>

    </para>

    <simplesect id="idb-pcdata-rationale">

      <title>Rationale</title>

      <para>

	This seems more consistent with spaces between numbers not being

	parsed as strings than the alternative.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-define">

    <title>The &lt;define&gt; Function</title>

    <para>

      The <define> function creates a new function in the environment in

      which it is invoked. This is different than the <set> function

      which will modify the definition of an existing function if such exists.

      Only if no such function is defined in any of the active environments will

      <set> create a new function (and then in the outermost, or global,

      environment).

    </para>

    <simplesect id="idb-define-rationale">

      <title>Rationale</title>

      <para>

	We know from the examples in the specification (eg., in

	<ulink url="http://www.w3.org/TR/xexpr/#id-0045">section 45</ulink>)

	that <subtract> changes the definition of its first argument

	in at least the grandfather environment. It makes sense that <set>

	should do the same. When we come to <define>, however, we

	know from <ulink url="http://www.w3.org/TR/xexpr/#id-0003">section

	3</ulink> that it is equivalent to an attribute on the parent element

	and so it makes sense that it should create a variable in the parent

	environment.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-get">

    <title>The &lt;get&gt; Function</title>

    <para>

      The following two expressions are equivalent:

      <programlisting>

<get name="x"/>

&lt;get&gt;x&lt;/get&gt;<!--

   --></programlisting>

      The expression <x/> has the same effect except in the case of

      <add> and <subtract> where these two expressions are

      different:

      <programlisting>

<add><x/>1</add>

&lt;add&gt;&lt;get&gt;x&lt;/get&gt;1&lt;/add&gt;<!--

   --></programlisting>

      The first changes the definition of <x>, the second does not.

    </para>

    <para>

      Note that IDs are allowed to start with the dot (.) and hyphen (-)

      characters which are not valid as the first character in XML tags.

      Thus get must be used in the following:

      <programlisting>

<expr>

  <define name=".net">4.5.50709</define>

  <print><get>.net</get></print>

&lt;/expr&gt;<!--

   --></programlisting>

    </para>

    <para>

      Since <get> returns a function definition (just like

      <define>), it is possible to define functions of this type that

      take arguments and even invoke them in a somewhat circuitous manner:

      <programlisting>

<expr>

  <define name=".product" args="a b c d">

    <add>

      <multiply>

        <a/>

        <b/>

      </multiply>

      <multiply>

        <c/>

        <d/>

      </multiply>

    </add>

  </define>

  <expr>

    <define name="closure"/>

    <set name="closure">

      <get>.product</get>

    </set>

    <closure>1 2 3 4</closure>

  </expr>

&lt;/expr&gt;<!--

   --></programlisting>

    </para>

    <simplesect id="idb-get-rationale">

      <title>Rationale</title>

      <para>

	<ulink url="http://www.w3.org/TR/xexpr/#id-0014">Section 14</ulink>

	tells us that <get>x</get> and <x/> have the same

	effect in most cases (and thus presumably not all cases) and it

	would seem surprising if <get> were not to insulate a

	function in this manner.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-arithmetic">

    <title>Arithmetic Operators</title>

    <para>

      The empty arithmetic operators (<add/>, <subtract/>,

      <multiply/> and <divide/>) all evaluate to <nil/>.

    </para>

    <para>

      The <add> and <subtract> operators change their first

      argument in some circumstances as in this example from the specification:

      <programlisting>

<while>

  <gt><x/> 0</gt>

  <expr>

    <print newline="true"><x/><print>

    <subtract><x/> 1</subtract>

  </expr>

&lt;/while&gt;<!--

   --></programlisting>

    </para>

    <para>

      In general, the first agument will be modified if it is a function

      invocation that has no bindings and no arguments. Thus the following

      will print 9:

      <programlisting>

<define name="x"><multiply>2 3</multiply></define>

<add><x/>3</add>

&lt;print&gt;&lt;x/&gt;&lt;/print&gt;<!--

   --></programlisting>

      whereas this will print 6:

      <programlisting>

<define name="x"><multiply>2 3</multiply></define>

<add><x unused=""/>3</add>

&lt;print&gt;&lt;x/&gt;&lt;/print&gt;<!--

   --></programlisting>

    </para>

    <para>

      Where arguments are modified, this occurs as the arguments are being

      evaluated. Thus this expression:

      <programlisting>

&lt;add&gt;&lt;x/&gt;&lt;x/&gt;&lt;x/&gt;&lt;/add&gt;<!--

   --></programlisting>

      will multiply <x> by 4 rather than by 3.

    </para>

    <simplesect id="idb-arithmetic-rationale">

      <title>Rationale</title>

      <para>

	The examples in the specification imply that <add> and

	<subtract> modify their first argument when it is a

	variable. The iterative example in

	<ulink url="http://www.w3.org/TR/xexpr/#id-0008">section 8</ulink>

	wouldn't work if <multiply> worked the same way (and the

	definition of &lt;2pi&gt; in <ulink

	url="http://www.w3.org/TR/xexpr/#id-0007">section 7</ulink> would

	not be expected to modify the definition of <pi> each time

	it is called). Note that this example is erroneous: IDs can't contain

	numbers.

      </para>

      <para>

	It seems undesirable to modify functions that take arguments.

	Making the decision based on the invocation rather than the

	function definition makes expressions much easier to read.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-comparison">

    <title>Comparison Functions</title>

    <para>

      The empty comparison functions (<eq/>, <neq/>, <leq/>,

      <geq/>, <lt/> and <gt/>) and comparison functions with

      exactly one argument all evaluate to <true/>.

    </para>

    <para>

      The ordered comparison functions (<leq>, <geq>, <lt>

      and <gt>) act as if the equivalent mathematical operator was

      inserted between their arguments. Thus:

      <programlisting>

<lt>

  1 2 3

&lt;/lt&gt;<!--

   --></programlisting>

      is equivalent to the mathematical expression:

      <screen>1 &lt; 2 &lt; 3</screen>

      and:

      <programlisting>

<leq>

  1 2 3

&lt;/leq&gt;<!--

   --></programlisting>

      is equivalent to the mathematical expression:

      <screen>1 ≤ 2 ≤ 3</screen>

    </para>

    <para>

      When comparing objects of different types:

      <itemizedlist>

	<listitem>

	  Numbers will be implicitly cast between <float> and

	  <integer> where that involves no loss of precision

	</listitem>

	<listitem>

	  Strings will be compared byte-by-byte as UTF8 encoded strings

	</listitem>

	<listitem>

	  Functions will always be completely evaluated

	</listitem>

	<listitem>

	  Invocations of the constant functions are ordered as <false/>

	  < <nil/> < <true/>

	</listitem>

      </itemizedlist>

    </para>

    <simplesect id="idb-comparison-rationale">

      <title>Rationale</title>

      <para>

	The empty comparison functions equaluate to <true> by analogy

	with the comparison functions.

      </para>

      <para>

	The ordering of the comparison functions is confused in the

	specification with the examples for <lt> and <gt> agreeing

	with libxexpr's behaviour and the examples for <leq> and

	<geq> doing the opposite. The choice was arbitary.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-redefining-builtins">

    <title>Redefining Builtin Functions</title>

    <para>

      Attempting to redefine a builtin function results in an error.

    </para>

    <simplesect id="idb-redefining-builtins-rationale">

      <title>Rationale</title>

      <para>

	While this could be implemented, there is no mention of it in the

	specification and it would complicate the implementation with no

	obvious benefit.

      </para>

    </simplesect>

  </sect1>

  <sect1 id="idb-namespaces">

    <title>Namespaces</title>

    <para>

      libxexpr considers an element's namespace to be part of its name

      and thus elements in a namespace other than the XEXPR namespace as

      are always distinct from functions defined by XEXPR. In addition,

      functions defined using <define> are defined in the

      XEXPR namespace.

    </para>

    <para>

      libxexpr provides hooks for extending the XEXPR language by allowing

      handlers to be installed for other namespaces.

    </para>

    <para>

      Elements which are in no namespace are treated as if they were in the

      XEXPR namespace.

    </para>

    <simplesect id="idb-namespaces-rationale">

      <title>Rationale</title>

      <para>

	Being able to extend the XEXPR language is vital for it to be useful

	and namespaces are the obvious way to do this.

      </para>

    </simplesect>

  </sect1>

</chapter>