Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/OrgTangle/ntangle

Command-line utility for Tangling of Org documents — programmed in Nim.
https://github.com/OrgTangle/ntangle

literate-programming nim org-mode tangle

Last synced: 2 months ago
JSON representation

Command-line utility for Tangling of Org documents — programmed in Nim.

Awesome Lists containing this project

README 

        
#+title: NTangle



/Command-line utility for Tangling of Org documents — programmed in

Nim./



[[https://github.com/OrgTangle/ntangle/actions/workflows/test.yml][https://github.com/OrgTangle/ntangle/actions/workflows/test.yml/badge.svg]]



* What is Tangling

From [[https://orgmode.org/manual/Extracting-source-code.html][Org Manual -- Extracting source code]]:



#+begin_quote

Extracting source code from code blocks is a basic task in /literate

programming/. Org has features to make this easy. In literate

programming parlance, documents on creation are /woven/ with code and

documentation, and on export, the code is *tangled* for execution by a

computer.



Org facilitates weaving and tangling for producing, maintaining,

sharing, and exporting literate programming documents. Org provides

extensive customization options for extracting source code.



When Org tangles ~src~ code blocks, it expands, merges, and transforms

them. Then Org recomposes them into one or more separate files, as

configured through the options. During this /tangling/ process, Org

expands variables in the source code, and resolves any Noweb style

references (see [[https://orgmode.org/manual/Noweb-reference-syntax.html][Noweb reference syntax]]).

#+end_quote



/You can visit the same Org manual section from within Emacs by going

to this Info manual node: ~(org) Extracting Source Code~./

* Why ~ntangle~?

While the tangling of Org documents works great from within Emacs, it

can be quite a bit slow for large Org documents. This project aims to

provide /almost/ the same tangling functionality at a much higher

speed.



You do *not* need Emacs or Org mode installed to use ~ntangle~.

* Installation



[[https://github.com/nim-lang/nimble][~nimble~]] can be used to install ~ntangle~. This utility ships with Nim

installations. Think of it as the equivalent of the Python ~pip~.



/See [[https://github.com/dom96/choosenim#installation][*choosenim* installation]] to install *nim* and *nimble*./



To install ~ntangle~:

#+begin_example

nimble install ntangle

#+end_example



Above installs the binary in the *~/.nimble/bin/* directory.

* Features

** Tangling /minus Noweb/ [7/8]

- [X] Understands global tangle header-args in ~#+property~ keywords

- [X] Understands tangle header-args directly above Org source blocks

- [-] Understands tangle subtree property drawer header-args

  - [X] Rudimentary parsing of the property drawer

    header-args. ~ntangle~ does not check the validity of the property

    drawer (i.e. ~:PROPERTIES:~ appears immediately after the heading,

    and it ends with ~:END:~, and that the properties are only between

    them, etc.). Also ~header-args~ is treated the same as

    ~header-args+~ for simplicity for now.

  - [ ] Treat ~header-args~ vs ~header-args+~ values correctly.

- [X] Understands the precendence order of the tangle header-args when

  a mix of global and source block header-args are used

- [X] Language-specific header-args (e.g. ~#+property: header-args:nim

  :tangle yes~)

- [X] Concatenating multiple source blocks to the same tangled file

- [X] Respects comma-escaping in source blocks

- [X] Removes common indentation, but also retains the indentation

  where needed

*** Supported ~header-args~ switches [5/7]

- [X] ~:tangle~

- [X] ~:padline~

- [X] ~:shebang~

- [X] ~:mkdirp~

- [X] ~:tangle-mode~

- [ ] ~:comments~

- [ ] ~:no-expand~

** Noweb [0/1]

- [ ] Noweb support. I sorely miss the lack of ~noweb~ support.. I use

  it heavily in [[https://github.com/kaushalmodi/eless][~eless~]].



/There is *no* plan to support Org Babel functions with Noweb, like

evaluating code blocks during tangling, etc. (just use Emacs for those

:D)./

*** Supported ~header-args~ switches for Noweb [0/3]

- [ ] ~:noweb~

- [ ] ~:noweb-ref~

- [ ] ~:noweb-sep~

* Screenshot

[[https://raw.githubusercontent.com/OrgTangle/ntangle/master/doc/img/Screenshot_ntangle_v0.4.2.png][https://raw.githubusercontent.com/OrgTangle/ntangle/master/doc/img/Screenshot_ntangle_v0.4.2.png]]

* Usage

Add one or more Org files (files with names ending in ".org") or

directory names after the ~ntangle~ command. If directory names are

added, only the files in there with names ending with ".org" will be

parsed.

#+begin_example

ntangle 

#+end_example



or a list of files:



#+begin_example

ntangle   ..

#+end_example



or a list of directories:



#+begin_example

ntangle   ..

#+end_example



or a mix of lists of files and directories:



#+begin_example

ntangle     ..

#+end_example



The tangled files will be created in paths relative to the source Org

file.

* Org mode file samples for tangling

You can find samples of the supported Org mode tangling in the [[https://github.com/OrgTangle/ntangle/tree/master/tests][*test*

directory]] of this project.

* Org Tangle Syntax

~ntangle~ expects the Org files to use the ~header-args~ property

syntax used in Org mode 9.0 and newer. There was a minor syntax change

with *header-args* property in Org 9.0 ([[https://code.orgmode.org/bzg/org-mode/src/a85ba9fb9bc7518bc0b654c79812f5606be84c58/etc/ORG-NEWS#L1042][see ORG-NEWS]]).



So if you used the below in Org 8.x and older:

#+begin_src org

# Deprecated syntax

,#+property: tangle yes

#+end_src



Refactor that to:

#+begin_src org

# Org 9.0 syntax

,#+property: header-args :tangle yes

#+end_src



Similarly, refactor a property drawer from:

#+begin_src org

# Deprecated syntax

,* Some heading

:PROPERTIES:

:tangle: yes

:END:

#+end_src



To:

#+begin_src org

# Org 9.0 syntax

,* Some heading

:PROPERTIES:

:header-args: :tangle yes

:END:

#+end_src

* Development

Below assumes that you have ~nim~ and ~nimble~ installed.

** Building

#+begin_example

git clone https://github.com/OrgTangle/ntangle

cd ntangle

nimble build # creates the ntangle binary in the same directory

# nimble build -d:release # same as above but creates an optimized binary

#+end_example

** Testing

#+begin_src shell :results output verbatim

# cd to the git repo dir

./tests/test.sh

#+end_src

* History

I was [[https://www.reddit.com/r/emacs/comments/8m5wuf/a_python_version_of_orgbabeltangle_for_literate/dzl3ooo/][motivated]] to start this project after reading about the

[[https://github.com/OrgTangle/org-babel-tangle.py][~org-babel-tangle.py~]] Python project by @thblt.



I wanted to just see how easy it was to translate a Python script to

Nim (it was very easy!), and from there, this project started

snowballing, gathering features of its own :).

* Other Org tangling implementations

See [[https://github.com/OrgTangle]].