CLAC(1)

📦 version 0.3.5, in nixos 26.05, nixpkgs unstable

💅 CLAC(1) — the command line, stack-based calculator with postfix notation ✨

okay so picture this: a calculator, but make it iconic. That's clac, bestie — a stack-based calculator with postfix notation that lives in your terminal, and yes this is section 1 of the manual, we're doing this properly 🎀

🌸 NAME 🌸

clac — a command line, stack-based calculator with postfix notation. Literally that's it, that's the whole vibe. 🦋

✨ SYNOPSIS ✨

clac [expression]

💖 DESCRIPTION 💖

clac is a command line, stack-based calculator with postfix notation that displays the stack contents at all times. The way it just... shows you everything, constantly? Obsessed. As you type, stack changes are reflected immediately. No cap, you literally watch the math happen. 😭

So here's the tea on how a stack-based postfix calculator works: entering a number pushes it on a stack, and arithmetic operations pop their arguments from the stack and push the result. Since every operation takes a fixed number of arguments, there's zero room for ambiguity — parentheses and operator precedence are simply not needed. Postfix notation is also known as reverse Polish notation, or RPN. iykyk 💅

🫶 Non-interactive mode

If an expression is provided, clac will process it and print each element in the stack starting from the top. It will then exit immediately. Boom, done, bye. ✨

🎀 Commands

When a command requires an argument, it pops a value from the stack. If the stack is empty, a zero is provided instead — yes, a lil freebie zero, no big deal. 🍓

In the descriptions below, the top of the stack (and thus the first value popped) is represented by the letter a, while the second value popped is represented by the letter b. For example, if the stack is composed of the numbers 1, 2 and 3 (with 3 at the top of the stack), when we describe the sum then a will be 3 and b will be 2.

⚠️ It is important to note that subtraction and division invert the order of the arguments before performing the operation: with 1, 2 and 3 in the stack, when you type - it will pop the values 3 and 2 and push the result of 2 - 3. This is in the tradition of other postfix calculators and programming languages. Not a bug, it's heritage. 💀

A description of the available commands follows. Buckle up. 👑

🔥 Arithmetic operations

  • + — Pop two values a and b and push the result of a + b.
  • - — Pop two values a and b and push the result of b - a.
  • * — Pop two values a and b and push the result of a * b.
  • / — Pop two values a and b and push the result of b / a.

🧚 Modulo operation

  • % — Pop two values a and b and push the remainder of the Euclidean division of b by a.

⭐ Exponentiation

  • ^ — Pop two values a and b and push the result of b ^ a.
  • exp — Pop the value a and push the result of e ^ a.

🌈 Logarithm

  • ln — Pop the value a and push its natural logarithm.
  • log — Pop the value a and push its logarithm to base 10.

🎀 Factorial

  • ! — Pop the value a and push its factorial.

🦋 Trigonometry

  • sin — Pop the value a and push its sine.
  • cos — Pop the value a and push its cosine.
  • tan — Pop the value a and push its tangent.
  • asin — Pop the value a and push its arc sine.
  • acos — Pop the value a and push its arc cosine.
  • atan — Pop the value a and push its arc tangent.
  • atan2 — Pop two values a and b and push the arc tangent of b / a, using the signs of a and b to determine the quadrant. Look at it being all thorough 🫶

💜 Error function

  • erf — Pop the value a and push its error function.

🌸 Summation

  • sum — Pop all the values in the stack and push their sum.
  • add — Pop the value a and remove that many items from the stack. Push their sum.

🍓 Product

  • prod — Pop all the values in the stack and push their product.
  • mul — Pop the value a and remove that many items from the stack. Push their product.

✨ Rounding

  • ceil — Pop the value a and push the smallest integer value greater than or equal to a.
  • floor — Pop the value a and push the largest integer value less than or equal to a.
  • round — Pop the value a and push the integer value closest to a.

🎀 Absolute value

  • abs — Pop the value a and push the non-negative value of a.

💅 Binary operations

  • and — Pop two values a and b and push the binary AND of a and b.
  • or — Pop two values a and b and push the binary OR of a and b.
  • xor — Pop two values a and b and push the binary XOR of a and b.

👑 Stack manipulation

  • swap — Pop two values a and b and push the values a, b.
  • dup — Pop the value a and push the values a, a.
  • roll — Pop two values a and b and rotate b elements in the stack a times.
  • drop — Remove the top of the stack. bye bestie 👋
  • clear — Remove all the elements in the stack.
  • count — Push the number of items in the stack.
  • _ — Push on the stack the result of the last operation. your little memory-keeper 🥺

🧺 Stashing

  • stash — Pop the value a and move that many items to the stash.
  • fetch — Pop the value a and move that many items from the stash.
  • . — Stash the top of the stack.
  • , — Fetch one stashed item.
  • : — Stash all the items in the stack.
  • ; — Fetch all stashed items.

🕰️ History

Use C-p / C-n or Up / Down to navigate the history. the nostalgia trip we deserve 💜

🌟 User defined operations

It is possible to define operations (or words, as they are usually called in stack based programming languages) by editing the words configuration file. It is not created by default, but clac will use some environment variables in order to search for word definitions.

  • $CLAC_WORDS — If set, it should point to a file containing word definitions.
  • $XDG_CONFIG_HOME — If set, clac will search for $XDG_CONFIG_HOME/clac/words
  • $HOME — If set, clac will search for $HOME/.config/clac/words

🎨 How to define words

Words are defined as aliases, with one alias on each line. Empty lines are ignored. Here are some examples:

pi 3.14159265358979323846
tau "pi 2 *"
sqrt "0.5 ^"

Note that an alias has two parts: a word to be defined and its meaning. That's why the tau and sqrt definitions are enclosed in double quotes. If the double quotes are removed, clac will complain that it can't parse the command. For example, if we remove the double quotes from sqrt and start clac, we will get this error message:

Incorrect definition: sqrt 0.5 ^
(~/.config/clac/words:3)

User defined words can be used as if they were built-in commands:

$ clac "42 dup * pi *"
5541.76944093239

🙈 Comments

Any lines that begin with # are considered comments and are ignored. There are no inline comments, and any # characters that are not the first character of a line are interpreted literally. To define # as a word, wrap it in double quotes in the definition:

# This is a comment.
"#" count

The first line is ignored, and the second line assigns # to the operation count. sneaky but valid 💅

📋 How to list defined words

If you type words and hit enter, clac will list the defined words. show me the roster bestie 🫶

🔄 How to reload defined words

If you type reload and hit enter, clac will reload the words file. refresh, reset, rebrand ✨

💀 EXAMPLES 💀

While the most interesting aspect of clac is the ability to visualize the stack as it is updated with each key press, at some point you may want use clac just to get a quick result or call it from a script. For that reason, clac can be used in non-interactive mode by invoking it with an argument.

Here are some examples of non-interactive invocations:

$ clac "3 4 +"
7
$ clac "2 3 4 +"
7
2

When clac finishes evaluating the expression "2 3 4 +", there are two elements in the stack: the number 7 at the top of the stack and the number 2 at the bottom of the stack. The elements are printed in order, one per line, starting from the top of the stack. top-down, always, no exceptions 👑

This other example uses the stashing features. Let's say we want to push two numbers and get the result of their multiplication plus the square of the second number.

$ clac "4 3 dup dup * . * , +"
21

Another example that uses the stash would be to get the average of all the elements in the stack:

$ clac "1 2 3 4 count . sum , /"
2.5

In fact, if you find yourself calculating averages very often, you can define the word avg as "count . sum , /". reuse, recycle, slay 🧚

🫶 AUTHOR 🫶

Michel Martens <mail@soveran.com> — ty for the calculator king 💜

and that's the whole page!! 🌈 this gorgeous thing is from May 3, 2017 and it's the CLAC(1) page, so like... go forth and calculate, bestie. mwah 💋✨🎀

📦 where this page comes from