guide/11-code-blocks.html
692 lines · 71562 bytes
1<!DOCTYPE html>
2<html lang="en">
3<head>
4<meta charset="utf-8">
5<meta name="viewport" content="width=device-width, initial-scale=1">
6<title>Code blocks · Orgstar</title>
7<meta name="description" content="Source blocks in Orgstar: highlighting, editing, running with Babel, results, header arguments, noweb and tangling.">
8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
9<link rel="stylesheet" href="../theme.css">
10<link rel="stylesheet" href="../syntax.css">
11<link rel="stylesheet" href="../style.css">
12</head>
13<body>
14<header class="site">
15<a class="site-title" href="../index.html">Orgstar</a>
16<nav>
17<a href="../install.html">Install</a>
18<a href="../quickstart.html">Quick start</a>
19<a href="index.html">Manual</a>
20</nav>
21</header>
22<main>
23<h1>Code blocks</h1>
24<p class="lede">Orgstar runs and tangles source blocks the way Org Babel does, and refuses anything it would run differently.</p>
25<nav class="toc" aria-label="On this page">
26<h2>On this page</h2>
27<ul>
28<li><a href="#source-blocks">Source blocks</a>
29<ul>
30<li><a href="#syntax-highlighting">Syntax highlighting</a></li>
31</ul></li>
32<li><a href="#editing-a-block-apart">Editing a block apart</a></li>
33<li><a href="#running-a-block">Running a block</a>
34<ul>
35<li><a href="#languages-that-run">Languages that run</a></li>
36<li><a href="#the-trust-prompt">The trust prompt</a></li>
37<li><a href="#eval">:eval</a></li>
38<li><a href="#cancelling-a-run">Cancelling a run</a></li>
39</ul></li>
40<li><a href="#results">Results</a>
41<ul>
42<li><a href="#value-or-output">Value or output</a></li>
43<li><a href="#result-types">Result types</a></li>
44<li><a href="#result-formats">Result formats</a></li>
45<li><a href="#inserting">Inserting</a></li>
46<li><a href="#wrap">:wrap</a></li>
47<li><a href="#results-in-files">Results in files</a></li>
48</ul></li>
49<li><a href="#header-arguments">Header arguments</a>
50<ul>
51<li><a href="#where-they-come-from">Where they come from</a></li>
52<li><a href="#lisp-in-header-values">Lisp in header values</a></li>
53<li><a href="#header-argument-reference">Header argument reference</a></li>
54<li><a href="#arguments-that-are-refused">Arguments that are refused</a></li>
55</ul></li>
56<li><a href="#variables">Variables</a>
57<ul>
58<li><a href="#tables-in-variables">Tables in variables</a></li>
59<li><a href="#standard-input-and-arguments">Standard input and arguments</a></li>
60</ul></li>
61<li><a href="#sessions">Sessions</a></li>
62<li><a href="#caching">Caching</a></li>
63<li><a href="#noweb">Noweb</a></li>
64<li><a href="#calls">Calls</a>
65<ul>
66<li><a href="#call-lines">#+CALL: lines</a></li>
67<li><a href="#inline-calls-and-blocks">Inline calls and blocks</a></li>
68</ul></li>
69<li><a href="#emacs-lisp-blocks">Emacs Lisp blocks</a></li>
70<li><a href="#graphics">Graphics</a></li>
71<li><a href="#tangling">Tangling</a>
72<ul>
73<li><a href="#tangle-and-file-names">:tangle and file names</a></li>
74<li><a href="#tangling-arguments">Tangling arguments</a></li>
75<li><a href="#comments">Comments</a></li>
76<li><a href="#writing-the-files">Writing the files</a></li>
77<li><a href="#what-tangling-refuses">What tangling refuses</a></li>
78</ul></li>
79<li><a href="#on-ios">On iOS</a></li>
80</ul>
81</nav>
82<h2 id="source-blocks">Source blocks</h2>
83<p>A source block holds code in a named language:</p>
84<pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python</span>
85return 6 * 7
86<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
87<p>Orgstar reads the same syntax Org does: the language after <code class="verbatim">#+begin_src</code>, then any switches such as <code class="verbatim">-i</code> or <code class="verbatim">-r</code>, then header arguments. A <code class="verbatim">#+NAME:</code> line above a block names it, so other blocks, <code class="verbatim">#+CALL:</code> lines and <code class="verbatim">:var</code> references can refer to it.</p>
88<p>Lines inside a block that start with <code class="verbatim">*</code> or <code class="verbatim">#+</code> are protected with a leading comma, as Org does (<code class="verbatim">org-escape-code-in-region</code>). The comma is removed when the block runs, tangles or exports, and when you edit the block apart.</p>
89<h3 id="syntax-highlighting">Syntax highlighting</h3>
90<p>On the Mac, the code in a block is highlighted in the editor and in the block editor. Highlighting uses tree-sitter grammars for these language names:</p>
91<table>
92<thead>
93<tr><th>Language names</th><th>Grammar</th></tr>
94</thead>
95<tbody>
96<tr><td><code class="verbatim">sh</code>, <code class="verbatim">bash</code>, <code class="verbatim">shell</code>, <code class="verbatim">zsh</code></td><td>Bash</td></tr>
97<tr><td><code class="verbatim">python</code>, <code class="verbatim">python3</code>, <code class="verbatim">py</code></td><td>Python</td></tr>
98<tr><td><code class="verbatim">emacs-lisp</code>, <code class="verbatim">elisp</code></td><td>Emacs Lisp</td></tr>
99<tr><td><code class="verbatim">c</code></td><td>C</td></tr>
100<tr><td><code class="verbatim">c++</code>, <code class="verbatim">cpp</code></td><td>C++</td></tr>
101<tr><td><code class="verbatim">r</code></td><td>R</td></tr>
102<tr><td><code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">node</code></td><td>JavaScript</td></tr>
103<tr><td><code class="verbatim">java</code></td><td>Java</td></tr>
104<tr><td><code class="verbatim">scheme</code></td><td>Scheme</td></tr>
105<tr><td><code class="verbatim">clojure</code>, <code class="verbatim">clj</code></td><td>Clojure</td></tr>
106<tr><td><code class="verbatim">haskell</code></td><td>Haskell</td></tr>
107<tr><td><code class="verbatim">rust</code></td><td>Rust</td></tr>
108<tr><td><code class="verbatim">go</code></td><td>Go</td></tr>
109<tr><td><code class="verbatim">ruby</code></td><td>Ruby</td></tr>
110<tr><td><code class="verbatim">json</code></td><td>JSON</td></tr>
111<tr><td><code class="verbatim">yaml</code>, <code class="verbatim">yml</code></td><td>YAML</td></tr>
112<tr><td><code class="verbatim">toml</code>, <code class="verbatim">conf-toml</code></td><td>TOML</td></tr>
113<tr><td><code class="verbatim">lua</code></td><td>Lua</td></tr>
114</tbody>
115</table>
116<p>Names are matched without regard to case. Blocks in any other language show as plain monospaced text. The iOS app does not highlight code.</p>
117<h2 id="editing-a-block-apart">Editing a block apart</h2>
118<p><code class="verbatim">org-edit-special</code> edits a block's contents in a separate editor. Put the caret in a <code class="verbatim">src</code>, <code class="verbatim">example</code> or <code class="verbatim">export</code> block (or on a <code class="verbatim">#+TBLFM:</code> line; see <a href="10-tables.html">Tables</a>) and run <strong>Edit Block</strong>.</p>
119<table>
120<thead>
121<tr><th>Preset</th><th>Key</th></tr>
122</thead>
123<tbody>
124<tr><td>Emacs</td><td><code class="verbatim">C-c '</code></td></tr>
125<tr><td>Doom</td><td><code class="verbatim">C-c '</code>, or <code class="verbatim">SPC m '</code> in normal state</td></tr>
126<tr><td>Mac</td><td><code class="verbatim">⌃⌘'</code></td></tr>
127</tbody>
128</table>
129<p>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.</p>
130<table>
131<thead>
132<tr><th>Action</th><th>Keys</th></tr>
133</thead>
134<tbody>
135<tr><td>Save</td><td><code class="verbatim">C-c '</code> or ⌘Return, or <strong>Save Block</strong></td></tr>
136<tr><td>Leave</td><td><code class="verbatim">C-c C-k</code> or Escape, or <strong>Cancel</strong></td></tr>
137</tbody>
138</table>
139<p>If the block changed in the main editor while you edited it, the edit is not saved and the message area says so.</p>
140<p>On iOS the block opens in a plain text sheet with Cancel and Save buttons.</p>
141<h2 id="running-a-block">Running a block</h2>
142<p><code class="verbatim">C-c C-c</code> in a source block runs it (<code class="verbatim">org-babel-execute-src-block</code>) and writes its result under it. The same command runs a <code class="verbatim">#+CALL:</code> line or an inline <code class="verbatim">src_</code> block when the caret is on one.</p>
143<table>
144<thead>
145<tr><th>Preset</th><th>Key</th></tr>
146</thead>
147<tbody>
148<tr><td>Emacs</td><td><code class="verbatim">C-c C-c</code></td></tr>
149<tr><td>Doom</td><td><code class="verbatim">C-c C-c</code> in normal, insert and visual state</td></tr>
150<tr><td>Mac</td><td><code class="verbatim">⌃⌘X</code></td></tr>
151</tbody>
152</table>
153<p>The program runs in the folder of the file, or in <code class="verbatim">:dir</code>. It reads the code on standard input. While it runs, the message area shows "Running <em>language</em> block…"; when it ends, it shows "Code block evaluation complete." or the problem.</p>
154<p>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.</p>
155<p>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.</p>
156<h3 id="languages-that-run">Languages that run</h3>
157<p>On the Mac, Orgstar starts each interpreter through <code class="verbatim">/usr/bin/env</code>. Because an app opened from the Dock does not see your shell's <code class="verbatim">PATH</code>, Orgstar adds <code class="verbatim">/opt/homebrew/bin</code>, <code class="verbatim">/usr/local/bin</code>, <code class="verbatim">/Library/TeX/texbin</code>, <code class="verbatim">/usr/bin</code> and <code class="verbatim">/bin</code> to the end of it.</p>
158<table>
159<thead>
160<tr><th>Language</th><th>Program run</th></tr>
161</thead>
162<tbody>
163<tr><td><code class="verbatim">sh</code>, <code class="verbatim">bash</code>, <code class="verbatim">zsh</code>, <code class="verbatim">fish</code>, <code class="verbatim">ksh</code>, <code class="verbatim">dash</code>, <code class="verbatim">ash</code>, <code class="verbatim">csh</code>, <code class="verbatim">mksh</code>, <code class="verbatim">posh</code></td><td>The shell of that name</td></tr>
164<tr><td><code class="verbatim">shell</code></td><td>The shell in <code class="verbatim">SHELL</code>, or <code class="verbatim">/bin/sh</code></td></tr>
165<tr><td><code class="verbatim">python</code></td><td><code class="verbatim">python3</code>, or the program in <code class="verbatim">:python</code></td></tr>
166<tr><td><code class="verbatim">emacs-lisp</code>, <code class="verbatim">elisp</code></td><td><code class="verbatim">emacs -Q --batch</code>; see Emacs Lisp blocks below</td></tr>
167<tr><td><code class="verbatim">ruby</code></td><td><code class="verbatim">ruby</code></td></tr>
168<tr><td><code class="verbatim">js</code>, <code class="verbatim">javascript</code></td><td><code class="verbatim">node</code></td></tr>
169<tr><td><code class="verbatim">R</code></td><td><code class="verbatim">Rscript -</code></td></tr>
170<tr><td><code class="verbatim">awk</code></td><td><code class="verbatim">awk -f /dev/stdin</code></td></tr>
171<tr><td><code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">mermaid</code></td><td><code class="verbatim">dot</code>, <code class="verbatim">plantuml</code>, <code class="verbatim">mmdc</code>; see Graphics below</td></tr>
172</tbody>
173</table>
174<p>For <code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">R</code> and <code class="verbatim">awk</code>, <code class="verbatim">:cmd</code> names a different program. These languages always return their standard output, and <code class="verbatim">:var</code> is refused for them.</p>
175<p>Any other language is refused with "No way to run <em>language</em> blocks yet."</p>
176<p>A run that takes longer than five minutes is stopped. Runs in a <code class="verbatim">:session</code> have no time limit.</p>
177<h3 id="the-trust-prompt">The trust prompt</h3>
178<p>Before a block runs, Orgstar asks "Run this <em>language</em> block? (yes, no, always)", as <code class="verbatim">org-confirm-babel-evaluate</code> does.</p>
179<ul>
180<li><code class="verbatim">yes</code> runs it this once.</li>
181<li><code class="verbatim">no</code> does not run it.</li>
182<li><code class="verbatim">always</code> runs it and remembers the block, so it runs without asking next time.</li>
183</ul>
184<p>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 <code class="verbatim">trusted.json</code> in Orgstar's Application Support folder (<code class="verbatim">~/Library/Application Support/Orgstar</code> 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.</p>
185<p>When a block's <code class="verbatim">:var</code> or <code class="verbatim">:stdin</code> 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."</p>
186<h3 id="eval"><code class="verbatim">:eval</code></h3>
187<table>
188<thead>
189<tr><th>Value</th><th>Effect</th></tr>
190</thead>
191<tbody>
192<tr><td><code class="verbatim">never</code>, <code class="verbatim">no</code></td><td>The block does not run: "Evaluation of this <em>language</em> code block is disabled."</td></tr>
193<tr><td><code class="verbatim">query</code></td><td>Asks every time, with only <code class="verbatim">yes</code> and <code class="verbatim">no</code>. A block reached through <code class="verbatim">:var</code> with <code class="verbatim">:eval query</code> makes the whole chain ask every time.</td></tr>
194<tr><td>anything else, or absent</td><td>Runs after the trust prompt.</td></tr>
195</tbody>
196</table>
197<p><code class="verbatim">never-export</code> and <code class="verbatim">no-export</code> only stop evaluation during export in Org. Orgstar does not run blocks during export, so with these values the block runs from <code class="verbatim">C-c C-c</code> like any other.</p>
198<h3 id="cancelling-a-run">Cancelling a run</h3>
199<p>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 <a href="12-export.html">Export</a> and <a href="10-tables.html">Tables</a>). With nothing running it shows "Nothing is running". The command is also in the command palette.</p>
200<p>Only one block runs at a time. Starting another block cancels the one that is running.</p>
201<p>Cancelling a block that runs in a <code class="verbatim">:session</code> stops the session's interpreter, so the session's state is lost. The next block in that session starts a new one.</p>
202<p>The iOS app has no cancel command.</p>
203<h2 id="results">Results</h2>
204<p>The result is written after a <code class="verbatim">#+RESULTS:</code> line below the block (<code class="verbatim">org-babel-insert-result</code>). Running again replaces it. A named block's result goes under <code class="verbatim">#+RESULTS: name</code>, wherever that line is in the file. An unnamed block's result is the <code class="verbatim">#+RESULTS:</code> 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.</p>
205<pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh</span>
206echo hello
207<span class="keyword control block end org">#+end_src</span>
208</span>
209<span class="keyword other keyword org">#+RESULTS:</span>
210: hello</span></code></pre>
211<p>By default a result is shaped like this:</p>
212<ul>
213<li>Text of fewer than ten lines gets a =: = prefix on each line.</li>
214<li>Text of ten lines or more goes in an <code class="verbatim">#+begin_example</code> block.</li>
215<li>A table becomes an aligned Org table.</li>
216</ul>
217<h3 id="value-or-output">Value or output</h3>
218<table>
219<thead>
220<tr><th>Word</th><th>Result</th></tr>
221</thead>
222<tbody>
223<tr><td><code class="verbatim">value</code></td><td>The value of the block. This is the default.</td></tr>
224<tr><td><code class="verbatim">output</code></td><td>Everything the program printed on standard output.</td></tr>
225</tbody>
226</table>
227<p>What "value" means depends on the language:</p>
228<table>
229<thead>
230<tr><th>Language</th><th>Value</th></tr>
231</thead>
232<tbody>
233<tr><td>Shells, by default</td><td>Standard output, read as a table: tab-separated columns, then comma-separated, then space-separated; a single field is a plain value.</td></tr>
234<tr><td>Shells, <code class="verbatim">:results value</code> written out</td><td>The exit status of the last command.</td></tr>
235<tr><td>Python</td><td>What the block returns. The body runs as a function, so it needs <code class="verbatim">return</code>. <code class="verbatim">:return expr</code> adds a final <code class="verbatim">return expr</code>.</td></tr>
236<tr><td>Python in a <code class="verbatim">:session</code></td><td>The value of the last expression.</td></tr>
237<tr><td>Emacs Lisp</td><td>The value of the last form.</td></tr>
238<tr><td><code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">R</code>, <code class="verbatim">awk</code></td><td>Standard output, always.</td></tr>
239</tbody>
240</table>
241<p>Python lists of lists become tables, with <code class="verbatim">None</code> rows as rules. A flat list becomes a one-row table. Emacs Lisp lists become tables the same way, with <code class="verbatim">hline</code> for rules. Numbers are written the way Emacs prints them.</p>
242<h3 id="result-types">Result types</h3>
243<table>
244<thead>
245<tr><th>Word</th><th>Effect</th></tr>
246</thead>
247<tbody>
248<tr><td><code class="verbatim">table</code>, <code class="verbatim">vector</code></td><td>Read the result as a table. This is the default for values.</td></tr>
249<tr><td><code class="verbatim">list</code></td><td>Write a plain list, one =- = item per line or per element.</td></tr>
250<tr><td><code class="verbatim">scalar</code>, <code class="verbatim">verbatim</code></td><td>Write the result as text without reading it as a table.</td></tr>
251<tr><td><code class="verbatim">file</code></td><td>Write a link to a file (see Results in files below).</td></tr>
252</tbody>
253</table>
254<p><code class="verbatim">:results verbatim</code> on an Emacs Lisp value writes it as <code class="verbatim">prin1</code> would, with quotes around strings.</p>
255<h3 id="result-formats">Result formats</h3>
256<table>
257<thead>
258<tr><th>Word</th><th>Written as</th></tr>
259</thead>
260<tbody>
261<tr><td><code class="verbatim">raw</code></td><td>The text as it is, so Org markup in it takes effect.</td></tr>
262<tr><td><code class="verbatim">drawer</code></td><td>Between <code class="verbatim">:results:</code> and <code class="verbatim">:end:</code>.</td></tr>
263<tr><td><code class="verbatim">code</code></td><td>In a <code class="verbatim">#+begin_src</code> block of the block's language.</td></tr>
264<tr><td><code class="verbatim">org</code></td><td>In a <code class="verbatim">#+begin_src org</code> block.</td></tr>
265<tr><td><code class="verbatim">html</code></td><td>In a <code class="verbatim">#+begin_export html</code> block.</td></tr>
266<tr><td><code class="verbatim">latex</code></td><td>In a <code class="verbatim">#+begin_export latex</code> block.</td></tr>
267<tr><td><code class="verbatim">pp</code></td><td>Python: formatted with <code class="verbatim">pprint</code>; written as text.</td></tr>
268</tbody>
269</table>
270<p>Lines that start with <code class="verbatim">*</code> or <code class="verbatim">#+</code> inside <code class="verbatim">code</code>, <code class="verbatim">org</code>, <code class="verbatim">html</code> and <code class="verbatim">latex</code> results are comma-protected.</p>
271<h3 id="inserting">Inserting</h3>
272<table>
273<thead>
274<tr><th>Word</th><th>Effect</th></tr>
275</thead>
276<tbody>
277<tr><td><code class="verbatim">replace</code></td><td>Replace the previous result. This is the default.</td></tr>
278<tr><td><code class="verbatim">append</code></td><td>Add after the previous result.</td></tr>
279<tr><td><code class="verbatim">prepend</code></td><td>Add before the previous result.</td></tr>
280<tr><td><code class="verbatim">silent</code></td><td>Show the output in the message area and write nothing.</td></tr>
281<tr><td><code class="verbatim">none</code>, <code class="verbatim">discard</code></td><td>Write nothing.</td></tr>
282</tbody>
283</table>
284<p>Words from different groups combine: <code class="verbatim">:results output list append</code>. A later word replaces an earlier one from the same group.</p>
285<h3 id="wrap"><code class="verbatim">:wrap</code></h3>
286<p><code class="verbatim">:wrap</code> puts the result in a block, ahead of any format word.</p>
287<table>
288<thead>
289<tr><th>Value</th><th>Wrapped in</th></tr>
290</thead>
291<tbody>
292<tr><td><code class="verbatim">:wrap</code> alone</td><td><code class="verbatim">#+begin_results</code> … <code class="verbatim">#+end_results</code></td></tr>
293<tr><td><code class="verbatim">:wrap example</code></td><td><code class="verbatim">#+begin_example</code> … <code class="verbatim">#+end_example</code></td></tr>
294<tr><td><code class="verbatim">:wrap src python</code></td><td><code class="verbatim">#+begin_src python</code> … <code class="verbatim">#+end_src</code></td></tr>
295<tr><td><code class="verbatim">:wrap export html</code></td><td><code class="verbatim">#+begin_export html</code> … <code class="verbatim">#+end_export</code></td></tr>
296<tr><td><code class="verbatim">:wrap no</code>, <code class="verbatim">:wrap nil</code></td><td>No wrapping</td></tr>
297</tbody>
298</table>
299<p>Inside <code class="verbatim">example</code>, <code class="verbatim">src</code> and <code class="verbatim">export</code> wrappers, lines starting with <code class="verbatim">*</code> or <code class="verbatim">#+</code> are comma-protected.</p>
300<h3 id="results-in-files">Results in files</h3>
301<p>With <code class="verbatim">:results file</code>, the result is a link instead of text.</p>
302<table>
303<thead>
304<tr><th>Header</th><th>Effect</th></tr>
305</thead>
306<tbody>
307<tr><td><code class="verbatim">:file name</code></td><td>Write the result into <code class="verbatim">name</code> and link to it. Without <code class="verbatim">:results file</code>, <code class="verbatim">:file</code> has no effect, except in graphics blocks.</td></tr>
308<tr><td><code class="verbatim">:output-dir dir</code></td><td>Put <code class="verbatim">:file</code> under <code class="verbatim">dir</code>. The folder must exist.</td></tr>
309<tr><td><code class="verbatim">:file-desc text</code></td><td>Give the link a description: <code class="verbatim">[[file:name][text]]</code>. An empty <code class="verbatim">:file-desc</code> uses the file name.</td></tr>
310</tbody>
311</table>
312<p>A relative <code class="verbatim">:file</code> is written in the folder the block ran in: the file's folder, or <code class="verbatim">:dir</code>. Without <code class="verbatim">:file</code>, <code class="verbatim">:results file</code> takes the result itself as the path to link to.</p>
313<pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :results file :file out.txt :file-desc Output</span>
314echo hello
315<span class="keyword control block end org">#+end_src</span>
316</span>
317<span class="keyword other keyword org">#+RESULTS:</span>
318<span class="punctuation definition link org">[[</span><span class="markup underline link org">file:out.txt</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">[</span><span class="string other link title org">Output</span><span class="punctuation definition link org">]]</span></span></code></pre>
319<h2 id="header-arguments">Header arguments</h2>
320<h3 id="where-they-come-from">Where they come from</h3>
321<p>Orgstar merges header arguments in this order, each layer overriding the ones before it (<code class="verbatim">org-babel-get-src-block-info</code>):</p>
322<ol>
323<li><code class="verbatim">#+PROPERTY: header-args …</code> in the file, then <code class="verbatim">header-args</code> properties of the block's headings, from the outermost heading inwards.</li>
324<li><code class="verbatim">header-args:LANG</code> the same way, for blocks in language <code class="verbatim">LANG</code>.</li>
325<li>The arguments on the <code class="verbatim">#+begin_src</code> line.</li>
326<li><code class="verbatim">#+HEADER:</code> lines above the block.</li>
327<li>For a call, the call's arguments (see Calls below).</li>
328</ol>
329<p>A property written with a <code class="verbatim">+</code>, such as <code class="verbatim">header-args+</code>, adds to the value inherited from above instead of replacing it. In a property drawer, <code class="verbatim">:header-args:sh:</code> is one property name, so its value applies only to <code class="verbatim">sh</code> blocks.</p>
330<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PROPERTY:</span><span class="string unquoted org"> header-args :results output</span>
331
332<span class="markup heading org"><span class="punctuation definition heading org">*</span> Scripts
333</span>:PROPERTIES:
334:header-args:sh: :dir /tmp
335:END:
336
337<span class="keyword other keyword org">#+HEADER:</span><span class="string unquoted org"> :results verbatim</span>
338<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :var name="world"</span>
339echo "hello $name"
340<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
341<p>Without any of these, a block has <code class="verbatim">:results replace</code>, <code class="verbatim">:exports code</code>, <code class="verbatim">:session none</code>, <code class="verbatim">:cache no</code>, <code class="verbatim">:noweb no</code>, <code class="verbatim">:hlines no</code> and <code class="verbatim">:tangle no</code>. An inline <code class="verbatim">src_</code> block defaults to <code class="verbatim">:exports results</code> and <code class="verbatim">:hlines yes</code>.</p>
342<h3 id="lisp-in-header-values">Lisp in header values</h3>
343<p>A header value that starts with <code class="verbatim">(</code>, <code class="verbatim">'</code>, <code class="verbatim">`</code> or <code class="verbatim">[</code> and is not in quotes is Lisp, as in <code class="verbatim">org-babel-read</code>. Orgstar evaluates it with its own Emacs Lisp interpreter, which also knows <code class="verbatim">buffer-file-name</code>, <code class="verbatim">default-directory</code>, <code class="verbatim">system-type</code> and the functions <code class="verbatim">expand-file-name</code>, <code class="verbatim">file-name-directory</code>, <code class="verbatim">file-name-nondirectory</code>, <code class="verbatim">file-name-sans-extension</code> and <code class="verbatim">file-name-as-directory</code>.</p>
344<pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :dir (concat "/" "usr") :results output</span>
345pwd
346<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
347<p>A string or number takes the place of the form. Lisp that the interpreter cannot evaluate is refused where it matters: for <code class="verbatim">:var</code> ("is Lisp that only Emacs can evaluate"), <code class="verbatim">:colnames</code> and <code class="verbatim">:rownames</code>, and any header of a <code class="verbatim">:cache yes</code> block.</p>
348<h3 id="header-argument-reference">Header argument reference</h3>
349<table>
350<thead>
351<tr><th>Argument</th><th>Values</th><th>Effect</th></tr>
352</thead>
353<tbody>
354<tr><td><code class="verbatim">:results</code></td><td>see Results above</td><td>How the result is collected, shaped and inserted.</td></tr>
355<tr><td><code class="verbatim">:wrap</code></td><td>block type and parameters</td><td>Wraps the result in a block.</td></tr>
356<tr><td><code class="verbatim">:file</code></td><td>file name</td><td>Where a file result goes; required for graphics.</td></tr>
357<tr><td><code class="verbatim">:output-dir</code></td><td>folder</td><td>Folder for <code class="verbatim">:file</code>.</td></tr>
358<tr><td><code class="verbatim">:file-desc</code></td><td>text</td><td>Description of a file result's link.</td></tr>
359<tr><td><code class="verbatim">:var</code></td><td><code class="verbatim">name=value</code></td><td>Passes a value in (see Variables below).</td></tr>
360<tr><td><code class="verbatim">:colnames</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code>, Lisp list</td><td>Header row of table variables (see Tables in variables below).</td></tr>
361<tr><td><code class="verbatim">:rownames</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code>, Lisp list</td><td>First column of table variables.</td></tr>
362<tr><td><code class="verbatim">:hlines</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code></td><td>Keep rules in table variables.</td></tr>
363<tr><td><code class="verbatim">:separator</code></td><td>text</td><td>Column separator for tables in shell variables; a tab by default.</td></tr>
364<tr><td><code class="verbatim">:hline-string</code></td><td>text</td><td>What a rule becomes in a shell variable with <code class="verbatim">:hlines yes</code>; <code class="verbatim">hline</code> by default.</td></tr>
365<tr><td><code class="verbatim">:dir</code></td><td>folder</td><td>Folder to run in, relative to the file's folder. It must exist.</td></tr>
366<tr><td><code class="verbatim">:session</code></td><td>name, <code class="verbatim">none</code></td><td>Runs in a long-lived interpreter (see Sessions below). Shells and Python only.</td></tr>
367<tr><td><code class="verbatim">:stdin</code></td><td>name of a table, list or block</td><td>Feeds the value to standard input. Shells only.</td></tr>
368<tr><td><code class="verbatim">:cmdline</code></td><td>arguments</td><td>Command-line arguments. Shells, <code class="verbatim">dot</code>, <code class="verbatim">plantuml</code> and <code class="verbatim">mermaid</code> only.</td></tr>
369<tr><td><code class="verbatim">:shebang</code></td><td><code class="verbatim">#!…</code> line</td><td>Runs the block as a script with this first line. Shells only; also used by tangling.</td></tr>
370<tr><td><code class="verbatim">:padline</code></td><td><code class="verbatim">no</code></td><td>No blank line after the shebang of a script, or between tangled blocks.</td></tr>
371<tr><td><code class="verbatim">:python</code></td><td>program</td><td>Python interpreter to use.</td></tr>
372<tr><td><code class="verbatim">:cmd</code></td><td>program</td><td>Interpreter for <code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">R</code> and <code class="verbatim">awk</code>.</td></tr>
373<tr><td><code class="verbatim">:return</code></td><td>expression</td><td>Python: the value to return.</td></tr>
374<tr><td><code class="verbatim">:cache</code></td><td><code class="verbatim">yes</code>, <code class="verbatim">no</code></td><td>Skip the run when the result is current (see Caching below).</td></tr>
375<tr><td><code class="verbatim">:eval</code></td><td><code class="verbatim">never</code>, <code class="verbatim">no</code>, <code class="verbatim">query</code>, …</td><td>Whether and how to ask before running (see <code class="verbatim">:eval</code> above).</td></tr>
376<tr><td><code class="verbatim">:noweb</code></td><td>see Noweb below</td><td>Expands <code class="verbatim"><<name>></code> references.</td></tr>
377<tr><td><code class="verbatim">:noweb-ref</code></td><td>name</td><td>Makes the block part of <code class="verbatim"><<name>></code>.</td></tr>
378<tr><td><code class="verbatim">:noweb-sep</code></td><td>text</td><td>Separator between blocks joined under one <code class="verbatim">:noweb-ref</code>; a newline by default.</td></tr>
379<tr><td><code class="verbatim">:noweb-prefix</code></td><td><code class="verbatim">no</code></td><td>Do not repeat the text before <code class="verbatim"><<name>></code> on each expanded line.</td></tr>
380<tr><td><code class="verbatim">:exports</code></td><td><code class="verbatim">code</code>, <code class="verbatim">results</code>, <code class="verbatim">both</code>, <code class="verbatim">none</code></td><td>What export shows (see <a href="12-export.html">Export</a>).</td></tr>
381<tr><td><code class="verbatim">:tangle</code></td><td>see Tangling below</td><td>Where tangling writes the block.</td></tr>
382</tbody>
383</table>
384<h3 id="arguments-that-are-refused">Arguments that are refused</h3>
385<p>Orgstar does not run a block whose arguments it would handle differently from Emacs. Instead it says why and runs nothing.</p>
386<table>
387<thead>
388<tr><th>Argument</th><th>Refused for</th><th>Message</th></tr>
389</thead>
390<tbody>
391<tr><td><code class="verbatim">:prologue</code>, <code class="verbatim">:epilogue</code>, <code class="verbatim">:post</code></td><td>every language when running (tangling uses <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code>)</td><td>"<code class="verbatim">:prologue</code> isn't supported yet; nothing was run."</td></tr>
392<tr><td><code class="verbatim">:stdin</code>, <code class="verbatim">:shebang</code></td><td>languages other than shells</td><td>"<code class="verbatim">:stdin</code> isn't supported yet; nothing was run."</td></tr>
393<tr><td><code class="verbatim">:cmdline</code></td><td>languages other than shells and graphics</td><td>"<code class="verbatim">:cmdline</code> isn't supported for <em>language</em> yet; nothing was run."</td></tr>
394<tr><td><code class="verbatim">:session</code></td><td>languages other than shells and Python</td><td>"<code class="verbatim">:session</code> isn't supported for <em>language</em> yet; nothing was run."</td></tr>
395<tr><td><code class="verbatim">:var</code></td><td><code class="verbatim">ruby</code>, <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">R</code>, <code class="verbatim">awk</code></td><td>"<code class="verbatim">:var</code> isn't supported for <em>language</em> yet."</td></tr>
396</tbody>
397</table>
398<h2 id="variables">Variables</h2>
399<p><code class="verbatim">:var name=value</code> passes a value into the block (<code class="verbatim">org-babel-ref-resolve</code>). One <code class="verbatim">:var</code> can hold several assignments separated by spaces, and you can repeat <code class="verbatim">:var</code>. A later assignment to the same name replaces an earlier one.</p>
400<table>
401<thead>
402<tr><th>Value</th><th>Meaning</th></tr>
403</thead>
404<tbody>
405<tr><td><code class="verbatim">5</code>, <code class="verbatim">2.5</code></td><td>A number.</td></tr>
406<tr><td><code class="verbatim">"two words"</code></td><td>A string. <code class="verbatim">\n</code> and <code class="verbatim">\t</code> in it are a newline and a tab.</td></tr>
407<tr><td><code class="verbatim">'(1 2)</code>, <code class="verbatim">(+ 1 2)</code>, <code class="verbatim">'((1 2) hline (3 4))</code></td><td>Lisp: evaluated to a string, number, list or table.</td></tr>
408<tr><td><code class="verbatim">tbl</code></td><td>The table or plain list under <code class="verbatim">#+NAME: tbl</code> in the same file.</td></tr>
409<tr><td><code class="verbatim">gen</code></td><td>The result of the source block named <code class="verbatim">gen</code>, which runs first.</td></tr>
410<tr><td><code class="verbatim">double(n=4)</code></td><td>The result of the block named <code class="verbatim">double</code>, run with <code class="verbatim">n</code> set to 4.</td></tr>
411</tbody>
412</table>
413<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> nums</span>
414<span class="markup other table org">| 1 | 2 |</span>
415<span class="markup other table org">| 3 | 4 |</span>
416
417<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :var t=nums :var scale=10</span>
418return [[c * scale for c in row] for row in t]
419<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
420<p>A referenced block runs before the block that refers to it, after the one trust prompt that covers them all. A block with <code class="verbatim">:cache yes</code> and a current result gives that result without running. A chain that leads back to itself is refused with "<em>name</em> refers to itself through :var".</p>
421<p>These are not supported and are refused:</p>
422<ul>
423<li>Indexing into a table, such as <code class="verbatim">tbl[1,2]</code>: "References like … aren't supported yet."</li>
424<li>A name that matches nothing in the file: "Can't find … for :var."</li>
425<li>References to other files.</li>
426</ul>
427<p>How a value reaches the code depends on the language:</p>
428<table>
429<thead>
430<tr><th>Language</th><th>Scalars</th><th>Lists</th><th>Tables</th></tr>
431</thead>
432<tbody>
433<tr><td>bash</td><td>quoted string</td><td>indexed array (<code class="verbatim">declare -a</code>)</td><td>two or more columns: associative array keyed by the first column (<code class="verbatim">declare -A</code>); one column: indexed array</td></tr>
434<tr><td>other shells</td><td>quoted string</td><td>one item per line</td><td>rows on lines, cells separated by a tab or <code class="verbatim">:separator</code></td></tr>
435<tr><td>fish</td><td><code class="verbatim">set name 'value'</code></td><td>as other shells</td><td>as other shells</td></tr>
436<tr><td>Python</td><td>literal</td><td>list</td><td>list of lists, <code class="verbatim">None</code> for rules</td></tr>
437<tr><td>Emacs Lisp</td><td><code class="verbatim">let</code>-bound value</td><td>list</td><td>list of lists, <code class="verbatim">hline</code> for rules</td></tr>
438</tbody>
439</table>
440<p>For <code class="verbatim">shell</code> blocks, the bash forms are used when <code class="verbatim">SHELL</code> is bash.</p>
441<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> kv</span>
442<span class="markup other table org">| a | 1 |</span>
443<span class="markup other table org">| b | 2 |</span>
444
445<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> bash :var t=kv :results output</span>
446echo ${t[a]} ${t[b]}
447<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
448<h3 id="tables-in-variables">Tables in variables</h3>
449<p>A table passed as a variable loses some of its structure first (<code class="verbatim">org-babel-disassemble-tables</code>):</p>
450<ul>
451<li>Rules are removed, unless <code class="verbatim">:hlines yes</code>.</li>
452<li>The first row is taken off as column names when <code class="verbatim">:colnames yes</code>, or when the table's only rule is under the first row. <code class="verbatim">:colnames no</code> keeps it as data.</li>
453<li>The first column is taken off as row names when <code class="verbatim">:rownames yes</code>.</li>
454</ul>
455<p>If the result is a table of the same width (for columns) or height (for rows), the names are put back on it (<code class="verbatim">org-babel-reassemble-table</code>). <code class="verbatim">:colnames</code> and <code class="verbatim">:rownames</code> can also be Lisp lists of names to put on the result, such as <code class="verbatim">:colnames '("x" "y")</code>.</p>
456<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> tbl</span>
457<span class="markup other table org">| a | b |</span>
458<span class="markup other table org">|---+---|</span>
459<span class="markup other table org">| 1 | x |</span>
460<span class="markup other table org">| 2 | y |</span>
461
462<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :var t=tbl</span>
463return [r + ["!"] for r in t]
464<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
465<h3 id="standard-input-and-arguments">Standard input and arguments</h3>
466<p>For shell blocks, <code class="verbatim">:stdin name</code> sends a table, list or block result to standard input, a table as tab-separated lines. <code class="verbatim">:cmdline</code> gives the script arguments, and <code class="verbatim">:shebang</code> its first line. With any of the three, the block is written to an executable script and run by the shell (<code class="verbatim">org-babel-sh-evaluate</code>); without <code class="verbatim">:shebang</code>, the first line is <code class="verbatim">#!/usr/bin/env</code> and the shell's name. A block with <code class="verbatim">:stdin</code> or <code class="verbatim">:cmdline</code> runs as a script even with a <code class="verbatim">:session</code>, and leaves the session untouched; <code class="verbatim">:shebang</code> alone runs in the session.</p>
467<pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :cmdline one "two words" :results output</span>
468for a in "$@"; do echo "[$a]"; done
469<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
470<h2 id="sessions">Sessions</h2>
471<p><code class="verbatim">:session name</code> 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 and Python on the Mac.</p>
472<ul>
473<li><code class="verbatim">:session</code> with no name uses <code class="verbatim">*language*</code>, such as <code class="verbatim">*sh*</code>. <code class="verbatim">:session none</code> runs without one.</li>
474<li>A session belongs to one folder, one interpreter and one name. Blocks in different folders, or with different names, do not share state.</li>
475<li>A session starts in the block's <code class="verbatim">:dir</code>, or the file's folder, the first time it is used.</li>
476<li>A shell session's output is what the block prints. <code class="verbatim">:results value</code> gives the exit status of the last command.</li>
477<li>A Python session runs the block at top level. Its value is the value of the last expression, so <code class="verbatim">return</code> is not used.</li>
478<li>Sessions stop when you quit Orgstar, or when you cancel a block running in one.</li>
479</ul>
480<pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :session py :results output</span>
481a = 2
482print("set")
483<span class="keyword control block end org">#+end_src</span>
484</span>
485<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> python :session py</span>
486a * 3
487<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
488<h2 id="caching">Caching</h2>
489<p>With <code class="verbatim">:cache yes</code>, Orgstar computes a SHA-1 hash of the block's header arguments and expanded body, as <code class="verbatim">org-babel-sha1-hash</code> does, and writes it on the results line: <code class="verbatim">#+RESULTS[hash]:</code>. When you run the block again and the hash matches, nothing runs and the message area shows the cached value ("Cached: …").</p>
490<p>Change the block or its arguments and it runs again. Results inserted with <code class="verbatim">append</code> or <code class="verbatim">prepend</code> carry no hash. Inline blocks are not cached. A cached block that has Lisp in its header arguments the interpreter cannot evaluate is refused.</p>
491<p>C, C++, D, Fortran and Clojure blocks don't run in Orgstar, but their hash is taken over the body as tangling expands it (see Tangling below), as Emacs does. A result Emacs wrote for such a block with <code class="verbatim">:cache yes</code> is recognised as current, and <code class="verbatim">C-c C-c</code> shows it.</p>
492<h2 id="noweb">Noweb</h2>
493<p>A noweb reference <code class="verbatim"><<name>></code> in a block's body stands for other code. Whether references expand depends on <code class="verbatim">:noweb</code> and on what is happening:</p>
494<table>
495<thead>
496<tr><th><code class="verbatim">:noweb</code></th><th>Running</th><th>Tangling</th><th>Exporting</th></tr>
497</thead>
498<tbody>
499<tr><td><code class="verbatim">no</code> (default)</td><td>no</td><td>no</td><td>no</td></tr>
500<tr><td><code class="verbatim">yes</code></td><td>expands</td><td>expands</td><td>no</td></tr>
501<tr><td><code class="verbatim">tangle</code></td><td>no</td><td>expands</td><td>no</td></tr>
502<tr><td><code class="verbatim">eval</code></td><td>expands</td><td>no</td><td>no</td></tr>
503<tr><td><code class="verbatim">no-export</code></td><td>expands</td><td>expands</td><td>no</td></tr>
504<tr><td><code class="verbatim">strip-export</code></td><td>expands</td><td>expands</td><td>no</td></tr>
505<tr><td><code class="verbatim">strip-tangle</code></td><td>expands</td><td>removes the references</td><td>no</td></tr>
506</tbody>
507</table>
508<p>Exported code always shows the references as written; see <a href="12-export.html">Export</a>.</p>
509<p><code class="verbatim"><<name>></code> expands to the first of these that exists:</p>
510<ol>
511<li>The contents of the heading whose <code class="verbatim">ID</code> property is <code class="verbatim">name</code>, or whose <code class="verbatim">CUSTOM_ID</code> is <code class="verbatim">name</code> without its leading <code class="verbatim">#</code>.</li>
512<li>The body of the source block named <code class="verbatim">name</code>.</li>
513<li>The bodies of all blocks with <code class="verbatim">:noweb-ref name</code>, joined by each block's <code class="verbatim">:noweb-sep</code> (a newline by default).</li>
514</ol>
515<p>Blocks under a <code class="verbatim">COMMENT</code> heading are skipped. A referenced block expands its own references according to its own <code class="verbatim">:noweb</code>, up to 32 levels deep.</p>
516<p>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. <code class="verbatim">:noweb-prefix no</code> turns this off.</p>
517<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> greeting</span>
518<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh</span>
519echo hello
520<span class="keyword control block end org">#+end_src</span>
521</span>
522<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :noweb yes</span>
523<<greeting>>
524echo world
525<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
526<p>A reference that runs a block, <code class="verbatim"><<name()>></code>, is refused: "Noweb references that run a block (…) aren't supported yet; nothing was run."</p>
527<h2 id="calls">Calls</h2>
528<h3 id="call-lines"><code class="verbatim">#+CALL:</code> lines</h3>
529<p><code class="verbatim">#+CALL:</code> runs a named block with other arguments, as Org's library of Babel calls do (<code class="verbatim">org-babel-lob-get-info</code>). Run it with <code class="verbatim">C-c C-c</code> on the line.</p>
530<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+NAME:</span><span class="string unquoted org"> double</span>
531<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh :var n=2</span>
532echo $((n*2))
533<span class="keyword control block end org">#+end_src</span>
534</span>
535<span class="keyword other keyword org">#+CALL:</span><span class="string unquoted org"> double(n=5)</span>
536
537<span class="keyword other keyword org">#+RESULTS:</span>
538: 10</span></code></pre>
539<p>The full form is <code class="verbatim">#+CALL: name[inside](arguments) end</code>:</p>
540<ul>
541<li><code class="verbatim">name</code> is the block to run. It must be in the same file.</li>
542<li><code class="verbatim">[inside]</code> holds header arguments applied to the block, such as <code class="verbatim">[:results raw]</code>.</li>
543<li><code class="verbatim">(arguments)</code> are <code class="verbatim">:var</code> assignments, separated by commas.</li>
544<li><code class="verbatim">end</code> holds header arguments for the call's result, such as <code class="verbatim">:results verbatim</code>.</li>
545</ul>
546<p>The call also takes the <code class="verbatim">header-args</code> and <code class="verbatim">header-args:LANG</code> properties, and <code class="verbatim">#+PROPERTY:</code> lines, where the call is, with <code class="verbatim">LANG</code> the called block's language. They apply after the called block's own header arguments and before <code class="verbatim">[inside]</code>, as in Org.</p>
547<p>The result goes under the call. A <code class="verbatim">#+NAME:</code> line above the <code class="verbatim">#+CALL:</code> names the result.</p>
548<h3 id="inline-calls-and-blocks">Inline calls and blocks</h3>
549<p>An inline source block, <code class="verbatim">src_sh{echo hi}</code>, runs with <code class="verbatim">C-c C-c</code> on it. Header arguments go in brackets: <code class="verbatim">src_sh[:var x=3]{echo $x}</code>. The result is written right after the block as a <code class="verbatim">results</code> macro:</p>
550<pre><code class="language-org highlight"><span class="text org">Text src_sh{echo hi} {{{results(<span class="markup raw inline org">=hi=</span>)}}} end.</span></code></pre>
551<p>Running again replaces the macro. With <code class="verbatim">:results raw</code> 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.</p>
552<p>An inline call, <code class="verbatim">call_double(n=6)</code>, has the same parts as a <code class="verbatim">#+CALL:</code> line: <code class="verbatim">call_name[inside](arguments)[end]</code>. <code class="verbatim">C-c C-c</code> on an inline call runs it, and its result is written after it as a <code class="verbatim">results</code> macro, as for inline blocks. It takes the properties where it is as a <code class="verbatim">#+CALL:</code> line does.</p>
553<h2 id="emacs-lisp-blocks">Emacs Lisp blocks</h2>
554<p>On the Mac, an <code class="verbatim">emacs-lisp</code> or <code class="verbatim">elisp</code> block runs in a new <code class="verbatim">emacs -Q --batch</code> for each run, with lexical binding on. <code class="verbatim">-Q</code> means your init file and packages are not loaded, and nothing carries over between runs. Orgstar looks for Emacs at <code class="verbatim">ORGSTAR_EMACS</code>, then <code class="verbatim">/opt/homebrew/bin/emacs</code>, <code class="verbatim">/usr/local/bin/emacs</code>, <code class="verbatim">/Applications/Emacs.app/Contents/MacOS/Emacs</code>, <code class="verbatim">/run/current-system/sw/bin/emacs</code> and <code class="verbatim">/usr/bin/emacs</code>. Without Emacs, the block fails with "Emacs isn't installed, so Emacs Lisp blocks can't run."</p>
555<p>On iOS, Emacs Lisp blocks run in Orgstar's own Emacs Lisp interpreter. It covers ordinary list, string, number and control forms, <code class="verbatim">princ</code> and <code class="verbatim">message</code>. 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.</p>
556<p>Variables are bound with <code class="verbatim">let</code> around the body. <code class="verbatim">:results output</code> collects what the block prints with <code class="verbatim">princ</code>, <code class="verbatim">prin1</code>, <code class="verbatim">print</code> and <code class="verbatim">terpri</code>.</p>
557<h2 id="graphics">Graphics</h2>
558<p><code class="verbatim">dot</code> (Graphviz), <code class="verbatim">plantuml</code> and <code class="verbatim">mermaid</code> blocks draw a picture into <code class="verbatim">:file</code>, and the result is a link to it. <code class="verbatim">:file</code> is required: "<em>language</em> code blocks need a :file header argument". The file's extension picks the output format; with none, <code class="verbatim">png</code> is used.</p>
559<table>
560<thead>
561<tr><th>Language</th><th>Command</th></tr>
562</thead>
563<tbody>
564<tr><td><code class="verbatim">dot</code></td><td><code class="verbatim">dot -T/ext/ -o file</code></td></tr>
565<tr><td><code class="verbatim">plantuml</code></td><td><code class="verbatim">plantuml -p -t/ext/</code>, output to the file</td></tr>
566<tr><td><code class="verbatim">mermaid</code></td><td><code class="verbatim">mmdc -i input -o file</code></td></tr>
567</tbody>
568</table>
569<p>A <code class="verbatim">plantuml</code> body without an <code class="verbatim">@start…</code> line is wrapped in <code class="verbatim">@startuml</code> and <code class="verbatim">@enduml</code>. <code class="verbatim">:cmdline</code> adds options to the command. The program must be installed and on the <code class="verbatim">PATH</code> described under Languages that run.</p>
570<pre><code class="language-org highlight"><span class="text org"><span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> dot :file graph.svg</span>
571digraph { a -> b }
572<span class="keyword control block end org">#+end_src</span>
573</span>
574<span class="keyword other keyword org">#+RESULTS:</span>
575<span class="punctuation definition link org">[[</span><span class="markup underline link org">file:graph.svg</span><span class="punctuation definition link org">]</span><span class="punctuation definition link org">]</span></span></code></pre>
576<h2 id="tangling">Tangling</h2>
577<p>Tangling writes source blocks to the files their <code class="verbatim">:tangle</code> argument names (<code class="verbatim">org-babel-tangle</code>).</p>
578<table>
579<thead>
580<tr><th>Command</th><th>Emacs and Doom</th><th>Mac</th><th>What it tangles</th></tr>
581</thead>
582<tbody>
583<tr><td>Tangle File</td><td><code class="verbatim">C-c C-v t</code>, <code class="verbatim">C-c C-v C-t</code></td><td><code class="verbatim">⌃⌘V</code></td><td>Every block in the file</td></tr>
584<tr><td>Tangle Block</td><td>none</td><td>none</td><td>The block at the caret (Emacs: <code class="verbatim">C-u C-c C-v t</code>)</td></tr>
585<tr><td>Tangle Block's Target</td><td>none</td><td>none</td><td>Every block going to the same file as the one at the caret (Emacs: <code class="verbatim">C-u C-u C-c C-v t</code>)</td></tr>
586</tbody>
587</table>
588<p>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 <em>N</em> code blocks from <em>file</em>".</p>
589<h3 id="tangle-and-file-names"><code class="verbatim">:tangle</code> and file names</h3>
590<table>
591<thead>
592<tr><th><code class="verbatim">:tangle</code></th><th>Target</th></tr>
593</thead>
594<tbody>
595<tr><td><code class="verbatim">no</code> (default)</td><td>Not tangled.</td></tr>
596<tr><td><code class="verbatim">yes</code></td><td>The Org file's name with the language's extension, as Org's language files define it (<code class="verbatim">org-babel-tangle-lang-exts</code>): <code class="verbatim">py</code> for <code class="verbatim">python</code>, <code class="verbatim">rb</code> for <code class="verbatim">ruby</code>, <code class="verbatim">pl</code> for <code class="verbatim">perl</code>, <code class="verbatim">cpp</code> for <code class="verbatim">C++</code>, <code class="verbatim">d</code> for <code class="verbatim">D</code>, <code class="verbatim">awk</code>, <code class="verbatim">sed</code>, <code class="verbatim">lua</code>, <code class="verbatim">hs</code> for <code class="verbatim">haskell</code>, <code class="verbatim">java</code>, <code class="verbatim">tex</code> for <code class="verbatim">latex</code>, <code class="verbatim">ly</code> for <code class="verbatim">LilyPond</code>, <code class="verbatim">F90</code> for <code class="verbatim">fortran</code>, <code class="verbatim">clj</code> for <code class="verbatim">clojure</code>, <code class="verbatim">cljs</code> for <code class="verbatim">clojurescript</code>, <code class="verbatim">cs</code> for <code class="verbatim">csharp</code>, <code class="verbatim">groovy</code>, <code class="verbatim">jl</code> for <code class="verbatim">julia</code>, <code class="verbatim">lisp</code>, <code class="verbatim">max</code> for <code class="verbatim">maxima</code>, <code class="verbatim">ml</code> for <code class="verbatim">ocaml</code>, <code class="verbatim">pde</code> for <code class="verbatim">processing</code>, <code class="verbatim">el</code> for <code class="verbatim">emacs-lisp</code> and <code class="verbatim">elisp</code>, and <code class="verbatim">bib</code> for <code class="verbatim">bibtex</code>. Any other language is its own extension (<code class="verbatim">notes.sh</code> for <code class="verbatim">sh</code>).</td></tr>
597<tr><td>a path</td><td>That file, relative to the Org file's folder. <code class="verbatim">~</code> is expanded.</td></tr>
598<tr><td>Lisp</td><td>Evaluated as described under Lisp in header values, with <code class="verbatim">buffer-file-name</code> set to the Org file.</td></tr>
599</tbody>
600</table>
601<p>Blocks under a <code class="verbatim">COMMENT</code> heading, or a heading tagged <code class="verbatim">ARCHIVE</code>, are skipped. Blocks going to the same file are written in the order they appear.</p>
602<pre><code class="language-org highlight"><span class="text org"><span class="keyword other keyword org">#+PROPERTY:</span><span class="string unquoted org"> header-args:python :tangle script.py</span>
603
604<span class="markup heading org"><span class="punctuation definition heading org">*</span> Tool
605</span>:PROPERTIES:
606:header-args: :tangle bin<span class="markup italic org">/tool.sh :mkdirp yes :shebang "#!/</span>bin/sh"
607:END:
608
609<span class="markup raw block org"><span class="keyword control block begin org">#+begin_src</span><span class="variable parameter org"> sh</span>
610echo tool
611<span class="keyword control block end org">#+end_src</span></span></span></code></pre>
612<h3 id="tangling-arguments">Tangling arguments</h3>
613<table>
614<thead>
615<tr><th>Argument</th><th>Values</th><th>Effect</th></tr>
616</thead>
617<tbody>
618<tr><td><code class="verbatim">:mkdirp</code></td><td><code class="verbatim">yes</code></td><td>Create the target's folder if it is missing.</td></tr>
619<tr><td><code class="verbatim">:tangle-mode</code></td><td><code class="verbatim">(identity #o755)</code>, <code class="verbatim">#o755</code>, <code class="verbatim">o755</code>, <code class="verbatim">rwxr-xr-x</code>, <code class="verbatim">u+x,g-r</code></td><td>Set the file's mode. A symbolic mode starts from <code class="verbatim">644</code>. When several blocks give a mode, the first one counts.</td></tr>
620<tr><td><code class="verbatim">:shebang</code></td><td><code class="verbatim">#!…</code> line</td><td>First line of the file, written once. Makes the file mode <code class="verbatim">755</code> unless <code class="verbatim">:tangle-mode</code> says otherwise.</td></tr>
621<tr><td><code class="verbatim">:padline</code></td><td><code class="verbatim">no</code></td><td>No blank line between this block and the one before it.</td></tr>
622<tr><td><code class="verbatim">:comments</code></td><td><code class="verbatim">no</code>, <code class="verbatim">link</code>, <code class="verbatim">yes</code>, <code class="verbatim">org</code>, <code class="verbatim">both</code>, <code class="verbatim">noweb</code></td><td>Comments around each block (below).</td></tr>
623<tr><td><code class="verbatim">:noweb</code></td><td>see Noweb above</td><td>Expand or strip <code class="verbatim"><<name>></code> references.</td></tr>
624<tr><td><code class="verbatim">:prologue</code>, <code class="verbatim">:epilogue</code></td><td>text</td><td>A line before and after the block's code.</td></tr>
625<tr><td><code class="verbatim">:var</code></td><td>as for running</td><td>Shell scalars become assignments, Python values become assignments, Emacs Lisp values are <code class="verbatim">let</code>-bound. For the languages below, as their Org language files write them.</td></tr>
626<tr><td><code class="verbatim">:no-expand</code></td><td>any</td><td>Write the body without <code class="verbatim">:var</code>, <code class="verbatim">:prologue</code>, <code class="verbatim">:epilogue</code> or the language's wrapping.</td></tr>
627</tbody>
628</table>
629<p>A table in <code class="verbatim">:var</code> loses its first row when its only rule is under that row, or with <code class="verbatim">:colnames yes</code>, and its rules unless <code class="verbatim">:hlines yes</code>, as when the block runs. This holds for every language.</p>
630<p><code class="verbatim">C</code>, <code class="verbatim">C++</code>, <code class="verbatim">cpp</code>, <code class="verbatim">D</code>, <code class="verbatim">java</code>, <code class="verbatim">fortran</code> and <code class="verbatim">clojure</code> blocks are written as Org's <code class="verbatim">org-babel-expand-body:LANG</code> writes them:</p>
631<table>
632<thead>
633<tr><th>Language</th><th>Written</th></tr>
634</thead>
635<tbody>
636<tr><td><code class="verbatim">C</code>, <code class="verbatim">C++</code>, <code class="verbatim">cpp</code></td><td><code class="verbatim">#include</code> lines from <code class="verbatim">:includes</code>, <code class="verbatim">#define</code> lines from <code class="verbatim">:defines</code>, <code class="verbatim">using namespace</code> lines from <code class="verbatim">:namespaces</code>, the <code class="verbatim">:var</code> declarations with table sizes and column-name helpers, then the body between <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code>, wrapped in <code class="verbatim">int main()</code> unless it has a <code class="verbatim">main</code> or <code class="verbatim">:main no</code> is given.</td></tr>
637<tr><td><code class="verbatim">D</code></td><td><code class="verbatim">module mmm;</code>, <code class="verbatim">import</code> lines from <code class="verbatim">:imports</code> plus <code class="verbatim">std.stdio</code> and <code class="verbatim">std.conv</code>, the <code class="verbatim">:var</code> declarations, and the body wrapped in <code class="verbatim">int main()</code> as for C.</td></tr>
638<tr><td><code class="verbatim">java</code></td><td>The body between <code class="verbatim">:prologue</code> and <code class="verbatim">:epilogue</code>, wrapped in a <code class="verbatim">main</code> method when it has no method and in a class when it has none. The class is named by <code class="verbatim">:classname</code> or the body's own class; a dotted <code class="verbatim">:classname</code> adds a <code class="verbatim">package</code> line. <code class="verbatim">:imports</code> adds <code class="verbatim">import</code> lines, and <code class="verbatim">:var</code> values become static fields.</td></tr>
639<tr><td><code class="verbatim">fortran</code></td><td><code class="verbatim">#include</code> and <code class="verbatim">#define</code> lines from <code class="verbatim">:includes</code> and <code class="verbatim">:defines</code>, then the <code class="verbatim">:var</code> declarations and the body in <code class="verbatim">program main</code>, unless the body has its own <code class="verbatim">program</code> statement (then <code class="verbatim">:var</code> is refused) or <code class="verbatim">:main no</code> is given.</td></tr>
640<tr><td><code class="verbatim">clojure</code></td><td><code class="verbatim">(ns …)</code> from <code class="verbatim">:ns</code>, the body in a <code class="verbatim">let</code> of the <code class="verbatim">:var</code> values, and a printer around it unless <code class="verbatim">:results output</code>.</td></tr>
641</tbody>
642</table>
643<p>With <code class="verbatim">:hlines yes</code>, a table that keeps rules is refused for C, C++, D and Fortran; Java writes <code class="verbatim">null</code> for each rule.</p>
644<p>Block switches also apply. <code class="verbatim">-r</code> removes coderef labels such as <code class="verbatim">(ref:name)</code>, using the format from <code class="verbatim">-l</code> if given. <code class="verbatim">-i</code> keeps the block's indentation. Otherwise common indentation and surrounding blank lines are removed.</p>
645<h3 id="comments">Comments</h3>
646<table>
647<thead>
648<tr><th><code class="verbatim">:comments</code></th><th>Written</th></tr>
649</thead>
650<tbody>
651<tr><td><code class="verbatim">no</code></td><td>The code only.</td></tr>
652<tr><td><code class="verbatim">link</code>, <code class="verbatim">yes</code></td><td>A comment with a link back to the block before the code, and "<em>name</em> ends here" after it.</td></tr>
653<tr><td><code class="verbatim">org</code></td><td>The Org text between the heading (or the previous block) and this block, as a comment.</td></tr>
654<tr><td><code class="verbatim">both</code></td><td>The Org text and the link comments.</td></tr>
655<tr><td><code class="verbatim">noweb</code></td><td>Link comments, plus link comments around each expanded noweb reference.</td></tr>
656</tbody>
657</table>
658<p>The link is relative to the tangled file's folder. <em>name</em> is the block's <code class="verbatim">#+NAME</code>, or the heading's title and the block's number under that heading, such as <code class="verbatim">Setup:2</code>.</p>
659<p>Comments need the language's comment syntax. Orgstar knows it for: <code class="verbatim">emacs-lisp</code>, <code class="verbatim">elisp</code>, <code class="verbatim">lisp</code>, <code class="verbatim">scheme</code>, <code class="verbatim">asm</code> (<code class="verbatim">;;</code>); <code class="verbatim">python</code>, <code class="verbatim">ruby</code>, <code class="verbatim">perl</code>, <code class="verbatim">conf</code>, <code class="verbatim">toml</code>, <code class="verbatim">makefile</code>, <code class="verbatim">awk</code>, <code class="verbatim">tcl</code>, <code class="verbatim">m4</code>, <code class="verbatim">icon</code>, <code class="verbatim">desktop</code> and the shells except <code class="verbatim">fish</code> (<code class="verbatim">#</code>); <code class="verbatim">js</code>, <code class="verbatim">javascript</code>, <code class="verbatim">java</code>, <code class="verbatim">cpp</code>, <code class="verbatim">C++</code>, <code class="verbatim">objc</code>, <code class="verbatim">csharp</code>, <code class="verbatim">idl</code>, <code class="verbatim">pike</code>, <code class="verbatim">antlr</code>, <code class="verbatim">verilog</code> (<code class="verbatim">//</code>); <code class="verbatim">c</code>, <code class="verbatim">C</code>, <code class="verbatim">css</code> (<code class="verbatim">/* */</code>); <code class="verbatim">lua</code>, <code class="verbatim">sql</code>, <code class="verbatim">sqlite</code>, <code class="verbatim">vhdl</code> (<code class="verbatim">--</code>); <code class="verbatim">latex</code>, <code class="verbatim">tex</code>, <code class="verbatim">prolog</code> (<code class="verbatim">%%</code>); <code class="verbatim">ps</code>, <code class="verbatim">metapost</code> (<code class="verbatim">%</code>); <code class="verbatim">f90</code>, <code class="verbatim">dcl</code> (<code class="verbatim">!</code>); <code class="verbatim">html</code>, <code class="verbatim">xml</code>, <code class="verbatim">nxml</code>, <code class="verbatim">mhtml</code>, <code class="verbatim">sgml</code> (<code class="verbatim"><!-- --></code>); <code class="verbatim">octave</code> (<code class="verbatim">##</code>); <code class="verbatim">pascal</code> (<code class="verbatim">{ }</code>); <code class="verbatim">texinfo</code> (<code class="verbatim">@c</code>); <code class="verbatim">bibtex</code> (<code class="verbatim">@Comment</code>); <code class="verbatim">nroff</code> (<code class="verbatim">\"</code>); <code class="verbatim">bat</code> (<code class="verbatim">rem</code>). For any other language, <code class="verbatim">:comments</code> other than <code class="verbatim">no</code> stops tangling with a message.</p>
660<h3 id="writing-the-files">Writing the files</h3>
661<ul>
662<li>A file whose contents would not change is left alone, so its modification time stays the same.</li>
663<li>A read-only file is replaced.</li>
664<li>Tangling into the Org file itself is refused: "Not allowed to tangle into the same file as self".</li>
665</ul>
666<h3 id="what-tangling-refuses">What tangling refuses</h3>
667<p>Tangling stops, writes nothing and says why when:</p>
668<ul>
669<li><code class="verbatim">:var</code> refers to a source block, which would have to run: "would run a block while tangling".</li>
670<li>A shell block's <code class="verbatim">:var</code> is a table or list.</li>
671<li><code class="verbatim">:var</code> is used in a language other than shells, Python, Emacs Lisp, C, C++, D, Java, Fortran and Clojure.</li>
672<li>A C, C++, D or Fortran block's <code class="verbatim">:var</code> table keeps rules (with <code class="verbatim">:hlines yes</code>), or a value has no type the language takes.</li>
673<li>A Lisp header value cannot be evaluated: "is Lisp tangling can't evaluate yet; nothing was tangled."</li>
674<li><code class="verbatim">:tangle-mode</code> is in a form it does not read.</li>
675<li><code class="verbatim">:comments</code> needs a comment syntax it does not know.</li>
676</ul>
677<h2 id="on-ios">On iOS</h2>
678<ul>
679<li>Only Emacs Lisp blocks run, in Orgstar's own interpreter. Any other language fails with "<em>language</em> blocks need the Mac to run.", and so does an Emacs Lisp block whose <code class="verbatim">:var</code> refers to a block in another language.</li>
680<li>There are no sessions and no graphics.</li>
681<li>The trust prompt works the same way, with its own <code class="verbatim">trusted.json</code> on the device.</li>
682<li>There is no cancel command.</li>
683<li>Tangling works, for files in folders Orgstar can write to.</li>
684<li>Edit Block opens a plain text sheet without highlighting.</li>
685</ul>
686<p>See <a href="14-ios.html">iOS</a> for the rest of the iOS app.</p>
687</main>
688<footer class="site">
689Orgstar is 0BSD-licensed. Source: <a href="https://gitbay.org/krz/orgstar">gitbay.org/krz/orgstar</a>.
690</footer>
691</body>
692</html>