RPN Engine Guide

Revised: 2011-04-09.


Table of Contents

Introduction
Words
Basic Operations
'<text>' (string constant)
"<text>" (string constant)
<number> (numeric constant)
$<position> (input value)
$<position>! (required input value)
$<position>$ (input state)
$<position>@ (input stamp)
$<position>. (input point name)
$<position>? (input value present?)
$<position>= (input value replacement)
:$<position>= (input value replacement)
$* (all input values)
$*! (all input values required)
$# (inputs count)
$0 (result value)
$0! (required result value)
$0= (result value replacement)
:$0= (result value replacement)
$0$ (result state)
$0$= (result state replacement)
:$0$= (result state replacement)
$0@ (result stamp)
$0. (result point name)
#<location> (memory value)
#<location>= (memory value replacement)
:$#<location>= (memory value replacement)
@<position> (parameter value)
@<position>! (required parameter value)
bpt (breakpoint opportunity)
deleted? (deleted state?)
fail
nop
! (required value)
return (program end)
stored (stored result value)
stored! (required stored result value)
stored? (result value stored?)
type (object type)
Stack Operations
: or dup (duplicate top entry)
[ or mark (partition stack)
] or unmark (join top stack partitions)
at (value from a stack position)
clear (clear stack)
copy (copy stack values)
default (default value)
depth (stack depth)
depth* (whole stack depth)
drop (stack item drop)
dump (stack dump)
dump* (whole stack dump)
eq (equal)
ne (not equal)
nip (drop next)
null (push null)
null? (top is null)
unmark* (join all stack partitions)
DateTime Operations
- (substraction)
+ (addition)
day (day of month)
--day (previous day)
++day (next day)
-days (days substraction)
+days (days addition)
dim (days in month)
dow (day of week)
hour (hour of day)
--hour (previous hour)
++hour (next hour)
_hour (floor the hour)
~hour (round the hour)
hours (convert hours)
join (join date_time fields)
midnight
milli (millisecond of second)
--milli (previous millisecond)
++milli (next millisecond)
_milli (floor the millisecond)
~milli (round the millisecond)
millis (convert milliseconds)
minute (minute of hour)
--minute (previous minute)
++minute (next minute)
_minute (floor the minute)
~minute (round the minute)
minutes (convert minutes)
mjd (convert to date_time)
month (month of year)
--month (previous month)
++month (next month)
-months (substract months)
+months (add months)
noon
now
raw
second (second of minute)
--second (previous second)
++second (next second)
_second (floor the second)
~second (round the second)
seconds (convert seconds)
split (split date_time)
today
tomorrow
tz
year
--year (previous year)
++year (next year)
-years (substract years)
+years (add years)
yesterday
Double Operations
0? (is zero?)
0~? (is near zero?)
0+? (is zero or more?)
0-? (is zero or less?)
abs (absolute value)
acos (arc cosine)
+ (add)
asin (arc sine)
atan (arc tangent)
cbrt (cube root)
ceil (ceiling)
cos (cosine)
cosh (hyperbolic cosine)
deg (conversion to degrees)
/ (divide)
/% (divide with remainder)
e
eq (equal)
eq~ (near equal)
float
float?
floor
ge (greater or equal)
gt (greater)
hypot
inf?
+inf
-inf
le (less or equal)
log (natural logarithm)
log10 (base 10 logarithm)
lt (less)
max (maximum)
min (minimum)
* (multiply)
nan
nan?
ne (not equal)
neg (negative)
number?
pi
** (power)
rad (conversion to radians)
% (remainder)
round
sin (sine)
sinh (hyperbolic sine)
sqrt (square root)
- (substract)
tan (tangent)
tanh (hyperbolic tangent)
Long Operations
0? (is zero?)
0+? (is zero or more?)
0-? (is zero or less?)
abs (absolute value)
+ (add)
and (binary and)
/ (divide)
/% (divide with remainder)
-- (decrement)
eq (equal)
float
ge (greater or equal)
gt (greater)
++ (increment)
int
int?
le (less or equal)
lshft (left shift)
lt (less)
max (maximum)
min (minimum)
* (multiply)
ne (not equal)
neg (negative)
not (complement)
or (binary or)
% (remainder)
rshft (right shift)
rshftz (right shift zero fill)
- (substract)
xor (binary exclusive or)
Boolean Operations
?: (conditional value)
and
assert
bool
false
false!
not
or
true
true!
xor
String Operations
+ (concatenate)
debug (debug log)
empty?
error (error log)
format
format*
info (info log)
lower (lower case)
str (string conversion)
str?
substring
trim
upper (upper case)
warn (warn log)
Compound Operations
{ (begin)
} (end)
break
continue
do
if
reduce
#reduce
try
unless
while
Container Operations
append
apply
container?
dict
dict?
entries
get
keys
put
remove
size
tuple
tuple?
values
Configuration

Introduction

The RPN engine implements a mini language to help transform some input values into a result value. It is inspired by the Forth language.

A RPN (Reverse Polish Notation, also known as Postfix notation) program makes operators follow their operands.

Example:

2 3 +

produces 5.

Most Forth implementations use a stack to hold operands and results; so does the RPN engine.

In the previous example, the words '2' and '3' put their values on the stack; the '+' word then pops out the two top values from the stack and pushes back their sum.

As an other example, to compute ((2 + 3) * 4), one can use:

2 3 + 4 *

or

4 2 3 + *

to produce 20.

Words

The following sections describe the RPN engine words by module.

Since each module may overload a word definition implemented by a previously registered module, their order is significant; here, they are described in their usual registration order .

Each word description begins with a synopsis (inside parenthesis) of its effect on the RPN stack: the items on the left of the '--' mark represent the top of the stack before, those on the right represent the top of the stack after.

Basic Operations

The BasicOperations module is not optional and does not need to be configured.

'<text>' (string constant)

( -- string )

Pushes the <text> as a String. The usual escape conventions using backslash can be used.

"<text>" (string constant)

( -- string )

Pushes the <text> as a String. The usual escape conventions using backslash can be used.

<number> (numeric constant)

( -- number )

Any word that can be decoded as a Long according to Java conventions is taken as such; otherwise, a conversion to Double is attempted; if it fails, the word is looked up in the words registry. The result of the conversion of <number> is pushed on the stack.

$<position> (input value)

( -- value )

The value of the input declared at the origin-1 <position> for the result point is pushed on the stack.

$<position>! (required input value)

( -- value )

If present and not null, the value of the input declared at the origin-1 <position> for the result point is pushed on the stack; otherwise, the operation fails.

$<position>$ (input state)

( -- state )

The state of the input declared at the origin-1 <position> for the result point is pushed on the stack.

$<position>@ (input stamp)

( -- stamp )

The time stamp of the input declared at the origin-1 <position> for the result point is pushed on the stack.

$<position>. (input point name)

( -- name )

The name of the point for the input declared at the origin-1 <position> for the result point is pushed on the stack.

$<position>? (input value present?)

( -- boolean )

The value of the input declared at the origin-1 <position> for the result point is pushed on the stack.

$<position>= (input value replacement)

( value -- )

Pops a value from the stack and stores it as a replacement for the value for the input declared at the origin-1 <position> for the result point.

:$<position>= (input value replacement)

( value -- value )

Stores the value at the top of the stack as a replacement for the value for the input declared at the origin-1 <position> for the result point.

$* (all input values)

( -- ... )

The value for all the inputs declared for the result point are pushed on the stack (last on top).

$*! (all input values required)

( -- ... )

The value for all the inputs declared for the result point are pushed on the stack (last on top). If any of those inputs is absent or null, the operation will fail.

$# (inputs count)

( -- count )

Pushes the number of declared inputs on the stack.

$0 (result value)

( -- value )

The value of the result is pushed on the stack.

$0! (required result value)

( -- value )

If not null, the value of the result is pushed on the stack; otherwise, the operation fails.

$0= (result value replacement)

( value -- )

Pops a value from the stack and stores it as a replacement for the value of the result.

:$0= (result value replacement)

( value -- value )

Stores the value at the top of the stack as a replacement for the value of the result.

$0$ (result state)

( -- state )

The state of the result is pushed on the stack.

$0$= (result state replacement)

( value -- )

Pops a value from the stack and stores it as a replacement for the state of the result.

:$0$= (result state replacement)

( value -- value )

Stores the value at the top of the stack as a replacement for the state of the result.

$0@ (result stamp)

( -- stamp )

The time stamp of the result is pushed on the stack.

$0. (result point name)

( -- name )

The name of the result point is pushed on the stack.

#<location> (memory value)

( -- value )

The value of the origin-1 memory <location> is pushed on the stack.

#<location>= (memory value replacement)

( value -- )

Pops a value from the stack and stores it as a replacement for the value fof the origin-1 memory <location>.

:$#<location>= (memory value replacement)

( value -- value )

Stores the value at the top of the stack as a replacement for the value of the origin-1 memory <location>.

@<position> (parameter value)

( -- value )

The value of the result point parameter at the origin-1 <position> is pushed on the stack.

@<position>! (required parameter value)

( -- value )

If present and not null, the value of the result point parameter at the origin-1 <position> is pushed on the stack; otherwise, the operation fails.

bpt (breakpoint opportunity)

( -- )

Does nothing but provides a breakpoint opportunity for debugging the engine.

deleted? (deleted state?)

( state -- boolean )

If the object popped from the stack is the deleted state object, push true; otherwise, push false.

fail

( -- )

Fails.

nop

( -- )

Does nothing.

! (required value)

( value -- )

Fails if the object popped from the stack is null.

return (program end)

( -- )

Ends execution of operations for the current program.

stored (stored result value)

( -- value )

The stored value of the result is pushed on the stack.

stored! (required stored result value)

( -- value )

If available and not null, the stored value of the result is pushed on the stack.; otherwise, the operation fails.

stored? (result value stored?)

( -- boolean )

If the result value is stored, push true, otherwise, push false.

type (object type)

( x -- type )

Pushes the name of the class of the object popped from the stack.

Stack Operations

The StackOperations module provides generic stack operations.

This module supports transparent stack partitioning using marks.

: or dup (duplicate top entry)

( x -- x x )

Duplicates the top entry on the stack..

Example:

1.0 2.0 dup

leaves 1.0 2.0 2.0 on the stack.

[ or mark (partition stack)

( -- )

Starts a new stack partition.

] or unmark (join top stack partitions)

( -- )

Joins the two top stack partitions. Does nothing if the stack is not partitioned.

at (value from a stack position)

( ... position -- ... value )

Pops from the stack a number representing an origin-0 position, starting from the top of the stack. The object at this position is pushed on the stack .

Example:

1.0 2.0 3.0 4.0 2 at

leaves 1.0 2.0 3.0 4.0 3.0 on the stack.

clear (clear stack)

( ... depth -- )

Pops from the stack the number of stack locations to drop, then drops them from the stack.

Example:

1.0 2.0 3.0 2 clear

leaves 1.0 on the stack.

copy (copy stack values)

( ... depth -- ... ... )

Pops from the stack the number of stack locations to copy, then pushes them on the stack.

Example:

1.0 2.0 3.0 2 copy

leaves 1.0 2.0 3.0 2.0 3.0 on the stack.

default (default value)

( value default -- )

Pops a default value from the stack, then if the top of the stack is null, replaces it by the default value.

Example:

$1 0.0 default

gets the first input if it is present and not null, otherwise leaves 0.0 on the stack.

depth (stack depth)

( -- depth )

Pushes on the stack the number of entries in the top stack partition.

Example:

1.0 [ 2.0 3.0 depth copy

leaves 1.0 2.0 3.0 2.0 3.0 on the stack.

depth* (whole stack depth)

( -- depth )

Pushes on the stack the number of entries in the whole top stack.

Example:

1.0 [ 2.0 3.0 depth* clear

leaves nothing on the stack.

drop (stack item drop)

( x -- )

Drops the top item on the stack.

Example:

1.0 2.0 drop

leaves 1.0 on the stack.

dump (stack dump)

( -- )

List in the log the content of the top stack partition.

dump* (whole stack dump)

( -- )

List in the log the content of the whole stack.

eq (equal)

( x y -- y==x )

Replaces the two top stack entries with the boolean result of the top one being equal to the next.

Example:

1.0 2.0 eq

leaves false on the stack.

ne (not equal)

( x y -- y!=x )

Replaces the two top stack entries with the boolean result of the top one not being equal to the next.

Example:

1.0 2.0 ne

leaves true on the stack.

nip (drop next)

( x y -- y )

Drops the second entry from the top of the stack.

Example:

1.0 2.0 nip

leaves 2.0 on the stack.

null (push null)

( -- null )

Places a null value on the stack.

null? (top is null)

( x -- x==null )

Replaces the top stack entry with the boolean result of its comparison with null.

unmark* (join all stack partitions)

( -- )

Joins all the stack partitions. Does nothing if the stack is not partitioned.

DateTime Operations

The DateTimeOperations module provides operations on DateTime objects and their derivatives.

- (substraction)

( elapsed_1 elapsed_2 -- elapsed_1-elapsed_2:elapsed )
( date_time elapsed -- date_time-elapsed:date_time )
( date_time_1 date_time_2 -- date_time_1-date_time_2:elapsed )

This operation is overloaded within the module. Depending on the type of the top two objects on the stack, it will substract Elapsed times and produce an Elapsed time, substract an Elapsed time from a DateTime to product a DateTime or substracts DateTimes to produce an Elapsed time.

Example:

"2000-02-01 12:30:10.5" mjd 2 hours - str

leaves "2000-02-01T10:30:10.5-05" on the stack (in the Montreal timezone).

+ (addition)

( elapsed_1 elapsed_2 -- elapsed_1+elapsed_2:elapsed )
( date_time elapsed -- date_time+elapsed:date_time )

This operation is overloaded within the module. Depending on the type of the top two objects on the stack, it will add Elapsed times and produce an Elapsed time or add an Elapsed time to a DateTime to product a DateTime.

Example:

"2000-02-01 12:30:10.5" mjd 2 hours + str

leaves "2000-02-01T14:30:10.5-05" on the stack (in the Montreal timezone).

day (day of month)

( date_time -- day_of_month )

Replaces the DateTime with its day of the month origin-1 number.

Example:

"2000-02-01 12:30:10.5" mjd day

leaves 1 on the stack.

--day (previous day)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time on the previous day.

Example:

"2000-02-01 12:30:10.5" mjd --day str

leaves "2000-01-31T12:30:10.5-05" on the stack (in the Montreal timezone).

++day (next day)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time on the next day.

Example:

"2000-02-01 12:30:10.5" mjd ++day str

leaves "2000-02-02T12:30:10.5-05" on the stack (in the Montreal timezone).

-days (days substraction)

( date_time days -- date_time-days:date_time )

Pops a number and use it to replace the DateTime with a new one representing the same time when going back this number of days.

Example:

"2000-02-01 12:30:10.5" mjd 2 -days str

leaves "2000-01-30T12:30:10.5-05" on the stack (in the Montreal timezone).

+days (days addition)

( date_time days -- date_time+days:date_time )

Pops a number and use it to replace the DateTime with a new one representing the same time when going forward this number of days.

Example:

"2000-02-01 12:30:10.5" mjd 2 +days str

leaves "2000-02-03T12:30:10.5-05" on the stack (in the Montreal timezone).

dim (days in month)

( date_time -- days_in_month )

Replaces the DateTime with the number of days in its month.

Example:

"2000-02-01 12:30:10.5" mjd dim

leaves 29 on the stack.

dow (day of week)

( date_time -- day_of_week )

Replaces the DateTime with its origin-0 day of week.

Example:

"2000-02-01 12:30:10.5" mjd dow

leaves 2 (Tuesday) on the stack.

hour (hour of day)

( date_time -- hour_of_day )

Replaces the DateTime with its hour of day number.

Example:

"2000-02-01 12:30:10.5" mjd hour

leaves 12 on the stack.

--hour (previous hour)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the previous hour.

Example:

"2000-02-01 12:30:10.5" mjd --hour str

leaves "2000-02-01T11:30:10.5-05" on the stack (in the Montreal timezone).

++hour (next hour)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the next hour.

Example:

"2000-02-01 12:30:10.5" mjd ++hour str

leaves "2000-02-01T13:30:10.5-05" on the stack (in the Montreal timezone).

_hour (floor the hour)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at the beginning of the hour.

Example:

"2000-02-01 12:30:10.5" mjd _hour str

leaves "2000-02-01T12:00-05" on the stack (in the Montreal timezone).

~hour (round the hour)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at a rounded value for the hour.

Example:

"2000-02-01 12:30:10.5" mjd ~hour str

leaves "2000-02-01T13:00-05" on the stack (in the Montreal timezone).

hours (convert hours)

( elapsed -- hours:double )
( hours:double -- elapsed )
( date_time -- hours:double )

This operation is overloaded within the module. Depending on the type of the top object on the stack, it will convert an ElapsedTime to hours, convert hours to an ElapsedTime or convert a DateTime to hours since 1858-11-17 00:00 UTC.

Example:

2 hours str

leaves "0T02:00" on the stack.

join (join date_time fields)

( year month day hour minute second:double -- date_time )

This operation will join year, month, day, hour, minute and second (to the millisecond) into a DateTime.

Example:

2000 02 01 12 30 10.5 join str

leaves "2000-02-01 12:30:10.5" on the stack (in the Montreal timezone).

midnight

( date_time -- date_time )

Replaces the DateTime with a new one representing the same day at midnight.

Example:

"2000-02-01 12:30:10.5" mjd midnight str

leaves "2000-02-01T00:00-05" on the stack (in the Montreal timezone).

milli (millisecond of second)

( date_time -- milli_second )

Replaces the DateTime with the millisecond within the second.

Example:

"2000-02-01 12:30:10.5" mjd milli

leaves 500 on the stack.

--milli (previous millisecond)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the previous millisecond.

Example:

"2000-02-01 12:30:10.5" mjd --milli str

leaves "2000-02-01T11:30:10.499-05" on the stack (in the Montreal timezone).

++milli (next millisecond)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the next millisecond.

Example:

"2000-02-01 12:30:10.5" mjd ++milli str

leaves "2000-02-01T13:30:10.501-05" on the stack (in the Montreal timezone).

_milli (floor the millisecond)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at the beginning of the millisecond.

Example:

"2000-02-01 12:30:10.5678" mjd _milli str

leaves "2000-02-01T12:30:10.567-05" on the stack (in the Montreal timezone).

~milli (round the millisecond)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at a rounded value for the millisecond.

Example:

"2000-02-01 12:30:10.5678" mjd ~milli str

leaves "2000-02-01T13:30.10.568-05" on the stack (in the Montreal timezone).

millis (convert milliseconds)

( elapsed -- millis:double )
( millis:double -- elapsed )
( date_time -- millis:double )

This operation is overloaded within the module. Depending on the type of the top object on the stack, it will convert an ElapsedTime to milliseconds, convert milliseconds to an ElapsedTime or convert a DateTime to milliseconds since 1858-11-17 00:00 UTC.

Example:

2 millis - str

leaves "0T00:00:00.002" on the stack.

minute (minute of hour)

( date_time -- minute_of_hour )

Replaces the DateTime with its minute of the hour number.

Example:

"2000-02-01 12:30:10.5" mjd minute

leaves 30 on the stack.

--minute (previous minute)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the previous minute.

Example:

"2000-02-01 12:30:10.5" mjd --minute str

leaves "2000-02-01T12:29:10.5-05" on the stack (in the Montreal timezone).

++minute (next minute)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the next minute.

Example:

"2000-02-01 12:30:10.5" mjd ++minute str

leaves "2000-02-01T12:31:10.5-05" on the stack (in the Montreal timezone).

_minute (floor the minute)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at the beginning of the minute.

Example:

"2000-02-01 12:30:10.5" mjd _minute str

leaves "2000-02-01T12:30-05" on the stack (in the Montreal timezone).

~minute (round the minute)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at a rounded value for the minute.

Example:

"2000-02-01 12:30:10.5" mjd ~minute str

leaves "2000-02-01T12:30-05" on the stack (in the Montreal timezone).

minutes (convert minutes)

( elapsed -- minutes:double )
( minutes:double -- elapsed )
( date_time -- minutes:double )

This operation is overloaded within the module. Depending on the type of the top object on the stack, it will convert an ElapsedTime to minutes, convert minutes to an ElapsedTime or convert a DateTime to minutes since 1858-11-17 00:00 UTC.

Example:

2 minutes - str

leaves "0T00:02" on the stack.

mjd (convert to date_time)

( elapsed -- date_time )
( raw -- date_time )
( string -- date_time )

This operation is overloaded within the module. Depending on the type of the top object on the stack, it will convert an ElapsedTime, a raw value or a String to a DateTime.

Example:

"2000-02-01 12:30:10.5" mjd str

leaves "2000-02-01T12:30:10.5-05" on the stack (in the Montreal timezone).

month (month of year)

( date_time -- month_of_year )

Replaces the DateTime with its month of the year number (1-12).

Example:

"2000-02-01 12:30:10.5" mjd month

leaves 2 on the stack.

--month (previous month)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the previous month.

Example:

"2000-02-01 12:30:10.5" mjd --month str

leaves "2000-01-01T12:30:10.5-05" on the stack (in the Montreal timezone).

++month (next month)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the next month.

Example:

"2000-02-01 12:30:10.5" mjd ++month str

leaves "2000-03-01T12:30:10.5-05" on the stack (in the Montreal timezone).

-months (substract months)

( date_time months -- date_time )

Pops a number of months and the DateTime and pushes a new DateTime at the number of months before the original.

Example:

"2000-02-01 12:30:10.5" mjd 2 -months str

leaves "1999-12-01T12:30:10.5-05" on the stack (in the Montreal timezone).

+months (add months)

( date_time months -- date_time )

Pops a number of months and the DateTime and pushes a new DateTime at the number of months before the original.

Example:

"2000-02-01 12:30:10.5" mjd 2 +months str

leaves "2000-04-01T12:30:10.5-05" on the stack (in the Montreal timezone).

noon

( date_time -- date_time )

Replaces the DateTime with a new one representing the same day at noon.

Example:

"2000-02-01 12:30:10.5" mjd noon str

leaves "2000-02-01T12:00-05" on the stack (in the Montreal timezone).

now

( -- date_time )

Pushes the current system time as a DateTime.

raw

( date_time -- raw )

Replaces the DateTime with its raw (internal) representation (the number of tenths of microseconds since 1858-11-17 00:00 UTC).

Example:

"2000-02-01 12:30:10.5" mjd raw

leaves 44561430105000000 on the stack (in the Montreal timezone).

second (second of minute)

( date_time -- second_of_minute )

Replaces the DateTime with its second of the minute number.

Example:

"2000-02-01 12:30:10.5" mjd second

leaves 10 on the stack.

--second (previous second)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the previous second.

Example:

"2000-02-01 12:30:10.5" mjd --second str

leaves "2000-02-01T12:30:09.5-05" on the stack (in the Montreal timezone).

++second (next second)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the next second.

Example:

"2000-02-01 12:30:10.5" mjd ++second str

leaves "2000-02-01T12:30:11.5-05" on the stack (in the Montreal timezone).

_second (floor the second)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at the beginning of the second.

Example:

"2000-02-01 12:30:10.5" mjd _second str

leaves "2000-02-01T12:30:10-05" on the stack (in the Montreal timezone).

~second (round the second)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time at a rounded value for the second.

Example:

"2000-02-01 12:30:10.5" mjd ~second str

leaves "2000-02-01T12:30:11-05" on the stack (in the Montreal timezone).

seconds (convert seconds)

( elapsed -- seconds:double )
( seconds:double -- elapsed )
( date_time -- seconds:double )

This operation is overloaded within the module. Depending on the type of the top object on the stack, it will convert an ElapsedTime to seconds, convert seconds to an ElapsedTime or convert a DateTime to seconds since 1858-11-17 00:00 UTC.

Example:

2 seconds - str

leaves "0T00:00:02" on the stack.

split (split date_time)

( elapsed -- days hours minutes seconds:double )
( date_time -- year month day hour minute second:double )

This operation is overloaded within the module. Depending on the type of the top object on the stack, it will split an ElapsedTime to days, hours, minutes and seconds, or split a DateTime to year, month, day, hour, minute and second (to the millisecond).

Example:

"2000-02-01 12:30:10.5" mjd split

leaves 2000 02 01 12 30 10.5 on the stack.

today

( -- date_time )

Pushes the value of midnight based on the current system time as a DateTime.

tomorrow

( -- date_time )

Pushes the value of tomorrow at midnight based on the current system time as a DateTime.

tz

( string -- )

Sets the time zone for the current computation.

Example:

"GMT" tz

sets the time zone to GMT.

year

( date_time -- year )

Replaces the DateTime with its year number.

Example:

"2000-02-01 12:30:10.5" mjd year

leaves 2000 on the stack.

--year (previous year)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the previous year.

Example:

"2000-02-01 12:30:10.5" mjd --year str

leaves "1999-02-01T12:30:10.5-05" on the stack (in the Montreal timezone).

++year (next year)

( date_time -- date_time )

Replaces the DateTime with a new one representing the same time for the next year.

Example:

"2000-02-01 12:30:10.5" mjd ++year str

leaves "2001-02-01T12:30:10.5-05" on the stack (in the Montreal timezone).

-years (substract years)

( date_time years -- date_time )

Pops a number of years and the DateTime and pushes a new DateTime at the number of years before the original.

Example:

"2000-02-01 12:30:10.5" mjd 2 -years str

leaves "1998-02-01T12:30:10.5-05" on the stack (in the Montreal timezone).

+years (add years)

( date_time years -- date_time )

Pops a number of years and the DateTime and pushes a new DateTime at the number of years before the original.

Example:

"2000-02-01 12:30:10.5" mjd 2 +years str

leaves "2002-02-01T12:30:10.5-05" on the stack (in the Montreal timezone).

yesterday

( -- date_time )

Pushes the value of yesterday at midnight based on the current system time as a DateTime.

Double Operations

The DoubleOperations module provides operations on Double objects.

0? (is zero?)

( value -- value==0.0 )

Pops a number and pushes true if the number is equal to 0.0, false otherwise.

0~? (is near zero?)

( value delta -- value~0.0 )

Pops a delta and a number and pushes true if the number is near 0.0 within the delta, false otherwise.

Example:

-0.3 0.5 0~?

leaves true on the stack (-0.3 is within 0.5 of 0.0).

0+? (is zero or more?)

( value -- value>=0.0 )

Pops a number and pushes true if the number is equal to 0.0 or positive, false otherwise.

0-? (is zero or less?)

( value -- value<=0.0 )

Pops a number and pushes true if the number is equal to 0.0 or negative, false otherwise.

abs (absolute value)

( x -- abs(x) )

Pops a number and pushes its absolute value.

acos (arc cosine)

( x -- acos(x) )

Pops a number and pushes its arc cosine.

Example:

0.0 acos

leaves 1.5707963267948966 on the stack.

+ (add)

( x y -- x+y )

Pops two number and pushes their sum.

asin (arc sine)

( x -- asin(x) )

Pops a number and pushes its arc sine.

Example:

0.0 asin

leaves 0.0 on the stack.

atan (arc tangent)

( x -- atan(x) )

Pops a number and pushes its arc tangent.

Example:

0.0 atan

leaves 0.0 on the stack.

cbrt (cube root)

( x -- cbrt(x) )

Replaces a number by its cube root.

ceil (ceiling)

( x -- ceil(x) )

Replaces a number by the smallest whole number greater or equal to this number.

cos (cosine)

( x -- cos(x) )

Pops a number and pushes its cosine.

Example:

pi 2 / cos

leaves 0.0 on the stack.

cosh (hyperbolic cosine)

( x -- cosh(x) )

Pops a number and pushes its hyperbolic cosine.

Example:

0.0 cosh

leaves 1.0 on the stack.

deg (conversion to degrees)

( radians -- degrees )

Pops a number in radians and pushes its value in degrees.

Example:

pi deg

leaves 180.0 on the stack.

/ (divide)

( x y -- x/y )

Pops two number and pushes the result of the division of one by the other.

/% (divide with remainder)

( x y -- x%y x/y )

Pops two number and pushes the quotient and remainder of the division of one by the other.

e

( -- e )

Pushes 2.7182818284590452354.

eq (equal)

( x y -- x==y )

Pops two numbers and pushes true if one is equal to the other, false otherwise.

eq~ (near equal)

( x y delta -- x~~y )

Pops a delta and two numbers and pushes true if the numbers are equal within the delta, false otherwise.

Example:

-0.7 -1.0 0.5 eq~

leaves true on the stack (-0.7 is within 0.5 of -1.0).

float

( x -- float(x) )

Converts a number to a floating-point (double) number.

float?

( x -- boolean )

Pops a number and pushes true if it is a floating-point number, false otherwise.

floor

( x -- floor(x) )

Replaces a number by the largest whole number less or equal to this number.

ge (greater or equal)

( x y -- x>=y )

Pops two numbers and pushes true if one is greater or equal to the other, false otherwise.

gt (greater)

( x y -- x>y )

Pops two numbers and pushes true if one is greater than the other, false otherwise.

hypot

( x y -- hypot(x,y) )

Replaces two numbers (x, y) by the value of sqrt(x**2 + y**2) .

inf?

( x -- boolean )

Pops a number and pushes true if it represents an infinite value, false otherwise.

+inf

( -- +inf )

Pushes a value representing positive infinity.

-inf

( -- -inf )

Pushes a value representing negative infinity.

le (less or equal)

( x y -- x<=y )

Pops two numbers and pushes true if one is less or equal to the other, false otherwise.

log (natural logarithm)

( x -- log(x) )

Replaces a number by its natural logarithm.

log10 (base 10 logarithm)

( x -- log10(x) )

Replaces a number by its base 10 logarithm.

lt (less)

( x y -- x<y )

Pops two numbers and pushes true if one is less than the other, false otherwise.

max (maximum)

( x y -- max(x,y) )

Pops two numbers and pushes the greater of them.

min (minimum)

( x y -- min(x,y) )

Pops two numbers and pushes the smaller of them.

* (multiply)

( x y -- x*y )

Pops two number and pushes their product.

nan

( -- nan )

Pushes a 'Not-a-Number' (NaN) value.

nan?

( x -- boolean )

Pops a number and pushes true if it represents a 'Not-a-Number' (NaN) value, false otherwise.

ne (not equal)

( x y -- x!=y )

Pops two numbers and pushes true if one is not equal to the other, false otherwise.

neg (negative)

( x -- -x )

Replaces a number by its negative.

number?

( x -- boolean )

Pops a value and pushes true if it is a number, false otherwise.

pi

( -- pi )

Pushes pi, the ratio of the circumference of a circle to its diameter.

** (power)

( x y -- x**y )

Pops two number and pushes the result of one at the power of the other.

rad (conversion to radians)

( degrees -- radians )

Pops a number in degrees and pushes its value in radians.

Example:

90.0 rad

leaves 1.5707963267948966 on the stack.

% (remainder)

( x y -- x%y )

Pops two number and pushes the remainder of the division of one by the other.

round

( x -- round(x) )

Replaces a number by its closest whole value..

sin (sine)

( x -- sin(x) )

Pops a number and pushes its sine.

Example:

pi 2 / sin

leaves 1.0 on the stack.

sinh (hyperbolic sine)

( x -- sinh(x) )

Pops a number and pushes its hyperbolic sine.

Example

0.0 sinh

leaves 0.0 on the stack.

sqrt (square root)

( x -- sqrt(x) )

Replaces a number by its square root.

- (substract)

( x y -- x-y )

Pops two number and pushes their difference.

tan (tangent)

( x -- tan(x) )

Pops a number and pushes its tangent.

tanh (hyperbolic tangent)

( x -- tanh(x) )

Pops a number and pushes its hyperbolic tangent.

Long Operations

The LongOperations module provides operations on Long objects.

0? (is zero?)

( value -- value==0 )

Pops a number and pushes true if the number is equal to 0, false otherwise.

0+? (is zero or more?)

( value -- value>=0 )

Pops a number and pushes true if the number is equal to 0 or positive, false otherwise.

0-? (is zero or less?)

( value -- value<=0 )

Pops a number and pushes true if the number is equal to 0 or negative, false otherwise.

abs (absolute value)

( x -- abs(x) )

Pops a number and pushes its absolute value.

+ (add)

( x y -- x+y )

Pops two number and pushes their sum.

and (binary and)

( x y -- x&y )

Pops two number and pushes the result of a binary 'and' operation.

/ (divide)

( x y -- x/y )

Pops two number and pushes the result of the division of one by the other.

/% (divide with remainder)

( x y -- x%y x/y )

Pops two number and pushes the quotient and remainder of the division of one by the other.

-- (decrement)

( x -- x-1 )

Replaces a number by its decremented value.

eq (equal)

( x y -- x==y )

Pops two numbers and pushes true if one is equal to the other, false otherwise.

float

( x -- float(x) )

Converts a number to a floating-point (double) number.

ge (greater or equal)

( x y -- x>=y )

Pops two numbers and pushes true if one is greater or equal to the other, false otherwise.

gt (greater)

( x y -- x>y )

Pops two numbers and pushes true if one is greater than the other, false otherwise.

++ (increment)

( x -- x+1 )

Replaces a number by its incremented value.

int

( x -- int(x) )

Converts a number to an integer (long) number.

int?

( x -- boolean )

Pops a number and pushes true if it is an integer number, false otherwise.

le (less or equal)

( x y -- x<=y )

Pops two numbers and pushes true if one is less or equal to the other, false otherwise.

lshft (left shift)

( x y -- x<<y )

Pops two number and pushes the result of the left shift of one by the number of bits specified by the other.

lt (less)

( x y -- x<y )

Pops two numbers and pushes true if one is less than the other, false otherwise.

max (maximum)

( x y -- max(x,y) )

Pops two numbers and pushes the greater of them.

min (minimum)

( x y -- min(x,y) )

Pops two numbers and pushes the smaller of them.

* (multiply)

( x y -- x*y )

Pops two number and pushes their product.

ne (not equal)

( x y -- x!=y )

Pops two numbers and pushes true if one is not equal to the other, false otherwise.

neg (negative)

( x -- -x )

Replaces a number by its negative.

not (complement)

( x -- ~x )

Replaces a number by its complement.

or (binary or)

( x y -- x&y )

Pops two number and pushes the result of a binary 'or' operation.

% (remainder)

( x y -- x%y )

Pops two number and pushes the remainder of the division of one by the other.

rshft (right shift)

( x y -- x>>y )

Pops two number and pushes the result of the right shift of one by the number of bits specified by the other.

rshftz (right shift zero fill)

( x y -- x>>>y )

Pops two number and pushes the result of the right shift with zero fill of one by the number of bits specified by the other.

- (substract)

( x y -- x-y )

Pops two number and pushes their difference.

xor (binary exclusive or)

( x y -- x^y )

Pops two number and pushes the result of a binary 'xor' operation.

Boolean Operations

The BooleanOperations module provides operations on Boolean objects.

?: (conditional value)

( ifFalse ifTrue condition -- condition?ifTrue:ifFalse )

Pops a boolean value as a condition and leaves one of the next two top values on the stack.

Example:

1 2 false ?:

leaves 1 on the stack.

and

( x y -- x&&y )

Pops two boolean values and pushes true if both are true, false otherwise.

assert

( x -- )

Pops a boolean value and fails if it is null or false.

bool

( x -- bool(x) )

Converts a string to a boolean value.

false

( -- false )

Pushes a false value.

false!

( x -- )

Pops a boolean value and fails if it is true.

not

( x -- !x )

Pops a boolean value and pushes true if it is false, false otherwise.

or

( x y -- x||y )

Pops two boolean values and pushes true if either is true, false otherwise.

true

( -- true )

Pushes a true value.

true!

( x -- )

Pops a boolean value and fails if it is false.

xor

( x y -- x^y )

Pops two boolean values and pushes true if they are different, false otherwise.

String Operations

The StringOperations module provides operations on String objects.

+ (concatenate)

( x y -- xy )

Pops two strings and pushes their concatenation.

debug (debug log)

( x -- )

Pops a string value and put it in a log message at 'debug' level.

empty?

( x -- boolean )

Pops a string and pushes true if its lenght is 0, false otherwise.

error (error log)

( x -- )

Pops a string value and put it in a log message at 'error' level.

format

( ... format -- ... text )

Pops a format string and peeks at the content of the top stack partition to push a formatted text.

format*

( ... format -- ... text )

Pops a format string and peeks at the content of the whole stack to push a formatted text.

info (info log)

( x -- )

Pops a string value and put it in a log message at 'info' level.

lower (lower case)

( string -- lower(string) )

Pops a string value and pushes it with all lower case characters.

str (string conversion)

( x -- str(x) )

Pops a value and pushes is string representation.

str?

( x -- boolean )

Pops a value and pushes true if it is a string, false otherwise.

substring

( string from to -- substring )

Pops a limit index (to), a start index (from) and a string and pushes a substring including characters form the start index up to but not including the limit index.

trim

( string -- trim(string) )

Pops a string value and pushes it with white spaces removed at both ends.

upper (upper case)

( string -- upper(string) )

Pops a string value and pushes it with all upper case characters.

warn (warn log)

( x -- )

Pops a string value and put it in a log message at 'warn' level.

Compound Operations

The CompoundOperations module provides compound operations.

{ (begin)

( -- )

Begins bundling all the following operations until the next "}" (end) word. This allows operations like if or do which expect to be followed by single instructions to apply to the whole block.

} (end)

( -- )

Ends the bundling of operations initiated by the preceeding "{" (begin) word.

break

( -- )

Breaks the current loop instruction (do or while).

continue

( -- )

Continues the current loop instruction (do or while).

do

( -- )

Executes the following operation, then pops a boolean value and repeats the operation if the value is true.

if

( boolean -- )

Pops a boolean value and executes the following operation if the value is true.

If the following word is else, then execute the operation following that word if and only if the boolean value was false. When the else word is present, the operation following the if is optional.

reduce

( ... -- value )

While the size of the current stack is greater than 1, executes the following operation.

#reduce

( ... size -- values )

Pops a target size and, while the size of the current stack is greater than the target size, executes the following operation.

try

( -- )

Executes the following operation, then if it fails, executes the next operation after clearing the part of the stack built by the tried operation..

unless

( -- )

Pops a boolean value and executes the following operation if the value is false.

while

( boolean -- )

Pops a boolean value and, if the value is true, executes the following operation and repeats.

Container Operations

The ContainerOperations module provides container operations, most of which are available only while executing the apply operation. Two types of container are supported: the tuple hold a sequence of values, the dict holds key and value pairs. Both types allow random access to their values: the dict by its keys, the tuple by an origin 0 index.

append

( x -- )

Available only to apply on a tuple: pops a value and appends it to the tuple.

apply

( container -- )

Pops a container (tuple or dict) and applies the next operation to that container.

container?

( x -- boolean )

Pops a value and pushes true if it is a container, false otherwise.

dict

( -- dict )

Pushes an empty dict.

dict?

( x -- boolean )

Pops a value and pushes true if it is a dict, false otherwise.

entries

( -- entries )

Available only to apply on a dict: pushes the dict entries. Each entry takes two locations on the stack: the key on top and the value under the key.

get

( key|index -- value )

Available only to apply: pushes the value at popped key or index.

keys

( -- keys )

Available only to apply on a dict: pushes the dict keys.

put

( value key|index -- )

Available only to apply: pops the key or index and puts the popped value at the corresponding position in the container. When necessary, a tuple will be extended with null values.

remove

( key|index -- value )

Available only to apply: pushes and removes the value at popped key or index.

size

( -- size )

Available only to apply: pushes the container size (number of values).

tuple

( -- tuple )

Pushes an empty tuple.

tuple?

( x -- boolean )

Pops a value and pushes true if it is a tuple, false otherwise.

values

( -- values )

Available only to apply: pushes the container values.

Configuration

An instance of the RPN engine comes configured with all the bundled modules. It may be used directly, or cloned if one wants to specify macros and additional words.

The configuration is done with the Module parameter in the RPN engine definition inside the metadata. This parameter allows multiple values, each being a reference to the ClassDef for a RPN module.

The order of the module class references is important since the word overloading works by looking from last to first.

A RPN engine definition may add macro and word definitions with the Macro and Word parameters. These definitions will then be available to all the transforms associated with that engine.

Each transform for a RPN engine must supply a RPN program with the Program parameter. This program can access the values specified by the Param parameter. It may also add macro and word definitions.