# The &mathemagics; Handbook

## Introduction

This document describes &mathemagics; version 1.0.

&mathemagics; is a full-featured scientific calculator. It uses Reverse Polish Notation, or RPN. &mathemagics; can store and use user-defined functions and variables, and comes with large number of built-in functions.

Have fun with &mathemagics;!

## Usage

This chapter describes usage of &mathemagics;'s features.

### Reverse Polish Notation (RPN)

Most calculators use an algebraic system of input. In this system, one enters arguments to a function after entering the function itself. For example, to add 2 and 2, one would enter `2 + 2`.

&mathemagics; uses the Reverse Polish Notation system for input. With RPN, arguments are entered before the function. So to add 2 and 2, one would enter "2 2 +".

RPN is based around the stack. The stack stores numbers. When you execute a function, like x^y, the operation takes its arguments from the stack. If there are not enough numbers on the stack, &mathemagics; will tell you. In &mathemagics;, the stack is shown as a pile of line-entries. The first stack level is on the very bottom.

### Modifying the Stack

To enter something onto the stack, type it into the line-entry on the main toolbar. Then press the Return key. The number you entered will be pushed onto the stack. You can enter multiple numbers onto the stack at once by separating them with spaces.

To modify numbers already on the stack, click in the line-entry that represents the stack level. Then modify the displayed number by typing the new number you want into the line-entry. Finally, press return and the number will be saved onto that stack level. If you ever want to get rid of any stack changes you've made in this way, Choose the Edit->Revert Stack Changes.

To drop a stack level, replace the text in its line-entry with nothing. Then press return as you normall would in that line-entry.

To roll values on the stack upwards from a level, click the button to the right of the stack level you want to roll from. If the Inv button is checked, this will roll the values down; otherwise, it will roll them up.

### Using Functions

&mathemagics; comes with many built-in functions. You can access most of them from the Operations menu. The functions take their arguments from the numbers on the stack.

Alternatively, you can type the name of the function directly into the main line-entry.

### Variables

Variable syntax in &mathemagics; are slightly tricky to use.

Assigning Variables

- `2 $example=` will create the variable example and assign the value 2 to it.

  `2 level $example=` will create the variable example and assign the value of the second stack level to it.

  So, to assign the value on stack level 1 to a variable, write the variable name (prefaced by '$') followed immediately by '='.

Using Variables

- To push the variable example on the stack, simply enter `$example`. In this way, using variables is the same as using any other number in equations. If you enter a variable that has no value assigned to it, nothing is pushed onto the stack.

## Scripting

&mathemagics; can be scripted by defining your own functions.

### Defining Your Own Functions

You can define your own functions in &mathemagics;.

Creating Functions

- `example=2 *` will create the function example. As defined, this function multiplies the bottom stack level by two. Functions can use any variables, and even call other functions

Using Functions

- To use the function example, simply enter `example`. The function will be evaluated.

### Useful Functions for Scripting

There are a few useful built-in functions that you can use when scripting &mathemagics;. Of course, all other built-in functions are also available for use.

Function | Arguments | Result
`reqargs` | 1: number of required arguments | stops function execution if stack does not have enough arguments
`stopif` | 1: whether or not to stop (1 for true ($true), anything else for false ($false)) | stop function execution if specified
`at` | 1: level number (0-indexed) | drops stack level 1; pushes value of stack level onto stack
`level` | 1: level number (1-indexed) | drops stack level 1; pushes value of stack level onto stack

## Notes on Specific Functions

Some built-in functions in &mathemagics; require extra explanation. This follows.

### Left Shift (lsh) and Right Shift (rsh)

`lsh` left shifts the integer part of the displayed value (multiplies it by 2) n times, where n is the next input number, and gives an integer result:

- `10 3 lsh` gives 80 (10 multiplied by 2 three times).

  `10.345 3 lsh` also gives 80.

`rsh` right shifts the value (performs an integer divide by 2) n times.

- `16 2 rsh` gives 4 (16 divided by 2 twice).

  `16.999 2 rsh` also gives 4.

### And, Or and XOr

The `and`, `or` and `xor` functions perform bitwise logical operations and therefore appear more meaningful if the Base is set to Hexadecimal, Octal or Binary rather than Decmal. In the following examples Base is set to Binary.

`and` does a logical AND.

- `101 110 and` gives 100

`or` does the logical OR.

- `101 110 or` gives 111

`xor` performs the logical XOR (exclusive OR) operation.

- `101 110 xor` gives 11

## Questions and Answers

How do I get pi=3.1415926...?

There is a predefined variable pi. To use it, enter `$pi`.

How do I get e, the Euler number?

There is a predefined variable e. To use it, enter `$e`.

## Credits and License

&mathemagics; Program copyright 2001-2002 Jason Katz-Brown jason@katzbrown.com.

Documentation copyright 2002:

- Jason Katz-Brown jason@katzbrown.com

&underFDL;

## Installation

&mathemagics; is part of the &tde; project. For more details about &tde; visit http://trinitydesktop.org.

&mathemagics;'s website is https://mirror.git.trinitydesktop.org/gitea/TDE/mathemagics

### Compilation and Installation

In order to compile and install &mathemagics; on your system, type the following in the base directory; distribution:

    % mkdir -p build
    % cd build
    % cmake ../
    % make
    % make install

Since &mathemagics; uses cmake you should have not trouble compiling it. Default options for cmake build are available in the INSTALL file.