Next: , Previous: , Up: Working with Source Code   [Contents][Index]


14.10 Noweb Reference Syntax

Org supports named blocks in Noweb146 style syntax:

<<CODE-BLOCK-ID>>

Org can replace the construct with the source code, or the results of evaluation, of the code block identified as CODE-BLOCK-ID.

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

no

Default. No expansion of Noweb syntax references in the body of the code when evaluating, tangling, or exporting.

yes

Expansion of Noweb syntax references in the body of the code block when evaluating, tangling, or exporting.

tangle

Expansion of Noweb syntax references in the body of the code block when tangling. No expansion when evaluating or exporting.

no-export

Expansion of Noweb syntax references in the body of the code block when evaluating or tangling. No expansion when exporting.

strip-export

Expansion of Noweb syntax references in the body of the code block when expanding prior to evaluating or tangling. Removes Noweb syntax references when exporting.

eval

Expansion of Noweb syntax references in the body of the code block only before evaluating.

In the 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

Noweb insertions honor prefix characters that appear before the Noweb syntax reference. This behavior is illustrated in the following example. Because the ‘<<example>>’ Noweb reference appears behind the SQL comment syntax, each line of the expanded Noweb reference is commented. 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 without newlines in them, inline Noweb references are acceptable.

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

#+NAME: if-true
#+BEGIN_SRC python :exports none
  print('do things when true')
#+end_src

#+name: if-false
#+begin_src python :exports none
  print('do things when false')
#+end_src

this code block:

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

expands to:

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

When expanding Noweb style references, Org concatenates code blocks by matching the reference name to either the code block name or, if none is found, to the ‘noweb-ref’ header argument.

For simple concatenation, set this ‘noweb-ref’ header argument at the sub-tree or file level. In the example Org file shown next, the body of the source code in each block is extracted for concatenation to a pure code 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. To change this newline separator, edit the ‘noweb-sep’ header argument.

Eventually, Org can include the results of a code block rather than its body. To that effect, append parentheses, possibly including arguments, to the code block name, as shown below.

<<code-block-name(optional arguments)>>

Note that when using the above approach to a code block’s results, the code block name set by ‘NAME’ keyword is required; the reference set by ‘noweb-ref’ does not work in that case.

Here is an example that demonstrates how the exported content changes when Noweb style references are used with parentheses versus without. With:

#+NAME: some-code
#+BEGIN_SRC python :var num=0 :results output :exports none
  print(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 now the expansion contains the results of the code block ‘some-code’, not the code block itself:

100

Footnotes

(146)

For Noweb literate programming details, see http://www.cs.tufts.edu/~nr/noweb/.


Next: , Previous: , Up: Working with Source Code   [Contents][Index]