Table of Contents

• Introduction
• Tutorial
  • install polymode in emacs
  • how to insert code block quickly
  • Add dependence in project.clj
  • Load org file
  • The special requirement for org files
  • a new code block header argument ~load~
• License

Introduction

This is a clojure library designed to extend the clojure syntax so it can load org file as source file directly.

The implementation details of literate-clojure is in file core.org (pdf version).

This library is provided to make litrate programming more happy in clojure,without pain of tangling code from org files.

This library contains the following files:

• ./src/literate_clojure/core.org
  The implementation and documentation and literate clojure reader.
• ./src/literate_clojure/core.clj
  The tangled codes of literate clojure reader, generated from ./src/literate_clojure/core.clj.
• ./src/literate_clojure/core.pdf
  The weaved documentation, generated from ./src/literate_clojure/core.clj by org mode’s publish feature.
• test/literate_clojure/core_test.org
  The testcase of literate-clojure.
• test/literate_clojure/core_test.clj
  The bootstrap file of test cases.
• ./README.org
  The usage and introduction of literate-clojure.
• ./project.clj
  the lein project file of literate-clojure.
• ./demo/project.clj
  the lein project file of a demo of how to use literate-clojure.
• ./demo/src/demo/literate_core.clj
  The demo documentation and codes.
• ./demo/src/demo/core.clj
  the bootstrap file to load ./demo/src/demo/literate_core.clj.
• ./.travis.yml
  The config file used by Web service travis ci to test this library.

Tutorial

install polymode in emacs

It’s better to edit the org file with polymode,which will make code block use its native file mode. The following elisp scripts in .emacs will install it.

(use-package poly-org
    :ensure t)

Usually I will add the following line as the first line of an clojure source file (*.clj or *.cljs)

# -*- encoding:utf-8 Mode: POLY-ORG;  -*- --- 

But GitHub will not render such file in org mode, to fix this issue, I will add the following line as the first line instead.

# -*- encoding:utf-8 Mode: ORG;  -*- --- 

And in my Emacs configuration file, I will add a hook to enable polymode for such file:

(defun enable-poly-org-mode ()
  (when (and buffer-file-name (not (string= "org" (downcase (file-name-extension buffer-file-name)))))
    (poly-org-mode 1)))
(add-hook 'org-mode-hook 'enable-poly-org-mode)

So Github can render such source file as org mode correctly.

how to insert code block quickly

Please have a look of the section How to insert code block in org file in library literate-elisp.

Add dependence in project.clj

To use this library, please add dependence in your project.clj:

:dependencies [[literate-clojure "0.1.1"]]

Load org file

Then in one of your source file,add the following codes to install the org syntax for clojure reader:

(require 'literate-clojure.core)
(literate-clojure.core/install-org-dispatcher)
(load-file "src/demo/core.org")

Now you can use literate_core.clj to write your documentation and source codes together, and any codes in core.org will be loaded automatically.

The special requirement for org files

The org files must start with a sharp and a space, for example I usually add the following line to the beginning of an org file:

# -*- encoding:utf-8 Mode: POLY-ORG;  -*- --- 

It will use Emacs library poly-org-mode which is a lightweight library to support multiple major mode in one file, so you can edit clojure code natively in an org file.

a new code block header argument load

Please have a look of the section handle org syntax in ./src/literate_clojure/core.org.

License

Copyright © 2018 Jingtao Xu

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.

This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.