Code blocks

orgstar runs and tangles source blocks the way Org Babel does, and refuses anything it would run differently.

Source blocks

A source block holds code in a named language:

#+begin_src python
return 6 * 7
#+end_src

orgstar reads the same syntax Org does: the language after #+begin_src, then any switches such as -i or -r, then header arguments. A #+NAME: line above a block names it, so other blocks, #+CALL: lines and :var references can refer to it.

Lines inside a block that start with * or #+ are protected with a leading comma, as Org does (org-escape-code-in-region). The comma is removed when the block runs, tangles or exports, and when you edit the block apart.

Syntax highlighting

The code in a block is highlighted in the editor on the Mac and on iOS, in the iOS reader, and in the Mac's block editor, in the theme's syntax-* colours. Highlighting uses tree-sitter grammars for these language names:

Names are matched without regard to case. Blocks in any other language show as plain monospaced text.

Editing a block apart

org-edit-special edits a block's contents in a separate editor. Put the caret in a src, example or export block (or on a #+TBLFM: line; see Tables) and run Edit Block.

On the Mac the block opens in a sheet titled with the block's kind and language, with the same highlighting as the main editor. The protecting commas are removed while you edit and added back when you save.

If the block changed in the main editor while you edited it, the edit is not saved and the message area says so.

On iOS the block opens in a plain text sheet with Cancel and Save buttons.

Running a block

C-c C-c in a source block runs it (org-babel-execute-src-block) and writes its result under it. The same command runs a #+CALL: line or an inline src_ block when the caret is on one.

The program runs in the folder of the file, or in :dir. It reads the code on standard input. While it runs, the message area shows "Running language block…"; when it ends, it shows "Code block evaluation complete." or the problem.

If the program writes to standard error or exits with a non-zero status, the message area shows the exit status and the first line of standard error. The result is still inserted, as Emacs does.

The block's text is remembered when the run starts. If you edit the block while it runs, so it can no longer be found, the result is not written.

Languages that run

On the Mac, orgstar starts each interpreter through /usr/bin/env. Because an app opened from the Dock does not see your shell's PATH, orgstar adds /opt/homebrew/bin, /usr/local/bin, /Library/TeX/texbin, /usr/bin and /bin to the end of it.

For js, javascript and R, :cmd names a different program. awk takes :cmd-line arguments after its program, and :in-file as the file it reads.

Any other language is refused with "No way to run language blocks yet."

A run that takes longer than five minutes is stopped. Runs in a :session have no time limit.

Compiled languages

On the Mac, C, C++, cpp, D, java, fortran and clojure blocks run as Org's ob-C, ob-java, ob-fortran and ob-clojure run them. orgstar writes the body, expanded as tangling writes it (see Tangling below), to a source file in a temporary folder, compiles it and runs the program in the file's folder or :dir, with a newline on standard input. What the compiler prints is dropped.

FLAGS is :flags, LIBS is :libs or the inherited LIBS property, and CMDLINE is :cmdline. A Lisp list works for :flags and :libs; its items are joined with spaces.

When :imports is absent, a D block reads the IMPORTS property where it is, and a Fortran block without :includes or :defines reads the INCLUDES and DEFINES properties, as Org does when it runs them. :session is ignored for these languages, as in Org.

Java's defaults are :results output and :dir . (org-babel-default-header-args:java). The .java and .class files are written in the folder the block runs in, under folders for the class's package (org/ex/Hello.java for :classname org.ex.Hello), and are left there. The class is :classname, the body's own class with its package, or Main.

Any other Clojure backend is refused: "The cider backend for clojure needs Emacs; orgstar runs babashka or clojure-cli."

Before a run, orgstar checks that each program it needs is on the PATH described above. If not, the block fails with "gcc isn't installed, so C blocks can't run." (g++ for C++, rdmd, gfortran, or the commands :javac and :java name). For Clojure without a :backend, the message is "Neither bb nor clojure is installed, so clojure blocks can't run."

The trust prompt

Before a block runs, orgstar asks "Run this language block? (yes, no, always)", as org-confirm-babel-evaluate does.

• yes runs it this once.
• no does not run it.
• always runs it and remembers the block, so it runs without asking next time.

A remembered block is identified by the file's path and the exact text of the block. Any change to the block, or moving the file, makes orgstar ask again. The remembered hashes are kept in trusted.json in orgstar's Application Support folder (~/Library/Application Support/Orgstar on the Mac). The same file records table formulas you allowed to run Lisp. To forget every choice, delete the file while orgstar is not running.

When a block's :var or :stdin refers to other blocks that have to run first, you are asked once for all of them. The prompt covers the block you ran and every block its references reach. If any of those blocks changes while the chain runs, orgstar stops with "The blocks changed while running; nothing more was run."

:eval

never-export and no-export only stop evaluation during export in Org. orgstar does not run blocks during export, so with these values the block runs from C-c C-c like any other.

Cancelling a run

On the Mac, Edit ▸ Cancel Running Task (⌘.) stops the running block. Its result is not inserted, and the message area shows "Code block canceled." The same command stops an export or table recalculation running in Emacs (see Export and Tables). With nothing running it shows "Nothing is running". The command is also in the command palette.

Only one block runs at a time. Starting another block cancels the one that is running.

Cancelling a block that runs in a :session stops the session's interpreter, so the session's state is lost. The next block in that session starts a new one.

The iOS app has no cancel command.

Results

The result is written after a #+RESULTS: line below the block (org-babel-insert-result). Running again replaces it. A named block's result goes under #+RESULTS: name, wherever that line is in the file. An unnamed block's result is the #+RESULTS: line right after it, past blank lines. The result keeps the block's indentation, so a block inside a list item keeps its result inside the item.

#+begin_src sh
echo hello
#+end_src

#+RESULTS:
: hello

By default a result is shaped like this:

• Text of fewer than ten lines gets a =: = prefix on each line.
• Text of ten lines or more goes in an #+begin_example block.
• A table becomes an aligned Org table.

Value or output

What "value" means depends on the language:

Python lists of lists become tables, with None rows as rules. A flat list becomes a one-row table. Emacs Lisp lists become tables the same way, with hline for rules. Numbers are written the way Emacs prints them.

Result types

:results verbatim on an Emacs Lisp value writes it as prin1 would, with quotes around strings.

With :results output list, the list made from the output is written as an example, in lines such as : - a, as Org writes it:

#+begin_src sh :results output list
printf 'a\nb\n'
#+end_src

#+RESULTS:
: - a
: - b

Result formats

Lines that start with * or #+ inside code, org, html and latex results are comma-protected.

Inserting

Words from different groups combine: :results output list append. A later word replaces an earlier one from the same group.

:wrap

:wrap puts the result in a block, ahead of any format word.

Inside example, src and export wrappers, lines starting with * or #+ are comma-protected.

Results in files

With :results file, the result is a link instead of text.

A relative :file is written in the folder the block ran in: the file's folder, or :dir. Without :file, :results file takes the result itself as the path to link to.

#+begin_src sh :results file :file out.txt :file-desc Output
echo hello
#+end_src

#+RESULTS:
[[file:out.txt][Output]]

Header arguments

Where they come from

orgstar merges header arguments in this order, each layer overriding the ones before it (org-babel-get-src-block-info):

1. #+PROPERTY: header-args … in the file, then header-args properties of the block's headings, from the outermost heading inwards.
2. header-args:LANG the same way, for blocks in language LANG.
3. The arguments on the #+begin_src line.
4. #+HEADER: lines above the block.
5. For a call, the call's arguments (see Calls below).

A property written with a +, such as header-args+, adds to the value inherited from above instead of replacing it. In a property drawer, :header-args:sh: is one property name, so its value applies only to sh blocks.

#+PROPERTY: header-args :results output

* Scripts
:PROPERTIES:
:header-args:sh: :dir /tmp
:END:

#+HEADER: :results verbatim
#+begin_src sh :var name="world"
echo "hello $name"
#+end_src

Without any of these, a block has :results replace, :exports code, :session none, :cache no, :noweb no, :hlines no and :tangle no. An inline src_ block defaults to :exports results and :hlines yes.

Lisp in header values

A header value that starts with (, ', ` or [ and is not in quotes is Lisp, as in org-babel-read. orgstar evaluates it with its own Emacs Lisp interpreter, which also knows buffer-file-name, default-directory, system-type and the functions expand-file-name, file-name-directory, file-name-nondirectory, file-name-sans-extension and file-name-as-directory.

#+begin_src sh :dir (concat "/" "usr") :results output
pwd
#+end_src

A string or number takes the place of the form. Lisp that the interpreter cannot evaluate is refused where it matters: for :var ("is Lisp that only Emacs can evaluate"), :colnames and :rownames, and any header of a :cache yes block.

Header argument reference

Arguments that are refused

orgstar does not run a block whose arguments it would handle differently from Emacs. Instead it says why and runs nothing.

Variables

:var name=value passes a value into the block (org-babel-ref-resolve). One :var can hold several assignments separated by spaces, and you can repeat :var. A later assignment to the same name replaces an earlier one.

#+NAME: nums
| 1 | 2 |
| 3 | 4 |

#+begin_src python :var t=nums :var scale=10
return [[c * scale for c in row] for row in t]
#+end_src

A referenced block runs before the block that refers to it, after the one trust prompt that covers them all. A block with :cache yes and a current result gives that result without running. A chain that leads back to itself is refused with "name refers to itself through :var".

These are not supported and are refused:

• Indexing into a table, such as tbl[1,2]: "References like … aren't supported yet."
• A name that matches nothing in the file: "Can't find … for :var."
• References to other files.

How a value reaches the code depends on the language:

For shell blocks, the bash forms are used when SHELL is bash. :prologue and :epilogue add a line before the variables and one after the body, in every language that runs; in Emacs Lisp only when the block has variables, as org-babel-expand-body:emacs-lisp does. C, C++, D, Java, Fortran and Clojure blocks get declarations as their expansion writes them; see Tangling below.

#+NAME: kv
| a | 1 |
| b | 2 |

#+begin_src bash :var t=kv :results output
echo ${t[a]} ${t[b]}
#+end_src

Tables in variables

A table passed as a variable loses some of its structure first (org-babel-disassemble-tables):

• Rules are removed, unless :hlines yes.
• The first row is taken off as column names when :colnames yes, or when the table's only rule is under the first row. :colnames no keeps it as data.
• The first column is taken off as row names when :rownames yes.

If the result is a table of the same width (for columns) or height (for rows), the names are put back on it (org-babel-reassemble-table). Clojure results don't get them back, as in Org. :colnames and :rownames can also be Lisp lists of names to put on the result, such as :colnames '("x" "y").

#+NAME: tbl
| a | b |
|---+---|
| 1 | x |
| 2 | y |

#+begin_src python :var t=tbl
return [r + ["!"] for r in t]
#+end_src

Standard input and arguments

For shell blocks, :stdin name sends a table, list or block result to standard input, a table as tab-separated lines. :cmdline gives the script arguments, and :shebang its first line. With any of the three, the block is written to an executable script and run by the shell (org-babel-sh-evaluate); without :shebang, the first line is #!/usr/bin/env and the shell's name. A block with :stdin or :cmdline runs as a script even with a :session, and leaves the session untouched; :shebang alone runs in the session.

#+begin_src sh :cmdline one "two words" :results output
for a in "$@"; do echo "[$a]"; done
#+end_src

Sessions

:session name runs the block in an interpreter that stays running, so variables, functions and the working folder carry over to the next block in the same session. Sessions work for shells, Python, Ruby, JavaScript (Node) and R on the Mac.

• :session with no name uses *language*, such as *sh*. :session none runs without one.
• A session belongs to one folder, one interpreter and one name. Blocks in different folders, or with different names, do not share state.
• A session starts in the block's :dir, or the file's folder, the first time it is used.
• A shell session's output is what the block prints. :results value gives the exit status of the last command.
• A Python session runs the block at top level. Its value is the value of the last expression, so return is not used.
• A Ruby session runs each block in the same binding, and a JavaScript session in Node's global context, so local variables and var and let declarations carry over. Their value is the value of the last expression, written as without a session (inspect, util.inspect); return is not used. Errors go to the block's error output and leave the session running.
• An R session runs each block with source(…, print.eval = TRUE) in one R --slave process; its result is the output, as without a session.

Emacs runs these with packages beyond Org: inf-ruby for Ruby, ESS for R, and js-comint or skewer for JavaScript; with plain node, ob-js refuses sessions. orgstar's sessions don't need them, and their results can differ in detail from those packages' echoed output.

• Sessions stop when you quit orgstar, or when you cancel a block running in one.

#+begin_src python :session py :results output
a = 2
print("set")
#+end_src

#+begin_src python :session py
a * 3
#+end_src

Caching

With :cache yes, orgstar computes a SHA-1 hash of the block's header arguments and expanded body, as org-babel-sha1-hash does, and writes it on the results line: #+RESULTS[hash]:. When you run the block again and the hash matches, nothing runs and the message area shows the cached value ("Cached: …").

Change the block or its arguments and it runs again. Results inserted with append or prepend carry no hash. Inline blocks are not cached. A cached block that has Lisp in its header arguments the interpreter cannot evaluate is refused.

The hash of a C, C++, D, Java, Fortran or Clojure block is taken over the body as the language expands it (see Tangling below), with the IMPORTS, INCLUDES and DEFINES properties where the block is, and Java's default header arguments, as Emacs does. A result Emacs wrote for such a block with :cache yes is recognised as current, and C-c C-c shows it.

Noweb

A noweb reference <<name>> in a block's body stands for other code. Whether references expand depends on :noweb and on what is happening:

Exported code always shows the references as written; see Export.

<<name>> expands to the first of these that exists:

1. The contents of the heading whose ID property is name, or whose CUSTOM_ID is name without its leading #.
2. The body of the source block named name.
3. The bodies of all blocks with :noweb-ref name, joined by each block's :noweb-sep (a newline by default).

Blocks under a COMMENT heading are skipped. A referenced block expands its own references according to its own :noweb, up to 32 levels deep.

Text before the reference on its line is repeated before each line the reference brings in, so references inside comments or indented code keep their prefix. :noweb-prefix no turns this off.

#+NAME: greeting
#+begin_src sh
echo hello
#+end_src

#+begin_src sh :noweb yes
<<greeting>>
echo world
#+end_src

A reference that runs a block, <<name()>>, is refused: "Noweb references that run a block (…) aren't supported yet; nothing was run."

Calls

#+CALL: lines

#+CALL: runs a named block with other arguments, as Org's library of Babel calls do (org-babel-lob-get-info). Run it with C-c C-c on the line.

#+NAME: double
#+begin_src sh :var n=2
echo $((n*2))
#+end_src

#+CALL: double(n=5)

#+RESULTS:
: 10

The full form is #+CALL: name[inside](arguments) end:

• name is the block to run. It must be in the same file.
• [inside] holds header arguments applied to the block, such as [:results raw].
• (arguments) are :var assignments, separated by commas.
• end holds header arguments for the call's result, such as :results verbatim.

The call also takes the header-args and header-args:LANG properties, and #+PROPERTY: lines, where the call is, with LANG the called block's language. They apply after the called block's own header arguments and before [inside], as in Org.

The result goes under the call. A #+NAME: line above the #+CALL: names the result.

Inline calls and blocks

An inline source block, src_sh{echo hi}, runs with C-c C-c on it. Header arguments go in brackets: src_sh[:var x=3]{echo $x}. The result is written right after the block as a results macro:

Text src_sh{echo hi} {{{results(=hi=)}}} end.

Running again replaces the macro. With :results raw the result goes in as it is, without the macro. An inline result must be one line, and a table result must be a single cell.

An inline call, call_double(n=6), has the same parts as a #+CALL: line: call_name[inside](arguments)[end]. C-c C-c on an inline call runs it, and its result is written after it as a results macro, as for inline blocks. It takes the properties where it is as a #+CALL: line does.

Emacs Lisp blocks

On the Mac, an emacs-lisp or elisp block runs in a new emacs -Q --batch for each run, with lexical binding on. -Q means your init file and packages are not loaded, and nothing carries over between runs. orgstar looks for Emacs at ORGSTAR_EMACS, then /opt/homebrew/bin/emacs, /usr/local/bin/emacs, /Applications/Emacs.app/Contents/MacOS/Emacs, /run/current-system/sw/bin/emacs and /usr/bin/emacs. Without Emacs, the block fails with "Emacs isn't installed, so Emacs Lisp blocks can't run."

On iOS, Emacs Lisp blocks run in orgstar's own Emacs Lisp interpreter. It covers ordinary list, string, number and control forms, princ and message. A block that uses something the interpreter does not have fails with "This block uses Emacs Lisp that runs only in Emacs, on the Mac." A Lisp error fails the run, as it does in Emacs.

Variables are bound with let around the body. :results output collects what the block prints with princ, prin1, print and terpri.

Graphics

dot (Graphviz), plantuml and mermaid blocks draw a picture into :file, and the result is a link to it. :file is required: "language code blocks need a :file header argument". The file's extension picks the output format; with none, png is used.

A plantuml body without an @start… line is wrapped in @startuml and @enduml. :cmdline adds options to the command. The program must be installed and on the PATH described under Languages that run.

#+begin_src dot :file graph.svg
digraph { a -> b }
#+end_src

#+RESULTS:
[[file:graph.svg]]

Tangling

Tangling writes source blocks to the files their :tangle argument names (org-babel-tangle).

All three are in the Org menu and the command palette. Tangling uses the text in the editor, saved or not, and the message area reports "Tangled N code blocks from file".

:tangle and file names

Blocks under a COMMENT heading, or a heading tagged ARCHIVE, are skipped. Blocks going to the same file are written in the order they appear.

#+PROPERTY: header-args:python :tangle script.py

* Tool
:PROPERTIES:
:header-args: :tangle bin/tool.sh :mkdirp yes :shebang "#!/bin/sh"
:END:

#+begin_src sh
echo tool
#+end_src

Tangling arguments

A table in :var loses its first row when its only rule is under that row, or with :colnames yes, and its rules unless :hlines yes, as when the block runs. This holds for every language.

C, C++, cpp, D, java, fortran and clojure blocks are written as Org's org-babel-expand-body:LANG writes them:

With :hlines yes, a table that keeps rules is refused for C, C++, D and Fortran; Java writes null for each rule.

Block switches also apply. -r removes coderef labels such as (ref:name), using the format from -l if given. -i keeps the block's indentation. Otherwise common indentation and surrounding blank lines are removed.

Comments

The link is relative to the tangled file's folder. name is the block's #+NAME, or the heading's title and the block's number under that heading, such as Setup:2.

Comments need the language's comment syntax. orgstar knows it for: emacs-lisp, elisp, lisp, scheme, asm (;;); python, ruby, perl, conf, toml, makefile, awk, tcl, m4, icon, desktop and the shells except fish (#); js, javascript, java, cpp, C++, objc, csharp, idl, pike, antlr, verilog (//); c, C, css (/* */); lua, sql, sqlite, vhdl (--); latex, tex, prolog (%%); ps, metapost (%); f90, dcl (!); html, xml, nxml, mhtml, sgml (<!-- -->); octave (##); pascal ({ }); texinfo (@c); bibtex (@Comment); nroff (\"); bat (rem). For any other language, :comments other than no stops tangling with a message.

Writing the files

• A file whose contents would not change is left alone, so its modification time stays the same.
• A read-only file is replaced.
• Tangling into the Org file itself is refused: "Not allowed to tangle into the same file as self".

What tangling refuses

Tangling stops, writes nothing and says why when:

• :var refers to a source block, which would have to run: "would run a block while tangling".
• A shell block's :var is a table or list.
• :var is used in a language other than shells, Python, Emacs Lisp, C, C++, D, Java, Fortran and Clojure.
• A C, C++, D or Fortran block's :var table keeps rules (with :hlines yes), or a value has no type the language takes.
• A Lisp header value cannot be evaluated: "is Lisp tangling can't evaluate yet; nothing was tangled."
• :tangle-mode is in a form it does not read.
• :comments needs a comment syntax it does not know.

On iOS

• Only Emacs Lisp blocks run, in orgstar's own interpreter. Any other language, compiled languages included, fails with "language blocks need the Mac to run." (for example "C blocks need the Mac to run."), and so does an Emacs Lisp block whose :var refers to a block in another language.
• There are no sessions and no graphics.
• The trust prompt works the same way, with its own trusted.json on the device.
• There is no cancel command.
• Tangling works, for files in folders orgstar can write to.
• Edit Block opens a plain text sheet without highlighting.

See iOS for the rest of the iOS app.