docs/manual/guide/11-code-blocks.org

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.

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 ruby, js, javascript, R and awk, :cmd names a different program. These languages always return their standard output, and :var is refused for them.

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.

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."

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."

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.

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.

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.

: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

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

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

: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.

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]]

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.

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.

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

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

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

#+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.

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.

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

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.

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.

• 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".

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.