Soft84

Introduction

Soft84 is a calculator app for Android OS devices. You can install it from Google's Android Market. It is inspired by Hewlett Packard's HP 48 calculator, though it is not functionally equivalent yet. At the moment it is a capable RPN scientific calculator with units and rudimentary programming features.

It uses several libraries for arbitrary precision arithmetic: GNU Multiple Precision (GMP), GNU MP Floating/Rounding (MPFR), and GNU MP Complex (MPC). In principle it can be an arbitrary precision calculator, though at the moment it is hard-coded to 100 decimal digits of precision.

Soft84 is released under the GPL V2. If you are really interested in the source, let me know and I will provide you access to my git repository. But here is a source snapshot from 2012/01/16

User interface fundamentals

Soft84 uses what is known as Reverse Polish Notation. This means that you enter numbers onto a stack, and then perform operations on that stack. Most operations take the top two elements of the stack (though physically displayed at the bottom of the display) and combine them to form a new element on the stack that replaces them. For example, to compute 123+321, you would type 123 then enter, then 321, then +. The answer 444 would be on the top of the stack.

Starting at the top, here is a description of the elements of the Soft84 interface:

stack display: The top portion of the display contains the current contents of the stack. The "top of stack" (where operations occur) is displayed at the bottom of the area. The 1: represents the depth of the stack -- higher numbers mean it is deeper (lower) in the stack. If the stack is too big to fit on the screen, this area is finger-scrollable.
status bar: The left part of the status bar indicates the current file path, ":" represents the root (the top-level). The right part of the status bar indicates the current mode. "stack" is the default stack view, "edit" is a view for editing compound objects, and several modifiers which will affect your next keypress will also be displayed here.
file-system buttons (blue): This area is a horizontally-scrollable list of the contents of the current directory. Buttons that are rounded are subdirectories, buttons which are square (none shown here) are files within the directories. Clicking on a subdirectory button enters that subdirectory. Clicking on a file button causes the contents of that file to be pushed onto the stack, or executed if the button contains a << >> program. The user directory is for your own storage (much like memory on a traditional calculator), math provides access to more advanced mathematical operations (such as lg and sin), prog holds commands useful for programming, units has a lot of units (like inches, seconds, etc), and edit provides a couple commands useful when in edit mode. Pressing the Android option (or menu) button will bring up commands to edit within the user directory.
up button (blue): Goes to the previous directory within the filesystem.
abc button (purple): Brings up the Android keyboard, for entering characters and punctuation, such as in the name of a variable. When you are done you can generally clear the Android keyboard with the back button.
swp button (purple): Swaps the top two elements of the stack.
enter button (purple): Terminates the current entry area, causing its result to be pushed on the stack or inserted into the edit buffer. It also can be used to terminate edit mode.
<-- button (purple): Backspace within the current entry area, or pop from stack (discard top value). Hold this button down to clear all the elements on the stack.
orange buttons: Basic arithmetic operators, including inversion.
grey buttons: Basic numeric entry buttons, including decimal point, sign inversion (for negative numbers), and E (base 10 exponent). For example, to enter one million (1 with six zeros after it), you may enter 1E6.

Android devices have a hardware button called "menu" or "option" which will bring up an alternate set of buttons. The blue buttons operate on a file entry that is selected by clicking on it. The orange buttons are primarily for files that do not exist yet, so you had to enter the name manually with the abc mode. The grey buttons begin various input modes. The purple buttons provide miscellaneous functionality.

ref (blue): Changes to "REF" mode, which will push the name of the next button that you click onto the stack.
val (blue): Changes to "VAL" mode, which will push the value of the next file that you click onto the stack. This is useful for file entries that contain << >> programs, so that you can view or edit the program instead of executing it.
sto (blue): Changes to "STO" mode, which will store the value on the top of the stack into the next file that you click.
erase (blue): Changes to "ERASE" mode, which deletes the next file you click.
mkdir (orange): Creates a subdirectory according to the name on the top of the stack. If a string name was entered, it will be created in the current directory. If a symbolic name (like from ref) is on the stack, that name will provide the path.
store (orange): Takes two arguments off the stack, the name of the file (on the top of the stack) and the value to store into it.
" (grey): Begins string entry mode, for entering string literals.
# (grey): Begins integer-entry mode. Integers can be of an arbitrary length and are always presented precisely, but cannot have a decimal point.
[] (grey): Begins list-entry mode. In list-entry mode, you can click on a point within the list to move the cursor. Values typed in will be inserted before the current cursor position. Backspace will delete the thing before the cursor.
<<>> (grey): Begin program-entry mode. The program editor is very similar to the list editor. Programs are basically lists of commands which are executed in order. Currently there is no sense of scoping or control-flow (except for function calls), so it is pretty limited. Note that in the editor, if you execute an operator like + or sin, a call to that operator is inserted.
undo (purple): Restores the stack to the state it was in before the last command was executed. Note that it only restores the stack -- any changes to the filesystem are irreversible.
edit (purple): Edits the item on the top of the stack.

Programming fundamentals

At its core, Soft84 is an interpretter for a simple language with a typed stack, not dissimilar from "Reverse Polish Lisp" (RPL) used by some HP calculators.

In this language, everything is either a literal (which pushes its own value onto the stack), or a reference to a file-system object (which is a function call if that object's value is code).

If a token begins with alphabetic or colon (:), then it is a file-system reference. If there is no colon, the object is first searched for in the current directory, then in the (hidden) :builtins directory, and then as a fall-back it is assumed to be a not-yet-created item in the current directory.

If a token begins with numeric, decimal point (.), or minus sign (-), then it is a floating-point number. It may have a base-10 exponent supplied such as E6. After the number's value is fully specified an optional unit can be provided, of the form _unit.

If a token begins with a quote mark (") then it is a string literal which can contain \r, \n, \t, \\, \" or any regular character and terminates at the next unescaped ".

If a token begins with a pound sign (#) then it is an integer literal. Integer literals cannot have units, or exponents, or decimal points, though they can be negative (XXX - bug). Integers are useful for precise arithmetic (such as currency), and for binary arithmetic, and for base conversions (XXX - not yet).

If a left bracket ([) is encountered, then the tokens up to the right bracket (]) are collected into a list, which is then pushed onto the stack as a literal.

If a code start token (<<) is encountered, then the tokens up to the code end token (>>) are collected into a list, which will be executed if the file it is stored in is called, or if the :builtin:eval command is executed.