{"id":13861983,"url":"https://github.com/OrgTangle/ntangle","last_synced_at":"2025-07-14T11:31:59.645Z","repository":{"id":43395273,"uuid":"135108494","full_name":"OrgTangle/ntangle","owner":"OrgTangle","description":"Command-line utility for Tangling of Org documents — programmed in Nim.","archived":false,"fork":false,"pushed_at":"2022-03-03T20:11:39.000Z","size":399,"stargazers_count":74,"open_issues_count":8,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-08-05T06:04:34.864Z","etag":null,"topics":["literate-programming","nim","org-mode","tangle"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OrgTangle.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-28T04:12:34.000Z","updated_at":"2024-07-09T15:13:06.000Z","dependencies_parsed_at":"2022-09-23T10:08:39.281Z","dependency_job_id":null,"html_url":"https://github.com/OrgTangle/ntangle","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrgTangle%2Fntangle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrgTangle%2Fntangle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrgTangle%2Fntangle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OrgTangle%2Fntangle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OrgTangle","download_url":"https://codeload.github.com/OrgTangle/ntangle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225974263,"owners_count":17553916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["literate-programming","nim","org-mode","tangle"],"created_at":"2024-08-05T06:01:34.205Z","updated_at":"2024-11-22T22:30:19.957Z","avatar_url":"https://github.com/OrgTangle.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp"],"sub_categories":[],"readme":"#+title: NTangle\n\n/Command-line utility for Tangling of Org documents — programmed in\nNim./\n\n[[https://github.com/OrgTangle/ntangle/actions/workflows/test.yml][https://github.com/OrgTangle/ntangle/actions/workflows/test.yml/badge.svg]]\n\n* What is Tangling\nFrom [[https://orgmode.org/manual/Extracting-source-code.html][Org Manual -- Extracting source code]]:\n\n#+begin_quote\nExtracting source code from code blocks is a basic task in /literate\nprogramming/. Org has features to make this easy. In literate\nprogramming parlance, documents on creation are /woven/ with code and\ndocumentation, and on export, the code is *tangled* for execution by a\ncomputer.\n\nOrg facilitates weaving and tangling for producing, maintaining,\nsharing, and exporting literate programming documents. Org provides\nextensive customization options for extracting source code.\n\nWhen Org tangles ~src~ code blocks, it expands, merges, and transforms\nthem. Then Org recomposes them into one or more separate files, as\nconfigured through the options. During this /tangling/ process, Org\nexpands variables in the source code, and resolves any Noweb style\nreferences (see [[https://orgmode.org/manual/Noweb-reference-syntax.html][Noweb reference syntax]]).\n#+end_quote\n\n/You can visit the same Org manual section from within Emacs by going\nto this Info manual node: ~(org) Extracting Source Code~./\n* Why ~ntangle~?\nWhile the tangling of Org documents works great from within Emacs, it\ncan be quite a bit slow for large Org documents. This project aims to\nprovide /almost/ the same tangling functionality at a much higher\nspeed.\n\nYou do *not* need Emacs or Org mode installed to use ~ntangle~.\n* Installation\n\n[[https://github.com/nim-lang/nimble][~nimble~]] can be used to install ~ntangle~. This utility ships with Nim\ninstallations. Think of it as the equivalent of the Python ~pip~.\n\n/See [[https://github.com/dom96/choosenim#installation][*choosenim* installation]] to install *nim* and *nimble*./\n\nTo install ~ntangle~:\n#+begin_example\nnimble install ntangle\n#+end_example\n\nAbove installs the binary in the *~/.nimble/bin/* directory.\n* Features\n** Tangling /minus Noweb/ [7/8]\n- [X] Understands global tangle header-args in ~#+property~ keywords\n- [X] Understands tangle header-args directly above Org source blocks\n- [-] Understands tangle subtree property drawer header-args\n  - [X] Rudimentary parsing of the property drawer\n    header-args. ~ntangle~ does not check the validity of the property\n    drawer (i.e. ~:PROPERTIES:~ appears immediately after the heading,\n    and it ends with ~:END:~, and that the properties are only between\n    them, etc.). Also ~header-args~ is treated the same as\n    ~header-args+~ for simplicity for now.\n  - [ ] Treat ~header-args~ vs ~header-args+~ values correctly.\n- [X] Understands the precendence order of the tangle header-args when\n  a mix of global and source block header-args are used\n- [X] Language-specific header-args (e.g. ~#+property: header-args:nim\n  :tangle yes~)\n- [X] Concatenating multiple source blocks to the same tangled file\n- [X] Respects comma-escaping in source blocks\n- [X] Removes common indentation, but also retains the indentation\n  where needed\n*** Supported ~header-args~ switches [5/7]\n- [X] ~:tangle~\n- [X] ~:padline~\n- [X] ~:shebang~\n- [X] ~:mkdirp~\n- [X] ~:tangle-mode~\n- [ ] ~:comments~\n- [ ] ~:no-expand~\n** Noweb [0/1]\n- [ ] Noweb support. I sorely miss the lack of ~noweb~ support.. I use\n  it heavily in [[https://github.com/kaushalmodi/eless][~eless~]].\n\n/There is *no* plan to support Org Babel functions with Noweb, like\nevaluating code blocks during tangling, etc. (just use Emacs for those\n:D)./\n*** Supported ~header-args~ switches for Noweb [0/3]\n- [ ] ~:noweb~\n- [ ] ~:noweb-ref~\n- [ ] ~:noweb-sep~\n* Screenshot\n[[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]]\n* Usage\nAdd one or more Org files (files with names ending in \".org\") or\ndirectory names after the ~ntangle~ command. If directory names are\nadded, only the files in there with names ending with \".org\" will be\nparsed.\n#+begin_example\nntangle \u003cFILE.org\u003e\n#+end_example\n\nor a list of files:\n\n#+begin_example\nntangle \u003cFILE1.org\u003e \u003cFILE2.org\u003e ..\n#+end_example\n\nor a list of directories:\n\n#+begin_example\nntangle \u003cDIR1\u003e \u003cDIR2\u003e ..\n#+end_example\n\nor a mix of lists of files and directories:\n\n#+begin_example\nntangle \u003cFILE1.org\u003e \u003cDIR1\u003e \u003cFILE2.org\u003e \u003cDIR2\u003e ..\n#+end_example\n\nThe tangled files will be created in paths relative to the source Org\nfile.\n* Org mode file samples for tangling\nYou can find samples of the supported Org mode tangling in the [[https://github.com/OrgTangle/ntangle/tree/master/tests][*test*\ndirectory]] of this project.\n* Org Tangle Syntax\n~ntangle~ expects the Org files to use the ~header-args~ property\nsyntax used in Org mode 9.0 and newer. There was a minor syntax change\nwith *header-args* property in Org 9.0 ([[https://code.orgmode.org/bzg/org-mode/src/a85ba9fb9bc7518bc0b654c79812f5606be84c58/etc/ORG-NEWS#L1042][see ORG-NEWS]]).\n\nSo if you used the below in Org 8.x and older:\n#+begin_src org\n# Deprecated syntax\n,#+property: tangle yes\n#+end_src\n\nRefactor that to:\n#+begin_src org\n# Org 9.0 syntax\n,#+property: header-args :tangle yes\n#+end_src\n\nSimilarly, refactor a property drawer from:\n#+begin_src org\n# Deprecated syntax\n,* Some heading\n:PROPERTIES:\n:tangle: yes\n:END:\n#+end_src\n\nTo:\n#+begin_src org\n# Org 9.0 syntax\n,* Some heading\n:PROPERTIES:\n:header-args: :tangle yes\n:END:\n#+end_src\n* Development\nBelow assumes that you have ~nim~ and ~nimble~ installed.\n** Building\n#+begin_example\ngit clone https://github.com/OrgTangle/ntangle\ncd ntangle\nnimble build # creates the ntangle binary in the same directory\n# nimble build -d:release # same as above but creates an optimized binary\n#+end_example\n** Testing\n#+begin_src shell :results output verbatim\n# cd to the git repo dir\n./tests/test.sh\n#+end_src\n* History\nI 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\n[[https://github.com/OrgTangle/org-babel-tangle.py][~org-babel-tangle.py~]] Python project by @thblt.\n\nI wanted to just see how easy it was to translate a Python script to\nNim (it was very easy!), and from there, this project started\nsnowballing, gathering features of its own :).\n* Other Org tangling implementations\nSee [[https://github.com/OrgTangle]].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOrgTangle%2Fntangle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOrgTangle%2Fntangle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOrgTangle%2Fntangle/lists"}