epher user guide

Welcome! epher is a programmable, scriptable calculator. You can use it for a quick calculation, or build up your own functions and small programs — and everything is available in six languages.

This guide is for complete beginners. It starts with the simplest possible calculation and builds up to the full power of the language. Every example shows what you type and what epher answers.

There are four ways to use epher — pick whichever suits you:

The desktop app, the command line, and the terminal UI are one program: a single download installs the epher command, which does all three. The web app is the exception — it needs no download at all.

All four versions understand exactly the same language. Learn it once, use it anywhere.

1. The epher language

This chapter teaches the language shared by every version of epher. In the web app or desktop app, type an expression and press Enter (or click the = button). In the CLI, start the session with epher repl and type after the epher> prompt. In the TUI (epher tui), just type and press Enter. In the CLI you can also write epher "expression" to evaluate one expression directly.

1.1 Your first calculation

Type this:

2 + 3 * 4

epher answers:

14

Multiplication is done before addition, exactly like in mathematics. That rule is called operator precedence.

1.2 Order of operations

The full precedence order, from strongest to weakest:

1. ! factorial
2. ^ power
3. * and / multiplication and division
4. + and - addition and subtraction

Use parentheses to change the order:

(2 + 3) * 4

20

The ^ operator computes powers, and it works right-to-left:

2 ^ 10

1024

2 ^ 3 ^ 2

512

(2 ^ 3 ^ 2 means 2 ^ (3 ^ 2), which is 2 ^ 9 = 512.)

Powers can be fractional — 2 ^ 0.5 is the square root of 2:

2 ^ 0.5

1.4142135623730951

Subtraction and division work left-to-right:

10 - 3 - 2

5

1.3 The special numbers pi, e, tau and phi

The famous constants are built in:

pi

3.141592653589793

2 * pi

6.283185307179586

e

2.718281828459045

Two more: tau is a full turn (2 pi), and phi is the golden ratio:

tau

6.283185307179586

phi

1.618033988749895

1.4 Comparing and logic

You can compare numbers. The result is either true or false:

3 > 2

true

1 != 2

true

Combine comparisons with and, or and not:

3 > 2 and 2 < 3

true

not 3 > 2

false

1.5 Variables

Give a name to a value with a single =:

x = 5

5

epher repeats the value back to you. From now on, x can be used anywhere:

x ^ 2

25

You can change a variable whenever you like — it keeps its value until you change it:

x = x + 1

6

Names can contain letters and underscores, like radius or my_total. They cannot contain spaces or start with a number.

1.6 Decisions with if

if chooses between two values:

if 3 > 2 then 10 else 20

10

The shape is always if condition then value_if_true else value_if_false. The else part is required.

A more useful example with a variable:

price = 100
if price > 50 then 2 else 1

2

epher does not have text values — both branches of an if must be numbers (or the results of comparisons).

1.7 Loops with while

while repeats a statement as long as a condition holds:

x = 0; while x < 5 do x = x + 1; x

5

Read that script as: start x at 0; while x is less than 5, add 1 to x; then show x. The result is 5 because the loop ran five times.

Safety net: epher stops any loop after 100,000 steps and shows error: step limit exceeded. That protects you from loops that would never end. If you see it, your condition probably never became false.

1.8 Your own functions with def

A function is a calculation with a name and parameters:

def f(x) = x ^ 2

Then use it:

f(7)

49

Functions can take several parameters:

def area(w, h) = w * h
area(3, 4)

12

You can also define a function with no parameters:

def answer() = 42
answer()

42

1.9 Recursion: a function that calls itself

The most famous example — the Fibonacci numbers:

def fib(n) = if n <= 1 then n else fib(n - 1) + fib(n - 2)

fib(10)

55

fib(10) is the 10th Fibonacci number. The function calls itself with smaller arguments until it reaches n <= 1. This works because the if ... then ... else ... form only calculates the branch it needs.

A function's body is a single expression — one line. Combine several calculations with ; in a script instead (next section).

1.10 Scripts: several statements at once

A script is several statements joined with ;, executed one after another:

x = 10; y = x + 5; x + y

25

Scripts are how you build small programs: set up variables, loop, and show a final result.

1.11 Exact results: frac, dec and big

Normally epher calculates with decimal numbers like a pocket calculator. Some numbers look better exact.

frac(n, d) makes an exact fraction:

1 / 3

0.3333333333333333

frac(1, 3)

1/3

Fractions stay exact through calculations:

frac(1, 3) * 3

1

dec(x) makes an exact decimal. Compare these two:

0.1 + 0.2

0.30000000000000004

dec(0.1) + dec(0.2)

0.3

The first result is the tiny rounding error every computer makes with decimal numbers. dec() removes it.

big(x) makes an exact whole number, for values too large for a pocket calculator:

big(10 ^ 20)

100000000000000000000

1.12 Built-in functions

epher has the functions of a scientific calculator, grouped by family.

Trigonometry works in radians — use deg and rad to convert:

Powers, roots and logarithms (on a calculator log is base 10):

Rounding, signs and whole numbers:

Statistics take any number of arguments:

The exact layers from section 1.11 stay:

They combine like everything else:

min(sqrt(16), 5)

4

1.13 Reading errors

When something goes wrong, epher tells you instead of guessing:

1 / 0

error: division by zero

sqrt(-4)

error: domain error: sqrt of negative number -4

unknown_name

error: unknown name: unknown_name

foo(1)

error: unknown name: foo

The last example is important: epher tells you exactly which name it does not know, so you can fix your expression.

1.14 Quick reference

2. The web app (PWA)

2.1 Opening it

The web app lives at:

https://epher.org/pwa/

No installation is needed — it works in any modern browser on a computer, phone, or tablet.

2.2 Your first calculation

1. Click the text field (it is already focused when the page loads).
2. Type an expression, for example 2 + 3 * 4.
3. Press Enter or click the = button.

The result appears in large text below the field. Everything from chapter 1 works here, including variables, functions, and scripts.

2.3 History

Every calculation is added to the history list beneath the result, so you can scroll back and see what you did. The history is kept while the page is open.

2.4 Graphing

Type graph followed by an expression and press Enter:

graph x ^ 2

epher draws the curve y = f(x) from x = −10 to x = 10 beneath the input, with a caption showing what was plotted. You can graph any expression, including your own functions:

def f(x) = x ^ 3
graph f(x)

Points where the expression has no value (a division by zero, for example) are skipped, leaving a gap in the curve.

2.5 Installing it and using it offline

The web app is a progressive web app: after one visit it works fully offline, and you can install it like a normal app.

• Chrome, Edge, or Android: click the install icon in the address bar (or Install app in the browser menu), then confirm.
• iPhone / iPad (Safari): tap Share → Add to Home Screen.
• Other browsers: look for Install or Add to Home Screen in the menu.

Once installed, launch it from your home screen or app list — it opens instantly, even with no internet connection.

2.6 What the web app does not do

The web app is intentionally simple: it evaluates expressions and keeps a session history. The save, save script, and language commands work in the desktop, command line, and terminal versions (chapters 3, 4, and 5) — in the web app they answer with a note that saving works there. The history is not saved between visits.

3. The desktop app

The desktop app is a normal window around the same web app. Everything in chapter 2 applies; the difference is only how you install and start it.

3.1 Installing

Download one installer for your system from the epher website:

• Windows: run epher-windows-x86_64.exe. The installer puts epher on your PATH — open a new CMD or PowerShell window and epher "2 + 2" works. Because the build is not signed, choose More info → Run anyway on the first launch.
• macOS: open epher-macos-aarch64.dmg and drag epher into Applications. Because the build is not signed, the first launch needs a right-click → Open.
• Linux (Debian/Ubuntu): the .deb package

sudo apt install ./epher-linux-x86_64.deb

• Linux (Fedora/RHEL): the .rpm package

sudo dnf install ./epher-linux-x86_64.rpm

• Linux (any distro, including Arch): the AppImage — make it executable and run it:

chmod +x epher-linux-x86_64.AppImage
./epher-linux-x86_64.AppImage

Every installer contains the whole epher — the desktop app, the command line (chapter 4), and the terminal UI (chapter 5) — as the single epher command. On Linux, the package puts epher in /usr/bin.

3.2 Using it

Launch epher like any other application. You get a window with the same interface as the web app: type an expression, press Enter or click =, and read the result. Graphing works here too — graph x ^ 2 draws in the window (chapter 2.4). The window can be resized freely.

You can also open it from a terminal: a bare epher (or epher gui) starts the desktop app. On macOS, use the Install the epher command button inside the app to put epher on your terminal PATH.

3.3 Storage: one store with the CLI and TUI

The desktop app shares its storage with the command line and terminal versions. Functions, scripts, history, and the language preference live in one place — ~/.epher on your computer (or EPHER_STORE_DIR, chapter 4.6) — and everything saved in one version is available in the others:

def area(w, h) = w * h
save area

Define area in the desktop app, save it, close the window — then open the CLI and area(3, 4) just works. It works the other way too: functions and scripts you saved in the CLI or TUI are already there when the desktop window opens, including variables set by saved scripts. The save, save script, and language commands from chapter 4 work exactly the same here.

The web app in the browser is the one version that does not use this storage — it keeps each session to itself (chapter 2.6).

4. The command line (CLI)

The CLI is the text side of the same epher program as the desktop app. It has three modes: one-shot evaluation, piped scripts, and an interactive session for longer work.

4.1 One-shot calculations

Give the expression as an argument:

epher "2 + 3 * 4"

14

You can do anything from chapter 1 that is a single expression:

epher "if 3 > 2 then 10 else 20"

10

An expression that starts with a minus sign works directly:

epher "-2 + 5"

3

One-shot mode evaluates exactly one expression. Statements — variables, functions, loops — need the interactive session or a piped script (section 4.2).

4.2 Piped scripts

epher - reads expressions from standard input, one line at a time — the way scripting languages are used in pipelines:

printf "x = 3\nx * 10\n" | epher -

= 3
= 30

Everything from chapter 1 works, and the lines share one session: a function defined on an early line is available later, and save writes to the same store as always. Errors print and the script keeps going.

4.3 The interactive session (REPL)

Start it with epher repl:

epher repl

A bare epher with no arguments opens the desktop app (chapter 3).

epher prints its prompt and waits:

epher>

Now type anything from chapter 1, one line at a time. Variables keep their values between lines:

epher> x = 5
= 5
epher> x ^ 2
= 25

Each answer is shown as = result. To leave, type quit (or exit):

epher> quit

Your history is remembered: the next time you run epher repl, the previous session's lines are still there.

4.4 Saving functions and scripts

Define a function, then save it:

epher> def fib(n) = if n <= 1 then n else fib(n - 1) + fib(n - 2)
epher> save fib
saved fib

The save fib command stores the function on disk. Next time you start the session, fib is already defined:

epher> fib(10)
= 55

To save a whole script (the last line you typed) use save script:

epher> x = 0; while x < 5 do x = x + 1; x
= 5
epher> save script count_to_five
saved script count_to_five

Saved scripts run automatically when epher starts, so anything they define is ready for you.

4.5 Changing the interface language

The interface language is chosen from the languages you set on your device. To override it, type language followed by one of: en, zh-CN, hi, es, fr, ar:

epher> language fr
language set to fr

The choice is remembered for next time. Note: the language you type — the expression language — is always the same, in any interface language.

4.6 Where your data lives

Functions, scripts, history, and your language choice are stored in one folder on your computer:

~/.epher

Delete that folder to start completely fresh. To use a different location, set the environment variable EPHER_STORE_DIR before starting epher:

EPHER_STORE_DIR=/tmp/my-epher epher repl

5. The terminal UI (TUI)

The TUI is a full-screen version of the interactive session, inside your terminal. It is part of the same epher program — start it with:

epher tui

5.1 The screen

The screen is divided into panels:

• Expression — the input line (top).
• The current result right below it.
• History — every line you entered, with its answer.
• Graph — the plot from the graph command (bottom).
• A hint line shows the keyboard shortcuts.

5.2 Keys

5.3 Graphing

Type graph followed by an expression, and press Enter:

graph x ^ 2

epher samples the curve from x = −10 to x = 10 and draws it as an ASCII plot in the Graph panel. The caption above the plot shows what is plotted: y = x ^ 2.

You can graph any expression, including your own functions — first define one, then graph it:

def f(x) = x ^ 3
graph f(x)

Points where the expression has no value (for example division by zero) are simply skipped, leaving a gap in the plot.

5.4 Saving and persistence

The TUI shares its storage with the CLI: everything saved in one is available in the other. Functions, scripts, history, and the language preference live in ~/.epher (chapter 4.6), and the same save, save script, and language commands work here.

6. Your data and privacy

• The installed epher program — desktop app, CLI, and TUI — stores functions, scripts, history, and the language choice locally in ~/.epher (or EPHER_STORE_DIR). Nothing leaves your computer.
• The web app keeps nothing on disk: history lasts only while the page is open. The web app can work offline because the page itself is stored by your browser.

All four versions run the calculation entirely on your device — nothing is sent anywhere.