Catena commands and the standard library

A sequence is a short program you write in Catena, Castiel's built-in scripting language. Most of a sequence is ordinary arithmetic — the same expressions you would type into the calculator — but a sequence also needs to talk: to ask you for a value, to show a result, to keep a record on the paper tape, and to reach the built-in mathematical functions. It does that through commands and the standard library.

This chapter teaches those building blocks concept-first. It covers how a sequence gets input from you, the three ways it can produce output, the answer register that lets one line feed the next, and the families of ready-made functions you can call. It stops at a readable summary of the functions grouped by family; the exhaustive, one-row-per-function table lives in the Catena reference.

If you have not yet met sequences, read Bags first for the one container type these commands work with, then come back here.

Commands are verbs

Everything in a sequence is either a value, an expression, or a command. A command is a verb: PROMPT asks, DISPLAY shows, PRINT records, OUT does both. You write the verb, then its arguments. Two conventions make commands read like plain instructions rather than code:

• Brackets are optional. SQRT 2 and SQRT(2) are the same call; PRINT "Done" needs no parentheses. Use brackets when they make a line clearer or when you need to group arguments, and leave them off when the line reads fine without them.
• The arrow -> sends a result somewhere. A line that produces a value can end with -> name to store the value under that name. You will see this on input (PROMPT ... -> price) and on plain results alike.

Command names are written here in the form Castiel treats as canonical. A subset of functions also answer to a second, calculator-style spelling (an alias); where that matters it is noted, and the full alias list is in the Catena reference.

Getting input: PROMPT and ASK

PROMPT stops the sequence, shows a question, and waits for you to type an answer. The answer is sent to a variable with ->:

PROMPT "Net price?" -> price

ASK is the same command under a second name — use whichever reads better in your sequence.

Declaring the expected type. Add AS <type> and Castiel validates what you typed before accepting it:

PROMPT "Your age?" AS Int -> age

If the entry is not valid for the declared type — letters where a whole number was asked for, say — the sequence does not guess or silently convert. It re-asks with a short hint and waits again, so a sequence can never carry a bad value forward from a mis-typed answer.

Showing results: DISPLAY, PRINT, and OUT

A sequence has two places it can send output: the main output area on screen, and the shared paper tape — the running, auditable log that every mode writes into (see the paper tape). Three commands cover every combination of the two:

DISPLAY "Item price in EUR: " itemPrice
PRINT "Sum over 5000 — VAT +5%"
OUT total

DISPLAY is for the answer you want to read right now; it does not clutter the tape. PRINT is for the record — a heading, an assumption, a note explaining why a step was taken — without disturbing the on-screen answer. OUT exists so the everyday "show it and also keep it" case is one line instead of two near-identical ones.

Concatenation for presentation. When you place a piece of text and a value next to each other on an output line — "Item price in EUR: " itemPrice — they are joined into one readable string. This joining is presentation only: it happens in DISPLAY, PRINT, and OUT, and it does not turn the number into text anywhere else in your sequence. It is simply how you label a value for the person reading it.

Because PRINT and OUT write to the same tape as hand calculations, a sequence's output sits in the running log alongside everything else you have done, and you can scroll back through a whole worked problem later. Editing and exporting that tape is covered in the paper tape.

The answer register: Ans, STO, and RCL

Physical calculators keep the last result in an Ans key so you can build the next calculation on it. Catena works the same way, and extends it to a short history of recent answers.

Bare Ans is the latest result. Any line that produces a value but does not store it — a plain price * 1.23 on its own — is shown inline and becomes the newest Ans. This is the sequence equivalent of pressing =. Writing Ans on a later line pulls that value back:

120 * 1.05      # a plain result line: shown, and pushed onto Ans
Ans -> subtotal # store the latest answer into a variable

Reaching older answers. Ans is a small history, newest first. Ans[2] is the answer before the latest, Ans[3] the one before that; Ans2 and Ans3 are shorter names for the same two. Bare Ans always means the most recent — it is the one deliberate shorthand, chosen because "Ans = the last answer" is how every calculator behaves.

Ans      # the latest result
Ans[2]   # the previous result (also written Ans2)
Ans[3]   # the one before that  (also written Ans3)

Ans is filled by Castiel and is read-only to your sequence: you can read it and copy from it, but you cannot assign into it. When you store from it (Ans -> total), the value is copied out, so total keeps its number even as newer results push Ans along. How many answers the history keeps is a Castiel setting.

STO and RCL. For users coming from a physical calculator, STO and RCL mirror the store and recall keys. STO -> total is the same as Ans -> total; RCL total reads the value back. They are familiar names over ordinary storing and reading — use them or the plain -> form, whichever you prefer.

The math functions

The standard library gives every mathematical function the calculator knows, callable by name from a sequence. Names are lowercase — sin, sqrt, log — and brackets around the argument are optional. Some functions additionally accept an uppercase or calculator-style spelling (for example sqrt also answers to SQRT, log to LOG, and the combinatorics functions to nCr / nPr); those extra spellings are listed per function in the Catena reference, which is the exhaustive table. This chapter groups them so you know what exists.

• Elementary arithmetic — sqrt, cbrt, nthroot, square, cube, pow, abs, sign, and the reciprocal. The building blocks for everyday expressions.
• Rounding and parts of a number — round, floor, ceil, trunc, frac, and fixed-decimal rounding. These control how a value is cut down to whole numbers or fixed places.
• Trigonometry — sin, cos, tan, their reciprocals cot, sec, csc, the inverses asin, acos, atan (and atan2), plus the hyperbolic family sinh, cosh, tanh and their inverses. These read the active angle mode exactly as they do on the keypad; the theory and the mode trap are covered in the trigonometry chapter.
• Logarithms and exponentials — log (base ten), ln (natural), a general log_a for any base, and the exp family.
• Angle and coordinate conversions — deg2rad / rad2deg and the gradian pairs, degrees-minutes-seconds conversions, and the polar/rectangular pair pol / rec. These always perform the named conversion regardless of the current angle mode.
• Number theory and combinatorics — gcd, lcm, mod, permutations and combinations, prime factorisation, and fraction simplification.
• Factorials — factorial (the x! key), and the double factorial.

Each function takes a fixed number of arguments and returns a value you can store, display, or feed into the next expression. Where an argument is outside a function's valid range — the square root of a negative real, or a tan at an angle where it is undefined — Castiel reports a domain error rather than returning a meaningless number.

Aggregates: working across a whole bag

When your data is a bag — Catena's one collection type — five aggregate commands summarise it in a single call, which is the idiomatic alternative to writing a loop:

prices = {12.50, 8.00, 21.30}
OUT "Total: " SUM(prices)
OUT "Average: " AVERAGE(prices)
OUT "Items: " COUNT(prices)

Each takes one bag and gives back a single value. Bags, and the richer filter-and-map operations that go beyond these five, are the subject of the Bags chapter.

Currency and other host conversions

Some standard commands reach outside the calculator for live data. CURRENCY converts an amount between two currencies using current rates:

CURRENCY("USD", 49.99, "EUR") -> inEuros
OUT inEuros

You give it the source currency, the amount, and the target currency, and it returns the converted value. CURRENCY is a ready-made command built on Castiel's general facility for calling out to host services; the mechanism behind it, and the other connector-backed commands, are described in Connectors and the API.

Worked examples

Example 1 — ask, compute, show and record. Prompt for a net price, add 20 percent tax, and put the gross on both the screen and the tape:

PROMPT "Net price?" AS Number -> net
tax = net * 0.2
OUT "Gross: " net + tax

OUT shows the labelled gross on screen and files the same line to the paper tape, so the calculation is both answered and recorded in one step.

Example 2 — chaining with Ans. Total a price with a 5 percent surcharge, then add fixed postage, using the previous answer to carry the running figure forward:

120 * 1.05      # 126.00 — shown, and now the latest Ans
Ans + 3.50      # 129.50 — adds postage to the previous answer
OUT Ans         # show and record the final figure

Each plain result line becomes the new Ans, so the next line reads it without you naming an intermediate variable.

Example 3 — summarising a bag. Given a short list of readings, report the count, total, and average:

readings = {4.2, 5.1, 3.8, 6.0}
OUT "n = " COUNT(readings)
OUT "sum = " SUM(readings)
OUT "mean = " AVERAGE(readings)

Three aggregate calls replace what would otherwise be a loop with a running total and a counter.

See also

• Bags — the one container the aggregates and queries work on.
• Catena reference — the exhaustive, per-function table with every name and alias.
• The paper tape — where PRINT and OUT file their records, and how to edit and export them.
• Connectors and the API — the host-call facility behind CURRENCY and the other external commands.