blob: 51dbb56cb224fc4966249f5852e15665a348295e [file] [log] [blame]
/* math.h - interface to shell math "library" -- this allows shells to share
* the implementation of arithmetic $((...)) expansions.
* This aims to be a POSIX shell math library as documented here:
* See math.c for internal documentation.
/* The math library has just one function:
* arith_t arith(const char *expr, int *perrcode, arith_eval_hooks_t *hooks);
* The first argument is the math string to parse. All normal expansions must
* be done already. i.e. no dollar symbols should be present.
* The second argument is a semi-detailed error description in case something
* goes wrong in the parsing steps. Currently, those values are (for
* compatibility, you should assume all negative values are errors):
* 0 - no errors (yay!)
* -1 - unspecified problem
* -2 - divide by zero
* -3 - exponent less than 0
* -5 - expression recursion loop detected
* The third argument is a struct pointer of hooks for your shell (see below).
* The function returns the answer to the expression. So if you called it
* with the expression:
* "1 + 2 + 3"
* You would obviously get back 6.
/* To add support to a shell, you need to implement three functions:
* lookupvar() - look up and return the value of a variable
* If the shell does:
* foo=123
* Then the code:
* const char *val = lookupvar("foo");
* Will result in val pointing to "123"
* setvar() - set a variable to some value
* If the arithmetic expansion does something like:
* $(( i = 1))
* Then the math code will make a call like so:
* setvar("i", "1", 0);
* The storage for the first two parameters are not allocated, so your
* shell implementation will most likely need to strdup() them to save.
* endofname() - return the end of a variable name from input
* The arithmetic code does not know about variable naming conventions.
* So when it is given an experession, it knows something is not numeric,
* but it is up to the shell to dictate what is a valid identifiers.
* So when it encounters something like:
* $(( some_var + 123 ))
* It will make a call like so:
* end = endofname("some_var + 123");
* So the shell needs to scan the input string and return a pointer to the
* first non-identifier string. In this case, it should return the input
* pointer with an offset pointing to the first space. The typical
* implementation will return the offset of first char that does not match
* the regex (in C locale): ^[a-zA-Z_][a-zA-Z_0-9]*
/* To make your life easier when dealing with optional 64bit math support,
* rather than assume that the type is "signed long" and you can always
* use "%ld" to scan/print the value, use the arith_t helper defines. See
* below for the exact things that are available.
#ifndef SHELL_MATH_H
#define SHELL_MATH_H 1
typedef long long arith_t;
#define arith_t_fmt "%lld"
#define strto_arith_t strtoll
typedef long arith_t;
#define arith_t_fmt "%ld"
#define strto_arith_t strtol
typedef const char *(*arith_var_lookup_t)(const char *name);
typedef void (*arith_var_set_t)(const char *name, const char *val, int flags);
typedef char *(*arith_var_endofname_t)(const char *name);
typedef struct arith_eval_hooks {
arith_var_lookup_t lookupvar;
arith_var_set_t setvar;
arith_var_endofname_t endofname;
} arith_eval_hooks_t;
arith_t arith(const char *expr, int *perrcode, arith_eval_hooks_t*);