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(const char *expr, int *perrcode, arith_eval_hooks_t *hooks); 13 * 14 * The first 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 second argument is a semi-detailed error description in case something 18 * goes wrong in the parsing steps. 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 third argument is a struct pointer of hooks for your shell (see below). 27 * 28 * The function returns the answer to the expression. So if you called it 29 * with the expression: 30 * "1 + 2 + 3" 31 * You would obviously get back 6. 32 */ 33 34/* To add support to a shell, you need to implement three functions: 35 * 36 * lookupvar() - look up and return the value of a variable 37 * 38 * If the shell does: 39 * foo=123 40 * Then the code: 41 * const char *val = lookupvar("foo"); 42 * Will result in val pointing to "123" 43 * 44 * setvar() - set a variable to some value 45 * 46 * If the arithmetic expansion does something like: 47 * $(( i = 1)) 48 * Then the math code will make a call like so: 49 * setvar("i", "1", 0); 50 * The storage for the first two parameters are not allocated, so your 51 * shell implementation will most likely need to strdup() them to save. 52 * 53 * endofname() - return the end of a variable name from input 54 * 55 * The arithmetic code does not know about variable naming conventions. 56 * So when it is given an experession, it knows something is not numeric, 57 * but it is up to the shell to dictate what is a valid identifiers. 58 * So when it encounters something like: 59 * $(( some_var + 123 )) 60 * It will make a call like so: 61 * end = endofname("some_var + 123"); 62 * So the shell needs to scan the input string and return a pointer to the 63 * first non-identifier string. In this case, it should return the input 64 * pointer with an offset pointing to the first space. The typical 65 * implementation will return the offset of first char that does not match 66 * the regex (in C locale): ^[a-zA-Z_][a-zA-Z_0-9]* 67 */ 68 69/* To make your life easier when dealing with optional 64bit math support, 70 * rather than assume that the type is "signed long" and you can always 71 * use "%ld" to scan/print the value, use the arith_t helper defines. See 72 * below for the exact things that are available. 73 */ 74 75#ifndef SHELL_MATH_H 76#define SHELL_MATH_H 1 77 78PUSH_AND_SET_FUNCTION_VISIBILITY_TO_HIDDEN 79 80#if ENABLE_SH_MATH_SUPPORT_64 81typedef long long arith_t; 82#define arith_t_fmt "%lld" 83#define strto_arith_t strtoull 84#else 85typedef long arith_t; 86#define arith_t_fmt "%ld" 87#define strto_arith_t strtoul 88#endif 89 90typedef const char* FAST_FUNC (*arith_var_lookup_t)(const char *name); 91typedef void FAST_FUNC (*arith_var_set_t)(const char *name, const char *val); 92typedef char* FAST_FUNC (*arith_var_endofname_t)(const char *name); 93 94typedef struct arith_eval_hooks { 95 arith_var_lookup_t lookupvar; 96 arith_var_set_t setvar; 97 arith_var_endofname_t endofname; 98} arith_eval_hooks_t; 99 100arith_t arith(const char *expr, int *perrcode, arith_eval_hooks_t*); 101 102POP_SAVED_FUNCTION_VISIBILITY 103 104#endif 105