added references to a large literate programming project in ob-closure
[worg.git] / org-contrib / babel / languages / ob-doc-clojure.org
index f49e126..72942df 100644 (file)
@@ -1,12 +1,14 @@
-#+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
+#+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
 #+TITLE:      Org-babel-clojure
-#+AUTHOR:     Joel Boehland
-#+EMAIL:      joel dot boehland at evocomputing dot com
+#+AUTHOR:     Joel Boehland, Greg Raven
+#+EMAIL:      joel dot boehland at evocomputing dot com, soapy-smith at comcast dot net
 #+LANGUAGE:   en
-#+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
+#+HTML_HEAD:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
+#+LINK_UP:    ../languages.html
+#+LINK_HOME:  http://orgmode.org/worg/
 
 #+begin_html
   <div id="subtitle" style="float: center; text-align: center;">
@@ -22,7 +24,7 @@
   </div>
 #+end_html
 
-* Notes                                                            :noexport:
+* Notes                                                           :noexport:
 ** Template Design
   - What the user wants to know:
     - Required software
     - Org-babel conventions that might affect the language
     - How it modifies Org-babel
     - Common ways to use it
+ * Updated January 2014 to CIDER which replaces swank/slime.  Greg Raven
+
+* Introduction
+Clojure is a dynamic LISP dialect programming language which is built on the Java Virtual Machine (and also CLR and Javascript).
+
+org-babel-clojure allows Clojure code to be executed directly within embedded code blocks in Org-mode documents. 
+These code blocks and their results can be included in an exported document.
+
+The following covers details on how to implement Clojure source code blocks in Org Mode documents.
 
 * Requirements
-** A working Java install, version 1.5 or later
-   Installation instructions for java are beyond the scope of this
-   document, but instructions for all major platforms can easily be
-   found on [[http://java.sun.com][Sun's java website]].
-
-** A working Clojure install
-   You can set Clojure up separately as described in the
-   [[http://clojure.org/getting_started][official install document]] from the Clojure web site, but as you 
-   will see below, if you use ELPA to install the required packages, 
-   it can install Clojure for you.
-
-** Emacs ELPA package manager
-   Although it is possible to grab the different pieces and line all
-   the version numbers up so that it works, the process will most
-   likely bring you to bitter tears unless you are very experienced
-   and patient with setting up emacs, clojure, slime and swank. Save
-   yourself some trouble and use the [[http://tromey.com/elpa][Emacs Lisp Package Archive (ELPA)]].
-
-** Working (and recent) emacs ELPA clojure packages
-   You will need to install the following packages:
-   clojure-mode, swank-clojure, slime, slime-repl
-
-*** Installation
-    Once you have installed ELPA, you can do this easily in one step
-    within emacs by issuing the command:
-    
-#+begin_example
-   M-x package-list-packages
-#+end_example
-   
-   You will be presented with a buffer where you can select all of
-   these packages. Simply enter "i" on the lines of the packages you
-   wish to install, and when you are done selecting packages enter "x"
-   and ELPA will download and install these packages for you.
-   
-   Install these packages:
+A functional org-mode Clojure code block system requires several technologies:
+ * 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.
+ * [[http://www.gnu.org/software/emacs/][emacs 24.3]] or greater
+ * [[http://orgmode.org/][org-mode (development version)]] (as of January 23, 2014)
+ * [[http://clojure.org/][Clojure]] a LISP style language built on the Java Virtual Machine.
+ * The [[http://leiningen.org/][Leiningen]] Clojure project system
+ * [[https://github.com/clojure-emacs/clojure-mode][Clojure Mode]] for optimal editing of Clojure source code in emacs.
+ * [[https://github.com/clojure-emacs/cider][CIDER]] and IDE and REPL for Clojure.
+* Instructions for Installation
 
-#+begin_example
-   clojure-mode swank-clojure slime slime-repl
-#+end_example
+The following page is a recommended source of instructions for installing a working emacs/Clojure system.
+These instructions assume you already have a working Java installation.
 
-   At this point you should be able to start SLIME and have access to
-   a working Clojure REPL:
+[[http://clojure-doc.org/articles/tutorials/emacs.html][Clojure with Emacs]]
 
-#+begin_example
-   M-x slime
-#+end_example
-   
-   Note that if swank-clojure can't detect the Clojure jars, it will
-   prompt you for permission to download the required jars.
-
-** An up-to-date install of emacs-org-mode
-   You will probably need org-mode 6.34 or later
-
-* Advanced setup
-  There are quite a few usage modes for using emacs, clojure-mode,
-  swank-clojure, slime, and clojure. Following is a short description
-  in roughly easy to hard order. Note that the documentation for this
-  section comes mostly from Technomancy's writeup for the
-  [[http://github.com/technomancy/swank-clojure][swank-clojure project]].
-   
-** Use ELPA to install it for you (Easiest)
-   This is the shortest path to victory. Assuming you have a suitable
-   Java installed on your system, and the ELPA package manager
-   installed, you can simply install the required elisp packages, as
-   well as Clojure. 
-   
-** Project
-   Put your project's dependencies in the lib/ directory, either
-   manually or using [[http://github.com/technomancy/leiningen][Leiningen]] or Maven then launch:
+After successful installation using the instructions from the above linked page, the remaining
+task is to install the latest org-mode which includes support for CIDER.
+Follow the procedure described on this page to install the development version:
+
+[[http://orgmode.org/worg/org-faq.html#keeping-current-with-Org-mode-development][Download and compile the org-mode development version]]
 
+Next, add this line to your .emacs file:
 #+begin_example
-   M-x swank-clojure-project
+(add-to-list 'load-path "/full-path-to/org-mode/lisp")
 #+end_example
+The above code will load the development version of org-mode upon emacs invocation.
 
-   Note that you must have swank-clojure.jar in the lib/ directory, it
-   will not automatically add itself to the classpath as it did in
-   past versions that had to run from a checkout.
+** Configure Org-mode
 
-** Server
-   Users of [[http://github.com/technomancy/leiningen][Leiningen]] or clojure-maven-plugin can launch a server from
-   a shell and connect to it from within Emacs.
-   
-*** Set up Leiningen project.clj file
-    You should set up your project's project.clj file to look
-    something like this
+Add these lines to your .emacs file to configure org-mode for Clojure code blocks.
+Note that emacs lisp code blocks are turned on by default in org.
 
-#+begin_src clojure
-  (defproject my-project "0.1.0"
-    :description "My great Clojure project"
-    :dependencies [[org.clojure/clojure "1.1.0-alpha-SNAPSHOT"]
-                   [org.clojure/clojure-contrib "1.0-SNAPSHOT"]]
-    :dev-dependencies [[leiningen/lein-swank "1.0.0-SNAPSHOT"]])
-#+end_src
-    
-    Then from your project directory you can run the following:
+#+BEGIN_SRC emacs-lisp
+  (require 'org)
+  (require 'ob-clojure)
+#+END_SRC
 
-#+begin_example
-    $ lein swank
-#+end_example
+** Configure CIDER
 
-    A REPL should get started up on port 4005. Launch Emacs. Once Emacs is
-    up and running type:
+Add these lines to your .emacs file to configure CIDER:
 
-#+begin_example
-    M-x slime-connect
-#+end_example
+#+BEGIN_SRC emacs-lisp :tangle emacs.el
+  (setq org-babel-clojure-backend 'cider)
+  (require 'cider)
+#+END_SRC
 
-    Use the default settings. You’re now connected to a Clojure REPL with a properly
-    configured classpath for this particular project.
-    
-    Note that you could also connect to a remote server that you
-    started with the lein swank command as well using slime-connect.
+** Create a Clojure Project with Leiningen
 
-** Custom classpath (Hard)
-   If you know your way around setting up Java Classpaths and Emacs
-   load-paths, then you can set all of this up in your own custom
-   way. Set swank-clojure-classpath to a list of paths to the jars you
-   want to use and then use slime as before.
+Create a Leiningen project directory tree:
 
-*** Example
-     Let's say you have have the clojure.jar, clojure-contrib.jar and
-     swank-clojure.jar files in the directory ~/.my-clojure-jars.
+=lein new clojure-examples=
 
-     You could properly set swank-clojure-classpath by entering the
-     following elisp code into your *scratch* buffer:
+You should be able to descend into the newly create directory clojure-examples.  You should be able to see
+a Clojure project tree.  This would normally be used as an outline of a Clojure project.
+For the purposes of demonstrating Clojure source code in org-mode, this
+project is only used to allow Leiningen to deal with Java class paths and resolve
+dependencies.  In this case, it will download the Clojure core into your machine.  If other
+dependencies are required, they should be added to the project.clj file.  Please see
+the [[https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md][Leiningen tutorial]] for further details.  For the purposes of this demonstration,
+simply creating the project is sufficient to proceed.
 
-#+begin_example
-     (setq swank-clojure-classpath (directory-files "~/.my-clojure-jars" t ".jar$"))
-#+end_example
+* An Introduction to Org Code Block Evaluation
 
-     Then, move the cursor to the end of that elisp code and enter the command:
+This is a simple example which evaluates emacs LISP code.
+From within the Leiningen project directory, begin editing an org file:
 
-#+begin_example
-     M-j
-#+end_example
-    
-     You should now be able to start slime and have it be using the
-     jars entered above.
+=emacs clojure-examples.org=
 
+Copy the following into the Org buffer:
 #+begin_example
-     M-x slime
-#+end_example
-     
-* Usage
-  All the usage examples assume that you have a basic Clojure,
-  clojure-mode, swank-clojure and slime set up correctly. You should
-  be able to get a Clojure REPL when you issue the command:
-#+begin_example
-  M-x slime
+#+BEGIN_SRC emacs-lisp
+  (message "Yeah!")
+#+END_SRC
 #+end_example
-  Make sure this is working for you before proceeding with the
-  org-babel-clojure examples.
-** Non session execution
-    By default, org-babel will execute each block by starting up a
-    Clojure process and having it execute each source block in
-    isolation from the other source blocks. Due to the relatively long
-    startup time of a Java JVM, this can make execution of many blocks
-    very *slow*. Unless you really need the execution isolation for
-    some reason, it is recommended that you use sessions in
-    org-babel-clojure.
-    
-*** Examples
-**** Basic Functionality
-     Let's start really simple. We will just test the execution of a
-     simple Clojure form. Create an org file and insert the following:
+
+Notice that a ``code block'' is delimited by the lines =#+BEGIN_SRC emacs-lisp=
+and =#+END_SRC=.
+
+To see how a code block is evaluated, hit =C-c C-c= anywhere within the code block.
+
+The emacs minibuffer displays the output: yeah!
+This is the simplest possible example.  There are numerous options
+available for output and format of the result of code evaluation.
+Options are added to the =#+BEGIN_SRC= line.
+Please refer to the org-mode manual for usage of these options.
+Another source for information on options is this page at Worg:
+[[http://orgmode.org/worg/org-contrib/babel/header-args.html][Header arguments and result types in Org Babel]]
+Next, a similar process for executing code will be used with Clojure.
+
+* Connect to the REPL
+
+To compile and run Clojure code, you will need to connect to a REPL (Read Evaluation Print Loop).
+To connect the current Org buffer to a REPL:
+
+=M-x cider-jack-in RET=
+
+... and wait until you get a confirmation message in the minibuffer.
+A second buffer (window) should open, and a CIDER REPL prompt should appear.
+
+* Examples
+The following are Clojure code block examples.
+** Basic Functionality
+
+Let's start really simple. We will test the evaluation of a
+simple Clojure form. Insert the following into the org file:
+
 #+begin_example
-     #+srcname: basic-clojure
-     #+begin_src clojure :results silent
-       (+ 1 4)
-     #+end_src
+#+begin_src clojure :results silent
+  (+ 1 4)
+#+end_src
 #+end_example
     
-     Now place the cursor anywhere between the begin_src..end_src lines
-     and enter the command:
+Now place the cursor in the code block and enter the command:
 
-#+begin_example
-    C-c C-c
-#+end_example
+=C-c C-c=
     
-    This should execute the Clojure form, and echo the results: "5".
+This should evaluate the Clojure form, and echo the results: "5" in the mini-buffer.
     
-    Now let's insert the results into the buffer immediately after the
-    Clojure src block. Insert the following into your org file:
+Now let's insert the results into the buffer immediately after the Clojure code
+block. Insert the following into your org file:
 
 #+begin_example
-    #+srcname: basic-clojure-table-results
-    #+begin_src clojure :results value
-      [ 1 2 3 4]
-    #+end_src
+#+begin_src clojure :results value
+  [ 1 2 3 4]
+#+end_src
 #+end_example
 
-    Execute as before:
-#+begin_example
-    C-c C-c
-#+end_example
+Execute as before:
+
+=C-c C-c=
     
-    Now, immediately following this block, the following block should
-    have been inserted:
+Now, immediately following the code block, the following results block will be inserted:
 
 #+begin_example
-    #+resname: basic-clojure-table-results
-    | 1 | 2 | 3 | 4 |
+#+RESULTS
+[ 1 2 3 4]
 #+end_example
 
-    Note that the Clojure vector has been automagically converted to
-    an org table.
-** Session execution
-   org-babel-clojure supports executing code blocks in the context of
-   one or more SLIME REPL sessions. This means that after the initial
-   startup time, the code blocks will execute much quicker. It also
-   means that you can easily go back and inspect the transcript
-   between Emacs and Clojure that will be stored in the
-   *inferior-lisp* and REPL buffers. You can also use the powerful
-   debugging and inspection facilities provided by SLIME.
-
-*** Examples
-**** Basic Functionality
-     Let's mirror the simple non-session examples we did above, but
-     execute them within a session.
-     
-     Create an org file and insert the following:
-#+begin_example
-     #+srcname: basic-session-clojure :session s1
-     #+begin_src clojure :results silent
-        (+ 1 4)
-     #+end_src
-#+end_example
-    
-     This will initialize a session named "s1". Now place the cursor
-     anywhere between the begin_src..end_src lines and enter the
-     command:
+The result of the last form evaluated will be inserted into the results block.
 
+Here is another simple example, with the results of evaluation included:
 #+begin_example
-     C-c C-c
+#+begin_src clojure :results value
+  (def small-map {:a 2 :b 4 :c 8})
+  (:b small-map)
+#+end_src
+
+#+RESULTS:
+: 4
 #+end_example
-    
-     This should create a SLIME REPL buffer named "s1", and execute the
-     Clojure form, and echo the results: "5". Note that the initial
-     creation of this SLIME REPL can take several seconds. Once this
-     session has been created, the execution will happen very quickly.
 
-     Now let's insert the results into the buffer immediately after the
-     Clojure src block. Insert the following into your org file:
+** A More Complicated Example- Make a Graph and Insert It into the Document
 
-#+begin_example
-     #+srcname: basic-session-clojure-table-results
-     #+begin_src clojure :session s1 :results value
-        [ 1 2 3 4]
-     #+end_src
-#+end_example
+The next example will use an interesting Clojure based library called [[http://incanter.org/][Incanter]].
+The code will demonstrate the creation of a basic x-y line plot using the Incanter xy-plot function.
+There is a preliminary step which is required to download the Incanter library into your machine.
+In the Leiningen project, there is a file called =project.clj= which must
+have the Incanter library dependency added to it as follows:
 
-     Execute as before:
 #+begin_example
-     C-c C-c
+(defproject clojure-examples "0.1.0-SNAPSHOT"
+  :description "FIXME: write description"
+  :url "http://example.com/FIXME"
+  :license {:name "Eclipse Public License"
+            :url "http://www.eclipse.org/legal/epl-v10.html"}
+  :dependencies [[org.clojure/clojure "1.5.0"]
+                 [incanter "1.5.4"]])
 #+end_example
-    
-     As with the non-session code block, immediately following this block, the following block should
-     have been inserted:
 
-#+begin_example
-     #+resname: basic-session-clojure-table-results
-     | 1 | 2 | 3 | 4 |
-#+end_example
+After the =project.clj= file is modified, issue the command =lein deps= at the
+command line.  You must have an internet connection for this to successfully
+download the dependencies into your local machine.
 
-**** Multiple sessions
-     org-babel-clojure also supports multiple sessions executing
-     concurrently. The following example will illustrate two different
-     sessions running in isolation from each other.
-     
-     Create an org file with the following content:
+The following code block shows how the Incanter library is
+used to create an x-y line plot.  The =view= function will display the plot. 
+The plot is also saved to both PDF and PNG format image files.
 #+begin_example
-     #+srcname: set-clojure-session-var-s1
-     #+begin_src clojure :session s1 :results value
-     (def *var* [1 2 3])
-     #+end_src
-     
-     #+srcname: set-clojure-session-var-s2
-     #+begin_src clojure :session s2 :results value
-     (def *var* [3 4 5 6 7 8 9])
-     #+end_src
-
-     #+srcname: get-clojure-session-var-s1
-     #+begin_src clojure :session s1 :results value
-     (count *var*)
-     #+end_src
-     
-     #+srcname: get-clojure-session-var-s2
-     #+begin_src clojure :session s2 :results value
-     (count *var*)
-     #+end_src
+#+begin_src clojure
+  (use '(incanter core charts pdf))
+  ;;; Create the x and y data:
+  (def x-data [0.0 1.0 2.0 3.0 4.0 5.0])
+  (def y-data [2.3 9.0 2.6 3.1 8.1 4.5])
+  (def xy-line (xy-plot x-data y-data))
+  (view xy-line)
+  (save-pdf xy-line "incanter-xy-line.pdf")
+  (save xy-line "incanter-xy-line.png")
+#+end_src
 #+end_example
 
-     Execute the entire buffer
+To insert the image into the exported document, add this code:
 #+begin_example
-     C-c M-b b
+  #+CAPTION: A basic x-y line plot
+  #+NAME: fig:xy-line
+  [[./incanter-xy-line.pdf]]
 #+end_example
-    
-     You should have two separate SLIME REPL sessions being created,
-     and the results from executing each source block will be inserted
-     after the respective block. The resulting buffer should look
-     something like this:
-#+begin_example
-     #+srcname: set-clojure-session-var-s1
-     #+begin_src clojure :session s1 :results value
-     (def *var* [1 2 3])
-     #+end_src
-     
-     #+results: set-clojure-session-var-s1
-     : #'user/*var*
-
-     #+srcname: set-clojure-session-var-s2
-     #+begin_src clojure :session s2 :results value
-     (def *var* [3 4 5 6 7 8 9])
-     #+end_src
-
-     #+results: set-clojure-session-var-s2
-     : #'user/*var*
-
-     #+srcname: get-clojure-session-var-s1
-     #+begin_src clojure :session s1 :results value
-     (count *var*)
-     #+end_src
-     
-     #+results: get-clojure-session-var-s1
-     : 3
-
-     #+srcname: get-clojure-session-var-s2
-     #+begin_src clojure :session s2 :results value
-     (count *var*)
-     #+end_src
-   
-     #+results: get-clojure-session-var-s2
-     : 7
-#+end_example
-     
+
+Note that the file will be saved to the highest level of the Leiningen project.
+Depending on where you created the org file, the path to the file may have to be different
+than shown.
+** Export to LaTeX or HTML
+
+To export to LaTeX, =C-c C-e l l=.
+To export to HTML, =C-c C-e h h=.
+
+Note that the exported HTML will hyperlink the PDF file;
+to embed the image in the HTML, switch to the PNG image file.
+The exported LaTeX (.tex) file will embed either the PDF or PNG file.
+Graphical quality will be superior with the PDF file.
+
+* Session Evaluation
+
+By default, each individual code block will execute by starting a Clojure process.
+Each code block will execute in isolation from the others.  Due to the start-up
+time of a Java virtual machine, this can make execution of many blocks slow.
+The :session option will allow control of the process assigned to each code block.
+Please refer to the org manual for details on :session usage.
+
+* Additional Examples
+
+The above set-up and examples were intended for the beginner to achieve success
+with Clojure code blocks in org mode documents.
+
+Please refer to the documentation for emacs, Clojure-mode, and CIDER which are
+referenced in the requirements session for details on how to enhance the system
+beyond the basics described in this tutorial.
+
+More examples of Clojure code blocks can be found at these sites:
+ * [[http://bzg.fr/emacs-org-babel-overtone-intro.html][Emacs Org and Overtone]]
+ * [[https://github.com/lambdatronic/org-babel-example][Literate Programming Solution to the Potter Kata]]
+ * [[https://github.com/Greg-R/incanterchartcustom][Incanter Chart Customizations]]
+ * [[https://github.com/thi-ng/geom][thi.ng/geom: Comprehensive geometry toolkit for Clojure/ClojureScript developed in a literate programming style.]]