Literate Calc Mode

Literate programming for M-x calc. There is an announcement blog post.

Displays inline results for calculations, supports variables and updates as you type (if you want). Also works in your favourite markup mode.

Installing

Simply grab it from MELPA.

use-package

(use-package literate-calc-mode
  :ensure t)

straight.el

(straight-use-package 'literate-calc-mode)

package.el

Ensure you have MELPA available.

M-x package-install, select literate-calc-mode.

Manual

Just fetch literate-calc-mode.el, save it somewhere and load it into Emacs.

Configuration

There is a M-x customize group named after the mode which contains the following options:

literate-calc-mode-idle-time	How long to wait after typing to recalculate results (buffer-local)
literate-calc-mode-inhibit-line-functions	Hook functions called for each line to test whether to inhibit calculation (buffer-local)
literate-calc-mode-radix	Default radix/base for results (buffer-local)
literate-calc-mode-max-buffer-size	Maximum buffer size to activate the minor mode
literate-calc-usimplify-results	Apply usimplify to all results implicitly (buffer-local)
literate-calc-equals	The string used to indicate a result (default: ” => “)
literate-calc-mode-result-face	The face used when inserting results into the buffer
literate-calc-mode-identifier-face	The face used to highlight variables during assignment
literate-calc-mode-extra-options	Pass extra options to calc-eval (buffer-local) (default: '(calc-group-digits t))

The idle time prevents lag due to constant recalculation in the middle of typing, defaulting to 1 second.

These are the available inhibitors, which are all enabled by default:

literate-calc-mode-inhibit-in-src-blocks

Prevents evaluation inside org-mode src blocks

literate-calc-mode-inhibit-in-latex

Prevents evaluation inside org-mode LaTeX fragments

Of course you can also just setq / setq-default the options directly.

Calc Configuration

Because LCM uses Emacs calc under the hood, a lot of configuration options for calc also affect LCM operation.

An interesting one is calc-multiplication-has-precedence, which when non-nil means that multiplication will have higher precedence than division, which can lead to surprising results.

You can also use literate-calc-mode-extra-options to pass extra options to calc-eval. This can be used to for example change the digit grouping (calc-group-digits) or the word size (calc-word-size).

Use

There is both a major literate-calc-mode and a minor literate-calc-minor-mode. The major mode does some basic syntax highlighting, while the minor mode only evaluates all calc statements while typing.

The minor mode works quite well with org-/markdown mode or other markup language major modes.

There are also some functions which can be called without any mode being active:

M-x literate-calc-eval-line	Evaluates a single line
M-x literate-calc-eval-region	Evaluates within the selected region
M-x literate-calc-eval-buffer	Evaluates the whole buffer
M-x literate-calc-insert-results	Evaluates the whole buffer and inserts results
M-x literate-calc-remove-results	Removes all results and clears variables
M-x literate-calc-kill-result	Evaluates the current line and pushes the result to the kill ring
M-x literate-calc-clear-overlays	Removes all overlays and clears variables
M-x literate-calc-set-radix	Sets the radix/base output for the current buffer

Using Units

You can simply append units to your values like so:

Flour = 500g => Flour: 500 g

Unit conversion (and other complex functions) can be used by invoking the matching Algebraic Function.

= usimplify(1m + 3mm) => 1.003 m

You can also use unknown mathematical symbols:

= x*2 + x-3 => 3 x - 3

Evaluation in Org

Org-mode source blocks can be evaluated (C-c C-c by default).

If :results is set to value, which is the default, a block returns its last result. If :results is set to output, it will return the entire block, annotated with results.

Local variables can be defined in header arguments as :var a=38 b=4.

Changing radix/base

You can change the literate-calc-mode-radix custom variable to set the default base for number output globally for all literate-calc-mode buffers, but it’s also possible to change the output radix of the current buffer by calling the interactive function literate-calc-set-radix in your desired buffer. For example, M-x literate-calc-set-radix 16 will display results with base 16 (hex).

Example output with radix set to 16:

a0 = 2#11001100 => a0: 16#CC
a1 = 2#11110000 => a1: 16#F0
= and(a0, a1) => 16#C0

Full Example

This is a literate calc file.

Lines without "=" are ignored.

All results starting with "=>" are an overlay generated by
literate-calc-mode. That means they are displayed in Emacs, but not
actually in the buffer/file contents.

We can calculate a value like so:

= 2 + 2 => 4

If there is any string on the left hand side, it becomes a bound
variable.

Pi = 3.14159 => Pi: 3.14159

We can use this variable below the definiton.

Tau = Pi * 2 => Tau: 6.28318

Results are calculated using Emacs' own calc, so you can use formulas
as well.

= round(Pi, 2) => 3.14

Later bindings shadow earlier ones:

Pi = 3 => Pi: 3

= Pi => 3

Variable names can have spaces as well:

Monthly Expenses = 500 => Monthly Expenses: 500

Monthly Income = 1000 => Monthly Income: 1000

Annual Savings = 12 * (Monthly Income - Monthly Expenses) => Annual Savings: 6000

All values are recalculated on every update in a spreadsheet-like
fashion.

Calc also has a lot of advanced features, like arrays:

Numbers = [1 2 3] => Numbers: [1, 2, 3]

= 3 Numbers => [3, 6, 9]

Roadmap

There are some additional features I’m currently thinking about.

Semantic Highlighting

One of the original inspirations was Tydlig, which does similar things, but also has semantic highlighting. That means, variables are highlighted in different colours, but always the same one for a given variable, so that you can see where it’s used at a glance.

I might steal some code from rainbow-identifiers, which is one of the shorter existing implementations around, and adapt that to our needs.