<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE book SYSTEM "/home/logilab/docbook/dtd/docbookx.dtd" 
    [
      <!ENTITY legalnot SYSTEM "../legal_notice.en.xml">
    ] >

<!-- ############################################################ -->
<!-- ###   Second Book : Narval Technical Manual              ### -->
<!-- ############################################################ -->



<book id="narval-tech-man.en" lang='en'>

  <bookinfo>

    <title><application>Narval</application> Technical Manual</title>

    <titleabbrev>EnNarvalTechMan</titleabbrev>

    <authorgroup>
     <author>
      <firstname>Olivier</firstname>
      <surname>Cayrol</surname>
     </author>
     <author>
      <firstname>Alexandre</firstname>
      <surname>Fayolle</surname>
     </author>
     <author>
      <firstname>Sylvain</firstname>
      <surname>Thénault</surname>
     </author>
    </authorgroup>

    <abstract>
      <para><application>Narval</application> is both a language and an
    interpreter for this language. The language is well suited for writing
    intelligent personal assistants. This document presents its internal
    architecture and its coding philosophy. Reading this document is advised to
    all people wanting to study <application>Narval</application> source code,
    or just to understand how it works.</para>
    </abstract>

    <copyright>
     <year>2000-2005</year>
     <holder>Logilab</holder>
    </copyright>
    <copyright>
      <year>2004-2005</year>
      <holder>DoCoMo Euro-Labs GmbH</holder>
    </copyright>

    &legalnot;

    <revhistory>
      <revision>
	<revnumber>$Revision: 1.4 $</revnumber>
	<date>$Date: 2001/10/16 10:18:25 $</date>
	<authorinitials>$Author: alf $</authorinitials>
      </revision>
    </revhistory>

  </bookinfo>

<!-- ********************************************************** -->

  <preface id="preface.en"><title>Warning</title>

    <para>This document presents with great details how
    <application>Narval</application> works. It is expected that the reader has
    understood the purpose of the application, and some global knowledge of the
    functionalities. It is strongly advised to read the User Manual
    first.</para>

 </preface>

<!-- ********************************************************** -->

  <chapter id="narval-operation.en"> 

    <title><application>Narval</application> Operation</title>

    <sect1 id="narval-elements.en">

      <title>Elements, interfaces and adapters</title>

      <para>Everything in narval is based on what we call <glossterm
      linkend='gloss.element'>elements</glossterm>.  Those elements
      are used to hold any information but also to describe a desired
      behaviour of the agent, using elements such as <glossterm
      linkend='gloss.action'>actions</glossterm> and <glossterm
      linkend='gloss.recipe'>recipes</glossterm>, or to control it,
      using elements such as start-plan, <glossterm
      linkend='gloss.plan'>plans</glossterm>, etc...  All of them are
      manipulated by the interpreter and contained in it's
      <glossterm>memory</glossterm>.</para>

      <para>Elements are actually python class instances, and so defined in python 
      modules and (usually automatically) registered to the interpreter. Also, for a
      greater flexibility, the concepts of <emphasis>interface</emphasis> and
      <emphasis>adapter</emphasis> are used:
        <itemizedlist>
          <listitem>an interface is an abstract definition of available
	  attributes and methods that should define an element to provide a
	  logical set of data and services</listitem>
	  <listitem>an element implements some interfaces by having the required
	  attributes and methods. The implemented interfaces are explicitly
	  listed</listitem>
	  <listitem>an adapter is glue component providing a way adapt an interface to
          another</listitem>
	</itemizedlist>

      Interfaces and adapters, as elements, are defined by classes in python
      modules and registered to the interpreter.
      </para>

    </sect1>
 
    <sect1 id="narval-memory.en">

      <title>The memory: notion of context nesting</title>

      <para><application>Narval</application> has a <glossterm
      linkend='gloss.memory'>memory</glossterm> in which it stores
      <glossterm>elements</glossterm> that it handles. In the memory,
      elements are grouped according to the
      <glossterm>plans</glossterm> that use them. It is thus possible
      to define a context for each plan (see <xref
      linkend="fig-memory"/>).</para>

      <figure id="fig-memory">
	<title><application>Narval</application>'s memory</title>
	<mediaobject>
	  <imageobject>	    
	    <imagedata align="center" fileref="images/memory.en.png"	      
	      format="gif"/>	    
	  </imageobject>	  
	  <textobject>	    
	    <phrase><application>Narval</application>'s memory holds all the
	    handled elements</phrase>	    
	  </textobject>
	</mediaobject>
      </figure>

      <para>The <glossterm>context</glossterm> of a plan is the set of
      elements handled by the plan, i.e. all the elements created or
      used by the <glossterm linkend='gloss.step'>steps</glossterm> of
      the plan or that triggered the <glossterm
      linkend='gloss.transition'>transitions </glossterm> of the
      plan. The memory holds everything handled by
      <application>Narval</application>, that is, all the contents of
      the contexts, as well as general interest elements, such as
      plans, recipes or, as shown in the example (see <xref
      linkend="fig-memory"/>), a <classname>mailbox</classname>
      element which represents the mail box used by
      <application>Narval</application>. Since it is meant to be
      shared by several plans, this element is held in the memory, and
      in no specific context. When a plan is run from within another
      plan, its context is nested within its parent's context. This is
      the case in the example shown in <xref linkend="fig-memory"/>)
      with plan <classname>Plan 1.1</classname> having a context
      nested in plan <classname>Plan 1</classname>'s.</para>

      <para>During plan execution, elements are dynamically added to the
      different contexts (see element <classname>Element 3</classname> in <xref
      linkend="fig-memory"/>). Elements in memory that have not been used after a
      given amount of time may be automatically removed so that the memory size
      will not grow too much.</para>

    </sect1>

    <sect1 id="diff-plan-recipe.en">

      <title>Difference between recipes and plans</title>

      <sect2><title>Introduction to recipes</title>

	<para>A <glossterm linkend='gloss.recipe'>recipe</glossterm>
	is a specification of a sequence of <glossterm
	>steps</glossterm> and <glossterm >transitions</glossterm>
	necessary to complete a given task. Recipes represent
	everything a <application>Narval</application> can do. A
	recipe is described with steps and transitions but cannot be
	executed. This requires the instantiation of a <glossterm linkend='gloss.plan'>plan</glossterm>.</para>

	<para><glossterm>Recipes</glossterm> are
	<glossterm>elements</glossterm> stored in
	<application>Narval</application>'s
	<glossterm>memory</glossterm>.</para>

	<para>When a plan is built from a recipe (see <xref
	linkend="fig-recipeplan"/>), <application>Narval</application> creates a
	new <classname>plan</classname> element in memory, which has all the
	data required for the execution to the steps and transitions found in
	the recipe.</para>

	<figure id="fig-recipeplan"><title>Building a plan
	from a recipe</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="images/recipeplan.en.png"
	      format="gif"/>
	    </imageobject>
	    <textobject>
	      <phrase><application>Narval</application> builds the plan it is
	      about to execute using a recipe</phrase>
	    </textobject>
	  </mediaobject>	  
	</figure>

      </sect2>

      <sect2><title>Plan execution</title>

	<para>When executing a plan, <application>Narval</application> starts
	with the first step (see <xref linkend="running-step.en"/>). After that, the
	outgoing transitions of this step are evaluated, and if one can be
	fired, Narval runs the destination steps of the transition, and so
	on. Executing a plan is much like walking through a graph.</para>

	<para>In the next example, <xref linkend="fig-execplan"/>,
	after having run the <glossterm
	linkend='gloss.action'>action</glossterm> (label 1),
	<application>Narval</application> evaluates the transitions
	(label 2) and only fires one of them to select the next action
	(label 3).</para>

	<figure id="fig-execplan"><title>Plan execution</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="images/execplan.en.png"
	      format="gif"/>
	    </imageobject>
	    <textobject>
	      <phrase><application>Narval</application> executes a plan
	      (evaluation of the transitions and steps)</phrase>
	    </textobject>
	  </mediaobject>
	</figure>
	
      </sect2>

    </sect1>

    <sect1 id="running-step.en"><title>Running a step</title>

      <para>Two kinds of <glossterm
      linkend='gloss.step'>steps</glossterm> can exist in a
      <glossterm>recipe</glossterm>, depending on the target, which
      can be a <glossterm>recipe</glossterm> or an
      <glossterm>action</glossterm>.</para>

      <sect2><title>General behaviour</title>

	<para>If the step's target is a recipe,
	<application>Narval</application> creates a new plan from this
	recipe and executes it within the <glossterm
	linkend='gloss.context'>context</glossterm> of the parent plan
	(the context of the new plan is consequently nested within the
	current plan's).</para>

	<para>When the target is an action or transformation,
	<application>Narval</application> simply runs the target (see <xref
	linkend="exec-action.en"/>).</para>

      </sect2>

      <sect2 id="repeat-step.en"><title>Special behaviour: the
      <emphasis>foreach</emphasis> attribute</title>

	<para>The <emphasis>foreach</emphasis> attribute can only be set on
	steps whose target is an action. It specifies that
	the action must be run for each element matching a given input (the 
	<emphasis>foreach</emphasis> attribute gives the input identifier). 
        In the example presented on <xref
	linkend="fig-foreach"/>), the <function>Send_greetings</function> action
	takes an email address element as an input with Email_Ad as identifier 
        (those addresses are stored in <classname>Email_Ad</classname> elements), 
	and creates an new year greetings email (stored in an <classname>Email</classname> type
	element). The step representing this action has a foreach attribute
	set to <classname>Email_Ad</classname> as the desired input identifier. 
        The action will thus  be parallelized for each email found in memory
	(in the example, three times). In the end, the action will have created three
	<classname>Email</classname> elements.</para>

	<figure id="fig-foreach"><title>Foreach attribute in a step</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="images/foreach.en.png"
	      format="gif"/>
	    </imageobject>
	    <textobject>
	      <phrase>In <application>Narval</application>, a step with the
	      foreach attribute positioned one of the target inputs will be
	      executed for each element matching the input prototype in memory.</phrase>
	    </textobject>
	  </mediaobject>
	</figure>

      </sect2>

    </sect1>

    <sect1 id="exec-action.en"><title>Running an action or a transition</title>

      <note><title>Remark</title>

	<para>Unless explicitely noted, all that is said about actions is also
	true for transitions in this section. In order to make the text more
	readable, we shall only speak of actions.</para>

	</note>


      <sect2 id="DescAct"><title>Prototype of an action</title>

	<para>Actions used by <application>Narval</application> provide a
	prototype. In other words, they describe the elements they require in
	order to execute correctly and the elements that they produce when the
	execution was successful. For instance, the
	<function>Catch_new</function> action which gets new emails in a mail
	box, specifies that it needs a <classname>mailbox</classname> element as
	an input, and that it produces <classname>email</classname> elements as
	outputs.</para>

	<para>Each action input describes an element type that is required by
	the action. For each input, it is possible to specify additional
	properties.</para>

	<sect3 id="EntConsultConsom"><title>Used and consulted inputs</title>

	  <para>An input may be marked as used by an action using the
	  <emphasis>use</emphasis> attribute. When an action uses an input, an
	  element matching the input can only be passed once as an input to the
	  action. This is generally the expected behaviour for an action that
	  transforms an element into another element. On the opposite, if the
	  element is not marked as used, it can be used over and over by plans
	  instantiated from the same recipe. In this case the element is said to
	  be consulted.</para>

	  <para> If we consider <xref linkend="actionuse1"/>, action
	  <function>catch_new</function> has a <classname>mailbox</classname>
	  element as an input, and this input is consulted. When two plans
	  issued from the same recipe are run (labels&#160;1 and&#160;2), the
	  same <classname>mailbox</classname> element can be used both
	  times. This is obviously the expected behaviour since we always want
	  to fetch emails in the same mailbox.</para>

	  <figure id="actionuse1"><title>Action with a consulted
	  input</title>

	    <mediaobject>
	      <imageobject>
		<imagedata align="center" fileref="images/actionuse1.en.png"
		format="gif"/>
	      </imageobject>
	      <textobject>
		<phrase>A consulted input in an action can reuse the same
		element each time it is run within the same recipe</phrase>
	      </textobject>
	    </mediaobject>
	  </figure>

	  <para>On the other hand, in <xref linkend="actionuse2"/>, action
	  <function>Acknowl_mail</function> which acknowledges reception of
	  mails takes <classname>Email</classname> elements as inputs, and uses
	  them. As a consequence if, during the first execution (label 1), the
	  <classname>Email</classname> element number <classname>1</classname>
	  is processed, it is not processed again on the second execution (label
	  2), and element number <classname>2</classname> which was not there on
	  the first time is processed. Once again, this is the expected
	  behaviour, since we want to acknowledge each mail only once, but we
	  also wish to keep them in memory so that they can be passed to other
	  plans. </para>

	  <figure id="actionuse2"><title>Action with used inputs</title>
	    <mediaobject>
	      <imageobject>
		<imagedata align="center" fileref="images/actionuse2.en.png"
		format="gif"/>
	      </imageobject>
	      <textobject>
		<phrase>An action step input that uses elements cannot reuse the
		same element when run twice.</phrase>
	      </textobject>
	    </mediaobject>
	  </figure>

	</sect3>

	<sect3><title>Outdated inputs</title>

	  <para>There are times where it is necessary to make sure that an
	  element will never be reused after having been passed by an
	  action. This is called outdating the element, and is achieved by
	  specifying an <emphasis>outdates</emphasis> attribute on the input
	  with the value of 'yes'. This is like using the
	  <emphasis>use</emphasis> attribute, except that no other action or
	  transtion will ever be able to use the element. </para>

	  <para>A common use for this is emulating global variables in Narval:
	  if an action outputs an element of the same type as the outdated
	  input, the effect will as if the new element replaced the original
	  one.</para>
	  
	</sect3>

	<sect3><title>Single element or list of elements</title>

	  <para>In most cases, an action input is supposed to match only one
	  element at run time. However, it is sometimes necessary to specify
	  that an input can be matched by an unknown number of elements. For
	  instance, in <xref linkend="actionlist"/>, action
	  <function>Send_greetings2</function> takes a list of email addresses
	  (<classname>Email_Ad</classname> elements) as an input, in order to
	  send to all the persons in the list a new year greetings email. Please
	  note that this action creates a single <classname>email</classname>
	  regardless of the number of <classname>Email_Ad</classname>
	  elements. This is quite different from the foreach attribute in a
	  step: in <xref linkend="fig-foreach"/>, the
	  <function>Send_greetings</function> action step had created one
	  <classname>Email</classname> for each
	  <classname>Email_Ad</classname>.</para>

	  <para>For each input, the list attribute specifies whether a single
	  element or a list of elements must be used.</para>

	  <figure id="actionlist"><title>Action with a list of elements
	  input</title>
	    <mediaobject>
	      <imageobject>
		<imagedata align="center" fileref="images/actionlist.en.png"
		format="gif"/>
	      </imageobject>
	      <textobject>
		<phrase>An action with an input accepting a list of elements can
		be passed several elements matching the input. </phrase>
	      </textobject>
	    </mediaobject>
	  </figure>
	  
	</sect3>

	<sect3><title>Optional and mandatory inputs</title>

	  <para>It is also possible for an action to take optional
	  inputs. Optional inputs are not required for the execution of the step,
	  so if a matching element is not found for the step, this will not
	  prevent the step from executing properly. This is not the case for
	  mandatory inputs (by default if not specified otherwise), and if no
	  element can be found that matches a mandatory input, the action will
	  not be executed and the plan will be ended with an error.</para>

	  <para>In the example of <xref linkend="actionopt"/>, action
	  <function>Send_greetings3</function> has an optional
	  <classname>Signature</classname> input. If no
	  <classname>Signature</classname> element is present in memory, the
	  action will be run anyway.</para>

	  <figure id="actionopt"> <title>Action optional input</title>
	    <mediaobject>
	      <imageobject>
		<imagedata align="center" fileref="images/actionopt.en.png"
		  format="gif"/>
	      </imageobject>
	      <textobject>
		<phrase>If an input is optional, the action can be executed if
		no elements match the input</phrase>
	      </textobject>
	    </mediaobject>
	  </figure>

	</sect3>

	<sect3><title>Arguments of an action</title>

	  <para>It is also possible to specify arguments for an action
	  explicitly in a recipe. As for elements in memory, an argument is an
	  element that can be used by an action when it is run. The main
	  difference is that the element is statically specified in the recipe
	  instead of having been created dynamically at run time. If the argument
	  does not match any input, it is not used.</para>

	  <para>In the example of <xref linkend="actionarg"/>, action
	  <function>Send_greetings4</function> accepts a
	  <classname>Text</classname> element containing the greeting to be sent
	  in the email. The step has an argument providing this element
	  explicitly. This provides a facility for using a generic action that is
	  specialized when the recipe is written. For instance, in this example,
	  the same action can be used to send greetings in English or in
	  French.</para>

	  <figure id="actionarg">
	    <title>Step with an argument</title>
	    <mediaobject>
	      <imageobject>
		<imagedata align="center" fileref="images/actionarg.en.png"
		format="gif"/>
	      </imageobject>
	      <textobject>
		<phrase>Arguments to steps enable static specialization of
		actions in recipes</phrase>
	      </textobject>
	    </mediaobject>
	  </figure>

	</sect3>

	<sect3><title>Constraining the prototype in the Step</title>

	  <para>It is possible to constrain the prototype of an action in the
	  step, using the <classname>id</classname> attribute provided by the
	  action's inputs prototype. The description of the elements can be
	  precised by adding <classname>match</classname> statements, and some
	  attributes of the input can be overriden, depending on the value of
	  the attribute in the action prototype, as shown in the table
	  below.</para>

	  <table><title>attribute precedence</title>
	    <tgroup cols='3'>
	      <colspec colwidth='2*' valign="middle" align="center"/>
	      <colspec colwidth='1*' align="center"/>
	      <colspec colwidth='1*' align="center"/>
	      <thead>
		<row>
		  <entry> attribute</entry>
		  <entry> value in action</entry>
		  <entry> overridable in step</entry>
		</row>
	      </thead>
	      <tbody>
		<row>
		  <entry morerows='1'> optional</entry>
		  <entry> yes</entry>
		  <entry> yes</entry>
		</row>
		<row>
		  <entry> no</entry>
		  <entry> no</entry>
		</row>
		<row>
		  <entry morerows='1'> list</entry>
		  <entry> yes</entry>
		  <entry> yes</entry>
		</row>
		<row>
		  <entry> no</entry>
		  <entry> no</entry>
		</row>
		<row>
		  <entry morerows='1'> use</entry>
		  <entry> yes</entry>
		  <entry> no</entry>
		</row>
		<row>
		  <entry> no</entry>
		  <entry> yes</entry>
		</row>
		<row>
		  <entry morerows='1'>outdates</entry>
		  <entry> yes</entry>
		  <entry> no</entry>
		</row>
		<row>
		  <entry> no</entry>
		  <entry> yes</entry>
		</row>
	      </tbody>
	    </tgroup>
	  </table>

	  <para>This is a very powerful feature, that can be used, for instance,
	  to provide template actions, which can operate on different types of
	  argument. Which kind of argument precisely is specified in the recipe
	  as the action is embedded in a step.</para>

	</sect3>

      </sect2>

      <sect2 id="RechElAct"><title>Getting inputs before running an
      action</title>

	<para>When <application>Narval</application> is about to run an action
	step, it first gathers all the elements potentially acceptable by the
	action's inputs. Then the elements are assigned to each input according
	to a number of priorities: explicit arguments to the step have higher
	priority than elements that have validated the incoming transition,
	which have a higher priority than elements produced by an input step of
	that transition, which have a higher priority than elements in the
	context of the plan and so on with all the nested contexts up to the
	memory itself. This ordering enables to privilege elements that are
	close to the step.</para>

	<table>

	  <title>Priorities given to elements according to their origin when
	  assigning action inputs</title>

	  <tgroup cols="2">
	    <colspec colwidth='1*' align="center"/>
	    <colspec colwidth='4*'/>
	    <thead>
	      <row>
		<entry> Rank</entry> 
		<entry> Element origin</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> 1</entry> 
		<entry> action argument and step context</entry>
	      </row>
	      <row>
		<entry> 2</entry> 
		<entry> elements having validated a condition of the transition
		that has lead to the step.</entry>
	      </row>
	      <row>
		<entry> 3</entry> <entry> elements produced by an incoming step of
		that transition</entry>
	      </row>
	      <row>
		<entry> 4</entry> 
		<entry> context of the step's plan (elements in memory belonging
		to the context of that plan)</entry>
	      </row>
	      <row>
		<entry> 5</entry> 
		<entry> context of the caller plan (this can be iterated)</entry>
	      </row>
	      <row>
		<entry> 6</entry> 
		<entry> global memory</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>


	<para>The <emphasis>from_context</emphasis> and <emphasis>to_context</emphasis>
	attributes of an input can be used to control the memory area (from
	the parent step to the whole memory) from  which elements will
	selected for the input. For instance, if you set from_context to "plan",
	the elements lookup will start from the step's plan, skipping step 1 to 3
	of the above table. In the same way, if you set to_context to "plan",
	the elements lookup will stop to the step's plan, skipping step 5 and
	6. Available values for those attributes are "step", "plan",
	"parent_plan" and "memory"</para> 

	<para>Keep in mind that a given element can be assigned to only one
	input.</para>

	<para>If the input can be a list of elements, the list is built with
	elements having the same priority, for instance only elements having
	validated the transition leading to the step, or only elements coming
	from the context of the plan. It is therefore impossible to build a list
	with elements coming, for example, from the context of the action, from
	the transition and the context of the plan. The list with the higher
	priority is used.</para>

	<para>If the step has a <emphasis>foreach</emphasis> attribute (see <xref
	linkend="repeat-step.en"/>) on a given element type,
	<application>Narval</application> tries to assign all the matching
	elements to a single input. If this is not possible,
	<application>Narval</application> stops the execution of the plan and
	produces an error element (see below).</para>

	<para>If after input assignment one of the mandatory inputs is unmatched,
	<application>Narval</application> stops the plan execution and produces
	an <classname>error</classname> element in memory. This element
	describes the error (which plan was running, which action was being
	prepared and which input was missing). This is of course not the case
	for optional inputs.</para>

      </sect2>

      <sect2><title>Executing the action and fetching the outputs</title>

	<para>After having checked that all inputs are available,
	<application>Narval</application> launches the action using the selected
	elements as an arguments. The execution of the action can, of course, use
	several external programs. When the execution is over,
	<application>Narval</application> checks that the elements returned
	match the expected outputs described in the action prototype. If an
	unexpected element is found or if one output is matched by several
	elements <application>Narval</application> terminates the plan and
	creates an <classname>error</classname> element in memory. This element
	describes the running plan and step, and which output caused the
	problem.</para>

      </sect2>

      <sect2 id="ActErr"><title>Handling action generated errors</title>

	<para>Errors can occur during action execution, for instance a file that
	the action is supposed to read can be missing. However, we sometimes
	wish to handle such situations within the plan, and avoid aborting the
	execution. This is possible if the action produces an
	<classname>error</classname> element itself. In that case,
	<application>Narval</application> checks for the existence of specific
	transition dedicated to error handling (see <xref
	linkend="TransErr"/>). If such a transition is found in the step's
	outgoing transitions, and its conditions are matched, it is fired
	immediately and the execution goes on. Otherwise, the plan is aborted as
	described above.</para>

      </sect2>

      <sect2><title>Further execution of the plan</title>

	<para>The elements produced as outputs by the step are submitted to
	following transitions, so that their conditions can be evaluated.</para>

      </sect2>

    </sect1>

    <sect1 id="eval-transition.en"><title>Evaluating transitions</title>

      <para>In a plan, the transitions control the execution flow. <xref
      linkend="transitiondesc"/> shows a recipe with several transitions. Some
      have only one incoming step, and only one outgoing step, others have
      several incoming steps or several outgoing steps, or both. In order for a
      transition with several incoming steps to be fired, all the steps must
      have been successfully executed. When a transition has several outgoing
      steps, the execution of all the steps is parallelized.</para>

      <figure id="transitiondesc">
	<title>General presentation of transitions in a recipe</title>
	<mediaobject>
	  <imageobject>
	    <imagedata align="center" fileref="images/transitiondesc.en.png"
	    format="gif"/>
	  </imageobject>
	  <textobject>
	    <phrase>A transition links one or more steps to one or more other
	    steps.</phrase>
	  </textobject>
	</mediaobject>
      </figure>

      <sect2><title>Conditions in a transition</title>

	<para>Each transition can bear one or more conditions allowing to choose
	which transition will be fired, and thus what will be the execution
	path of the plan, according to the elements produced by the steps that
	where formerly executed, and the content of the global memory.</para>

	<para>A condition checks the presence in memory of an element having a
	number of specificities. It becomes true, thus giving a chance to the
	transition to be fired, only if such an element exists. On <xref
	linkend="transitioncond"/>, one of the transitions checks the existence
	of an element of type <classname>Elt1</classname> and the other one
	checks for an element of type <classname>Elt2</classname>. Since there
	is only an <classname>Elt1</classname> element in memory, only the
	former transition can be fired, and its outgoing steps will be
	executed. If two transitions can be fired at the same time, the
	transition with the highest priority is fired (see <xref
	linkend="PrioTransit"/>). In case of a tie, the behaviour is
	unspecified. Such a situation can be avoided by choosing carefully the
	conditions of the transitions and by assigning different priorities to
	transitions that may be simultaneously fireable.</para>

	<figure id="transitioncond">
	  <title>Handling of a transition's conditions by
	  <application>Narval</application></title>
	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="images/transitioncond.en.png"
		format="gif"/>
	    </imageobject>
	    <textobject>
	      <phrase>A condition in a transition checks that a given element is
	      in memory. It is verified only if the element exists.</phrase>
	    </textobject>
	  </mediaobject>
	</figure>

	<para>A transition can have several conditions. Each condition checks
	for the existence of a different element. Therefore, a transition with
	three conditions can be fired only if its three conditions are matched
	by three different elements.</para>

      </sect2>

      <sect2 id="TransErr"><title>Behaviour of transition</title>

	<para>The incoming links of a transition can optionally be flagged as
	error handling links.</para>

	<para>Normally this flag is not set. In this case, the transition can be
	fired only if the step connected to this link has been successfully
	executed and all the conditions of the transition are satisfied. </para>

	<para>If one of the input links is flagged as error handling, the
	transition can be fired only if the step connected to this link has
	produced an <classname>error</classname> element during its execution,
	and, of course, if all the conditions of the transition are
	matched.</para>

	<para>In <xref linkend="transitionerror"/>, on the left panel, an
	action has generated an <classname>Error</classname> element (see <xref
	linkend="ActErr"/>). This causes the transition on the error handling
	link to be activated, regardless of other transitions. On the left
	panel, since no error has occurred in the step, the normal link is
	activated, and the other transition is evaluated.</para>

	<figure id="transitionerror"><title>Transition behaviour (standard or
	error handling)</title>

	  <mediaobject>
	    <imageobject>
	      <imagedata align="center" fileref="images/transitionerror.en.png"
		format="gif"/>
	    </imageobject>
	    <textobject>
	      <phrase>A link with the error handling flag set can only be
	      activated if an <classname>error</classname> element was produced
	      by the step</phrase>
	    </textobject>
	  </mediaobject>
	</figure>

      </sect2>

      <sect2><title>Used and consulted elements</title>

	<para>Just as for action inputs (see <xref
	linkend="EntConsultConsom"/>), it is possible to specify that a
	condition will 'use' its matching element, so that the same element will
	not be able to match a condition of the transition more than once. For
	instance, if the first transition of a plan can be fired if an
	<classname>email</classname> element is available, and this element is
	used by the condition, the plan will be run only once for each
	email.</para>

      </sect2>

      <sect2><title>Context of a transition</title>

	<para>Just as for steps (see <xref linkend="RechElAct"/>), it is
	possible to specify a context for a transition condition. This forces
	<application>Narval</application> to look for elements in a given memory
	area, either the global memory or the context of the running plan, and
	to use these elements first to match the condition.  (see <xref
	linkend="UtilElEval"/>).</para>

      </sect2>

      <sect2 id="PrioTransit">

	<title>Priorities</title>

	<para>When several conditions are available after a step, a priority can
	be set on these transitions, so that <application>Narval</application>
	can break ties when selecting which transition to fire (the one with the
	highest priority is used). This enables having a default condition that
	will be fired if no other transition can be fired, or to solve
	situations where several transitions could be fired
	simultaneously.</para>

      </sect2>

      <sect2 id="UtilElEval"><title>Using elements to evaluate
      transitions</title>

	<para>When <application>Narval</application> must evaluate a transition,
	it first gathers all the elements that match each condition. Then it
	assigns an element to each condition, using the same algorithm as for
	action input assignment (see <xref linkend="RechElAct"/>). This
	privileges the elements that are closer to the transition. </para>

	<table>

	  <title>Selection order for element condition assignment in
	  transitions</title>

	  <tgroup cols="2">
	    <colspec colwidth='1*' align="center"/>
	    <colspec colwidth='4*'/>
	    <thead>
	      <row>
		<entry> Assignment order</entry> 
		<entry> Element location</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> 1</entry> 
		<entry> transition context</entry>
	      </row>
	      <row>
		<entry> 2</entry> 
		<entry> elements produced by incoming steps</entry>
	      </row>
	      <row>
		<entry> 3</entry> 
		<entry> current plan memory context</entry>
	      </row>
	      <row>
		<entry> 4</entry> 
		<entry> context of caller plans</entry>
	      </row>
	      <row>
		<entry> 5</entry> 
		<entry> global memory</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<para>An element can be assigned to at most one condition. If after
	condition assignment, a condition is still not matched, the transition is
	not fireable. If no transition in the plan is fireable, execution of the
	plan is suspended until another plan adds a new element in the memory
	that makes a transition fireable, and thus enables the plan execution to
	be resumed.</para>

      </sect2>

      <sect2> <title>Further execution of the plan</title>

	<para>When a transition is fired, <application>Narval</application>
	prepares the outgoing steps for execution and sends them the elements
	having matched the transition conditions.</para>

      </sect2>

    </sect1>

    <sect1 id="select-element.en">

      <title>Element selection and condition evaluation</title>

      <para>When an action is executed, <application>Narval</application> checks
      that the input elements given to the action and the output elements
      produced by the action match the action prototype. To evaluate a
      transition, <application>Narval</application> looks in memory for elements
      matching the description given in the condition. Similarly, to build the
      context of a step or of a transition, or to implement the foreach
      evaluation of a step, <application>Narval</application> selects elements
      in memory. In all cases, the same matching algorithm is used: only
      elements having at least the required patterns are eligible. For instance,
      the transition leading to an email forwarding action step lets through
      only mails sent by M. Dupont, without considering the email subject or
      body. This is done by writing a condition saying that we want an
      <classname>email</classname> element having the
      <varname>sender="M. Dupont"</varname> property. Each condition can specify
      several properties of an element and several conditions specify different
      elements. This is a very powerful tool to specify constraints pertaining to
      the execution flow of the steps, by restraining the prototype of the
      actions.</para>

    </sect1>

  </chapter>
  
  <!-- ********************************************************** --> 

  <chapter id="repr-n-tech.en">

     <title>Chosen representations and used techniques</title>

    <para><application>Narval</application> uses numerous techniques lying on
    the XML data description language and
    the Python programming language. The
    following sections will describe <application>Narval</application> majors
    implementation choices.</para>

    <sect1 id="desc-element.en">

      <title>Description of the various elements</title>

      <sect2 id="descrec"> <title>Description of a recipe</title>

	<para>A recipe is described using an XML tree. This tree contains a root node (the
	<classname>cookbook</classname> node) and below several child
	nodes. Each node can have attributes. The recipe XML tree is described below. A real recipe
	might, of course, have several <classname>step</classname> nodes and
	several <classname>transition</classname> nodes. Node ordering is
	unimportant.</para>

	<table><title>Description of recipe nodes</title>
	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> recipe</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> Recipes can appear as a top level element in Narval's
		memory. When serialized, they are usually stored in
		<classname>cookbook</classname> Nodes (this is only a convention
		though).</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> step+,transition*</entry>
	      </row>
	      <row>
		<entry> A recipe may consist of a single
		<classname>step</classname> element, which will be both the
		start and end step. In most cases, more than one steps will be
		used, and these steps will be connected by
		<classname>transition</classname> elements. The order of the
		child nodes is not important.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> group</entry> <entry> Mandatory. The name of the recipe group. This
		relates the recipe to a cookbook, and thus provides a namespace
		for the recipe, in which we are sure that no other recipe will
		have the same name.</entry>
	      </row>
	      <row rowsep='0'> <entry> name</entry> <entry> Mandatory. The name of
	      the recipe itself. When used as the target of a step or a start
	      plan command, the recipe will be refered to as
	      'group.name'.</entry>
	      </row>
	      <row rowsep='0'> <entry> restart</entry> <entry> Optional, defaults
	      to 'no'. Should be 'yes' if plans instanciated from this recipe
	      should restart after the end step has been completed.</entry>
	      </row>
	      <row rowsep='0'> <entry> decay</entry> <entry> Optional. Gives the
	      number of seconds after which plans instantiated from this recipe
	      will be forgotten</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>


	<table><title>Description of step nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> step</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> Steps encapsulate the behavioural units in a recipe,
		which can be <classname>actions</classname>,
		<classname>transformations</classname> or other
		<classname>recipes</classname>.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> arguments?,input*,output*</entry>
	      </row>
	      <row>
		<entry> Comments: a basic step is empty. If the target is an
		action or a transformation, explicit arguments can be provided
		in an <classname>argument</classname> node; the
		<classname>context</classname> child node can be used to specify
		the context in which the arguments will be fetched;
		<classname>input</classname> and <classname>output</classname>
		nodes can be used to provide restrictions to the prototype of
		the action or transformation. The order of the child nodes is
		not important.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> id</entry> <entry> Mandatory. The identifier of the step. Must be
		unique within a recipe</entry>
	      </row>
	      <row>
		<entry> type</entry><entry> Mandatory. The type of the target of
		the step. Must be one of 'recipe', 'action'</entry>
	      </row>
	      <row>
		<entry> target</entry> <entry> Mandatory. The name of the target
		of the step, generally of the form 'group.name'.</entry>
	      </row>
	      <row>
		<entry> foreach</entry> <entry> Optional. See <xref
		linkend='repeat-step.en'/> for more information </entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>

	<table><title>Description of transition nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> transition</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> Transitions are used to control the execution flow in the
		recipe. They can express conditional execution, or
		synchronization</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> in+,out+,condition,time?,context?</entry>
	      </row>
	      <row>
		<entry> <classname>in</classname> and <classname>out</classname>
		elements point to steps in the recipe, respectively the incoming
		and outgoing steps of the transition. The
		<classname>condition</classname> node specifies the elements
		that will trigger the transition. <classname>time</classname>
		provides transitions that are time-triggered, and
		<classname>context</classname> gives information about where
		to look for elements that could match the conditions. </entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> id</entry> <entry> Mandatory. The identifier of the
		transition. Must be unique within a recipe</entry>
	      </row>
	      <row>
		<entry> priority</entry><entry> Optional, defaults to 0. Used to
		break ties when determining which transition should be fired:
		the one with the highest priority is used.</entry>
	      </row>
	      <row>
		<entry> state</entry> <entry> This attribute is only valid for
		transitions in <classname>plan</classname> elements. It
		specifies the current state of the transition. Possible values
		are wait-step, wait-time, wait-condition, fireable, fired, fail,
		impossible</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>

	<table><title>Description of condition nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> condition</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry>  A condition is a set of <classname>match</classname>
		nodes, that should all be matched by the same element in order
		for the condition to be true.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> match+</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> use</entry> <entry> optional, defaults to no. Possible
		value are yes, no. If use is yes, then an element will only be
		able to match the condition once.</entry>
	      </row>
	      <row rowsep='0'>
		<entry> from_context</entry> <entry> Optional. The context from
		which elements lookup should start.</entry>
	      </row>
	      <row rowsep='0'>
		<entry> to_context</entry> <entry> Optional. The context
		where elements lookup should stop.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>

	<table><title>Description of match nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> match</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> a <classname>match</classname> describes a number of
		elements using an python expression</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> #PCDATA</entry>
	      </row>
	      <row>
		<entry> The python expression describing the matched
		elements. Elements for which the expresion evaluates to true, a non
		empty list of nodes, a non empty string or a non zero numeric
		value are matching elements. The expression should use the
		special <emphasis>elmt</emphasis> identifier, which represent
		the element currently being tested (actually the expression is
		ran against avery matchable element).</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>


	<table><title>Description of time nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> time</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> <classname>time</classname> nodes are used to describle
		a date, for instance the date when a condition can be fired. The
		syntax is inspired from crontab entries. Each attribute is a
comma separated list of values or '*' (default value). Each value can be an
integer between min and max (given below) or a range, such as a-b.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> EMPTY</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> seconds</entry> <entry> min = 0 max = 59</entry>
	      </row>
	      <row rowsep='0'>
		<entry> minutes</entry> <entry> min = 0 max = 59</entry>
	      </row>
	      <row rowsep='0'>
		<entry> hours</entry> <entry> min = 0 max = 23</entry>
	      </row>
	      <row rowsep='0'>
		<entry> monthdays</entry> <entry> min = 1 max = 31</entry>
	      </row>
	      <row rowsep='0'>
		<entry> months</entry> <entry> min = 1 max = 12</entry>
	      </row>
	      <row rowsep='0'>
		<entry> years</entry> <entry> min = -10000 max = 10000</entry>
	      </row>
	      <row rowsep='0'>
		<entry> yeardays</entry> <entry> min = 1 max = 366</entry>
	      </row>
	      <row rowsep='0'>
		<entry> weekdays</entry> <entry> min = 0 max = 6 (0 is monday)</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<table><title>Description of in nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> in</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> an <classname>in</classname> node has a reference
to a step in a plan or recipe.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> EMPTY</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> idref</entry> <entry> Mandatory. The identifier of the
		step.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<table><title>Description of out nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> out</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> an <classname>out</classname> node has a reference
to a step in a plan or recipe.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> EMPTY</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> idref</entry> <entry> Mandatory. The identifier of the
		step.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<para>Recipes are specified in XML
	files stored on the disk. When starting
	<application>Narval</application>, these files are read and recipes are
	stored in the memory.</para>

      </sect2>

      <sect2> <title>Description of a plan</title>

	<para>A plan looks like a recipe. It is also described as an XML
	tree. Plans have additional attributes allowing plan execution
	control. The plan tree is described below.</para>



	<table><title>Description of plan nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> plan</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> Plans can appear as a top level element in Narval's
		memory. Plans are instances of recipes, that Narval is able to
		run.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> step+,transition*,elements</entry>
	      </row>
	      <row>
		<entry> The steps and transitions are initially copied from the
		recipe from which the plan was instanciated. The
		<classname>elements</classname> node is used to store references
		to the elements used by the plan, which make up the context of
		the plan. Only Narval can create plans. </entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> recipename</entry> <entry> Mandatory. The name of the
		recipe from which the plan was instanciated.</entry>
	      </row>
	      <row rowsep='0'> <entry> start_step</entry> <entry> Mandatory. The
	      value of this attribute should be the id of the start step of the
	      plan</entry>
	      </row>
	      <row rowsep='0'> <entry> end_step</entry> <entry> Mandatory. The
	      value of this attribute should be the id of the final step of the
	      plan</entry>
	      </row>
	      <row rowsep='0'> <entry> restart</entry> <entry> Optional, defaults
	      to 'no'. Should be 'yes' if the plan should restart after the end
	      step has been completed.</entry>
	      </row>
	      <row rowsep='0'> <entry> decay</entry> <entry> Optional. Gives the
	      amount of time after which the will be forgotten</entry>
	      </row>
	      <row rowsep='0'> <entry> eid</entry> <entry> Optional. Element
	      identifier in Narval's memory.</entry>
	      </row>
	      <row rowsep='0'> <entry> parent_plan</entry> <entry> Optional. The
	      eid of the plan of in which the current plan is embedded as a
	      step.</entry>
	      </row>
	      <row rowsep='0'> <entry> parent_step</entry> <entry> Optional. The
	      id of the step of which the current plan is the target.</entry>
	      </row>
	      <row>
		<entry> state</entry> <entry> Specifies the current state of the
		plan. Possible values are ready, running, failed, end,
		failed-end, done</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>


	<para>Plans don't have to be specified in XML files as
	<application>Narval</application> builds them in memory from the
	recipes. However, <application>Narval</application> can save the content
	of its memory in a file. Therefore, plans might appear in this
	file.</para>

      </sect2>

      <sect2> <title>Notion of module. Description of the actions.</title>

      <para>Actions are grouped in modules. A module is a Python file containing
      the actions code. In this file, there is also an XML tree describing all
      the actions of the module and their prototype (i.e. their inputs and their
      outputs). This tree is described below.</para>

	<table><title>Description of module nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> module</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> <classname>module</classname> nodes hold lists of
		<classname>action</classname> nodes </entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> action*</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> name</entry> <entry> Optional. The name of the
		module. If provided, must be the name of the python file
		(without the .py extention)</entry>
	      </row>
	      <row rowsep='0'> <entry> version</entry> <entry> Optional.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>

	<table><title>Description of action nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> action</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> <classname>action</classname> nodes describe a way for
		Narval to do something, generally using python code.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> description*,input*,output*</entry>
	      </row>
	      <row>
		<entry> The input and output nodes are the prototype of the
		action.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> name</entry> <entry> Mandatory. The name of the
		action.</entry>
	      </row>
	      <row rowsep='0'> <entry> group</entry> <entry> Optional. If
	      provided, must be the name of module</entry>
	      </row>
	      <row rowsep='0'> <entry> func</entry> <entry> Mandatory. The name
	      of the python function implementing the action</entry>
	      </row>
	      <row rowsep='0'> <entry> eid</entry> <entry> Optional.  Element
	      identifier in Narval's memory. This is an internal attribute that
	      should not be set when writing a module</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>

	<table><title>Description of description nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> description</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> <classname>description</classname> nodes hold a short
		description of what an action does. All actions and
		transformations should provide at least an english
		description. Beware that if your description uses non-ascii
		characters, the encoding of the XML document must be set
		accordingly.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> #PCDATA</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='2'>
	    <colspec colname='c1' colwidth='1*' colsep='0'/>
	    <colspec colname='c2' colwidth='5*'/>
	    <thead>
	      <row>
		<entry> Attributes</entry><entry> </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row rowsep='0'>
		<entry> lang</entry> <entry> Mandatory. The iso notation for the
		language of the description</entry>
	      </row>
	    </tbody>
	  </tgroup>

	</table>

	<para>When <application>Narval</application> executes a plan and has to
	run an action, it firstly gets the action name in the plan XML
	tree. This name is compound of the module name followed by the action
	name (for example, <function>Email.catch_new</function> refers to the
	<function>catch_new</function> action of the <function>Email</function>
	module). <application>Narval</application> loads the corresponding
	module and runs the Python
	function associated with the action (in previous example,
	<application>Narval</application> loads <filename>Email.py</filename>
	Python module).</para>

	<para>The behaviour of the modules is further described in the modules
	programmer handbook.</para>

      </sect2>

      <sect2> <title>Description of transform elements</title>
	
	<para>Transforms in Narval conform to the XSLT specification. In order
	to be processed by Narval, tough, they must include some information
	about their prototype in a prototype node, which has to be a child of
	the root node of the transformation. Since this node is not in the XSLT
	namespace, it will be ignored by the tranformation engine.</para>

	<table><title>Description of prototype nodes</title>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> prototype</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> <classname>prototype</classname> nodes hold the
		prototype of a transformation.</entry>
	      </row>
	    </tbody>
	  </tgroup>

	  <tgroup cols='1'>
	    <colspec colname='c1' colwidth='1*'/>
	    <thead>
	      <row>
		<entry> Content model</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry> description*,input*,output*</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
	
	<para>More information is available in the Module Programmer Handbook.</para>

      </sect2>


<!--       <sect2> <title>Description of the other elements</title> -->

<!-- 	<para>Each element in the memory is described using an XML tree. For -->
<!-- 	example, an <classname>email</classname> element can be represented as -->
<!-- 	below.</para> -->

<!-- 	<programlistingco> -->

<!-- 	  <areaspec> -->

<!-- 	    <area id="dtd-email-email" coords="1" -->
<!-- 	      linkends="dtd-email-email-co"/> -->

<!-- 	    <area id="dtd-email-to" coords="2" linkends="dtd-email-to-co"/> -->

<!-- 	    <areaset id="dtd-email-name" coords=""> -->
<!-- 	      <area id="dtd-email-name-to" coords="3" -->
<!-- 		linkends="dtd-email-name-co"/> -->

<!--                <area id="dtd-email-name-from" coords="7" -->
<!-- 	      linkends="dtd-email-name-co"/> -->
<!--             </areaset> -->

<!-- 	    <areaset id="dtd-email-emailaddr" coords=""> -->
<!-- 	      <area id="dtd-email-emailaddr-to" coords="4" -->
<!-- 		linkends="dtd-email-emailaddr-co"/> -->

<!--                <area id="dtd-email-emailaddr-from" coords="8" -->
<!-- 	      linkends="dtd-email-emailaddr-co"/> -->
<!--             </areaset> -->

<!-- 	    <area id="dtd-email-from" coords="6" -->
<!-- 	      linkends="dtd-email-from-co"/> -->

<!-- 	    <area id="dtd-email-subject" coords="10" -->
<!-- 	      linkends="dtd-email-subject-co"/> -->

<!-- 	    <area id="dtd-email-signature" coords="11" -->
<!-- 	      linkends="dtd-email-signature-co"/> -->

<!-- 	    <area id="dtd-email-body" coords="12" -->
<!-- 	      linkends="dtd-email-body-co"/> -->

<!-- 	    <area id="dtd-email-body-multipart" coords="13" -->
<!-- 	      linkends="dtd-email-body-multipart-co"/> -->

<!-- 	    <area id="dtd-email-part" coords="15" -->
<!-- 	      linkends="dtd-email-part-co"/> -->

<!-- 	    <area id="dtd-email-part-type" coords="16" -->
<!-- 	      linkends="dtd-email-part-type-co"/> -->

<!-- 	  </areaspec> -->

<!-- 	<programlisting> -->
<!-- <![CDATA[ -->
<!-- <email> -->
<!--    <to> -->
<!--       <name>...</name> -->
<!--       <email_addr>...</email_addr> -->
<!--    </to> -->
<!--    <from> -->
<!--       <name>...</name> -->
<!--       <email_addr>...</email_addr> -->
<!--    </from> -->
<!--    <subject>...</subject> -->
<!--    <signature>...</signature> -->
<!--    <body -->
<!--         multipart -->
<!--    > -->
<!--       <part -->
<!--            type -->
<!--       > -->
<!--       </part> -->
<!--    </body> -->
<!-- </email> -->
<!-- ]]> -->

<!-- </programlisting> -->

<!-- 	<calloutlist> -->

<!-- 	  <callout id="dtd-email-email-co" arearefs="dtd-email-email"> -->
<!-- 	    <para>Description of an <classname>email</classname> element.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-to-co" arearefs="dtd-email-to"> -->
<!-- 	    <para>Recipient data.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-from-co" arearefs="dtd-email-from"> -->
<!-- 	    <para>Sender data.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-name-co" arearefs="dtd-email-name"> -->
<!-- 	    <para>Name of the recipient or the sender.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-emailaddr-co" arearefs="dtd-email-emailaddr"> -->
<!-- 	    <para>Email address of the recipient or the sender.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-subject-co" arearefs="dtd-email-subject"> -->
<!-- 	    <para>Email subject.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-signature-co" arearefs="dtd-email-signature"> -->
<!-- 	    <para>Email signature.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-body-co" arearefs="dtd-email-body"> -->
<!-- 	    <para>Email body.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-body-multipart-co" arearefs="dtd-email-body-multipart"> -->
<!-- 	    <para>Specifies the email has several parts (i.e. attached -->
<!-- 	    files).</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-part-co" arearefs="dtd-email-part"> -->
<!-- 	    <para>Email part.</para> -->
<!-- 	  </callout> -->

<!-- 	  <callout id="dtd-email-part-type-co" arearefs="dtd-email-part-type"> -->
<!-- 	    <para>Type of the part (text or file).</para> -->
<!-- 	  </callout> -->

<!-- 	</calloutlist> -->

<!--       </programlistingco> -->

<!-- 	<para>Each new type of elements <application>Narval</application> -->
<!-- 	handles must have an XML -->
<!-- 	description included in the correct DTD<footnote> -->
<!-- 	    <formalpara> -->
<!-- 	      <title>Document Type Definition (<acronym>DTD</acronym>)</title> -->
<!-- 	      <para>Description of the content of an XML file, in particular the -->
<!-- 	      elements and the attributes that might appear in this file.</para> -->
<!-- 	      </formalpara></footnote>.</para> -->

<!--       </sect2> -->

    </sect1>

    <sect1 id="mem-struct.en"> <title>Memory structure</title>

      <sect2> <title>Internal structure of the memory</title>

	<para><application>Narval</application> memory is a simple set of
	elements, that should be exportable as an XML tree. The various elements
	are attached to the root node (<classname>memory</classname>). Each element
	in the memory has got an id number called <parameter>eid</parameter>. </para>

     </sect2>

      <sect2> <title>Memory initialization</title>

	<para>When <application>Narval</application> starts, it fills its memory
	using the <filename>$NARVAL_HOME/data/memory.xml</filename>. This
	XML file contains a tree
	representing the initial memory. It might contain general data such as
	the user's name, the user's email address, his electronic mailbox,
	etc.</para>

	<para>This file may also contains <classname>start-plan</classname> elements
	permitting recipes instantiation and plans starting when initializing
	<application>Narval</application>.</para>

	<para>During its initialization, <application>Narval</application> loads
	the recipes in its memory. The recipes are described in XML files
	located in the <filename>$NARVAL_HOME/recipes/</filename> or
	in the <filename>$NARVAL_SHARE/recipes/</filename> directories.</para>

      </sect2>

    </sect1>

    <sect1 id="cond-expr.en"> 

      <title>Conditions expression and elements selection</title>

      <para>As described above, the elements selection and the conditions
      evaluation are computed thanks to an unique matching algorithm. Such as
      algorithm searches the memory for elements corresponding to a
      pattern. Each pattern is described in a <classname>match</classname> node
      (in the actions prototypes). Inserting several nodes allows the
      description of several patterns and, thus, the selection of elements of
      different kinds. Inside the <classname>match</classname> node, the pattern
      definition is expressed using the Python language.</para>


      <para>For instance, a condition waiting for an
      <classname>email</classname> element whose subject is
      <parameter>Hi there</parameter> is expressed as follow:
      <parameter>IEmail(elmt).subject == "Hi there"</parameter>. As Python syntax is very
      powerful, conditions might be much more complicated.</para>

    </sect1>

    <sect1 id="eval-fire.en"> 

      <title>Evaluation of the fireability of a transition</title>

      <para>When <application>Narval</application> evaluates the transitions of
      a plan in order to know which ones are fireable and to decide which one
      will be fired, it first classifies the transitions in three groups: the
      transitions that are impossible to fire, the undetermined transitions and
      the potentially fireable transitions.</para>

      <para>The impossible-to-fire transitions are the ones with an input step
      that has failed or has already been used by a previous evaluation (step in
      the <constant>failed</constant> state or the <constant>history</constant>
      state). A transition flagged as error handling that has a correctly
      executed input step or a transition not flagged as error handling that has
      a failed input step are also impossible to fired.</para>

      <para>The undetermined transitions are the ones with an input step being
      still executed (which does not allow knowing the result of the
      step).</para>

      <para>The potentially fireable transitions are the other ones. The
      conditions of each of these transitions must be checked in order to know
      if it can be fired.</para>

      <para>If all the transitions of a currently executed plan are impossible
      to fire, the plan fails and an <classname>error</classname> element is set
      in the memory. If a transition flagged as error handling is potentially
      fireable but can't be fired because of unsatisfied conditions, the plan
      also fails. In the other cases, the plan execution continues. Further
      execution can be immediate thanks to a potentially-fireable transition
      having all its conditions satisfied, or postponed as the plan waits for
      its undetermined transition to become impossible or potentially fireable,
      or for its potentially fireable transitions to have their conditions
      satisfied.</para>

      <para>Whatever could be the state of the other transitions, as a
      transition is fireable, it is fired.</para>

    </sect1>


  </chapter>

  <!-- ********************************************************** -->
  <chapter id="known-bugs.en">

    <title>Known Bugs</title>

    <para>A web page covering the known bugs of Narval should be available very
    soon now, if it is not already there.</para>

  </chapter>

  <!-- ********************************************************** --> 

  <chapter id="conclusion.en"> <title>Conclusion</title>

    <para>This documentation provides a skipping through of
    <application>Narval</application> code, exposing the main notions,
    describing the software and explaining major design choices. The interested
    reader should read now the source code of <application>Narval</application>,
    that is carefully commented, allowing the understanding of its exact
    detailed behaviour.</para>

  </chapter>

  <glossary id="gloss.en">

    <glossdiv>

      <title>Narval</title>

      <glossentry id='gloss.action'>

	<glossterm>Action</glossterm>

	<glossdef><para>Conceptually elementary transformation that
	<application>Narval</application> can do with
	<glossterm>elements</glossterm>.</para></glossdef>
	
      </glossentry>

      <glossentry id='gloss.arguments'>
	
	<glossterm>Arguments</glossterm>
	
	<glossdef><para>Set of fixed <glossterm>elements</glossterm> used by
	an <glossterm>action</glossterm>.</para></glossdef>
	
      </glossentry>

      <glossentry id='gloss.element'>
	
	<glossterm>Element</glossterm>
    
	<glossdef><para>Generic representation of an object: all
	entities manipulated by Narval are Elements. It may be an
	<glossterm>action</glossterm>, an email, a Web page, a
	<glossterm>plan</glossterm> or a
	<glossterm>recipe</glossterm>.  Technicaly, elements are
	applicative computing entity found in
	<glossterm>memory</glossterm>.</para></glossdef>
	
      </glossentry>
      
      <glossentry id='gloss.error'>

	<glossterm>Error handling</glossterm>

	<glosssee otherterm="transition"/>

      </glossentry>
      
      <glossentry id='gloss.memory'>

	<glossterm>Memory</glossterm>

	<glossdef><para>Storage place of the <glossterm>elements</glossterm>
	in which they can be accessed by the
	<glossterm>actions</glossterm>.</para></glossdef>

      </glossentry>

      <glossentry id='gloss.context'>

	<glossterm>Context</glossterm>

	<glossdef><para>The context of a <glossterm>plan</glossterm>
	is the set of <glossterm>elements</glossterm> handled by the
	plan, i.e. all the elements created or used by the
	<glossterm>steps</glossterm> of the plan or that triggered the
	<glossterm>transitions</glossterm> of the
	plan.</para></glossdef>

      </glossentry>

      <glossentry id='gloss.plan'>

	<glossterm>Plan</glossterm>

	<glossdef><para>Instance of a <glossterm>recipe</glossterm> allowing
	its execution.</para></glossdef>

      </glossentry>

      <glossentry id='gloss.recipe'>

	<glossterm>Recipe</glossterm>

	<glossdef><para>Sequence of <glossterm>steps</glossterm> linked by
	<glossterm>transitions</glossterm>, describing a functionality of
	<application>Narval</application>.</para></glossdef>

      </glossentry>

      <glossentry id='gloss.repetition'>

	<glossterm>Repetition</glossterm>

	<glosssee otherterm="step"/>

      </glossentry>

      <glossentry id="gloss.step">

	<glossterm>Step</glossterm>

	<glossdef><para>Basic brick of a <glossterm>recipe</glossterm> that
	can be either an <glossterm>action</glossterm> or an other
	<glossterm>recipe</glossterm>.</para> <para>A
	<glossterm>step</glossterm> can have a <glossterm>repetition</glossterm>
	behaviour: it is then executed in parallel as much as necessary in order
	to compute the <glossterm>element</glossterm> set on which the
	<glossterm>repetition</glossterm> is done (the
	<glossterm>step</glossterm> is said to have a
	<glossterm>repetition</glossterm> behaviour on these
	<glossterm>elements</glossterm> type).</para></glossdef>

      </glossentry>

      <glossentry id="gloss.transition">

	<glossterm>Transition</glossterm>

	<glossdef><para>Link between a set of origin
	<glossterm>steps</glossterm> and a set of destination
	<glossterm>steps</glossterm>, that can have a condition on
	<glossterm>elements</glossterm> found in
	<glossterm>memory</glossterm>. Each of the input can be flagged as
	<glossterm>error handling</glossterm>. If not set, the
	<glossterm>step</glossterm> linked with this input must be correctly
	executed to have the <glossterm>transition</glossterm> fireable. If set,
	the <glossterm>step</glossterm> linked with this input must generate an
	<classname>error</classname> <glossterm>element</glossterm> to have the
	<glossterm>transition</glossterm> fireable.</para></glossdef>

      </glossentry>

    </glossdiv>

    <glossdiv>

      <title>Computing Languages used in <application>Narval</application></title>

      <glossentry id="gloss.dom">

	<glossterm>Python</glossterm>

	<glossdef><para>Programming language. See <ulink
	url="http://www.python.org/">http://www.python.org/</ulink>.</para></glossdef>

      </glossentry>

      <glossentry id="xml">

	<glossterm>eXtensible Markup Language (<acronym>XML</acronym>)</glossterm>

	<glossdef><para>Data tagging language defined by the W3C. See <ulink
	url="http://www.w3c.org/XML/">http://www.w3c.org/XML/</ulink>.</para></glossdef>

      </glossentry>

    </glossdiv>

  </glossary>

</book>
