org-mode Working-with-Source-Code部分翻译

https://orgmode.org/manual/Working-with-Source-Code.html#Working-with-Source-Code

文章目录

用源码方式工作

用源码方式工作

这里的源代码是指使用人类可读的编程语言编写的计算机指令的纯文本集合，可能带有注释。当使用begin和end标记标识源代码时，Org可以管理Org文档中的源代码。使用源代码始于识别源代码块。源代码块可以放在Org文档中的几乎任何位置；它不限于文档的序言或结尾。但是，如果组织将源代码块放在Org注释内或固定宽度部分内，则无法对其进行管理。

这是用lisp写的一个源码块

#+BEGIN_SRC emacs-lisp
  (defun org-xor (a b)
     "Exclusive or."
     (if a (not b) b))
#+END_SRC

源码块是诸多org块类型之一
块还包括 “center”, “comment”, “dynamic”, “example”, “export”, “quote”, “special”, and “verse”.这取决于 ‘#+BEGIN_SRC’ 和 ‘#+END_SRC’中间的内容
以下各节介绍了Org用于处理源代码的工具的详细信息。

功能

15.1特点

Org可以用多种方式管理由“#+BEGIN_SRC”…“#+END_SRC”分隔的块中的源代码，这些方法可以简化现代源代码维护所必需的内务处理任务。Org可以编辑、格式化、提取、导出和发布源代码块。Org还可以编译和执行源代码块，然后捕获结果。组织模式文献有时将源代码块称为实时代码块，因为它们可以更改组织文档的内容或它导出的材料。用户可以通过调整用于编译、执行、提取和导出的头参数（请参见使用头参数）来控制每个源代码块的生存期。

为了编辑和格式化一个源代码块，Org使用了一个适当的Emacs主模式，其中包括专门为该语言的源代码设计的特性。

Org可以提取一个或多个源代码块，并将它们写入一个或多个源文件中，这一过程在文学编程术语中被称为tangling。

对于导出和发布，Org的后端可以适当地格式化源代码块，通常使用本机语法高亮显示。

对于执行和编译源代码块，用户可以配置Org以选择适当的编译器。Org提供工具来收集执行或编译器输出的结果，将其插入到Org文档中，和/或导出它。除此之外，还可以将链接链接到音频、视频和其他类型的图片中。Org还可以将编译器错误消息链接到源代码块中的相应行。

Org管理源代码块的一个重要特性是能够使用任何语言的源代码块的通用语法将变量、函数和结果传递给另一个。尽管大多数文学编程工具都局限于一种或另一种语言，但Org的语言无关性方法允许有文化的程序员将每个编程任务与适当的计算机语言相匹配，并将它们混合在一个单独的Org文档中。这种语言间的互操作性解释了为什么Org的源代码管理工具被其创建者ericschulte和dandavison命名为org babel。

Org模式通过将文本、数据、代码、执行环境的配置设置、执行结果以及相关的叙述、声明、参考以及内部和外部链接保存在一个单独的组织文档中，从而实现了发布可复制研究的容易验证和维护的承诺。

代码块的结构

Org提供了两种在Org文档中构造源代码的方法：在源代码块中，和直接内联。两种规格如下所示。

源代码块

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

不必硬记。
Org模式提供了一个将现有文本包装在块中的命令（请参见结构模板）。Org还与Emacs中的其他完成系统一起工作，其中一些系统早于Org，并且具有自定义的领域特定语言来定义模板。定期使用模板可以减少错误，提高准确性，并保持一致性。

内联代码块

src\<language>{<body>}

或

src\<language>[<header arguments>]{<body>}

‘#+NAME: ’

可选。命名源块，以便可以像函数一样从其他源块或内联代码中调用它来计算或捕获结果。来自其他块、其他文件和表公式（请参见电子表格）的代码可以使用该名称来引用源块。命名表与命名组织的目的相同。组织模式需要唯一的名称。对于重复的名称，组织模式的行为是未定义的。

‘#+BEGIN_SRC’ … ‘#+END_SRC’

强制性的。它们标记了Org所需块的开始和结束。“#+BEGIN_SRC”行接受其他参数，如下所述。

‘’

强制性的。它是块中源代码语言的标识符。有关受支持语言的标识符，请参阅语言。

‘’

可选。开关提供对代码执行、导出和格式的更精细的控制（请参阅文字示例中有关开关的讨论）。

‘

’

可选。标题参数控制代码块的计算、导出和纠缠的许多方面（请参见使用头参数）。使用Org的properties特性，可以有选择地将头参数应用于整个缓冲区或Org文档的特定子树。

‘’

指定语言标识符的方言的源代码。

使用头参数

Org有许多通用于所有语言的头参数。当特定语言可以在源代码块中使用时，会为它们添加新的头参数。头参数是用初始冒号指定的，后跟参数的小写名称。

由于头参数可以通过多种方式设置，所以在发生重叠或冲突的情况下，Org通过赋予本地设置更高的优先级来优先处理它们。例如，函数调用中的头值重写全局默认值中的头值。

系统范围头参

可以通过自定义org-babel-default-header-args变量来指定头参数的系统范围值，该变量默认为以下值：

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

下面的示例将“：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:，其中是语言的名称，每种语言都可以有单独的默认头参数。有关详细信息，请参阅特定语言的联机文档，网址为https://orgmode.org/worg/org-contrib/babel/。

The following example makes all the R code blocks execute in the same session. Setting ‘:results’ to ‘silent’ ignores the results of executions for all blocks, not just R code blocks; no results inserted for any block.
下面这个例子让所有的R语言块在同一session中执行，设置‘:results’ 为‘silent’ 在所有块中忽略执行结果，不仅仅是R语言块。所有块都没有result插入。

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

通过org的属性抽屉设置的头参应用于向下的子树，由于这些属性抽屉可以出现在文件层次结构中的任何位置，Org使用最外层的调用或源块来解析这些值。组织忽略org-use-property-inheritance 设置。

在本例中，对于子树中的所有代码块，‘:cache’ 默认为“yes”。

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

通过org-set-property函数定义的属性绑定到C-c C-x p，适用于所有活动语言。它们覆盖org-babel-default-header-args设置的属性。

语言特定的头参数也从属性的头参数：中读取，其中是语言标识符。例如，

* 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”继承设置。

特定于代码块的头参数

头参数通常在源代码块级别设置，在“#+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目前只接受复数形式的“#+HEADER:”拼写，这只是为了便于向后兼容。它可能会在某个时候被移除。
未命名代码块上的多行头参：

#+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

函数调用中的头参数

函数调用中的头参数是最具体的，并且在重叠的情况下覆盖所有其他设置。他们得到了最高的优先权。下面显示了两个“#+CALL:”示例。有关’CALL’关键字的完整语法，请参阅评估代码块。

在本例中，‘:exports results’ 头参数应用于‘#+CALL:’ 行的计算。

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

在本例中，‘:session special’ 头参数应用于“factorial”代码块的计算。

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

Environment of a Code Block 一个代码块的环境

https://orgmode.org/manual/Environment-of-a-Code-Block.html#Environment-of-a-Code-Block

Structure Templates 结构模版

只需按几下键，就可以插入空的结构块，例如“#+BEGIN_SRC”…“#+END_SRC”，或者将现有文本包装在这样的块中。

C-c C-, (org-insert-structure-template)

提示输入块结构类型，然后在点插入块。如果区域处于活动状态，则它将被包装在块中。首先提示用户输入键，这些键用于从下面的变量中查找结构类型。如果键是TAB、RET或SPC，则会提示用户输入块类型。

可用的结构类型在org-structure-template-alist中定义，增加或更改值见docstring。

Org Tempo将代码段扩展到org-structure-template-alist and org-tempo-keywords-alist中定义的结构。例如，<s TAB创建代码块。通过定制org-modules或在Emacs init文件中添加‘(require 'org-tempo)’
a ‘#+BEGIN_EXPORT ascii’ … ‘#+END_EXPORT’
c ‘#+BEGIN_CENTER’ … ‘#+END_CENTER’
C ‘#+BEGIN_COMMENT’ … ‘#+END_COMMENT’
e ‘#+BEGIN_EXAMPLE’ … ‘#+END_EXAMPLE’
E ‘#+BEGIN_EXPORT’ … ‘#+END_EXPORT’
h ‘#+BEGIN_EXPORT html’ … ‘#+END_EXPORT’
l ‘#+BEGIN_EXPORT latex’ … ‘#+END_EXPORT’
q ‘#+BEGIN_QUOTE’ … ‘#+END_QUOTE’
s ‘#+BEGIN_SRC’ … ‘#+END_SRC’
v ‘#+BEGIN_VERSE’ … ‘#+END_VERSE’