16.8 Extracting Source Code

Extracting source code from code blocks is a basic task in literate programming. Org has features to make this easy. In literate programming parlance, documents on creation are woven with code and documentation, and on export, the code is tangled for execution by a computer. Org facilitates weaving and tangling for producing, maintaining, sharing, and exporting literate programming documents. Org provides extensive customization options for extracting source code.

When Org tangles code blocks, it expands, merges, and transforms them. Then Org recomposes them into one or more separate files, as configured through the options. During this tangling process, Org expands variables in the source code, and resolves any noweb style references (see Noweb Reference Syntax).

Header arguments

The ‘tangle’ header argument specifies if the code block is exported to source file(s).

yes

Export the code block to source file. The file name for the source file is derived from the name of the Org file, and the file extension is derived from the source code language identifier. Example: ‘:tangle yes’.

no

The default. Do not extract the code in a source code file. Example: ‘:tangle no’.

FILENAME

Export the code block to source file whose file name is derived from any string passed to the ‘tangle’ header argument. Org derives the file name as being relative to the directory of the Org file’s location. Example: ‘:tangle FILENAME’.

The ‘mkdirp’ header argument creates parent directories for tangled files if the directory does not exist. A ‘yes’ value enables directory creation whereas ‘no’ inhibits it.

The ‘comments’ header argument controls inserting comments into tangled files. These are above and beyond whatever comments may already exist in the code block.

no

The default. Do not insert any extra comments during tangling.

link

Wrap the code block in comments. Include links pointing back to the place in the Org file from where the code was tangled.

yes

Kept for backward compatibility; same as ‘link’.

org

Nearest headline text from Org file is inserted as comment. The exact text that is inserted is picked from the leading context of the source block.

both

Includes both ‘link’ and ‘org’ options.

noweb

Includes ‘link’ option, expands noweb references (see Noweb Reference Syntax), and wraps them in link comments inside the body of the code block.

The ‘padline’ header argument controls insertion of newlines to pad source code in the tangled file.

yes

Default. Insert a newline before and after each code block in the tangled file.

no

Do not insert newlines to pad the tangled code blocks.

The ‘shebang’ header argument can turn results into executable script files. By setting it to a string value—for example, ‘:shebang "#!/bin/bash"’—Org inserts that string as the first line of the tangled file that the code block is extracted to. Org then turns on the tangled file’s executable permission.

The ‘tangle-mode’ header argument specifies what permissions to set for tangled files by set-file-modes. Permissions are given by an octal value, which can be provided calling the identity function on an elisp octal value. For instance, to create a read-only file one may use ‘:tangle-mode (identity #o444)’. To reduce the verbosity required, a octal shorthand is defined, ‘oXXX’ (‘o’ for octal). Using this, our read-only example is ‘:tangle-mode o444’. Omitting the ‘o’ prefix will cause the argument to be interpreted as an integer, which can lead to unexpected results (‘444’ is the same as ‘o674’). Two other shorthands are recognized, ls-style strings like ‘rw-r--r--’, and chmod-style permissions like ‘g+w’. Note that chmod-style permissions are based on org-babel-tangle-default-file-mode, which is ‘#o544’ by default.

When ‘:tangle-mode’ and ‘:shebang’ are both specified, the give ‘:tangle-mode’ will override the permissions from ‘:shebang’. When multiple source code blocks tangle to a single file with conflicting ‘:tangle-mode’ header arguments, Org’s behavior is undefined.

By default Org expands code blocks during tangling. The ‘no-expand’ header argument turns off such expansions. Note that one side-effect of expansion by org-babel-expand-src-block also assigns values (see Environment of a Code Block) to variables. Expansions also replace noweb references with their targets (see Noweb Reference Syntax). Some of these expansions may cause premature assignment, hence this option. This option makes a difference only for tangling. It has no effect when exporting since code blocks for execution have to be expanded anyway.

Functions

org-babel-tangle

Tangle the current file. Bound to C-c C-v t.

With prefix argument only tangle the current code block.

org-babel-tangle-file

Choose a file to tangle. Bound to C-c C-v f.

Tangle hooks

org-babel-pre-tangle-hook

This hook is run before the tangle process begins. The active buffer is buffer to be tangled.

org-babel-tangle-body-hook

This hook is run from a temporary buffer containing expanded code of every tangled code block. The hook can modify the expanded code as needed. The contents of the current buffer will be used as actual code block expansion.

org-babel-post-tangle-hook

This hook is run from within code files tangled by org-babel-tangle, making it suitable for post-processing, compilation, and evaluation of code in the tangled files.

org-babel-tangle-finished-hook

This hook is run after post-tangle hooks, in the original buffer.

Jumping between code and Org

Debuggers normally link errors and messages back to the source code. But for tangled files, we want to link back to the Org file, not to the tangled source file. To make this extra jump, Org uses org-babel-tangle-jump-to-org function with two additional source code block header arguments:

  1. Set ‘padline’ to true—this is the default setting.
  2. Set ‘comments’ to ‘link’, which makes Org insert links to the Org file.