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


OS_EvaluateExpression is defined to operate using a number of specified operations. These are unchanged since RISC OS 2 (and possibly earlier). Dependent on their context, the operations are applied to either numbers or 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 dependent 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)
      MOD Modulo (remainder)
      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 :

Return the leaf name from the path specified.
Example : LEAFNAME "ADFS::4.$.Directory.File"
Evaluates to: "File"
Return the directory name from the path specified.
Example : DIRNAME "ADFS::4.$.Directory.File"
Evaluates to: "ADFS::4.$.Directory"
Convert the path specified to its canonical form.
Example : CANONICALISE "ADFS::4.$.Directory.File"
Evaluates to: "ADFS::HardDisc4.$.Directory.File"
Format the current time in the format specified.
Example : TIMEFORMAT "%24-%MI-%SE"
Evaluates to: "18-27-22"
Returns boolean value of whether a system variable is set, -1 if set, 0 if not set.
Example : SET "Not$Set"
Evaluates to : 0
Returns the version number of a module multiplied by 100 or -1 if not present.
Example : MODULEVERSION "WindowManager"
Evaluates to: 607

Change in parsing rules

The operator parsing rules have changed slightly in version 0.13 of the EvaluateExpression module. Previous versions would have given the following sequence of results :

         *set LENGTH 77
         *eval LENGTH
         Unknown operand
         *set GTH 12
         *eval LENGTH
         Result is an integer, value :2
         *eval length
         Result is a string, value :7

That is, the operator prefix on a variable name would always be processed first, even if the operator was completely alphabetically named. The new parser will only treat alphabetic operators as being complete if they are followed by non-alphabetic characters. Thus, the above sequence of commands now produces :

         *set LENGTH 7
         *eval LENGTH
         Result is a string, value :7
         *set GTH 12
         *eval LENGTH
         Result is a string, value :7
         *eval length
         Result is a string, value :7

This is both more obvious and more deterministic. Where developers have used operators in this way in the past it was necessary to insert whitespace between the operator name and its parameter. It is not expected, due to the non-obvious behaviour of such evaluation, that this will cause any problems for the majority of developers.

Practical examples

*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

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015