Merge branch 'master' of orgmode.org:worg
[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
78 #+BEGIN_SRC emacs-lisp
79 (require 'org)
80
81 ;; We only need Emacs Lisp and Clojure in this tutorial:
82 (org-babel-do-load-languages
83  'org-babel-load-languages
84  '((emacs-lisp . t)
85    (clojure . t)))
86
87 (require 'ob-clojure)
88
89 ;; Use CIDER as the Clojure execution backend
90 (setq org-babel-clojure-backend 'cider)
91 #+END_SRC
92
93 ** Configure CIDER
94
95 Add these lines to your .emacs file to configure CIDER:
96
97 #+BEGIN_SRC emacs-lisp :tangle emacs.el
98 ;; Cider configuration
99 (require 'cider)
100 #+END_SRC
101
102 ** Create a Clojure Project with Leiningen
103
104 Create a Leiningen project directory tree:
105
106 =lein new clojure-examples=
107
108 You should be able to descend into the newly create directory clojure-examples.  You should be able to see
109 a Clojure project tree.  This would normally be used as an outline of a Clojure project.
110 For the purposes of demonstrating Clojure source code in org-mode, this
111 project is only used to allow Leiningen to deal with Java class paths and resolve
112 dependencies.  In this case, it will download the Clojure core into your machine.  If other
113 dependencies are required, they should be added to the project.clj file.  Please see
114 the [[https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md][Leiningen tutorial]] for further details.  For the purposes of this demonstration,
115 simply creating the project is sufficient to proceed.
116
117 * An Introduction to Org Code Block Evaluation
118
119 This is a simple example which evaluates emacs LISP code.
120 From within the Leiningen project directory, begin editing an org file:
121
122 =emacs clojure-examples.org=
123
124 Copy the following into the Org buffer:
125 #+begin_example
126 #+BEGIN_SRC emacs-lisp
127 (message "Yeah!")
128 #+END_SRC
129 #+end_example
130
131 Notice that a ``code block'' is delimited by the lines =#+BEGIN_SRC emacs-lisp=
132 and =#+END_SRC=.
133
134 To see how a code block is evaluated, hit =C-c C-c= anywhere within the code block.
135
136 The emacs minibuffer displays the output: yeah!
137 This is the simplest possible example.  There are numerous options
138 available for output and format of the result of code evaluation.
139 Options are added to the =#+BEGIN_SRC= line.
140 Please refer to the org-mode manual for usage of these options.
141  
142 Next, a similar process for executing code will be used with Clojure.
143
144 * Connect to the REPL
145
146 To compile and run Clojure code, you will need to connect to a REPL (Read Evaluation Print Loop).
147 To connect the current Org buffer to a REPL:
148
149 =M-x cider-jack-in RET=
150
151 ... and wait until you get a confirmation message in the minibuffer.
152 A second buffer (window) should open, and a CIDER REPL prompt should appear.
153
154 * Examples
155 The following are several Clojure code block examples.
156 ** Basic Functionality
157
158 Let's start really simple. We will test the evaluation of a
159 simple Clojure form. Insert the following into the org file:
160
161 #+begin_example
162 #+begin_src clojure :results silent
163 (+ 1 4)
164 #+end_src
165 #+end_example
166     
167 Now place the cursor in the code block and enter the command:
168
169 =C-c C-c=
170     
171 This should evaluate the Clojure form, and echo the results: "5" in the mini-buffer.
172     
173 Now let's insert the results into the buffer immediately after the Clojure code
174 block. Insert the following into your org file:
175
176 #+begin_example
177 #+begin_src clojure :results value
178 [ 1 2 3 4]
179 #+end_src
180 #+end_example
181
182 Execute as before:
183
184 =C-c C-c=
185     
186 Now, immediately following the code block, the following results block will be inserted:
187
188 #+begin_example
189 #+RESULTS
190 [ 1 2 3 4]
191 #+end_example
192
193 The result of the last form evaluated will be inserted into the results block.
194
195 Here is another simple example, with the results of evaluation included:
196 #+begin_example
197 #+begin_src clojure :results value
198 (def small-map {:a 2 :b 4 :c 8})
199 (:b small-map)
200 #+end_src
201
202 #+RESULTS:
203 : 4
204 #+end_example
205
206 ** A More Complicated Example- Make a Graph and Insert It into the Document
207
208 The next example will use an interesting Clojure based library called [[http://incanter.org/][Incanter]].
209 The code will demonstrate the creation of a basic x-y line plot using the Incanter xy-plot function.
210 There is a preliminary step which is required to download the Incanter library into your machine.
211 In the Leiningen project, there is a file called =project.clj= which must
212 have the Incanter library dependency added to it as follows:
213
214 #+begin_example
215 (defproject clojure-examples "0.1.0-SNAPSHOT"
216   :description "FIXME: write description"
217   :url "http://example.com/FIXME"
218   :license {:name "Eclipse Public License"
219             :url "http://www.eclipse.org/legal/epl-v10.html"}
220   :dependencies [[org.clojure/clojure "1.5.0"]
221                  [incanter "1.5.4"]])
222 #+end_example
223
224 After the =project.clj= file is modified, issue the command =lein deps= at the
225 command line.  You must have an internet connection for this to successfully
226 download the dependencies into your local machine.
227
228 The following code block shows how the Incanter library is
229 used to create an x-y line plot.  The =view= function will display the plot. 
230 The plot is also saved to both PDF and PNG format image files.
231 #+begin_example
232 #+begin_src clojure
233 (use '(incanter core charts pdf))
234 ;;; Create the x and y data:
235 (def x-data [0.0 1.0 2.0 3.0 4.0 5.0])
236 (def y-data [2.3 9.0 2.6 3.1 8.1 4.5])
237 (def xy-line (xy-plot x-data y-data))
238 (view xy-line)
239 (save-pdf xy-line "incanter-xy-line.pdf")
240 (save xy-line "incanter-xy-line.png")
241 #+end_src
242 #+end_example
243
244 To insert the image into the exported document, add this code:
245 #+begin_example
246 #+CAPTION: A basic x-y line plot
247 #+NAME: fig:xy-line
248 [[./incanter-xy-line.pdf]]
249 #+end_example
250
251 Note that the file will be saved to the highest level of the Leiningen project.
252 Depending on where you created the org file, the path to the file may have to be different
253 than shown.
254
255 To export to LaTeX, =C-c C-e l l=.
256 To export to HTML, =C-c C-e h h=.
257
258 Note that the exported HTML will hyperlink the PDF file;
259 to embed the image in the HTML, switch to the PNG image file.
260 The exported LaTeX (.tex) file will embed either the PDF or PNG file.
261 Graphical quality will be superior with the PDF file.
262
263 * Additional Examples
264
265 The above set-up and examples were intended for the beginner to achieve success
266 with Clojure code blocks in org mode documents.  Additional features can be added to
267 the system, mostly via changes to the .emacs configuration file.
268
269 Please refer to the documentation for emacs, Clojure-mode, and CIDER which are
270 referenced in the requirements session for details on how to enhance the system.
271
272 More examples of Clojure code blocks can be found at these sites:
273  * [[http://bzg.fr/emacs-org-babel-overtone-intro.html][Emacs Org and Overtone]]
274  * [[https://github.com/lambdatronic/org-babel-example][Literate Programming Solution to the Potter Kata]]
275  * [[https://github.com/Greg-R/incanterchartcustom][Incanter Chart Customizations]]