19 May 2016:   wsurveyEquation.js documentation

   Syntax:
       avalue=wsurvey_doEquation(equationString,lookupFunc )

   Where:
      equationString : a string containing an equation.
      lookupFunc : function object. Optional.

      avalue: will be a numeric value, or a string. Or null if an error occurred.

    The equation string can contain values, variable names, operators, and functions.

   lookupFunc should be a function object (not the function name) that is called as
      aval=lookupFunc(varname,defval)
    which returns a value associated with varname, or defval if varname is not specified

 More on equation:

   Parenthesis can be used to control order of evaluation.

   You can preface values, variables names, etc. with a - sign to indicate "negative value".

   The following operators are recognized:
       +  -  *  /  \ ^  == != > < <= >=  & ` |

        ^ is expoentiation
        \ is modulus division (9%4 = 1)
        & is logical and
        | is logical or
        ` is logical XOR

   The ==, !=, <, >, <=, and >=  are logical operators, and return a 0 (false) or 1 (true).

   The order of precedence is (with left to right precedence for operators in the same set):
       1) variable names
       2) functions and ( ). Note that arguments are processed recursively, using these rules
       3) ^
       4) * / and \
       5) + and -
       6)  == != > < >= and <=
       7) AND OR  and XOR
       8) $+  (string concatentation).

     Note that you can use 2 to 3 letter mnemonics instead ...
                instead of !=  you can use ! or NE
                instead of >=  you can use } or GE
                instead of <=  you can use {  or LE
                instead of >   you can use  GT or }
                instead of <   you can use  LT  or {
                instead of &&  you can use & or AND
                instead of ||  you can use | or OR
                instead of `   you can use XOR
                instead of $+  you can use $

     Note: when using  mnemonics (such as EQ... XOR) : you MUST have a space before and after, but case does NOT matter.

           Example:  ' myCost >= 100 '
                     ' myCost } 100 '
                     ' myCost Ge  100 '

    You can use scientific notation for your values: i.e.;  1003 or 1.003e3 ,  0.04 or 4.0e-2

    If you specified a lookupFunc, variable names can be specified.
      If you do not, then
          *  Two reserved variables can be used: PI and E (case insensitive).
          *  Otherwise, the value of a  global javascript variable is returned.
          *  If no such  global variable, a '' or 0 is returned.
       If you do, lookupFunc is called as:
          lookupFunc(varname,defaultValue)
          and should return a value (perhaps the defaultValue if varname can not be found)

    Note: the mnemonics mentioned above (such as  EQ NE GT LT GE LE AND OR XOR) are reserved -- they can not be used as variable names.

    You can include multiple argument functions. For example:
       ' 1.1e3 * ( -34.04 + myFunc2(109/3 , 5^2) ) '

   You can quote strings (using ' or ").  Quoted strings may contain spaces.
   If you 'quote' a number and use it in normal math calculations, the number will be used.
   If you quote a non-numeric string and use it in normal math calculations, a NaN is returned.

   Functions:
     a limited set of functions are recognized.
        Math.xxx : all the javascript math functions (with arbitrary number of arguments)
        Math.prod : product of arguments
        Math.sum  : sum of arguments
        EXISTS('xx')  : returns 0 or 1 if variable xx exists.
        MISSRV('xx',defval)  : returns value of XX if it exists, otherwise defval
        TRIM(avar)  : trims spaces. If avar is undefined, return ''
        IN(aword,wordList,caseSensitive)  : returns pointer to aword match to word in space delimited wordList (case insensitive by default)
                                           If no match, returns 0 (so if matches first word, returns 1)
                                           If caseSensitive=1, then case sensitive match done
        VAL(aname,defval)  : returns value of element with name=aname, defval if no such element (checkbox and radio button smart!)
        TEXT(aid,defval)  : returns text of element with id=aid (uses jQuery .text() function)
        NOT(equation) : the Not of value returned by equation: 1 if equation returns false of 0, otherwise 0.
        ALERT and CONFIRM and PROMPT  -- javascript functions. Alert will always return 1