~minshall/org-cli-tangle

tangle Emacs org-mode source blocks from the command line

9ce2cc3 new version 0.1.8

9 months ago

6f81fda test1.t non-varable.org: delete trailing spaces

9 months ago

#org-cli-tangle: command line tool to tangle org-mode source blocks

#Summary

org-cli-tangle is a command line utility to tangle source code blocks from Emacs Org Mode files.

#Usage

usage: org-cli-tangle -- --help
usage: org-cli-tangle -- --version
usage: org-cli-tangle -- FILE [...]
usage: org-cli-tangle -- OPTIONS FILE [...]

The first form prints out a help message, while the second the current version of org-cli-tangle. Both exit after printing their messages.

The third form is probably what will be of most use and (hopefully!) work in most cases.

The fourth form gives more options for which languages to enable in org-babel-load-languages, and which languages' source blocks to tangle.

For details information, please see the man page.

#Background and explanation

Emacs Org Mode files can contain blocks of source code, and, in addition to evaluating that code from within the Org Mode file (within an Emacs session), one can extract those blocks of source code into separate files, in a process known as tangling.

Often people would like to do this tangling process from the command line or from a makefile.

This is typically a fairly easy process. For example, the Org Mode info pages, in the section Batch Execution, gives an example shell script

#!/bin/sh
# Tangle files with Org mode
#
emacs -Q --batch --eval "
    (progn
      (require 'ob-tangle)
      (dolist (file command-line-args-left)
        (with-current-buffer (find-file-noselect file)
          (org-babel-tangle))))
  " "$@"

This short script works well in certain situations. However, if the file being tangled contains a source block passing a variable assignment (with a :var argument on the header line), then, in either of at least these two cases:

  • the source block is for langauges other than emacs-lisp (elisp)
  • the argument on the header line requires running some *other* source block which is *not* emacs-lisp (could be shell, for example, or any other language)

the resulting "tangled" file will not include a binding for that argument.

There are two main settings that control how org-babel-tangle-file processes a .org file:

  • the variable org-babel-load-languages. This defines the languages which Org Mode will evaluate (in source code blocks) while processing the file (assuming they need to be evaluated while tangling the file). Any source code blocks in other languages will not be processed.

    In current releases of Org Mode (at least version 9.6), org-babel-load-languages also restricts which source blocks can have an argument from the header line (:var) bound in the resulting tangled file.

  • The LANG-RE parameter passed when invoking org-babel-tangle-file. If this parameter, a regular expression, is not nil, then only source code blocks with a language matching this regular expression will be tangled.

By default (in the third form listed above under Usage), org-cli-tangle processes each input file and sets org-babel-load-languages to list *all* the languages found in source code blocks in that file, and then calls org-babel-tangle-file to tangle the file (leaving, again, by default, LANG-RE set to nil).

#Dependencies

To run, one needs

To build, one needs

To test, one needs

In addition, to do development, one needs

#Installation

There is a AUR org-cli-tangle package for Arch Linux.

Alternatively, download (or git clone) the source code and run

make install

#Other tools

I notice there are other tools available to help with this. I have not used them, but you may find them useful:

ntangle says that it runs faster than tangling with Emacs, and does not need Emacs (or Org Mode).

OrgTangle lists ntangle and several other utilities. The entries are several years old, so grepping the web you will likely find other solutions.

#Source code, bugs, suggestions

The project home page is https://sr.ht/~minshall/org-cli-tangle/.

Please see https://todo.sr.ht/~minshall/org-cli-tangle to file bug reports or make suggestions.