Movatterモバイル変換

Next:Library of Babel, Previous:Editing Source Code, Up:Working with Source Code [Contents][Index]

16.11 Noweb Reference Syntax ¶

Source code blocks can include references to other source code blocks,using a noweb¹⁵⁴ style syntax:

<<CODE-BLOCK-ID>>

whereCODE-BLOCK-ID refers to either the ‘NAME’ of a singlesource code block, or a collection of one or more source code blockssharing the same ‘noweb-ref’ header argument (seeUsing Header Arguments). Org can replace such references with the source code ofthe block or blocks being referenced, or, in the case of a singlesource code block named with ‘NAME’, with the results of an evaluationof that block.

The ‘noweb’ header argument controls expansion of noweb syntaxreferences. Expansions occur when source code blocks are evaluated,tangled, or exported.

‘no’: Default. No expansion of noweb syntax references in the body of thecode when evaluating, tangling, or exporting.
‘yes’: Expansion of noweb syntax references in the body of the code blockwhen evaluating, tangling, or exporting.
‘tangle’: Expansion of noweb syntax references in the body of the code blockwhen tangling. No expansion when evaluating or exporting.
‘strip-tangle’: Expansion of noweb syntax references in the body of the code blockwhen evaluating or exporting. Removes noweb syntax referenceswhen exporting.
‘no-export’: Expansion of noweb syntax references in the body of the code blockwhen evaluating or tangling. No expansion when exporting.
‘strip-export’: Expansion of noweb syntax references in the body of the code blockwhen expanding prior to evaluating or tangling. Removes nowebsyntax references when exporting.
‘eval’: Expansion of noweb syntax references in the body of the code blockonly before evaluating.

In the most simple case, the contents of a single source block isinserted within other blocks. Thus, in following example,

#+NAME: initialization#+BEGIN_SRC emacs-lisp  (setq sentence "Never a foot too far, even.")#+END_SRC#+BEGIN_SRC emacs-lisp :noweb yes  <<initialization>>  (reverse sentence)#+END_SRC

the second code block is expanded as

#+BEGIN_SRC emacs-lisp :noweb yes  (setq sentence "Never a foot too far, even.")  (reverse sentence)#+END_SRC

Note that noweb expansion does not automatically carry over ‘:var’header arguments¹⁵⁵.

You may also include the contents of multiple blocks sharing a common‘noweb-ref’ header argument, which can be set at the file, subtree,or code block level. In the example Org file shown next, the body ofthe source code in each block is extracted for concatenation to a purecode file when tangled.

#+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh  <<fullest-disk>>#+END_SRC* the mount point of the fullest disk  :PROPERTIES:  :header-args: :noweb-ref fullest-disk  :END:** query all mounted disks#+BEGIN_SRC sh  df \#+END_SRC** strip the header row#+BEGIN_SRC sh  |sed '1d' \#+END_SRC** output mount point of fullest disk#+BEGIN_SRC sh  |awk '{if (u < +$5) {u = +$5; m = $6}} END {print m}'#+END_SRC

By default a newline separates each noweb reference concatenation. Touse a different separator, edit the ‘noweb-sep’ header argument.

Alternatively, Org can include the results of evaluation of a singlecode block rather than its body [¹⁵⁶. Evaluation occurs when parentheses, possibly includingarguments, are appended to the code block name, as shown below.

<<NAME(optional arguments)>>

Note that in this case, a code block name set by ‘NAME’ keyword isrequired; the reference set by ‘noweb-ref’ will not work whenevaluation is desired.

Here is an example that demonstrates how the exported content changeswhen noweb style references are used with parentheses versus without.Given:

#+NAME: some-code#+BEGIN_SRC python :var num=0 :results output :exports noneprint(num*10)#+END_SRC

this code block:

#+BEGIN_SRC text :noweb yes  <<some-code>>#+END_SRC

expands to:

print(num*10)

Below, a similar noweb style reference is used, but with parentheses,while setting a variable ‘num’ to 10:

#+BEGIN_SRC text :noweb yes  <<some-code(num=10)>>#+END_SRC

Note that the expansion now contains the results of the code block‘some-code’, not the code block itself:

Noweb insertions honor prefix characters that appear before the nowebsyntax reference. This behavior is illustrated in the followingexample. Because the ‘<<example>>’ noweb reference appears behind theSQL comment syntax, each line of the expanded noweb reference iscommented. With:

#+NAME: example#+BEGIN_SRC text  this is the  multi-line body of example#+END_SRC

this code block:

#+BEGIN_SRC sql :noweb yes ---<<example>>#+END_SRC

expands to:

#+BEGIN_SRC sql :noweb yes ---this is the ---multi-line body of example#+END_SRC

Since this change does not affect noweb replacement text withoutnewlines in them, inline noweb references are acceptable.

This feature can also be used for management of indentation inexported code snippets. With:

#+NAME: if-true#+BEGIN_SRC python :exports noneprint('do things when true')#+end_src#+name: if-false#+begin_src python :exports noneprint('do things when false')#+end_src

this code block:

#+begin_src python :noweb yes :results outputif true:    <<if-true>>else:    <<if-false>>#+end_src

expands to:

if true:    print('do things when true')else:    print('do things when false')

This prefix behavior can be turned off in a block by setting the‘noweb-prefix’ header argument to ‘no’, as in:

#+BEGIN_SRC elisp :noweb-prefix no  (setq example-data "<<example>>")#+END_SRC

which expands to:

(setq example-data "this is themulti-line body of example")

When in doubt about the outcome of a source code block expansion, youcan preview the results with the following command:

C-c C-v v orC-c C-v C-v (org-babel-expand-src-block) ¶: Expand the current source code block according to its headerarguments and pop open the results in a preview buffer.

Movatterモバイル変換

16.11 Noweb Reference Syntax ¶

Footnotes

(154)

(155)

(156)