literate-calc-mode
display live =calc= results inline.
#+TITLE: Literate Calc Mode
Literate programming for =M-x calc=. There is an [[https://blog.sulami.xyz/posts/literate-calc-mode/][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.
#+caption: Demo [[file:./scrot.png]]
- Installing
Simply grab it from [[https://melpa.org/][MELPA]].
** [[https://github.com/jwiegley/use-package][use-package]]
#+begin_src emacs-lisp (use-package literate-calc-mode :ensure t) #+end_src
** [[https://github.com/raxod502/straight.el][straight.el]]
#+begin_src emacs-lisp (straight-use-package 'literate-calc-mode) #+end_src
** package.el
[[https://melpa.org/#/getting-started][Ensure you have MELPA available.]]
=M-x package-install=, select =literate-calc-mode=.
** Manual
Just fetch [[file:literate-calc-mode.el][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-modesrcblocksliterate-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:
#+begin_src fundamental Flour = 500g => Flour: 500 g #+end_src
Unit conversion (and other complex functions) can be used by invoking the matching [[https://www.gnu.org/software/emacs/manual/html_node/calc/Function-Index.html][Algebraic Function]].
#+begin_src fundamental = usimplify(1m + 3mm) => 1.003 m #+end_src
You can also use unknown mathematical symbols:
#+begin_src fundamental = x*2 + x-3 => 3 x - 3 #+end_src
** Solving equations
Equations can be solved with calc's solve function. For example, this
is solving for =y=:
#+begin_src fundamental y = solve(2y + 3 = 10, y) => y: 3.5 #+end_src
For now, solve expressions need to be the only expression within a
line to get evaluated correctly, so x = 5 + solve(.. will not work as
intended.
** 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:
#+begin_src fundamental a0 = 2#11001100 => a0: 16#CC a1 = 2#11110000 => a1: 16#F0 = and(a0, a1) => 16#C0 #+end_src
- Full Example
#+begin_src fundamental 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]
#+end_src
- Roadmap
There are some additional features I'm currently thinking about.
** Semantic Highlighting
One of the original inspirations was [[http://tydligapp.com/][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 [[https://github.com/Fanael/rainbow-identifiers][rainbow-identifiers]], which is one of the [[https://github.com/ankurdave/color-identifiers-mode][shorter existing implementations]] around, and adapt that to our needs.