ob-julia-vterm

Ob-julia-vterm provides Org Babel support for the Julia Programming Language.

Babel is a function of the Emacs Org-mode that provides ability of executing code in various programming languages in Org buffers. With ob-julia-vterm, you can embed and execute Julia code and also capture the results in your Org documents.

Installation

You need to have julia-vterm installed in Emacs.

You can install ob-julia-vterm from MELPA. If you want to install it manually, download ob-julia-vterm.el into somewhere in your local directory and install it with the following.

(package-install-file "/path-to-download-dir/ob-julia-vterm.el")

You need to enable julia-vterm code block evaluation by customizing org-babel-load-languages or by adding the following lines to your init file.

(require 'org)
(add-to-list 'org-babel-load-languages '(julia-vterm . t))
(org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)

By default, you need to specify julia-vterm as the language name for source blocks. To use julia as the language name, define the following aliases.

(defalias 'org-babel-execute:julia 'org-babel-execute:julia-vterm)
(defalias 'org-babel-variable-assignments:julia 'org-babel-variable-assignments:julia-vterm)

Features

• A src code block with julia-vterm (or julia if you define the above aliases) specified as language will be executed with C-c C-c (org-babel-execute-src-block). The code is sent to a julia-vterm REPL and the result is inserted below the src code block.
• You can specify value (functional mode, default) or output (scripting mode) for :results.
• Value results use Julia’s print by default. Specify pp in :results for REPL-style text/plain output.
• Long Arrays in value results are truncated using ellipses by default. To show the full result without omission, specify nolimit in the :results header argument.
• For graphics output (plots), specify file and graphics for :results and filename with :file. Then in the code block, save the output image with the filename. A link to the image is inserted as the result. It can be inline-displayed by Org.
  • For inline display of PDF or GIF/PNG animation, see org-inline-pdf and org-inline-anim.
• Session-based evaluation is supported.
  • With :session none, the code block is executed inside a let block.
  • With :session <name>, the code block is executed in the named session.
  • Unlike most other ob-* packages, the buffer name for the Julia session will be automatically formatted as *julia:<name>*. So, you can just specify the pure name, such as main or ses1, for the session name.
• Passing code block arguments using :var is supported.
  • Currently, only a number or a string can be passed.
  • Another code block or a result of a code block can be referred to and used as the argument.
• Execution of julia-vterm code blocks is asynchronous by default and does not block Emacs.
  • As an exception, if you use babel’s :var reference from another block, the referenced julia-vterm block will be executed synchronously.
  • Also, code blocks executed during export when :eval never-export is not specified will be executed synchronously so that the exported document contains their completed results.
  • At this time, it is not possible to explicitly specify synchronous execution.

Helper mode

Enable ob-julia-vterm-helper-mode in Org buffers to use Julia editing and REPL commands directly in source blocks.

(add-hook 'org-mode-hook #'ob-julia-vterm-helper-mode)

The following keys are active in julia-vterm source block bodies, and in julia source block bodies when the aliases above are defined.

• TAB performs Julia LaTeX substitution or indentation.
• RET runs the return key binding from the Julia source edit buffer.
• * inserts a literal asterisk using the standard self-insert command.
• C-<return> sends the active region or current line to the Julia REPL.

The following REPL-related keys are active in julia-vterm source blocks, and in julia source blocks when the aliases above are defined.

• C-c C-z switches to the Julia REPL selected for the current context.
• C-c C-d changes the selected Julia REPL’s working directory to the directory containing the Org file.

In regular Org text and source blocks for other languages, the original Org and minor-mode key bindings remain active.

Set ob-julia-vterm-helper-buffer-wide-repl-keys to non-nil to make C-c C-z and C-c C-d active throughout Org buffers. This overrides Org’s standard bindings for these keys.

Use setq-default to enable this behavior by default for new Org buffers.

Examples

#+BEGIN_SRC julia
2π
#+END_SRC

#+RESULTS:
: 6.283185307179586

#+BEGIN_SRC julia :results output
println("Hello, Julia!")
#+END_SRC

#+RESULTS:
: Hello, Julia!

#+BEGIN_SRC julia :results none :session ses1
x = 12345
#+END_SRC

#+BEGIN_SRC julia :results none :session ses2
x = 67890
#+END_SRC

#+BEGIN_SRC julia :results value :session ses1
x
#+END_SRC

#+RESULTS:
: 12345

#+NAME: radius
#+BEGIN_SRC julia :results value
12.345
#+END_SRC

#+BEGIN_SRC julia :results value :var r = radius
"The area of a circle with radius of $r is $(π * r ^ 2)."
#+END_SRC

#+RESULTS:
: The area of a circle with radius of 12.345 is 478.7756573542473.

#+BEGIN_SRC julia :results value file
using Plots
scatter(rand(100), rand(100))
savefig("plot.pdf")
#+END_SRC

#+RESULTS:
[[file:plot.pdf]]