Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

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.



Simply grab it from MELPA.


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


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


Ensure you have MELPA available.

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


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


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

literate-calc-mode-idle-timeHow long to wait after typing to recalculate results
literate-calc-mode-inhibit-line-functionsHook functions called for each line to test whether to inhibit calculation
literate-calc-mode-radixDefault radix/base for results
literate-calc-max-buffer-sizeMaximum buffer size to activate the minor mode

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:

Prevents evaluation inside org-mode src blocks
Prevents evaluation inside org-mode LaTeX fragments

Of course you can also just setq 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.


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-lineEvaluates a single line
M-x literate-calc-eval-bufferEvaluates the whole buffer
M-x literate-calc-insert-resultsEvaluates the whole buffer and inserts results
M-x literate-calc-clear-overlaysRemoves all overlays and clears variables
M-x literate-calc-remove-resultsRemoves all results and clears variables
M-x literate-calc-set-radixSets 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

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

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

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

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


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.