EvaluateExpression
==================

Introduction and Overview
-------------------------

The EvaluateExpression module provides the SWI OS_EvaluateExpression. This
call attempts to calculate the value of the string passed to it. Although
the SWI itself is not normally used by the programmer, its effects are seen
most commonly through the *SetEval and *If commands.

Technical details
-----------------

Operators

OS_EvaluateExpression is defined to operate using a number of defined
operations. These are unchanged since RISC OS 2 (and possibly earlier).
Dependant on their context, the operations are applied to either numbers of
strings, with the preference being for string operations.

 ( )      Grouping operators, applied using correct mathematical precedence
 - * /    Arithmetic operators
 +        Arithmetic operator, or if used on strings a concatenation operator
 =        Equality (either numeric or string dependant on its context, the
                    same condition applies to all the comparison operators)
 <>       Inequality
 <        Less than
 >        Greater than
 <=       Less than or equal to
 >=       Greater than or equal to
 >>>      Logical shift right (ignores sign)
 >>       Arithmetic shift right (sign extending)
 <<       Shift left (arithmetic shift and logical shift are the same)
 AND      Logical AND (both conditions must be true)
 OR       Logical OR (either condition may be true)
 EOR      Logical exclusive OR (one or the other may be true, but not both)
 NOT      Negate (inverts the bitpattern of a number)
 RIGHT    Obtain the rightmost characters from a string
 LEFT     Obtain the leftmost characters from a string
 STR      Convert a number to a string
 VAL      Convert a string to a number
 LEN      Find the length of a string
 
In addition, the EvaluateExpression module also provides a number of
extensions to these operators :
  LEAFNAME
     Return the leaf name from the path specified.
     Example:       LEAFNAME "ADFS::4.$.Directory.File"
     Evaluates to:  "File"
  DIRNAME
     Return the directory name from the path specified.
     Example:       DIRNAME "ADFS::4.$.Directory.File"
     Evaluates to:  "ADFS::4.$.Directory"
  CANONICALISE
     Convert the path specified to its canonical form.
     Example:       CANONICALISE "ADFS::4.$.Directory.File"
     Evaluates to:  "ADFS::HardDisc4.$.Directory.File"
  TIMEFORMAT
     Format the current time in the format specified.
     Example:       TIMEFORMAT "%24-%MI-%SE"
     Evaluates to:  "18-27-22"


Practical example:

  *SetEval Obey$AppName (LEAFNAME Obey$Dir) RIGHT (LEN (LEAFNAME Obey$Dir)-1)
  
  | Obey file 'which'
  IfThere Run:%0 Then SetEval Which CANONICALISE "Run:%0" Else Set Which Not on run path
  Echo <Which>
  Unset Which
