ob-ess-julia, a lightweight Julia support for Org mode using ESS

Important: Disclaimer

(Monday, October 3, 2022)

Please note that ob-ess-julia is deprecated and no longer maintained. Org has now a built-in support for Julia, so that ob-ess-julia has become pretty useless. All users of ob-ess-julia are invited to migrate to the built-in ob-julia solution.

Archive

Introduction

ob-ess-julia intends to offer a lightweight support for Julia language into Org mode. This is still an incomplete implementation to date, roughly in an alpha stage.

Why ob-ess-julia instead of ob-julia?

Julia has several backends within Emacs: julia-repl, julia-snail, and ess-julia. Furthermore, Julia can also be used through Jupyter using ob-ein or emacs-jupyter. The present package is based on ESS, but it would be unfair to “preempt” the name ob-julia, since using ESS is only one solution among other ones, and cannot be regarded as the canonical solution.

ob-ess-julia is basically a fork of the good old ob-julia, which is now orphaned. It has also several other forks, and I did not want any confusion among those packages. As a consequence, the general form of src blocks in ob-ess-julia is:

#+begin_src ess-julia

#+end_src

Implemented features and TODOs [71%]

• [X] External evaluation with verbatim output (:results output)
• [X] External evaluation with well-formatted output (:results value), for standard Julia data structures and DataFrames
• [X] Session evaluation (using inferior ESS processes) with :session header argument
• [X] Inline graphical outputs
• [X] Ability to indicate :width and :height of graphical outputs in pixels
• [X] Displaying output as org tables with :results value in session evaluation, with or without headers
• [X] Make ob-ess-julia compatible with polymode so that ess-julia-mode can be used as innermode in the src blocks
• [X] Handling variables passed with :var header argument
• [X] Host this package on MELPA
• [X] Improve documentation
• [ ] Handling :dir header argument to set working directory of ess-julia session (works, but with a glitch)
• [ ] Allow for more Julia types to be displayed with :results value (only arrays, dataframes, dictionaries and tuples are supported to date; other types might work as well but have not be tested yet)
• [ ] Better error management, in particular for graphical output
• [ ] Implement some simple unit tests

Alternatives for using Julia in Org mode

• ob-julia-vterm is a solid alternative, relying on julia-vterm (which avoids some of the limitations imposed by ESS and/or the usual terminal emulator).
• Another fork of the original ob-julia is available online. It offers advanced options such as async evaluation.
• Using a Jupyter Julia kernel from within Emacs is also possible.

How to use ob-ess-julia

Installation and settings

This package can be installed from MELPA. For instance, if you have use-package installed, simply add the following lines to your Emacs initialisation file:

;; Load ob-ess-julia and dependencies
(use-package ob-ess-julia
  :ensure t
  :config
  ;; Add ess-julia into supported languages:
  (org-babel-do-load-languages 'org-babel-load-languages
                               (append org-babel-load-languages
                                       '((ess-julia . t))))
  ;; Link this language to ess-julia-mode (although it should be done by default):
  (setq org-src-lang-modes
        (append org-src-lang-modes '(("ess-julia" . ess-julia)))))

Demo

Some examples of implemented features can be found in the file examples-ob-ess-julia.org.

Notes and tips

• :session names should be prefixed an suffixed by *, e.g. *julia* or *mysession* are convenient names.
• The following Julia packages are required: CSV, DelimitedFiles, Pipe. They are used for the :result value output type. They are loaded (with using) at the beginning of each Julia session started with ob-ess-julia (which is inelegant; but I couldn’t find a better option).
• I suggest the following settings for the Emacs initialisation file:

  ;; Shortcuts for Julia code block headers.
  ;; Shortcut for "normal" session evaluation with verbatim output:
  (add-to-list 'org-structure-template-alist
  	     '("j" . "src ess-julia :results output :session *julia* :exports both"))
  ;; Shortcut for inline graphical output within a session:
  (add-to-list 'org-structure-template-alist
  	     '("jfig" . "src ess-julia :results output graphics file :file FILENAME.png :session *julia* :exports both"))
  ;; Shortcut for well-formatted org table output within a session:
  (add-to-list 'org-structure-template-alist
  	     '("jtab" . "src ess-julia :results value table :session *julia* :exports both :colnames yes"))
      

• ob-ess-julia works better with polymode and company:

  ;; Add polymode:
  (use-package poly-org
    :ensure t)
  ;; Add company:
  (use-package company
    :ensure t)
  ;; Tweaks for company:
  (add-hook 'after-init-hook 'global-company-mode)
  (setq company-global-modes '(not org-mode text-mode))
  (setq ess-use-company 'script-only)
  ;; Add company quickhelp:
  (use-package company-quickhelp
    :ensure t
    :config
    (company-quickhelp-mode))
      

License

This package is under a CeCILL 2.1 license, which is compatible with GPL license.