Structure of Code Blocks (The Org Manual)

Next: Using Header Arguments, Previous: Features Overview, Up: Working with Source Code [Contents][Index]

16.2 Structure of Code Blocks ¶

Org offers two ways to structure source code in Org documents: in a source code block, and directly inline. Both specifications are shown below.

A source code block conforms to this structure:

#+NAME: <name>
#+BEGIN_SRC <language> <switches> <header arguments>
  <body>
#+END_SRC

Do not be put-off by having to remember the source block syntax. Org mode offers a command for wrapping existing text in a block (see Structure Templates). Org also works with other completion systems in Emacs, some of which predate Org and have custom domain-specific languages for defining templates. Regular use of templates reduces errors, increases accuracy, and maintains consistency.

An inline code block conforms to this structure:

src_<language>{<body>}

src_<language>[<header arguments>]{<body>}

‘#+NAME: <name>’

Optional. Names the source block so it can be called, like a function, from other source blocks or inline code to evaluate or to capture the results. Code from other blocks, other files, and from table formulas (see The Spreadsheet) can use the name to reference a source block. This naming serves the same purpose as naming Org tables. Org mode requires unique names. For duplicate names, Org mode’s behavior is undefined. Inline code blocks cannot have a name.

‘#+BEGIN_SRC’ … ‘#+END_SRC’

Mandatory. They mark the start and end of a block that Org requires. The ‘#+BEGIN_SRC’ line takes additional arguments, as described next.

‘<language>’ ¶

Optional. It is the identifier of the source code language in the block. See Languages, for identifiers of supported languages.

When ‘<language>’ identifier is omitted, the block also cannot have ‘<switches>’ and ‘<header arguments>’.

Language identifier is also used to fontify code blocks in Org buffers, when org-src-fontify-natively is set to non-nil. See Editing Source Code.

‘<switches>’ ¶

Optional. Switches provide finer control of the code execution, export, and format (see the discussion of switches in Literal Examples).

‘<header arguments>’ ¶

Optional. Heading arguments control many aspects of evaluation, export and tangling of code blocks (see Using Header Arguments). Using Org’s properties feature, header arguments can be selectively applied to the entire buffer or specific subtrees of the Org document.

‘<body>’

Source code in the dialect of the specified language identifier.