14.10 Noweb reference syntax

Org supports named blocks in Noweb style syntax. For Noweb literate programming details, see http://www.cs.tufts.edu/~nr/noweb/).

     <<code-block-name>>

For the header argument :noweb yes, Org expands Noweb style references in the ‘src’ code block before evaluation.

For the header argument :noweb no, Org does not expand Noweb style references in the ‘src’ code block before evaluation.

The default is :noweb no. Org defaults to :noweb no so as not to cause errors in languages where Noweb syntax is ambiguous. Change Org's default to :noweb yes for languages where there is no risk of confusion.

Org offers a more flexible way to resolve Noweb style references (see noweb-ref).

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 show 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 will not work.

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

For faster tangling of large Org mode files, set org-babel-use-quick-and-dirty-noweb-expansion variable to t. The speedup comes at the expense of not correctly resolving inherited values of the :noweb-ref header argument.