overgrown/docs/rpn.1

.\" 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 2024-06-17 "Harakit X.X.X"
.SH NAME
rpn \(en reverse polish notation evaluation
.\"
.SH SYNOPSIS

rpn
.RB [ numbers... ]
.RB [ operators... ]
.\"
.SH DESCRIPTION

Evaluate reverse polish notation.

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

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

For information on for reverse polish notation syntax, see
.BR rpn (7).
.\"
.SH STANDARD INPUT

If arguments are specified, they are interpreted as an expression to be
evaluated. Otherwise, whitespace-delimited numbers and operations are read from
the standard input.
.\"
.SH DIAGNOSTICS

In the event of an error, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code; however, in the event of a syntax error, the program will print an
error message and continue accepting input.
.\"
.SH CAVEATS

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

An infix notation calculation utility,
.BR 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
.BR dc (1)
pre-dates the standardized
.BR bc (1p),
the latter originally being a preprocessor for the former, and was included in
Second Edition UNIX and 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
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT

Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
.BR bc (1p),
.BR dc (1),
.BR rpn (7),
.I IEEE 754