Flume

BETA Version 0.9.0, November 2010

Flume is a fast, light utilitarian math environment. It can be used from the command-line for simple calculations, or in GUI form as a desktop calculator or a one-column spreadsheet. Calculations are performed with your CPU's floating point hardware, so the range and precision of numbers are somewhat limited, but suitable for most uses. Flume uses the FLTK user interface library, which makes it is especially efficient on TinyCore Linux. The source code of Flume is released under the GNU license. See

http://www.gnu.org/licenses/ for more details.

CAUTION: Flume 0.9.0 is BETA SOFTWARE. While due care was taken during development, it has not been tested exhaustively. Mathematical calculations in Flume are done within the precision and limitations of IEEE-standardized floating-point computations. Flume does NOT have arbitrarily high precision (like some math packages), and is subject to round-off errors and other issues. DO NOT use Flume BETA as your sole mathematics tool for your P.h. D dissertation, preparing tax filings, or unlocking the secrets of an ancient script. Even when Flume BETA is used in more mundane applications, it is likely at some point to produce an inaccurate result, lose your work, steal your dog, tell an embarrassing story at your wedding, or otherwise do something that disappoints you. Please help make Flume better by reporting bugs and offering suggestions. Suggestions are especially welcome that come with specific test cases that reproduce errors or code changes that can be easily integrated. Thanks!

Command-Line Options

--f filename load content of file "filename" into work area upon startup

--d angles expressed as degrees

--r angles expressed as radians (default)

--t N "terseness", with N = 0(very verbose) to 5 (very terse)

--v print name and version on command-line

Command-Line Mode

If you invoke Flume from the command line and provide it a mathematical expression after any command-line options, Flume will immediately try to calculate and print the result and then exit without opening the graphical user interface (GUI). For example, if you enter:

$ flume 6*7[Enter]

you will see the result:

6 * 7 = 42

Command-line mode will only parse and calculate one result, so some features of Flume, such as references, will not work properly. If your expression contains any characters that are special for the command-line shell, such as parentheses, please enclose your expression in double-quotes:

$ flume "1.0+(2.0*2.0)"[Enter]

1.0 + (2.0 * 2.0) = 5.0

Flume supports the following number formats:

Decimal integer: 7

Real number: 7.0

Scientific notation: 7.0e0

Hexadecimal integer: 0x07 or 0X07

Binary integer: 0`111 or 0b111 or 0B111

Note the first form of binary notation uses a back-quote, not single-quote! Negative numbers should be prefaced with a - (dash) with no space before the numerals.

Flume will parse your entries and try to provide grouping parentheses to resolve any ambiguity in the order of operations. For example, if you enter the expression

2*3+4^2

You will see flume re-write the expression as:

(2 * 3) + (4 ^ 2)

If this grouping is not what you intended, please edit the expression with the exact grouping you need.

Comments may be added to the end of an expression a semi-colon:

sin(pi / 4.0) ; sine of 45 degrees

All expressions in the main workspace area are recalculated each time you press the Enter key, so you may easily edit and update multiple results as in spreadsheet applications. Comments will be preserved, but any text between the equal symbol and the first semi-colon will be replaced by new results.

It is acceptable to enter a single number by itself as an expression, which is simply evaluated as the entered value (identity principle). This form is useful for changeable input values used in a later calculation. For example:

5.0 = 5.0 ; width, inches

7.0 = 7.0 ; length, inches

3.0 = 3.0 ; height, inches

p[3] * p[2] * p[1] = 105.0 ; volume, cubic inches

Operators, Functions, and Constants

The spelling of operators, functions, and constants is generally case-insensitive with exceptions noted below.

The following infix operators are used between two numbers or sub-expressions:

+ add

- subtract

* multiply

x or X multiply, or part of hex number if directly preceded by zero

of multiply (e.g. "1/2 of 732")

/ divide

^ raise to a power

MOD integer modulus

& or AND bit-wise integer AND

| or OR bit-wise integer OR

XOR bit-wise integer exclusive-OR

The following prefix operator should be used before its operand:

~ bit-wise integer NOT (invert)

The following postfix operators should be used after their operand:

% divide by 100.0

! factorial (non-neg. integers only)

Flume can compute the following functions:

sqrt() square root

sin() sine of an angle

cos() cosine of an angle

tan() tangent of an angle

arcsin() arcsine (inverse sine) of an angle

arccos() arccosine (inverse cosine) of an angle

arctan() arctangent (inverse tangent) of an angle

remainder() real-number remainder after division

deg2rad() multiply by PI/180.0

rad2deg() multiply by 180.0/PI

Note: for trigonometric functions, the default angle encoding is radians. From the GUI or command-line, the encoding can be switched to degrees.

Flume will provide the following constant values:

PI 3.141592...

e 2.7182818... (lower-case only!)

Referring to Prior Results

You may reuse prior results in an expression using absolute or relative references.

Absolute references specify an expression row (or "result") number in the form of r[n], where n is the row number from 0 (the first row number) up to the maximum. No matter where the absolute reference shows up, it refers to the same expression row. Warning: referring to a higher-number row will recall the old calculation result for that row, which may change during the subsequent calculations.

Relative references specify an expression row a specified number of rows displaced from the row containing the reference. The form of relative references is p[n], where n is the number of rows offset in the prior direction. For example, p[1] refers to the immediately prior row and p[2] refers to an expression two rows back. Negative values for the row offset will make forward-references, which may produce inconsistent results.

When Flume parses expressions, the single-quote character (') will be automatically expanded into p[1], while the double-quote character (") will be automatically expanded into p[2], making it a little more convenient to chain calculations together as you type them in.

Files

Flume may open and insert the contents of a text file into the main work area. This can be done by specifying a file on the command-line or by pressing the "Open" button in the GUI and selecting a file. The file selection dialog defaults to browsing files with the ".flume" filename extension, but ".ume", ".txt" or all files may be browsed by changing the filter field.

If the file contents are successfully retrieved, Flume will attempt to evaluate each line of the file. If any line is not a valid expression, Flume will report an error and place the editing cursor at the end of that expression. The name the retrieved file is displayed in the GUI main window title. If the content has been modified, the filename in the title will show an asterisk (*) prefix.

You may save your current workspace content as long as there has been at least one valid expression. The entire workspace content is saved to the file, even if some of that content has not been parsed and calculated yet. After Flume successfully writes the current workspace content to the file, the file modification flag and title asterisk is cleared.

If the file modification flag is currently set when try to quit or open a new file, you will be notified that quitting will cause the modifications to be discarded. You may either choose to discard and quit anyway or chose to cancel the quit request so you may save the modified content.

Quirks and Tricks

Flume doesn't (yet?) handle imaginary numbers, so sqrt(-1) returns "-nan" (not a number).

Multiple sequential "raise to the power" operators will expand into a strange looking expression, but will calculated OK. For example, 3^2^2 will expand to (3 ^ (2) ^ 2), but will still equal 81. Use parentheses if an exponent is a complicated expression.

Flume keeps track of the format of a number (integer, hexadecimal, etc.), and most results will "inherit" the format of the last number entered. You can exploit this behavior with the Multiplicative Identity (multiply by one), using the form of the number one you want to convert the first number or expression to. For example, to convert 192 into hexadecimal:

$ flume 192 x 0x01[enter]

192 x 0x01 = 0xC0

To convert 1/1000 into scientific notation:

$ flume "(1.0/1000) * 1e0"

(1.0 / 1000) * 1e0 = 1.000000e-03