added references to a large literate programming project in ob-closure
[worg.git] / org-contrib / babel / languages / ob-doc-clojure.org
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
5 #+TITLE:      Org-babel-clojure
6 #+AUTHOR:     Joel Boehland, Greg Raven
7 #+EMAIL:      joel dot boehland at evocomputing dot com, soapy-smith at comcast dot net
8 #+LANGUAGE:   en
9 #+HTML_HEAD:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
10 #+LINK_UP:    ../languages.html
11 #+LINK_HOME:  http://orgmode.org/worg/
12
13 #+begin_html
14   <div id="subtitle" style="float: center; text-align: center;">
15   <p>
16   Org-babel support for
17   <a href="http://clojure.org/">Clojure</a>
18   </p>
19   <p>
20   <a href="http://clojure.org/">
21   <img src="http://clojure.org/space/showimage/clojure-icon.gif"/>
22   </a>
23   </p>
24   </div>
25 #+end_html
26
27 * Notes                                                            :noexport:
28 ** Template Design
29   - What the user wants to know:
30     - Required software
31     - How to install it
32     - How to configure it in Org-babel
33     - Org-babel conventions that might affect the language
34     - How it modifies Org-babel
35     - Common ways to use it
36  * Updated January 2014 to CIDER which replaces swank/slime.  Greg Raven
37
38 * Introduction
39 Clojure is a dynamic LISP dialect programming language which is built on the Java Virtual Machine (and also CLR and Javascript).
40
41 org-babel-clojure allows Clojure code to be executed directly within embedded code blocks in Org-mode documents. 
42 These code blocks and their results can be included in an exported document.
43
44 The following covers details on how to implement Clojure source code blocks in Org Mode documents.
45
46 * Requirements
47 A functional org-mode Clojure code block system requires several technologies:
48  * Java 1.5 or greater.  Refer to the [[http://www.oracle.com/technetwork/java/index.html][Oracle Java download site]] or to your platform's software installation manager.
49  * [[http://www.gnu.org/software/emacs/][emacs 24.3]] or greater
50  * [[http://orgmode.org/][org-mode (development version)]] (as of January 23, 2014)
51  * [[http://clojure.org/][Clojure]] a LISP style language built on the Java Virtual Machine.
52  * The [[http://leiningen.org/][Leiningen]] Clojure project system
53  * [[https://github.com/clojure-emacs/clojure-mode][Clojure Mode]] for optimal editing of Clojure source code in emacs.
54  * [[https://github.com/clojure-emacs/cider][CIDER]] and IDE and REPL for Clojure.
55 * Instructions for Installation
56
57 The following page is a recommended source of instructions for installing a working emacs/Clojure system.
58 These instructions assume you already have a working Java installation.
59
60 [[http://clojure-doc.org/articles/tutorials/emacs.html][Clojure with Emacs]]
61
62 After successful installation using the instructions from the above linked page, the remaining
63 task is to install the latest org-mode which includes support for CIDER.
64 Follow the procedure described on this page to install the development version:
65
66 [[http://orgmode.org/worg/org-faq.html#keeping-current-with-Org-mode-development][Download and compile the org-mode development version]]
67
68 Next, add this line to your .emacs file:
69 #+begin_example
70 (add-to-list 'load-path "/full-path-to/org-mode/lisp")
71 #+end_example
72 The above code will load the development version of org-mode upon emacs invocation.
73
74 ** Configure Org-mode
75
76 Add these lines to your .emacs file to configure org-mode for Clojure code blocks.
77 Note that emacs lisp code blocks are turned on by default in org.
78
79 #+BEGIN_SRC emacs-lisp
80   (require 'org)
81   (require 'ob-clojure)
82 #+END_SRC
83
84 ** Configure CIDER
85
86 Add these lines to your .emacs file to configure CIDER:
87
88 #+BEGIN_SRC emacs-lisp :tangle emacs.el
89   (setq org-babel-clojure-backend 'cider)
90   (require 'cider)
91 #+END_SRC
92
93 ** Create a Clojure Project with Leiningen
94
95 Create a Leiningen project directory tree:
96
97 =lein new clojure-examples=
98
99 You should be able to descend into the newly create directory clojure-examples.  You should be able to see
100 a Clojure project tree.  This would normally be used as an outline of a Clojure project.
101 For the purposes of demonstrating Clojure source code in org-mode, this
102 project is only used to allow Leiningen to deal with Java class paths and resolve
103 dependencies.  In this case, it will download the Clojure core into your machine.  If other
104 dependencies are required, they should be added to the project.clj file.  Please see
105 the [[https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md][Leiningen tutorial]] for further details.  For the purposes of this demonstration,
106 simply creating the project is sufficient to proceed.
107
108 * An Introduction to Org Code Block Evaluation
109
110 This is a simple example which evaluates emacs LISP code.
111 From within the Leiningen project directory, begin editing an org file:
112
113 =emacs clojure-examples.org=
114
115 Copy the following into the Org buffer:
116 #+begin_example
117 #+BEGIN_SRC emacs-lisp
118   (message "Yeah!")
119 #+END_SRC
120 #+end_example
121
122 Notice that a ``code block'' is delimited by the lines =#+BEGIN_SRC emacs-lisp=
123 and =#+END_SRC=.
124
125 To see how a code block is evaluated, hit =C-c C-c= anywhere within the code block.
126
127 The emacs minibuffer displays the output: yeah!
128 This is the simplest possible example.  There are numerous options
129 available for output and format of the result of code evaluation.
130 Options are added to the =#+BEGIN_SRC= line.
131 Please refer to the org-mode manual for usage of these options.
132 Another source for information on options is this page at Worg:
133 [[http://orgmode.org/worg/org-contrib/babel/header-args.html][Header arguments and result types in Org Babel]]
134  
135 Next, a similar process for executing code will be used with Clojure.
136
137 * Connect to the REPL
138
139 To compile and run Clojure code, you will need to connect to a REPL (Read Evaluation Print Loop).
140 To connect the current Org buffer to a REPL:
141
142 =M-x cider-jack-in RET=
143
144 ... and wait until you get a confirmation message in the minibuffer.
145 A second buffer (window) should open, and a CIDER REPL prompt should appear.
146
147 * Examples
148 The following are Clojure code block examples.
149 ** Basic Functionality
150
151 Let's start really simple. We will test the evaluation of a
152 simple Clojure form. Insert the following into the org file:
153
154 #+begin_example
155 #+begin_src clojure :results silent
156   (+ 1 4)
157 #+end_src
158 #+end_example
159     
160 Now place the cursor in the code block and enter the command:
161
162 =C-c C-c=
163     
164 This should evaluate the Clojure form, and echo the results: "5" in the mini-buffer.
165     
166 Now let's insert the results into the buffer immediately after the Clojure code
167 block. Insert the following into your org file:
168
169 #+begin_example
170 #+begin_src clojure :results value
171   [ 1 2 3 4]
172 #+end_src
173 #+end_example
174
175 Execute as before:
176
177 =C-c C-c=
178     
179 Now, immediately following the code block, the following results block will be inserted:
180
181 #+begin_example
182 #+RESULTS
183 [ 1 2 3 4]
184 #+end_example
185
186 The result of the last form evaluated will be inserted into the results block.
187
188 Here is another simple example, with the results of evaluation included:
189 #+begin_example
190 #+begin_src clojure :results value
191   (def small-map {:a 2 :b 4 :c 8})
192   (:b small-map)
193 #+end_src
194
195 #+RESULTS:
196 : 4
197 #+end_example
198
199 ** A More Complicated Example- Make a Graph and Insert It into the Document
200
201 The next example will use an interesting Clojure based library called [[http://incanter.org/][Incanter]].
202 The code will demonstrate the creation of a basic x-y line plot using the Incanter xy-plot function.
203 There is a preliminary step which is required to download the Incanter library into your machine.
204 In the Leiningen project, there is a file called =project.clj= which must
205 have the Incanter library dependency added to it as follows:
206
207 #+begin_example
208 (defproject clojure-examples "0.1.0-SNAPSHOT"
209   :description "FIXME: write description"
210   :url "http://example.com/FIXME"
211   :license {:name "Eclipse Public License"
212             :url "http://www.eclipse.org/legal/epl-v10.html"}
213   :dependencies [[org.clojure/clojure "1.5.0"]
214                  [incanter "1.5.4"]])
215 #+end_example
216
217 After the =project.clj= file is modified, issue the command =lein deps= at the
218 command line.  You must have an internet connection for this to successfully
219 download the dependencies into your local machine.
220
221 The following code block shows how the Incanter library is
222 used to create an x-y line plot.  The =view= function will display the plot. 
223 The plot is also saved to both PDF and PNG format image files.
224 #+begin_example
225 #+begin_src clojure
226   (use '(incanter core charts pdf))
227   ;;; Create the x and y data:
228   (def x-data [0.0 1.0 2.0 3.0 4.0 5.0])
229   (def y-data [2.3 9.0 2.6 3.1 8.1 4.5])
230   (def xy-line (xy-plot x-data y-data))
231   (view xy-line)
232   (save-pdf xy-line "incanter-xy-line.pdf")
233   (save xy-line "incanter-xy-line.png")
234 #+end_src
235 #+end_example
236
237 To insert the image into the exported document, add this code:
238 #+begin_example
239   #+CAPTION: A basic x-y line plot
240   #+NAME: fig:xy-line
241   [[./incanter-xy-line.pdf]]
242 #+end_example
243
244 Note that the file will be saved to the highest level of the Leiningen project.
245 Depending on where you created the org file, the path to the file may have to be different
246 than shown.
247 ** Export to LaTeX or HTML
248
249 To export to LaTeX, =C-c C-e l l=.
250 To export to HTML, =C-c C-e h h=.
251
252 Note that the exported HTML will hyperlink the PDF file;
253 to embed the image in the HTML, switch to the PNG image file.
254 The exported LaTeX (.tex) file will embed either the PDF or PNG file.
255 Graphical quality will be superior with the PDF file.
256
257 * Session Evaluation
258
259 By default, each individual code block will execute by starting a Clojure process.
260 Each code block will execute in isolation from the others.  Due to the start-up
261 time of a Java virtual machine, this can make execution of many blocks slow.
262 The :session option will allow control of the process assigned to each code block.
263 Please refer to the org manual for details on :session usage.
264
265 * Additional Examples
266
267 The above set-up and examples were intended for the beginner to achieve success
268 with Clojure code blocks in org mode documents.
269
270 Please refer to the documentation for emacs, Clojure-mode, and CIDER which are
271 referenced in the requirements session for details on how to enhance the system
272 beyond the basics described in this tutorial.
273
274 More examples of Clojure code blocks can be found at these sites:
275  * [[http://bzg.fr/emacs-org-babel-overtone-intro.html][Emacs Org and Overtone]]
276  * [[https://github.com/lambdatronic/org-babel-example][Literate Programming Solution to the Potter Kata]]
277  * [[https://github.com/Greg-R/incanterchartcustom][Incanter Chart Customizations]]
278  * [[https://github.com/thi-ng/geom][thi.ng/geom: Comprehensive geometry toolkit for Clojure/ClojureScript developed in a literate programming style.]]