Emacs. Org Babel

2022-10-15 · 4 мин. для прочтения

Org Babel.

Содержание

1 Общая информация

Org Babel используется для работы с исходным кодом разных языков программирования внутри org-mode.
Исходный код задаётся в блоке #+BEGIN_SRC...#+END_SRC.
Для редактирования и форматирования блока исходного кода используется соответствующий основной режим Emacs, включающий функции, специально разработанные для исходного кода на этом языке.
Для выполнения компиляции блока исходного кода можно использовать соответствующий компилятор.
Важной особенностью управления блоками исходного кода в org-mode является возможность передавать переменные, функции и результаты друг другу, используя общий синтаксис для блоков исходного кода на любом языке.
Документация: https://org-babel.readthedocs.io/

2 Дополнительные пакеты

2.1 org-auto-tangle

Репозиторий: https://github.com/yilkalargaw/org-auto-tangle/
Автоматически выполнять tangle при сохранении файлов.

2.1.1 Настройка

Необходимо добавить хук к org-mode:

1(require 'org-auto-tangle)
2(add-hook 'org-mode-hook 'org-auto-tangle-mode)

Можно включить автосохранение для всех файлов:
```
1(setq org-auto-tangle-default t)
```

2.1.2 Опция в файле .org

В целевой файл следует добавить опцию для включения автосохранения:
```
1#+auto_tangle: t
```
Эта опция также может использоваться для указания переменных, которые должны быть сохраняется в асинхронном процессе запутывания:
```
1#+auto_tangle: vars:load-path
```

3 Структура блока кода

Исходный код может быть в блоке исходного кода и непосредственно в строке.

Блок исходного кода:

1#+NAME: <name>
2#+BEGIN_SRC <language> <switches> <header arguments>
3  <body>
4#+END_SRC

Блок встроенного кода:

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

Основные элементы:
- #+NAME: <name> : опциональное название блока исходного кода.
- #+BEGIN_SRC … #+END_SRC : обязательные ограничители блока.
- <language> : обязательный идентификатор языка исходного кода в блоке.
- <switches> : опциональная настройка кодового блока.
- <header arguments> : опциональные аргументы заголовка. Управляют многими аспектами выполнения и экспорта блоков кода.
- <body> : исходный код.

4 Исполнение кода блоков

4.1 Исполнение исходного кода

Org захватывает результаты выполнения блока кода и вставляет их в файл Org сразу после блока кода.
Точка вставки находится после новой строки и ключевого слова RESULTS (оно создаётся, если его не было).
По умолчанию Org разрешает выполнение только блоков кода Emacs Lisp.
Выполнение блоков кода: C-c C-c или C-c C-v e на кодовом блоке вызывает функцию org-babel-execute-src-block, которая выполняет код в блоке, собирает результаты и вставляет их в буфер.
Содержимое блока кода может быть исполнено из другого места файла.

Вызов можно выполнить с помощью ключевого слова:

1#+CALL: <name>(<arguments>)
2#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>

Можно использовать встроенные вызовы:
```
1... call_<name>(<arguments>) ...
2... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
```
- В этом случае результат представляется на основе переменной org-babel-inline-result-wrap, для которой по умолчанию задано значение =%s= для получения дословного текста.
Параметры вызова:
- <name> : имя блока кода. Если блок находится в другом файле, имя предваряется именем файла, за которым следует двоеточие.
- <arguments> : аргументы, передаваемые в блок кода.
- <inside header arguments> : внутренние аргументы заголовка в именованном блоке кода.
- <end header arguments> : влияют на результаты, возвращаемые блоком кода.

4.2 Ограничение на исполнение кода

Аргумент заголовка eval может ограничивать выполнение определённых блоков кода (в основном для обеспечения безопасности):
- never или no : никогда не исполнять код;
- query : запрашивает у пользователя разрешение на исполнение исходного кода;
- never-export или no-export : не исполнять исходный код при экспорте;
- query-export : запрашивает у пользователя разрешение на исполнение исходного кода во время экспорта.
Запрос на выполнение управляется переменной org-confirm-babel-evaluate.
Чтобы отключить запрос на выполнение, следует установить:
```
1(setq org-confirm-babel-evaluate nil)
```

5 Экспорт блоков кода

Можно экспортировать код из блоков babel, результаты выполнения блока кода.
Аргумент заголовка :exports должен указывать, экспортируется ли эта часть файла:
- code (:exports code) : Обычно является значением по умолчанию. Код включается в экспортируемый файл.
- results (:exports results) : Результаты выполнения кода включаются в экспортируемый файл.
- both (:exports both) : И код, и результаты выполнения включаются в экспортируемый файл.
- none (:exports none) : Ни код, ни результаты выполнения не включаются в экспортируемый файл.
Чтобы не выполнять блоки кода для ускорения экспорта, используется аргумент заголовка :eval never-export.
Для отключения исполнения кода глобально следует установить переменную org-export-use-babel в значение nil.

6 Экспорт рисунков `svg`

При экспорте результатов вычисления, являющимися фигурами в формате svg, можно внедрить код в текст.
Для этого нужно добавить к результату атрибут:
```
1#+attr_html: :inlined t
```

7 Задание конфигурации в свойствах

7.1 Аргументы заголовка уровня буфера

Строка #+PROPERTY:, расположенная в любом месте буфера, влияет на весь файл. Она устанавливает глобальное свойство.
Для babel свойства задаются для header-args.
Сгенерить все блоки исходного кода в файле:
```
1#+PROPERTY: header-args :tangle yes
```
Можно указать несколько аргументов:
```
1#+PROPERTY: header-args :results output :cache yes
```
Можно объединять свойства (накопленные значения):
```
1#+PROPERTY: header-args:R :exports results
2#+PROPERTY: header-args:R+ :width 800
```

7.2 Аргументы заголовка поддерева

Блок :PROPERTIES: действителен только для данного дерева (и поддеревьев):
```
1* Outline heading
2 :PROPERTIES:
3 :header-args: :results output :cache yes
4 :END:
```

7.3 Аргументы заголовка блока кода

Можно параметры указывать непосредственно в блоке кода:
```
1#+header: :exports code :var data=2
2#+begin_src emacs-lisp
3... some code ...
4#+end_src
```

Обновлено 2024-11-16

Emacs. Org Babel

1 Общая информация

2 Дополнительные пакеты

2.1 org-auto-tangle

2.1.1 Настройка

2.1.2 Опция в файле .org

3 Структура блока кода

4 Исполнение кода блоков

4.1 Исполнение исходного кода

4.2 Ограничение на исполнение кода

5 Экспорт блоков кода

6 Экспорт рисунков svg

7 Задание конфигурации в свойствах

7.1 Аргументы заголовка уровня буфера

7.2 Аргументы заголовка поддерева

7.3 Аргументы заголовка блока кода

Похожие

6 Экспорт рисунков `svg`