Orpie v1.4 User Manual

Paul J. Pelzl

August 30, 2004


``Because the equals key is for the weak.''

1  Introduction

Orpie is a console-based RPN (reverse polish notation) desktop calculator. The interface is similar to that of modern Hewlett-PackardTM calculators, but has been optimized for efficiency on a PC keyboard. The design is also influenced to some degree by the Mutt email client and the Vim editor.

Orpie does not have graphing capability, nor does it offer much in the way of a programming interface; other applications such as GNU Octave. are already very effective for such tasks. Orpie focuses specifically on helping you to crunch numbers quickly.

Orpie is written in Objective Caml (aka OCaml), a high-performance functional programming language with a whole lot of nice features. I highly recommend it.

2  Installation

This section describes how to install Orpie by compiling from source. Volunteers have pre-packaged Orpie for several popular operating systems, so you may be able to save yourself some time by installing from those packages. Please check the Orpie website for up-to-date package information.

Before installing Orpie, you should have installed the GNU Scientific Library (GSL) version 1.4 or greater. You will also need a curses library (e.g. ncurses), which is almost certainly already installed on your system. Finally, OCaml 3.07 or higher is required to compile the sources. You will need the Nums library that is distributed with OCaml; if you install OCaml from binary packages distributed by your OS vendor, you may find that separate Nums packages must also be installed.

I will assume you have received this program in the form of a source tarball, e.g. ``orpie-x.x.tar.gz''. You have undoubtedly extracted this archive already (e.g. using ``tar xvzf orpie-x.x.tar.gz''). Enter the root of the Orpie installation directory, e.g. ``cd orpie-x.x''. You can compile the sources with the following sequence: 
$ ./configure
$ make
Finally, run ``make install'' (as root) to install the executables. ``configure'' accepts a number of parameters that you can learn about with ``./configure --help''. Perhaps the most common of these is the --prefix option, which lets you install to a non-standard directory1.

3  Quick Start

This section describes how to use Orpie in its default configuration. After familiarizing yourself with the basic operations as outlined in this section, you may wish to consult Section 4 to see how Orpie can be configured to better fit your needs.

3.1  Overview

You can start the calculator by executing orpie. The interface has two panels. The left panel combines status information with context-sensitive help; the right panel represents the calculator's stack. (Note that the left panel will be hidden if Orpie is run in a terminal with less than 80 columns.)

In general, you perform calculations by first entering data on to the stack, then executing functions that operate on the stack data. As an example, you can hit 1<enter>2<enter>+ in order to add 1 and 2.

3.2  Entering Data

3.2.1  Entering Real Numbers

To enter a real number, just type the desired digits and hit enter. The space bar will begin entry of a scientific notation exponent. The 'n' key is used for negation. Here are some examples:
Keypresses Resulting Entry
1.23<enter> 1.23
1.23<space>23n<enter> 1.23e-23
1.23n<space>23<enter> -1.23e23

3.2.2  Entering Complex Numbers

Orpie can represent complex numbers using either cartesian (rectangular) or polar coordinates. See Section 3.5 to see how to change the complex number display mode.

A complex number is entered by first pressing '(', then entering the real part, then pressing ',' followed by the imaginary part. Alternatively, you can press '(' followed by the magnitude, then '<' followed by the phase angle. The angle will be interpreted in degrees or radians, depending on the current setting of the angle mode (see Section 3.5). Examples:
Keypresses Resulting Entry
(1.23, 4.56<enter> (1.23, 4.56)
(0.7072<45<enter> (0.500065915655126, 0.50006591...
(1.23n,4.56<space>10<enter> (-1.23, 45600000000)

3.2.3  Entering Matrices

You can enter matrices by pressing '['. The elements of the matrix may then be entered as described in the previous sections, and should be separated using ','. To start a new row of the matrix, press '[' again. On the stack, each row of the matrix is enclosed in a set of brackets; for example, the matrix
1 2
3 4
would appear on the stack as [[1, 2][3, 4]].

Examples of matrix entry:
Keypresses Resulting Entry
[1,2[3,4<enter> [[1, 2][3, 4]]
[1.2<space>10,0[3n,5n<enter> [[ 12000000000, 0 ][ -3, -5 ]]
[(1,2,3,4[5,6,7,8<enter> [[ (1, 2), (3, 4) ][ (5, 6), (...

3.2.4  Entering Data With Units

Real and complex scalars and matrices can optionally be labeled with units. After typing in the numeric portion of the data, press '_' followed by a units string. The format of units strings is described in Section 3.8.

Examples of entering dimensioned data:
Keypresses Resulting Entry
1.234_N*mm^2/s<enter> 1.234_N*mm^2*s^-1
(2.3,5_s^-4<enter> (2.3, 5)_s^-4
[1,2[3,4_lbf*in<enter> [[ 1, 2 ][ 3, 4 ]]_lbf*in
_nm<enter> 1_nm

3.2.5  Entering Integer Constants

An exact integer may be entered by pressing '#' followed by the desired digits. The base of the integer will be assumed to be the same as the current calculator base mode (see Section 3.5 to see how to set this mode). Alternatively, the desired base may be specified by pressing space and appending one of {b, o, d, h}, to represent binary, octal, decimal, or hexadecimal, respectively. On the stack, the representation of the integer will be changed to match the current base mode. Examples:
Keypresses Resulting Entry
#123456<enter> # 123456`d
#ffff<space>h<enter> # 65535`d
#10101n<space>b<enter> # -21`d

Note that integer constants may have unlimited length, and the basic arithmetic operations (addition, subtraction, multiplication, division) will be performed using exact arithmetic when both arguments are integers.

3.2.6  Entering Variable Names

A variable name may be entered by pressing '@' followed by the desired variable name string. The string may contain alphanumeric characters, dashes, and underscores. Example:
Keypresses Resulting Entry
@myvar @ myvar
Orpie also supports autocompletion of variable names. The help panel displays a list of pre-existing variables that partially match the name currently being entered. You can press '<tab>' to iterate through the list of matching variables.

As a shortcut, keys <f1>-<f12> will enter the variables (``registers'') @ r01 through @ r12.

3.2.7  Entering Data With an External Editor

Orpie can also parse input entered via an external editor. You may find this to be a convenient method for entering large matrices. Pressing 'E' will launch the external editor, and the various data types may be entered as illustrated by the examples below:
Data Type Sample Input String
integer constant #12345678`d, where the trailing letter is one of the base characters {b, o, d, h}
real number -123.45e67
complex number (1e10, 2) or (1 <90)
real matrix [[1, 2][3.1, 4.5e10]]
complex matrix [[(1, 0), 5][1e10, (2 <90)]]
variable @myvar
Real and complex numbers and matrices may have units appended; just add a units string such as ``_N*m/s'' immediately following the numeric portion of the expression.

Notice that the complex matrix input parser is quite flexible; real and complex matrix elements may be mixed, and cartesian and polar complex formats may be mixed as well.

Multiple stack entries may be specified in the same file, if they are separated by whitespace. For example, entering (1, 2) 1.5 into the editor will cause the complex value (1, 2) to be placed on the stack, followed by the real value 1.5.

The input parser will discard whitespace where possible, so feel free to add any form of whitespace between matrix rows, matrix elements, real and complex components, etc.

3.3  Executing Basic Function Operations

Once some data has been entered on the stack, you can apply operations to that data. For example, '+' will add the last two elements on the stack. By default, the following keys have been bound to such operations:
Keys Operations
+ add last two stack elements
- subtract element 1 from element 2
* multiply last two stack elements
/ divide element 2 by element 1
^ raise element 2 to the power of element 1
n negate last element
i invert last element
s square root function
a absolute value function
e exponential function
l natural logarithm function
c complex conjugate function
! factorial function
% element 2 mod element 1
S store element 2 in (variable) element 1
; evaluate variable to obtain contents

As a shortcut, function operators will automatically enter any data that you were in the process of entering. So instead of the sequence 2<enter>2<enter>+, you could type simply 2<enter>2+ and the second number would be entered before the addition operation is applied.

As an additional shortcut, any variable names used as function arguments will be evaluated before application of the function. In other words, it is not necessary to evaluate variables before performing arithmetic operations on them.

3.4  Executing Function Abbreviations

One could bind nearly all calculator operations to specific keypresses, but this would rapidly get confusing since the PC keyboard is not labeled as nicely as a calculator keyboard is. For this reason, Orpie includes an abbreviation syntax.

To activate an abbreviation, press ''' (quote key), followed by the first few letters/digits of the abbreviation, then hit enter. Orpie offers an autocompletion feature for abbreviations, so you only need to type enough of the operation to identify it uniquely. The matching abbreviations will appear in the left panel of the display, to assist you in finding the appropriate operation.

To avoid interface conflicts, abbreviations may be entered only when the entry buffer (the bottom line of the screen) is empty.

The following functions are available as abbreviations:
Abbreviations Functions
inv inverse function
pow raise element 2 to the power of element 1
sq square last element
sqrt square root function
abs absolute value function
exp exponential function
ln natural logarithm function
10^ base 10 exponential function
log10 base 10 logarithm function
conj complex conjugate function
sin sine function
cos cosine function
tan tangent function
sinh hyperbolic sine function
cosh hyperbolic cosine function
tanh hyperbolic tangent function
asin arcsine function
acos arccosine function
atan arctangent function
asinh inverse hyperbolic sine function
acosh inverse hyperbolic cosine function
atanh inverse hyperbolic tangent function
re real part of complex number
im imaginary part of complex number
gamma Euler gamma function
lngamma natural log of Euler gamma function
erf error function
erfc complementary error function
fact factorial function
gcd greatest common divisor function
lcm least common multiple function
binom binomial coefficient function
perm permutation function
trans matrix transpose
trace trace of a matrix
solvelin solve a linear system of the form Ax = b
mod element 2 mod element 1
floor floor function
ceil ceiling function
toint convert a real number to an integer type
toreal convert an integer type to a real number
add add last two elements
sub subtract element 1 from element 2
mult multiply last two elements
div divide element 2 by element 1
neg negate last element
store store element 2 in (variable) element 1
eval evaluate variable to obtain contents
purge delete a variable
total sum the columns of a real matrix
mean compute the sample means of the columns of a real matrix
sumsq sum the squares of the columns of a real matrix
var compute the unbiased sample variances of the columns of a real matrix
varbias compute the biased (population) sample variances of the columns of a real matrix
stdev compute the unbiased sample standard deviations of the columns of a real matrix
stdevbias compute the biased (pop.) sample standard deviations of the columns of a matrix
min find the minima of the columns of a real matrix
max find the maxima of the columns of a real matrix
utpn compute the upper tail probability of a normal distribution
uconvert convert element 2 to an equivalent expression with units matching element 1
ustand convert to equivalent expression using SI standard base units
uvalue drop the units of the last element

Entering abbreviations can become tedious when performing repetitive calculations. To save some keystrokes, Orpie will automatically bind recently-used operations with no prexisting binding to keys <f5>-<f12>. The current autobindings can be viewed by pressing 'h' to cycle between the various pages of the help panel.

3.5  Executing Basic Command Operations

In addition to the function operations listed in Section 3.3, a number of basic calculator commands have been bound to single keypresses:
Keys Operations
\ drop last element
| clear all stack elements
<pagedown> swap last two elements
<enter> duplicate last element (when entry buffer is empty)
u undo last operation
r toggle angle mode between degrees and radians
p toggle complex display mode between rectangular and polar
b cycle base display mode between binary, octal, decimal, hex
h cycle through multiple help windows
v view last stack element in a fullscreen editor
E create a new stack element using an external editor
P enter 3.1415...on the stack
C-L refresh the display
<up> begin stack browsing mode
Q quit Orpie

3.6  Executing Command Abbreviations

In addition to the function operations listed in Section 3.4, there are a large number of calculator commands that have been implemented using the abbreviation syntax:
Abbreviations Calculator Operation
drop drop last element
clear clear all stack elements
swap swap last two elements
dup duplicate last element
undo undo last operation
rad set angle mode to radians
deg set angle mode to degrees
rect set complex display mode to rectangular
polar set complex display mode to polar
bin set base display mode to binary
oct set base display mode to octal
dec set base display mode to decimal
hex set base display mode to hexidecimal
view view last stack element in a fullscreen editor
edit create a new stack element using an external editor
pi enter 3.1415...on the stack
rand generate a random number between 0 and 1 (uniformly distributed)
refresh refresh the display
about display a nifty ``About Orpie'' screen
quit quit Orpie

3.7  Browsing the Stack

Orpie offers a stack browsing mode to assist in viewing and manipulating stack data. Press <up> to enter stack browsing mode; this should highlight the last stack element. You can use the up and down arrow keys to select different stack elements. The following keys are useful in stack browsing mode:
Keys Operations
q quit stack browsing mode
<left> scroll selected entry to the left
<right> scroll selected entry to the right
r cyclically ``roll'' stack elements downward, below the selected element (inclusive)
R cyclically ``roll'' stack elements upward, below the selected element (inclusive)
v view the currently selected element in a fullscreen editor
E edit the currently selected element with an external editor
<enter> duplicate the currently selected element

The left and right scrolling option may prove useful for viewing very lengthy stack entries, such as large matrices. The edit option provides a convenient way to correct data after it has been entered on the stack.

3.8  Units Formatting

A units string is a list of units separated by '*' to indicate multiplication and '/' to indicate division. Units may be raised to real-valued powers using the '^' character. A contrived example of a valid unit string would be "N*nm^2*kg/s/in^-3*GHz^2.34".

Orpie supports the standard SI prefix set, {y, z, a, f, p, n, u, m, c, d, da, h, k, M, G, T, P, E, Z, Y} (note the use of 'u' for micro-). These prefixes may be applied to any of the following exhaustive sets of units:
String Length Unit
m meter
ft foot
in inch
yd yard
mi mile
pc parsec
AU astronomical unit
Ang angstrom
furlong furlong
pt PostScript point
pica PostScript pica
nmi nautical mile
lyr lightyear

String Mass Unit
g gram
lb pound mass
oz ounce
slug slug
lbt Troy pound
ton (USA) short ton
tonl (UK) long ton
tonm metric ton
ct carat
gr grain

String Time Unit
s second
min minute
hr hour
day day
yr year
Hz Hertz

String Temperature Unit
K Kelvin
R Rankine
Note: No, Celsius and Fahrenheit will not be supported. Because these temperature units do not share a common zero point, their behavior is ill-defined under many operations.
String Force Unit
N Newton
lbf pound force
dyn dyne
kip kip

String Energy Unit
J Joule
erg erg
cal calorie
BTU british thermal unit
eV electron volt

String Electrical Unit
A Ampere
C Coulomb
V volt
Ohm Ohm
F Farad
H Henry
T Tesla
G Gauss
Wb Weber
Mx Maxwell

String Power Unit
W Watt
hp horsepower

String Pressure Unit
Pa Pascal
atm atmosphere
bar bar
Ohm Ohm
mmHg millimeters of mercury
inHg inches of mercury

4  Advanced Configuration

Orpie reads a run-configuration textfile (generally /etc/orpierc or /usr/local/etc/orpierc) to determine key and command bindings. You can create a personalized configuration file in $HOME/.orpierc, and select bindings that match your usage patterns. The recommended procedure is to ``include'' the orpierc file provided with Orpie (see Section 4.1.1), and add or remove settings as desired.

4.1  orpierc Syntax

You may notice that the orpierc syntax is similar to the syntax used in the configuration file for the Mutt email client (muttrc).

Within the orpierc file, strings should be enclosed in double quotes ("). A double quote character inside a string may be represented by \" . The backslash character must be represented by doubling it (\\).

4.1.1  Including Other Rcfiles

Syntax: include filename_string

This syntax can be used to include one run-configuration file within another. This command could be used to load the default orpierc file (probably found in /etc/orpierc) within your personalized rcfile, ~/.orpierc. The filename string should be enclosed in quotes.

4.1.2  Setting Configuration Variables

Syntax: set variable=value_string

Several configuration variables can be set using this syntax; check Section 4.2 to see a list. The variables are unquoted, but the values should be quoted strings.

4.1.3  Creating Key Bindings

Syntax: bind key_identifier operation

This command will bind a keypress to execute a calculator operation. The various operations, which should not be enclosed in quotes, may be found in Section 4.3. Key identifiers may be specified by strings that represent a single keypress, for example "m" (quotes included). The key may be prefixed with "\\C" or "\\M" to represent Control or Meta (Alt) modifiers, respectively; note that the backslash must be doubled. A number of special keys lack single-character representations, so the following strings may be used to represent them: Due to differences between various terminal emulators, this key identifier syntax may not be adequate to describe every keypress. As a workaround, Orpie will also accept key identifiers in octal notation. As an example, you could use \024 (do not enclose it in quotes) to represent Ctrl-T.

Orpie includes a secondary executable, orpie-curses-keys, that prints out the key identifiers associated with keypresses. You may find it useful when customizing orpierc.

Multiple keys may be bound to the same operation, if desired.

4.1.4  Removing Key Bindings

Syntax:
unbind_function key_identifier
unbind_command key_identifier
unbind_edit key_identifier
unbind_browse key_identifier
unbind_abbrev key_identifier
unbind_variable key_identifier
unbind_integer key_identifier

These commands will remove key bindings associated with the various entry modes (functions, commands, editing operations, etc.). The key identifiers should be defined using the syntax described in the previous section.

4.1.5  Creating Key Auto-Bindings

Syntax: autobind key_identifier

In order to make repetitive calculations more pleasant, Orpie offers an automatic key binding feature. When a function or command is executed using its abbreviation, one of the keys selected by the autobind syntax will be automatically bound to that operation (unless the operation has already been bound to a key). The current set of autobindings can be viewed in the help panel by executing command_cycle_help (bound to 'h' by default).

The syntax for the key identifiers is provided in the previous section.

4.1.6  Creating Operation Abbreviations

Syntax: abbrev operation_abbreviation operation

You can use this syntax to set the abbreviations used within Orpie to represent the various functions and commands. A list of available operations may be found in Section 4.3. The operation abbreviations should be quoted strings, for example "sin" or "log".

Orpie performs autocompletion on these abbreviations, allowing you to type usually just a few letters in order to select the desired command. The order of the autocompletion matches will be the same as the order in which the abbreviations are registered by the rcfile--so you may wish to place the more commonly used operation abbreviations earlier in the list.

Multiple abbreviations may be bound to the same operation, if desired.

4.1.7  Removing Operation Abbreviations

Syntax: unabbrev operation_abbreviation

This syntax can be used to remove an operation abbreviation. The operation abbreviations should be quoted strings, as described in the previous section.

4.1.8  Creating Macros

Syntax: macro key_identifier macro_string

You can use this syntax to cause a single keypress (the key_identifier) to be interpreted as the series of keypresses listed in macro_string. The syntax for defining a keypress is the same as that defined in Section 4.1.3. The macro string should be a list of whitespace-separated keypresses, e.g. "2 <return> 2 +" (including quotes).

This macro syntax provides a way to create small programs; by way of example, the default orpierc file includes macros for the base 2 logarithm and the binary entropy function (bound to L and H, respectively), as well as ``register'' variable shortcuts (<f1> to <f12>).

Macros may call other macros recursively. However, take care that a macro does not call itself recursively; Orpie will not trap the infinite loop.

Note that operation abbreviations may be accessed within macros. For example, macro "A" "' a b o u t <return>" would bind A to display the ``about Orpie'' screen.

4.2  Configuration Variables

The following configuration variables may be set as described in Section 4.1.2:

4.3  Calculator Operations

Every calculator operation can be made available to the interface using the syntax described in Sections 4.1.3 and 4.1.6. The following is a list of every available operation.

4.3.1  Functions

The following operations are functions--that is, they will consume at least one argument from the stack. Orpie will generally abort the computation and provide an informative error message if a function cannot be successfully applied (for example, if you try to compute the transpose of something that is not a matrix).

For the integer constant data type, basic arithmetic operations will yield an exact integer constant result. Division of two integer constants will yield the quotient of the division. The more complicated functions will generally promote the integer constant to a real number, and as such the arithmetic will no longer be exact.

4.3.2  Commands

The following operations are referred to as commands; they differ from functions because they do not take an argument. Many calculator interface settings are implemented as commands.

4.3.3  Edit Operations

The following operations are related to editing during data entry. These commands cannot be made available as operation abbreviations, since abbreviations are not accessible while entering data. These operations should be made available as single keypresses using the bind keyword.

4.3.4  Browsing Operations

The following list of operations is available only in stack browsing mode. As abbreviations are unavailable while browsing the stack, these operations should be bound to single keypresses using the bind keyword.

4.3.5  Abbreviation Entry Operations

The following list of operations is available only while entering a function or command abbreviation. These operations must be bound to single keypresses using the bind keyword.

4.3.6  Variable Entry Operations

The following list of operations is available only while entering a variable name. As abbreviations are unavailable while entering variables, these operations should be bound to single keypresses using the bind keyword.

4.3.7  Integer Entry Operations

The following operation is available only while entering an integer; it can be made accessible by binding it to a single keypress using the bind keyword.

5  Licensing

Orpie is Free Software; it has been made available under version 2 of the GNU General Public License (GPL). You should have received a copy of the GPL along with this program, in the file ``COPYING''.

6  Credits

Orpie includes portions of the ocamlgsl bindings supplied by Olivier Andrieu, as well as the curses bindings from the OCaml Text Mode Kit written by Nicolas George. I would like to thank these authors for helping to make Orpie possible.

7  (Not So) Frequently Asked Questions

  1. Whatever happened to rpc?

    rpc, of course, would be the predecessor to Orpie. It was written in C++.

    Over the years I have grown increasingly disenchanted with C++, and as a result I lost interest in maintaining rpc. When I settled on OCaml as a replacement language, I began working on Orpie as a way to improve my OCaml abilities.

  2. What's wrong with C++? And what's this OCaml thing?

    <rant>
    C++ has had so many misfeatures bolted on that no one can possibly hold the entire syntax in his head at one time. The syntax is not only prohibitively vast, but also horribly ugly--especially when dealing with templates. The ability to use pointers presents many opportunities to shoot oneself in the foot. Garbage collection and exceptions exist as afterthoughts. In short, there are few compelling reasons to consider C++ for any project that does not require low-level hardware access.
    </rant>

    I found OCaml after searching for a Better Language that offers good performance. OCaml is a functional programming language with a pretty syntax, clean design, and all sorts of nice features that one really should expect from a modern programming language. It supports functional, imperative, and object-oriented programming paradigms, so it is well-suited to a broad class of programming tasks. The type-checking compiler is exceedingly strict, and I find that this improves my overall productivity by catching a lot of bugs prior to runtime. OCaml also interfaces with C quite easily, and there are bindings available for many commonly used libraries.

  3. Does Orpie include any enhancements over the old rpc?

    The biggest usability enhancement would be the rcfile for keybindings. The context-sensitive help panel is new, as is user-defined variable support, units handling, and autobindings. Integer data may be entered and manipulated with arbitrary precision (thanks to the Nums library that ships with OCaml). The error messages provided by Orpie are, on average, more informative than those provided by rpc; this is a direct consequence of OCaml's excellent exception handling support.

    I also believe that Orpie has fewer bugs in the input handler/parser, but this remains to be seen.

  4. When I use {+, -, *, /} on the numeric keypad under gnome-terminal, Orpie reads some letters instead of the expected symbols. Can I do anything about this?

    I was able to fix the problem by executing 
          $ export TERM=linux
    before launching Orpie. gnome-terminal sets $TERM to xterm, but apparently does not behave like a real xterm with respect to the numeric keypad.

  5. Orpie crashes with a segmentation fault on startup. What can I do?

    Try deleting the calculator state file (probably ~/.orpie/calc_state , unless you changed the data_dir configuration variable). Orpie makes use of OCaml's marshalling feature, which is very convenient but doesn't respond well to corrupt data files.

8  Contact info

Orpie author: Paul Pelzl <pelzlpj@eecs.umich.edu>
Orpie website: http://www.eecs.umich.edu/~pelzlpj/orpie


Feel free to contact me if you have bugs, feature requests, patches, etc. I would also welcome volunteers interested in packaging Orpie for various platforms.

Orpie is developed with the aid of the excellent GNU Arch RCS. Interested developers are advised to track Orpie development via my public archive:
      pelzlpj@eecs.umich.edu--2004 \
            http://www-personal.engin.umich.edu/~pelzlpj/tla/2004
Orpie uses tla's ``configs'' support. After getting a copy of the source, run
"tla build-config dist.arch" in the project tree root to grab the extra packages that Orpie depends on.

At the moment, I would really appreciate help writing additional test cases for the calculator object. It's not terribly difficult, just time-consuming. If you're interested in lending a hand, have a look at the source in calc_test.ml and use "make test.opt" to build the testing executable.

Do you feel compelled to compensate me for writing Orpie? As a poor, starving graduate student, I will gratefully accept donations.

1
The default installation prefix is /usr/local.
This document was translated from LATEX by HEVEA.