Using Header Arguments (翻译: Org 手册)

Org 内置了适用于所有语言的通用头部参数。随着各语言在源代码块中逐步支持，也会为特定语言新增专属头部参数。头部参数以英文冒号开头，后接小写的参数名进行指定。

由于头部参数可通过多种方式设置，当出现重复或冲突时，Org 遵循 局部设置优先级更高 的原则。例如函数调用中的头部参数值，会覆盖全局默认的参数值。

System-wide header arguments ¶

可通过自定义变量 org-babel-default-header-args 指定全局生效的头部参数值，其默认配置如下：

:session    => "none"
:results    => "replace"
:exports    => "code"
:cache      => "no"
:noweb      => "no"
:hlines     => "no"
:tangle     => "no"

行内源代码块（见 Structure of Code Blocks）使用略有差异的默认头部参数，定义在 org-babel-default-inline-header-args 中：

:session    => "none"
:results    => "replace"
:exports    => "results"
:hlines     => "yes"

行内代码块与普通代码块的默认头部参数中，最明显的区别在于 ‘:exports’ 参数。行内代码块默认只导出执行结果，而非代码本身。

与默认值不同，通过 Org mode 属性设置的头部参数（见 Header arguments in Org mode properties）对普通代码块和行内代码块均生效。

下面的示例将 ‘:noweb’ 头部参数默认设为 ‘yes’ ，使 Org 默认展开 ‘:noweb’ 引用。

(setq org-babel-default-header-args
      (cons '(:noweb . "yes")
            (assq-delete-all :noweb org-babel-default-header-args)))

每种语言均可通过自定义变量 org-babel-default-header-args:<LANG> 设置专属默认头部参数，其中 <LANG> 为对应语言名称。详细说明可参考各语言在线文档：https://orgmode.org/worg/org-contrib/babel/。

Header arguments in Org mode properties ¶

如需对整个缓冲区生效头部参数，可在 Org 文件任意位置使用 ‘PROPERTY’ 关键字（见 Property Syntax）。

下面的示例让所有 R 代码块在同一会话中执行。将 ‘:results’ 设为 ‘silent’ 会忽略所有代码块的执行结果（不只是 R 块），所有代码块均不插入结果。

#+PROPERTY: header-args:R  :session *R*
#+PROPERTY: header-args    :results silent

通过 Org 属性抽屉设置的头部参数（见 Property Syntax）在所在子树及下级节点生效。由于属性抽屉可出现在文件层级结构的任意位置，Org 以最外层调用或源代码块为准解析参数值，且不受 org-use-property-inheritance 设置影响。

本示例中，子树下所有代码块的 ‘:cache’ 默认值为 ‘yes’ 。

* sample header
  :PROPERTIES:
  :header-args:    :cache yes
  :END:

通过绑定到 C-c C-x p 的 org-set-property 函数定义的属性对所有激活语言生效，优先级高于 org-babel-default-header-args 中的设置。

语言专属的头部参数也可从属性 ‘header-args:<LANG>’ 中读取，其中 <LANG> 为语言标识符，示例如下：

* Heading
  :PROPERTIES:
  :header-args:clojure:    :session *clojure-1*
  :header-args:R:          :session *R*
  :END:
** Subheading
  :PROPERTIES:
  :header-args:clojure:    :session *clojure-2*
  :END:

上述配置会让 ‘Heading’ 和 ‘Subheading’ 下的 Clojure 块使用不同会话，而所有 R 块使用同一会话。 ‘Subheading’ 中的块会继承 ‘Heading’ 的设置。

Code block specific header arguments ¶

最常用的方式是在源代码块的 ‘#+BEGIN_SRC’ 行直接设置头部参数。该层级的参数优先级高于 org-babel-default-header-args 变量与属性中设置的参数。

下面的示例中， ‘:results’ 设为 ‘silent’ 会忽略代码执行结果； ‘:exports’ 设为 ‘code’ 表示仅将代码块主体导出为 HTML 或 LaTeX。

#+NAME: factorial
#+BEGIN_SRC haskell :results silent :exports code :var n=0
  fac 0 = 1
  fac n = n * fac (n-1)
#+END_SRC

src_haskell[:exports both]{fac 5}

代码块头部参数可分行书写，每行以 ‘#+HEADER:’ 开头。注意 Org 目前仅为兼容旧版支持复数形式的 ‘#+HEADERS:’ ，未来可能移除该写法。

#+HEADER: :var data1=1
#+BEGIN_SRC emacs-lisp :var data2=2
   (message "data1:%S, data2:%S" data1 data2)
#+END_SRC

#+RESULTS:
: data1:1, data2:2

#+NAME: named-block
#+HEADER: :var data=2
#+BEGIN_SRC emacs-lisp
  (message "data:%S" data)
#+END_SRC

#+RESULTS: named-block
  : data:2

Header arguments in function calls ¶

函数调用中的头部参数优先级最高，出现冲突时会覆盖所有其他设置。下面展示两个 ‘#+CALL:’ 示例。 ‘CALL’ 关键字的完整语法见 Evaluating Code Blocks。

本示例中， ‘:exports results’ 头部参数作用于 ‘#+CALL:’ 行的执行过程：

#+CALL: factorial(n=5) :exports results

本示例中， ‘:session special’ 头部参数作用于 ‘factorial’ 代码块的执行：

#+CALL: factorial[:session special](n=5)

16.3 Using Header Arguments ¶

System-wide header arguments ¶

Header arguments in Org mode properties ¶

Code block specific header arguments ¶

Header arguments in function calls ¶