Emacs. Org Babel

Обновлено 2024-11-16 4 мин. для прочтения Computer-Science

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

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

Links to this note

Emacs Org-Mode
Дмитрий Сергеевич Кулябов
Дмитрий Сергеевич Кулябов
Профессор кафедры теории вероятностей и кибербезопасности

Мои научные интересы включают физику, администрирование Unix и сетей.

Похожие