.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.

.TH rpn 1

.SH NAME

rpn \(en reverse polish notation evaluation

.SH SYNOPSIS

rpn
.RB [numbers...]\ [operators...]

.SH DESCRIPTION

Rpn evaluates reverse polish notation expressions either read from the standard
input or parsed from provided arguments. See the STANDARD INPUT section.

Upon evaluation, rpn will print the resulting number on the stack to the
standard output. Any further specified numbers will be placed at the end of the
stack.

For information on for reverse polish notation syntax, see rpn(7).

.SH STANDARD INPUT

If arguments are passed to rpn, it interprets them as an expression to be
evaluated. Otherwise, it reads whitespace-delimited numbers and operations from
the standard input.

.SH DIAGNOSTICS

If encountering a syntax error, rpn will exit with the appropriate error code
as defined by sysexits.h(3) and print an error message.

.SH CAVEATS

Due to precision constraints and the way floats are represented in accordance
with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point
arithmetic has rounding errors. This is somewhat curbed by using the
machine epsilon as provided by the Rust standard library to which to round
numbers. Because of this, variation is expected in the number of decimal places 
rpn can handle based on the platform and hardware of any given machine.

.SH RATIONALE

An infix notation calculation utility, bc(1p), is included in the POSIX
standard, but does not accept expressions as arguments; in scripts, any
predefined, non-interactive input must be piped into the program. A dc(1)
pre-dates the standardized bc(1p), the latter originally being a preprocessor
for the former, and was included in UNIX v2 onward. While it implements reverse
polish notation, it still suffers from being unable to accept an expression as
an argument.

.SH AUTHOR

Written by Emma Tebibyte <emma@tebibyte.media>.

.SH COPYRIGHT

Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.

.SH SEE ALSO

bc(1p), dc(1), rpn(7), IEEE 754