shell/math.h

   1 /* math.h - interface to shell math "library" -- this allows shells to share
   2  *          the implementation of arithmetic $((...)) expansions.
   3  *
   4  * This aims to be a POSIX shell math library as documented here:
   5  *      http://www.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_04
   6  *
   7  * See math.c for internal documentation.
   8  */
   9
  10 /* The math library has just one function:
  11  *
  12  * arith_t arith(arith_state_t *states, const char *expr);
  13  *
  14  * The expr argument is the math string to parse.  All normal expansions must
  15  * be done already.  i.e. no dollar symbols should be present.
  16  *
  17  * The state argument is a pointer to a struct of hooks for your shell (see below),
  18  * and a semi-detailed error code. Currently, those values are (for
  19  * compatibility, you should assume all negative values are errors):
  20  * 0 - no errors (yay!)
  21  * -1 - unspecified problem
  22  * -2 - divide by zero
  23  * -3 - exponent less than 0
  24  * -5 - expression recursion loop detected
  25  *
  26  * The function returns the answer to the expression.  So if you called it
  27  * with the expression:
  28  * "1 + 2 + 3"
  29  * you would obviously get back 6.
  30  */
  31
  32 /* To add support to a shell, you need to implement three functions:
  33  *
  34  * lookupvar() - look up and return the value of a variable
  35  *
  36  *      If the shell does:
  37  *              foo=123
  38  *      Then the code:
  39  *              const char *val = lookupvar("foo");
  40  *      will result in val pointing to "123"
  41  *
  42  * setvar() - set a variable to some value
  43  *
  44  *      If the arithmetic expansion does something like:
  45  *              $(( i = 1))
  46  *      then the math code will make a call like so:
  47  *              setvar("i", "1", 0);
  48  *      The storage for the first two parameters are not allocated, so your
  49  *      shell implementation will most likely need to strdup() them to save.
  50  *
  51  * endofname() - return the end of a variable name from input
  52  *
  53  *      The arithmetic code does not know about variable naming conventions.
  54  *      So when it is given an experession, it knows something is not numeric,
  55  *      but it is up to the shell to dictate what is a valid identifiers.
  56  *      So when it encounters something like:
  57  *              $(( some_var + 123 ))
  58  *      It will make a call like so:
  59  *              end = endofname("some_var + 123");
  60  *      So the shell needs to scan the input string and return a pointer to the
  61  *      first non-identifier string.  In this case, it should return the input
  62  *      pointer with an offset pointing to the first space.  The typical
  63  *      implementation will return the offset of first char that does not match
  64  *      the regex (in C locale): ^[a-zA-Z_][a-zA-Z_0-9]*
  65  */
  66
  67 /* To make your life easier when dealing with optional 64bit math support,
  68  * rather than assume that the type is "signed long" and you can always
  69  * use "%ld" to scan/print the value, use the arith_t helper defines.  See
  70  * below for the exact things that are available.
  71  */
  72
  73 #ifndef SHELL_MATH_H
  74 #define SHELL_MATH_H 1
  75
  76 PUSH_AND_SET_FUNCTION_VISIBILITY_TO_HIDDEN
  77
  78 #if ENABLE_SH_MATH_SUPPORT_64
  79 typedef long long arith_t;
  80 #define arith_t_fmt "%lld"
  81 #define strto_arith_t strtoull
  82 #else
  83 typedef long arith_t;
  84 #define arith_t_fmt "%ld"
  85 #define strto_arith_t strtoul
  86 #endif
  87
  88 /* ash's and hush's endofname is the same, so... */
  89 # define is_name(c)      ((c) == '_' || isalpha((unsigned char)(c)))
  90 # define is_in_name(c)   ((c) == '_' || isalnum((unsigned char)(c)))
  91 const char* FAST_FUNC endofname(const char *name);
  92
  93 typedef const char* FAST_FUNC (*arith_var_lookup_t)(const char *name);
  94 typedef void        FAST_FUNC (*arith_var_set_t)(const char *name, const char *val);
  95 //typedef const char* FAST_FUNC (*arith_var_endofname_t)(const char *name);
  96
  97 typedef struct arith_state_t {
  98         arith_var_lookup_t    lookupvar;
  99         arith_var_set_t       setvar;
 100 //      arith_var_endofname_t endofname;
 101         int                   errcode;
 102 } arith_state_t;
 103
 104 arith_t arith(arith_state_t *state, const char *expr);
 105
 106 POP_SAVED_FUNCTION_VISIBILITY
 107
 108 #endif