Notice this is the fork of the original rpnlib by @xoseperez
Main differences are:
- Configurable floating point type, can replace
float(old value type) withdouble(new default) - String support in expressions and variables
- Variable manipulation in expressions
RPNlib is a Reverse Polish Notation calculator for ESP8266 & ESP32 microcontrollers.
The library accepts a c-string with commands to execute and provides methods to evaluate the output.
It is meant to be embedded into third party software as a way to provide the user with a simple way of implementing a scripting language.
First, you should familiarize yourself with RPN calculation.
Reverse Polish notation (RPN), also known as Polish postfix notation or simply postfix notation, is a mathematical notation in which operators follow their operands, in contrast to Polish notation (PN), in which operators precede their operands. It does not need any parentheses as long as each operator has a fixed number of operands. The description "Polish" refers to the nationality of logician Jan Łukasiewicz, who invented Polish notation in 1924.
A simple calculation in infix notation might look like this:
( 4 - 2 ) * 5 + 1 =
The same calculation in RPN (postfix) will look like this:
4 2 - 5 * 1 +
It results in a shorter expression since parenthesis are unnecessary. Also the equals sign is not needed since all results are stored in the stack. From the computer point of view is much simpler to evaluate since it doesn't have to look forward for the operands.
The RPNlib is not an object-based (OOP) library but a context-based set of methods. This means you don't instantiate a library object but instead, you create a data context object that is passed along to all methods in the library.
A simple code would be:
- Create the context (where stack, variables and operators are stored)
rpn_context ctxt;- Initialize the context. Loads default operators via
rpn_init(ctxt)orrpn_operators_init(ctxt). Operator functions are not shared between contexts.
rpn_init(ctxt);- Optional Add any required variables.
rpn_value variable { static_cast<rpn_int>(12345) };
rpn_variable_set(ctxt, "variable", variable);- Optional Add a custom operator. Note that operator functions return
rpn_errorobject.
// takes 1 `<integer>` argument and pushes back `<integer> + 5`
rpn_operator_set(ctxt, "operator", 1, [](rpn_context& ctxt) -> rpn_error {
rpn_value value;
rpn_stack_pop(ctxt, value);
value = rpn_value { static_cast<rpn_int>(5) + value.toInt() };
rpn_stack_push(ctxt, value);
return 0; // generic integer success code
});- Process an expression string.
rpn_process(ctxt, "4 2 - 5 * 1 +");- Optional Use variable in the expression
rpn_process(ctxt, "$variable $variable -");- Inspect stack
Serial.printf("Stack size: %zu\n", rpn_stack_size(ctxt));
size_t index = 0;
rpn_stack_foreach(ctxt, [&index](rpn_stack_value::Type, rpn_value& value) { // NOTE: direct access to the stack value object
Serial.printf("Stack level #%u value: %f\n", index++, value.toFloat());
});- Optional Inspect variables
Serial.printf("Variables: %zu\n", rpn_variables_size(ctxt));
size_t index = 0;
rpn_variables_foreach(ctxt, [&index](const String& name, const rpn_value& value) {
Serial.printf("Variable #%u, %s = %f\n", index++, name.c_str(), value.toFloat());
});- Clear the context object. This removes everything on the stack, clears variables and all known operators.
rpn_clear(ctxt);- Tokens are separated by one ore more spaces (ASCII character code
32/ - Every expression is interpretted left-to-right, until the token cannot be parsed.
- When a valid token is found and is not an operator, it is immediately placed on the current stack.
- When a valid token is an operator, function associated with it is immediately called.
- Keyword
nullis reserved for the internal 'Null' type. - Keywords
trueandfalseare reserved for the internal 'Boolean' type. - Numbers in expressions are represented as
rpn_float(configurable type, eitherfloatordouble). - Integer values are represented as
rpn_int, can be used in operators. - Unsigned integer values are represented as
rpn_uint, can be used in operators. - All strings are represented as
String(Arduino class). Strings in expressions are surrounded by double quotation marks.
- Keyword
[creates a new stack. Any expression after that point uses the new stack. Previous stack is kept in memory. - Keyword
]moves all of the current stack contents into a previous one, inserting from the top. After that, appends it's size at the top and destroys the current stack. Any expression after that point uses the previous stack.
- Variable names are complete words, without spaces.
- Variables are accessed by using
$(by value) or&(by reference) before the word. - When variable has not been set yet,
$namewill result in an error. - When variable has not been set yet,
&namewill push it's value reference to the stack with default valueNull - When variable reference is specified multiple times, stack elements refer to the same underlying value.
- When variable value is specified multiple times, stack elements contain copies of the underlying value.
- When variable reference is duplicated using built-in operators, new stack element refers to the same underlying value.
- When variable set to 'Null' is finally removed from the stack it will be removed from the heap too.
- Operator and variable names are case-sensitive.
- Logical operations assume 'Boolean' and will cast every other type into it. Numeric values not equal to 0 are
true, andfalseotherwise. - All operators will throw an error if the number of available elements in the stack is less than the expected value.
- Some operators may throw an error when given argument type does not match the expected type
- Some operators may return different results depending on the type of elements.
- Some operators perform an automatic cast of the elements taken from the stack.
| Name | Stack operation | Description |
|---|---|---|
+ |
( a b -- c ) | sum a and b (when a and b types are different, convers b type into the type of a before doing the operation) |
- |
( a b -- c ) | subtract b from a |
* |
( a b -- c ) | multiply b by a |
/ |
( a b -- c ) | divide a by b (ends execution if b equals 0) |
mod |
( a b -- c ) | remainder of the division of b by a |
abs |
( a -- b ) | absolute value of the a (integer or float) |
round |
( a n -- b ) | round a (float) to the n-th decimal |
ceil |
( a -- b ) | b is the smallest integral value not less than a |
floor |
( a -- b ) | b is the largest integral value not greater than a |
int |
( a -- b ) | alias for "floor" |
eq |
( a b -- c ) | put true (boolean) on the stack when a equals to b, false (boolean) otherwise |
ne |
( a b -- c ) | a is not equal to b |
gt |
( a b -- c ) | a is greater than b |
ge |
( a b -- c ) | a is greater than or equal to b |
lt |
( a b -- c ) | a is less than b |
le |
( a b -- c ) | a is less than or equal to b |
cmp |
( a b -- c ) | c (integer) is -1 if a<b, 0 if a==b and 1 if a>b |
cmp3 |
( a b c -- d ) | d (integer) is -1 if a<b, 1 if a>c and 0 if equals to b or c or in the middle |
index |
( a v1 v2 ... b -- c ) | returns the a-nth value from the v# list, b is the number of values in the v# list. also accepts the result of ] as list's length |
map |
( a b c d e -- f ) | performs a rule of 3 mapping of the value a (number) which goes from b to c to d to e |
constrain |
(a b c -- d) | ensures a is between the range of b and c (inclusive) |
and |
( a b -- c ) | logical operation on the stack |
or |
( a b -- c ) | |
xor |
( a b -- c ) | only one of a or b can be converted into boolean true |
not |
( a -- b ) | |
dup |
( a -- a a ) | (note that references are duplicated instead of the values themselves) |
dup2 |
( a b -- a b a b ) | |
swap |
( a b -- b a ) | |
rot |
( a b c -- b c a ) | |
unrot |
( a b c -- c a b ) | |
drop |
( a -- ) | |
over |
( a b -- a b a ) | |
depth |
( -- n ) | where n (unsigned) is the number of elements on the stack |
exists |
(&var -- &var) | ends execution if var isn't an active variable |
deref |
(&var -- $var) | takes the value from var and copies it on the stack |
= |
( a &var -- &var ) | sets var to the value of a and keeps var reference on the stack |
ifn |
( a b c -- b or c ) | if a (boolean) is true, keeps b on the stack. otherwise, keeps c |
end |
( a -- ) | ends execution if a (boolean) is false |
Some operators are used in place of constant variables:
| Name | Stack operation | Description |
|---|---|---|
pi |
( -- a ) | where a (float) is the value of PI |
e |
( -- a ) | where a (float) is the value of e (base of the Napierian (Naperian) logarithm) |
inf |
( -- a ) | where a (float) is the value of floating point inf |
nan |
( -- a ) | where a (float) is the value of floating point quiet NaN |
In addition, when using RPNLIB_ADVANCED_MATH flag, these operators are available for floating point numbers:
| Name | Stack operation | Description |
|---|---|---|
sqrt |
( a -- b ) | where b is the square root of a (note: ends execution when a is not float) |
log |
( a -- b ) | where b is the log of a |
log10 |
( a -- b ) | where b is the log10 of a |
exp |
( a -- b ) | where b is exponential power of a (e^a) |
fmod |
( a b -- c ) | where c is the reminder of the a/b division |
pow |
( a b -- c ) | where c is a power b |
cos |
( a -- b ) | where b is cos(a). a is specified in radians |
sin |
( a -- b ) | where b is sin(a). a is specified in radians |
tan |
( a -- b ) | where b is tan(a). a is specified in radians |
To upload a new release:
$ # modify library.* to include a new version
$ git add library.*
$ git commit -m "Version $VERSION"
$ git tag -a -m $VERSION $VERSION
$ git push --follow-tagsCopyright (C) 2018-2019 by Xose Pérez
Copyright (C) 2020 by Maxim Prokhorov
The rpnlib library is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
The rpnlib library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with the rpnlib library. If not, see http://www.gnu.org/licenses/.