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