{"id":3402,"date":"2016-10-26T14:19:29","date_gmt":"2016-10-26T18:19:29","guid":{"rendered":"http:\/\/fgiasson.com\/blog\/?p=3402"},"modified":"2017-02-17T10:41:12","modified_gmt":"2017-02-17T15:41:12","slug":"literate-clojure-programming-tangle-all-in-org-mode","status":"publish","type":"post","link":"https:\/\/fgiasson.com\/blog\/index.php\/2016\/10\/26\/literate-clojure-programming-tangle-all-in-org-mode\/","title":{"rendered":"Literate [Clojure] Programming: Tangle All in Org-mode"},"content":{"rendered":"

This blog post is the fifth of a series of blog posts about Literate [Clojure] Programming in Org-mode<\/a> where I explain how I develop my [Clojure] applications using literate programming concepts and principles.<\/p>\n

This new blog post introduce a tool that is often necessary when developing literate applications using Org-mode: the tangle all<\/code> script. As I explained in a previous blog post, doing literate programming is often like writing: you write something, you review and update it\u00e2\u20ac\u00a6 often. This means that you may end-up changing multiple files in your Org-mode project. Depending how you configured you Emacs environment and Org-mode, you may have missed to tangle a file you changed that may cause issues down the road. This is the situation I will cover in this post.<\/p>\n

This series of blog posts about literate [Clojure] programming in Org-mode is composed of the following articles:<\/p>\n

    \n
  1. Configuring Emacs for Org-mode<\/a><\/li>\n
  2. Project folder structure<\/a><\/li>\n
  3. Anatomy of a Org-mode file<\/a><\/li>\n
  4. Tangling all project files<\/a> (this post)<\/li>\n
  5. Publishing documentation in multiple formats<\/a><\/li>\n
  6. Unit Testing<\/a><\/li>\n<\/ol>\n

    <\/p>\n

    \n

    Emacs: the Programmable Text Editor<\/h2>\n
    \n

    One of the beauty of Emacs<\/a> is that it is fully programmable. It is open source, anything can be accessed, changed and modified: even while running. It can be done because at its core, it is an Emacs Lisp<\/a> interpreter. This is the feature of the development environment that I leveraged to create a series of tools that I can use in my Org-mode literate programming projects.<\/p>\n<\/div>\n<\/div>\n

    \n

    Literate [Clojure] Programming Project Folder Structure<\/h2>\n
    \n

    Let’s take a look at the folder structure of a literate [Clojure] programming project:<\/p>\n

    - CHANGELOG.md\n- LICENCE\n- README.md\n- resources\n- org\n  - project.org\n  - publish.org\n  - tangle-all.org\n  - setup.org\n  - org_mode_clj_tests_utils\n    - core.org\n- pom.xml\n- project.clj\n- src\n  - org_mode_clj_tests_utils\n    - core.clj\n- target\n- test\n  - org_mode_clj_tests_utils\n    - core_test.clj\n<\/pre>\n
    In the root org<\/code> folder we have setup and configuration files, but also some tool<\/i> files. One of them is tangle-all.org<\/code> which we will cover below. This is where I add such tools that helps me with some specific tasks when developing literate programming applications in Emacs.<\/p>\n
    In my blog post Optimal Emacs Settings for Org-mode for Literate Programming<\/a> I have a section called Change Behaviors On Save<\/a> which explains how to configure Emacs and Org-mode to trigger some specific behavior when saving a file. One of these behavior is to automatically tangle the file that is being saved, such that you don’t forget to tangle it down the road. This is really handy and it works 95% of the time. However there are situations when this won’t fully work. For example, the file may be changed using another text editor than Emacs. Or someone else that would like to use your literate program may not have your modifications to the save behavior, etc. This is for these situations that such a tangle-all<\/code> script comes handy: the tool ensure you that you tangled all the files of your application.<\/p>\n<\/div>\n<\/div>\n
    \n
    Tangle All<\/h2>\n
    \n
    I choose to create, and use, the tangle-all<\/code> function in an Org-mode file. It could easily have been created as an Emacs package, or simply added in the .emacs<\/code> configuration file. However having it as Org files is handy. It becomes really portable. It follows the literate programming project’s code. It comes really handy when the literate program is shared in a repository like on GitHub. It becomes instantly available for other to be used without having to search and install a third party package or to hack their Emacs text editor. They only have to run the code in Org-mode and they get the capability without having to worry about anything else.<\/p>\n
    The (tangle-all)<\/code> function uses the (directory-files-recursive)<\/code> function adapted from Daniel M. German’s work<\/a>. The tangle-all.org<\/a> file is located at the root of the org<\/code> folder. What it does is to recursively check for Org-mode files from that location on the file system, and tangle all of them.<\/p>\n
    \n
    (<\/span>defun<\/span> directory-files-recursive<\/span> (<\/span>directory match maxdepth)<\/span>\n  \"List files in DIRECTORY and in its sub-directories. <\/span>\n   Return files that match the regular expression MATCH. Recurse only <\/span>\n   to depth MAXDEPTH. If zero or negative, then do not recurse\"<\/span>\n  (<\/span>let*<\/span> (<\/span>(<\/span>files-list '()<\/span>)<\/span>\n         (<\/span>current-directory-list\n          (<\/span>directory-files directory t)<\/span>)<\/span>)<\/span>\n    ;; <\/span>while we are in the current directory<\/span>\n    (<\/span>while<\/span> current-directory-list\n      (<\/span>let<\/span> (<\/span>(<\/span>f (<\/span>car current-directory-list)<\/span>)<\/span>)<\/span>\n        (<\/span>cond<\/span> \n         (<\/span>(<\/span>and\n           (<\/span>file-regular-p f)<\/span>\n           (<\/span>file-readable-p f)<\/span>\n           (<\/span>string-match match f)<\/span>)<\/span>\n          (<\/span>setq files-list (<\/span>cons f files-list)<\/span>)<\/span>)<\/span>\n         (<\/span>(<\/span>and\n           (<\/span>file-directory-p f)<\/span>\n           (<\/span>file-readable-p f)<\/span>\n           (<\/span>not (<\/span>string-equal \"..\"<\/span> (<\/span>substring f -2)<\/span>)<\/span>)<\/span>\n           (<\/span>not (<\/span>string-equal \".\"<\/span> (<\/span>substring f -1)<\/span>)<\/span>)<\/span>\n           (<\/span>> maxdepth 0)<\/span>)<\/span>     \n          ;; <\/span>recurse only if necessary<\/span>\n          (<\/span>setq files-list (<\/span>append files-list (<\/span>directory-files-recursive f match (<\/span>- maxdepth -1)<\/span>)<\/span>)<\/span>)<\/span>\n          (<\/span>setq files-list (<\/span>cons f files-list)<\/span>)<\/span>)<\/span>\n         (<\/span>t)<\/span>)<\/span>)<\/span>\n      (<\/span>setq current-directory-list (<\/span>cdr current-directory-list)<\/span>)<\/span>)<\/span>\n    files-list)<\/span>)<\/span>\n\n(<\/span>defun<\/span> tangle-all<\/span> ()<\/span>\n  \"Tangle all the Org-mode files in the directory of the file of the current buffer<\/span>\n   recursively in child folders. Returns the list of tangled files\"<\/span>\n  (<\/span>mapcar (<\/span>lambda<\/span> (<\/span>f)<\/span>\n            (<\/span>when<\/span> (<\/span>not (<\/span>file-directory-p f)<\/span>)<\/span>\n              (<\/span>org-babel-tangle-file f)<\/span>)<\/span>)<\/span>\n          (<\/span>directory-files-recursive (<\/span>file-name-directory (<\/span>buffer-file-name)<\/span>)<\/span> \"\\\\.org$\"<\/span> 20)<\/span>)<\/span>)<\/span>\n<\/pre>\n<\/div>\n
    \n
    (<\/span>tangle-all)<\/span>\n<\/pre>\n<\/div>\n
    The only thing a user as to do to tangle all the files is to open the tangle-all.org<\/code> file and then to execute all the code blocks in the current buffer using C-c C-v b<\/code>. That will evaluate the (tangle-all)<\/code> function and then it will call it. Finally the list of tangled files will be output.<\/p>\n<\/div>\n<\/div>\n
    \n
    Conclusion<\/h2>\n
    \n
    As you can see, it is really easy to create tools<\/i> to help us managing our literate programming applications. n the next and final article of this series, I will introduce another such tool used to weave<\/code> all documents in multiple different file formats.<\/p>\n<\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"
    This blog post is the fifth of a series of blog posts about Literate [Clojure] Programming in Org-mode where I explain how I develop my [Clojure] applications using literate programming concepts and principles. This new blog post introduce a tool that is often necessary when developing literate applications using Org-mode: the tangle all script. As […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[251,279,277,66],"tags":[252,254,274,276],"class_list":["post-3402","post","type-post","status-publish","format-standard","hentry","category-clojure","category-emacs","category-literate-programming","category-programming","tag-clojure-2","tag-emacs","tag-literateprogramming","tag-orgmode"],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts\/3402","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/comments?post=3402"}],"version-history":[{"count":6,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts\/3402\/revisions"}],"predecessor-version":[{"id":3609,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/posts\/3402\/revisions\/3609"}],"wp:attachment":[{"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/media?parent=3402"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/categories?post=3402"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/fgiasson.com\/blog\/index.php\/wp-json\/wp\/v2\/tags?post=3402"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}