Skip to content

sulami/literate-calc-mode.el

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

91 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Literate Calc Mode

https://melpa.org/packages/literate-calc-mode-badge.svg

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.

./scrot.png

Installing

Simply grab it from MELPA.

(use-package literate-calc-mode
  :ensure t)
(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-timeHow long to wait after typing to recalculate results (buffer-local)
literate-calc-mode-inhibit-line-functionsHook functions called for each line to test whether to inhibit calculation (buffer-local)
literate-calc-mode-radixDefault radix/base for results (buffer-local)
literate-calc-mode-max-buffer-sizeMaximum buffer size to activate the minor mode
literate-calc-usimplify-resultsApply usimplify to all results implicitly (buffer-local)
literate-calc-equalsThe string used to indicate a result (default: ” => “)
literate-calc-mode-result-faceThe face used when inserting results into the buffer
literate-calc-mode-identifier-faceThe face used to highlight variables during assignment
literate-calc-mode-extra-optionsPass 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-lineEvaluates a single line
M-x literate-calc-eval-regionEvaluates within the selected region
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-remove-resultsRemoves all results and clears variables
M-x literate-calc-kill-resultEvaluates the current line and pushes the result to the kill ring
M-x literate-calc-clear-overlaysRemoves all overlays 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
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.