Ecosyste.ms: Awesome

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

https://github.com/jingtaozf/literate-clojure

Load Clojure/ClojureScript code blocks from Org files
https://github.com/jingtaozf/literate-clojure

clojure emacs literate-programming literate-programs org-mode

Last synced: 12 days ago
JSON representation

Load Clojure/ClojureScript code blocks from Org files

Lists

README 

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

#+Startup: noindent

#+PROPERTY:    header-args        :results silent   :eval no-export   :comments org

#+OPTIONS:     num:nil toc:nil todo:nil tasks:nil tags:nil

#+OPTIONS:     skip:nil author:nil email:nil creator:nil timestamp:t

#+INFOJS_OPT:  view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js

[[https://clojars.org/literate-clojure][file:https://img.shields.io/clojars/v/literate-clojure.svg]]

[[https://travis-ci.com/jingtaozf/literate-clojure][file:https://travis-ci.com/jingtaozf/literate-clojure.svg?branch=master]]

[[https://github.com/jingtaozf/literate-clojure/actions][file:https://github.com/jingtaozf/literate-clojure/workflows/Clojure%20CI/badge.svg]]



* Table of Contents                                                   :TOC:

- [[#introduction][Introduction]]

- [[#tutorial][Tutorial]]

  - [[#install-polymode-in-emacs][install polymode in emacs]]

  - [[#how-to-insert-code-block-quickly][how to insert code block quickly]]

  - [[#add-dependence-in-projectclj][Add dependence in project.clj]]

  - [[#load-org-file][Load org file]]

  - [[#the-special-requirement-for-org-files][The special requirement for org files]]

  - [[#a-new-code-block-header-argument-load][a new code block header argument ~load~]]

- [[#license][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 [[https://github.com/jingtaozf/literate-clojure][literate-clojure]] is in file [[./src/literate_clojure/core.org][core.org]] ([[./src/literate_clojure/core.pdf][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 [[https://orgmode.org/manual/Triggering-publication.html#Triggering-publication][publish feature]].

- [[test/literate_clojure/core_test.org]] \\

  The testcase of [[https://github.com/jingtaozf/literate-clojure][literate-clojure]]. 

- [[test/literate_clojure/core_test.clj]] \\

  The bootstrap file of test cases.

- [[./README.org]] \\

  The usage and introduction of [[https://github.com/jingtaozf/literate-clojure][literate-clojure]].

- [[./project.clj]] \\

  the lein project file of [[https://github.com/jingtaozf/literate-clojure][literate-clojure]].

- [[./demo/project.clj]] \\

  the lein project file of a demo of how to use [[https://github.com/jingtaozf/literate-clojure][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 [[https://travis-ci.com/jingtaozf/literate-lisp][travis ci]] to test this library.



* Tutorial

** install polymode in emacs

It's better to edit the org file with [[https://polymode.github.io/][polymode]],which will make code block use its native file mode. 

The following elisp scripts in .emacs will install it.

#+BEGIN_SRC elisp

(use-package poly-org

    :ensure t)

#+END_SRC

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

#+BEGIN_SRC elisp

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

#+END_SRC

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.

#+BEGIN_SRC elisp

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

#+END_SRC

And in my Emacs configuration file, I will add a hook to enable [[https://polymode.github.io/][polymode]] for such file:

#+BEGIN_SRC elisp

(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)

#+END_SRC

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

** how to insert code block quickly

Please have a look of the section [[https://github.com/jingtaozf/literate-elisp/blob/master/literate-elisp.org#how-to-insert-code-block-in-org-file][How to insert code block in org file]] in library [[https://github.com/jingtaozf/literate-elisp][literate-elisp]].

** Add dependence in project.clj

To use this library, please add dependence in your [[./demo/project.clj][project.clj]]:

#+BEGIN_SRC clojure

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

#+END_SRC

** Load org file

Then in one of your [[./demo/src/demo/core.clj][source file]],add the following codes to install the org syntax for clojure reader:

#+BEGIN_SRC clojure

(require 'literate-clojure.core)

(literate-clojure.core/install-org-dispatcher)

(load-file "src/demo/core.org")

#+END_SRC

Now you can use [[./demo/src/demo/literate_core.clj][literate_core.clj]] to write your documentation and source codes together,

and any codes in [[./demo/src/demo/core.org][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:

#+BEGIN_SRC org

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

#+END_SRC

It will use Emacs library [[https://github.com/polymode/poly-org][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 [[./src/literate_clojure/core.org#handle-org-syntax][handle org syntax]] in [[./src/literate_clojure/core.org][./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.