What should functions do?

["Morris, Chuck E (IT)" <chuck.morris@ngc.com>]

Title: What should functions do?

Here are some ideas regarding functions.

- Chuck

Functions should be functional, in the sense that they are side effect free.  This means they can't modify the event board, which means they can't contain any catch or post instructions.  It also means they can't start scriplets, since the scriplets may contain catch or post instructions.  They may have exit (or we may call it return) instructions to allow multiple exit paths, but since they are called from Xpath expressions, the exit will never automatically "bubble up" and cause the calling scriplet or function to exit.  Other eTSM instructions like var, decide, loop, eval, etc. may be used.  Functions can call other functions, or call themselves recursively.  They may call external code, but correct results are not guaranteed unless the external code is side-effect free.

Everything that can be done in a function can be done in a scriplet, but it may be more efficient to use a function when possible because the translation into XSLT is more straightforward.  It also allows optomization, where the cached result from a previous call to the function can be used instead of executing the function again if the parameters are the same.

Another difference is that functions are called from within Xpath expressions rather than with a dedicated eTSM instruction like "start".  This means the parameters are passed by position rather than by name.  Parameters are always passed explicitly.  They can't be omitted, so they can't be assigned a default value  in the function definition code.  However, it is possible to assign the same name to multiple functions as long as they each have a different number of parameters.

Each parameter to the function and its return value should be typed.  Xpath 2 has a complicated type system, but I suggest we should limit it to just a few basic ones, maybe string, number, boolean, node, and QName.

Examples:

<!-- Build an XML name node -->
<etsm:function name="makename" type="node">
  <etsm:param name="first" type="string"/>
  <etsm:param name="last" type="string"/>
  <etsm:param name="initials" type="string"/>
  <etsm:param name="title" type="string"/>

  <name>
     <first><etsm:eval expr="$first"/></first>
     <last><etsm:eval expr="$last"/></last>
     <initials><etsm:eval expr="$initials"/></initials>
     <title><etsm:eval expr="$title"/></title>
  </name>
</etsm:function>

<!-- Given a name node, return a formal representation of the name as a string -->
<etsm:function name="formalname" type="string">
  <etsm:param name="name" type="node"/>
  <etsm:eval expr="concat($name/title, ' ', $name/first, ' ', $name/last)"/>
</etsm:function>

<!-- Given a name node, return a string representation of the name starting with the last name -->
<etsm:function name="lastfirstname" type="string">
  <etsm:param name="name" type="node"/>
  <etsm:eval expr="concat($name/last, ', ', $name/first, ' ', $name/initials)"/>
</etsm:function>