summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCarsten Dominik <carsten.dominik@gmail.com>2010-07-18 07:33:53 +0200
committerCarsten Dominik <carsten.dominik@gmail.com>2010-07-18 07:33:53 +0200
commitc3cfb22fcc9dcb06636d20bf891e6b0e8a31c357 (patch)
tree964ff274679570c3324612a678f421044faf0fa3
parentd5810cf41ca66a749609a49f8d76d8709b3ddcfa (diff)
parent4a64aa51c9db0ffa2c9398aef4fa5a2cd0188065 (diff)
downloadorg-mode-c3cfb22fcc9dcb06636d20bf891e6b0e8a31c357.tar.gz
Merge branch 'master' of git+ssh://repo.or.cz/srv/git/org-mode
-rw-r--r--doc/org.texi15
-rw-r--r--doc/orgguide.texi109
-rw-r--r--lisp/ob-exp.el16
-rw-r--r--lisp/ob-ocaml.el47
-rw-r--r--lisp/ob-tangle.el17
-rw-r--r--lisp/org.el12
6 files changed, 181 insertions, 35 deletions
diff --git a/doc/org.texi b/doc/org.texi
index d3a9d03..3b21dbb 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -436,7 +436,7 @@ Specific header arguments
* var:: Pass arguments to code blocks
* results:: Specify the type of results and how they will be collected and handled
* file:: Specify a path for file output
-* dir and remote execution:: Specify the default directory for code block execution
+* dir:: Specify the default directory for code block execution
* exports:: Export code and/or results
* tangle:: Toggle tangling and specify file name
* no-expand:: Turn off variable assignment and noweb expansion during tangling
@@ -11427,8 +11427,8 @@ The following header arguments are defined:
* results:: Specify the type of results and how they will
be collected and handled
* file:: Specify a path for file output
-* dir and remote execution:: Specify the default directory for code block
- execution
+* dir:: Specify the default (possibly remote)
+ directory for code block execution
* exports:: Export code and/or results
* tangle:: Toggle tangling and specify file name
* no-expand:: Turn off variable assignment and noweb
@@ -11717,7 +11717,7 @@ be prepended to the existing results. Otherwise the new results will be
inserted as with @code{replace}.
@end itemize
-@node file, dir and remote execution, results, Specific header arguments
+@node file, dir, results, Specific header arguments
@subsubsection @code{:file}
The header argument @code{:file} is used to specify a path for file output.
@@ -11733,7 +11733,7 @@ as python and ruby require that the code explicitly create output
corresponding to the path indicated by @code{:file}.
-@node dir and remote execution, exports, file, Specific header arguments
+@node dir, exports, file, Specific header arguments
@subsubsection @code{:dir} and remote execution
While the @code{:file} header argument can be used to specify the path to the
@@ -11801,7 +11801,7 @@ directory}. Therefore, if @code{default-directory} is altered using
which the link does not point.
@end itemize
-@node exports, tangle, dir and remote execution, Specific header arguments
+@node exports, tangle, dir, Specific header arguments
@subsubsection @code{:exports}
The @code{:exports} header argument specifies what should be included in HTML
@@ -11863,8 +11863,7 @@ references (see @ref{Noweb reference syntax}) with their targets. The
@subsubsection @code{:session}
The @code{:session} header argument starts a session for an interpreted
-language where state is preserved. This applies particularly to the
-supported languages python, R and ruby.
+language where state is preserved.
By default, a session is not started.
diff --git a/doc/orgguide.texi b/doc/orgguide.texi
index 6aeddd9..b9d75a5 100644
--- a/doc/orgguide.texi
+++ b/doc/orgguide.texi
@@ -2489,8 +2489,113 @@ Jekyll/blogging setup}}
@node Working With Source Code, Miscellaneous, Publishing, Top
@chapter Working with source code
+Org-mode provides a number of features for working with source code,
+including editing of code blocks in their native major-mode, evaluation of
+code blocks, tangling of code blocks, and exporting code blocks and their
+results in several formats.
-TBD
+@subheading Structure of Code Blocks
+The structure of code blocks is as follows:
+
+@example
+#+srcname: <name>
+#+begin_src <language> <switches> <header arguments>
+ <body>
+#+end_src
+@end example
+
+Where @code{<name>} is a string used to name the code block,
+@code{<language>} specifies the language of the code block
+(e.g. @code{emacs-lisp}, @code{shell}, @code{R}, @code{python}, etc...),
+@code{<switches>} can be used to control export of the code block,
+@code{<header arguments>} can be used to control many aspects of code block
+behavior as demonstrated below, and @code{<body>} contains the actual source
+code.
+
+@subheading Editing source code
+Use @kbd{C-c '} to edit the current code block. This brings up a language
+major-mode edit buffer containing the body of the code block. Saving this
+buffer will write the new contents back to the Org buffer. Use @kbd{C-c '}
+again to exit the edit buffer.
+
+@subheading Evaluating code blocks
+Use @kbd{C-c C-c} to evaluate the current code block and insert its results
+in the Org-mode buffer. By default, evaluation is only turned on for
+@code{emacs-lisp} code blocks, however support exists for evaluating blocks
+in many languages. For a complete list of supported languages see the
+manual. The following shows a code block and its results.
+
+@example
+#+begin_src emacs-lisp
+ (+ 1 2 3 4)
+#+end_src
+
+#+results:
+: 10
+@end example
+
+@subheading Extracting source code
+Use @kbd{C-c C-v t} to create pure source code files by extracting code from
+source blocks in the current buffer. This is referred to as ``tangling''---a
+term adopted from the literate programming community. During ``tangling'' of
+code blocks their bodies are expanded using @code{org-babel-expand-src-block}
+which can expand both variable and ``noweb'' style references. In order to
+tangle a code block it must have a @code{:tangle} header argument, see the
+manual for details.
+
+@subheading Header Arguments
+Many aspects of the evaluation and export of code blocks are controlled
+through header arguments. These can be specified globally, at the file
+level, at the outline subtree level, and at the individual code block level.
+The following describes some of the header arguments.
+@table @code
+@item :var
+The @code{:var} header argument is used to pass arguments to code blocks.
+The values passed to arguments can be literal values, values from org-mode
+tables and literal example blocks, or the results of other named code blocks.
+@item :results
+The @code{:results} header argument controls the @emph{collection},
+@emph{type}, and @emph{handling} of code block results. Values of
+@code{output} or @code{value} (the default) specify how results are collected
+from a code block's evaluation. Values of @code{vector}, @code{scalar}
+@code{file} @code{raw} @code{html} @code{latex} and @code{code} specify the
+type of the results of the code block which dictates how they will be
+incorporated into the Org-mode buffer. Values of @code{silent},
+@code{replace}, @code{prepend}, and @code{append} specify handling of code
+block results, specifically if and how the results should be inserted into
+the Org-mode buffer.
+@item :session
+A header argument of @code{:session} will cause the code block to be
+evaluated in a persistent interactive inferior process in Emacs. This allows
+for persisting state between code block evaluations, and for manual
+inspection of the results of evaluation.
+@item :exports
+Any combination of the @emph{code} or the @emph{results} of a block can be
+retained on export, this is specified by setting the @code{:results} header
+argument to @code{code} @code{results} @code{none} or @code{both}.
+@item :tangle
+A header argument of @code{:tangle yes} will cause a code block's contents to
+be tangled to a file named after the filename of the Org-mode buffer. An
+alternate file name can be specified with @code{:tangle filename}.
+@item :cache
+A header argument of @code{:cache yes} will cause associate a hash of the
+expanded code block with the results, ensuring that code blocks are only
+re-run when their inputs have changed.
+@item :noweb
+A header argument of @code{:noweb yes} will expand ``noweb'' style references
+on evaluation and tangling.
+@item :file
+Code blocks which output results to files (e.g. graphs, diagrams and figures)
+can accept a @code{:file filename} header argument in which case the results
+are saved to the named file, and a link to the file is inserted into the
+Org-mode buffer.
+@end table
+
+@subheading Library of Babel
+Use @kbd{C-c C-v l} to load the code blocks from an Org-mode files into the
+``Library of Babel'', these blocks can then be evaluated from any Org-mode
+buffer. A collection of generally useful code blocks is distributed with
+Org-mode in @code{contrib/library-of-babel.org}.
@seealso{
@uref{http://orgmode.org/manual/Working-with-source-code.html#Working-with-source-code,Chapter 14 of the manual}@*
@@ -2581,8 +2686,6 @@ manual}@*
@end ignore
@c Local variables:
-@c ispell-local-dictionary: "en_US-w_accents"
-@c ispell-local-pdict: "./.aspell.org.pws"
@c fill-column: 77
@c End:
diff --git a/lisp/ob-exp.el b/lisp/ob-exp.el
index b500e55..565c75f 100644
--- a/lisp/ob-exp.el
+++ b/lisp/ob-exp.el
@@ -97,13 +97,15 @@ none ----- do not display either code or results upon export"
(goto-char (match-beginning 0))
(let* ((info (org-babel-get-src-block-info))
(params (nth 2 info)))
- ;; expand noweb references in the original file
- (setf (nth 1 info)
- (if (and (cdr (assoc :noweb params))
- (string= "yes" (cdr (assoc :noweb params))))
- (org-babel-expand-noweb-references
- info (get-file-buffer org-current-export-file))
- (nth 1 info)))
+ ;; bail if we couldn't get any info from the block
+ (when info
+ ;; expand noweb references in the original file
+ (setf (nth 1 info)
+ (if (and (cdr (assoc :noweb params))
+ (string= "yes" (cdr (assoc :noweb params))))
+ (org-babel-expand-noweb-references
+ info (get-file-buffer org-current-export-file))
+ (nth 1 info))))
(org-babel-exp-do-export info 'block))))
(defun org-babel-exp-inline-src-blocks (start end)
diff --git a/lisp/ob-ocaml.el b/lisp/ob-ocaml.el
index 5ca9b7e..e0e4334 100644
--- a/lisp/ob-ocaml.el
+++ b/lisp/ob-ocaml.el
@@ -41,7 +41,8 @@
(require 'comint)
(eval-when-compile (require 'cl))
-(declare-function tuareg-run-caml "ext:taureg" ())
+(declare-function tuareg-run-caml "ext:tuareg" ())
+(declare-function tuareg-interactive-send-input "ext:tuareg" ())
(add-to-list 'org-babel-tangle-lang-exts '("ocaml" . "ml"))
@@ -55,7 +56,8 @@
(let ((vars (nth 1 (or processed-params (org-babel-process-params params)))))
(concat
(mapconcat
- (lambda (pair) (format "let %s = %s;" (car pair) (cdr pair)))
+ (lambda (pair) (format "let %s = %s;;" (car pair)
+ (org-babel-ocaml-elisp-to-ocaml (cdr pair))))
vars "\n") "\n" body "\n")))
(defun org-babel-execute:ocaml (body params)
@@ -67,14 +69,24 @@
(cdr (assoc :session params)) params))
(raw (org-babel-comint-with-output
(session org-babel-ocaml-eoe-output t full-body)
- (insert (concat (org-babel-chomp full-body) " ;;"))
- (comint-send-input nil t)
- (insert org-babel-ocaml-eoe-indicator)
- (comint-send-input nil t))))
+ (insert
+ (concat
+ (org-babel-chomp full-body)"\n"org-babel-ocaml-eoe-indicator))
+ (tuareg-interactive-send-input)))
+ (clean
+ (car (let ((re (regexp-quote org-babel-ocaml-eoe-output)) out)
+ (delq nil (mapcar (lambda (line)
+ (if out
+ (progn (setq out nil) line)
+ (when (string-match re line)
+ (progn (setq out t) nil))))
+ (mapcar #'org-babel-trim (reverse raw))))))))
(org-babel-reassemble-table
- (org-babel-ocaml-parse-output (org-babel-trim (car raw)))
- (org-babel-pick-name (nth 4 processed-params) (cdr (assoc :colnames params)))
- (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params))))))
+ (org-babel-ocaml-parse-output (org-babel-trim clean))
+ (org-babel-pick-name
+ (nth 4 processed-params) (cdr (assoc :colnames params)))
+ (org-babel-pick-name
+ (nth 5 processed-params) (cdr (assoc :rownames params))))))
(defvar tuareg-interactive-buffer-name)
(defun org-babel-prep-session:ocaml (session params)
@@ -88,6 +100,12 @@
(save-window-excursion (tuareg-run-caml)
(get-buffer tuareg-interactive-buffer-name))))
+(defun org-babel-ocaml-elisp-to-ocaml (val)
+ "Return a string of ocaml code which evaluates to VAL."
+ (if (listp val)
+ (concat "[|" (mapconcat #'org-babel-ocaml-elisp-to-ocaml val "; ") "|]")
+ (format "%S" val)))
+
(defun org-babel-ocaml-parse-output (output)
"Parse OUTPUT.
OUTPUT is string output from an ocaml process."
@@ -125,11 +143,12 @@ Emacs-lisp table, otherwise return the results as a string."
(org-babel-read
(if (and (stringp results) (string-match "^\\[.+\\]$" results))
(org-babel-read
- (replace-regexp-in-string
- "\\[|" "(" (replace-regexp-in-string
- "|\\]" ")" (replace-regexp-in-string
- "; " " " (replace-regexp-in-string
- "'" "\"" results)))))
+ (concat
+ "'" (replace-regexp-in-string
+ "\\[|" "(" (replace-regexp-in-string
+ "|\\]" ")" (replace-regexp-in-string
+ "; " " " (replace-regexp-in-string
+ "'" "\"" results))))))
results)))
(provide 'ob-ocaml)
diff --git a/lisp/ob-tangle.el b/lisp/ob-tangle.el
index 19b1840..8c71620 100644
--- a/lisp/ob-tangle.el
+++ b/lisp/ob-tangle.el
@@ -34,7 +34,6 @@
(declare-function org-link-escape "org" (text &optional table))
(declare-function org-heading-components "org" ())
-(declare-function with-temp-filebuffer "org-interaction" (file &rest body))
(defcustom org-babel-tangle-lang-exts
'(("emacs-lisp" . "el"))
@@ -54,6 +53,20 @@ then the name of the language is used."
:group 'org-babel
:type 'hook)
+(defmacro org-babel-with-temp-filebuffer (file &rest body)
+ "Open FILE into a temporary buffer execute BODY there like
+`progn', then kill the FILE buffer returning the result of
+evaluating BODY."
+ (declare (indent 1))
+ (let ((temp-result (make-symbol "temp-result"))
+ (temp-file (make-symbol "temp-file")))
+ `(let (,temp-result ,temp-file)
+ (find-file ,file)
+ (setf ,temp-file (current-buffer))
+ (setf ,temp-result (progn ,@body))
+ (kill-buffer ,temp-file)
+ ,temp-result)))
+
;;;###autoload
(defun org-babel-load-file (file)
"Load Emacs Lisp source code blocks in the Org-mode FILE.
@@ -176,7 +189,7 @@ exported source code blocks by language."
(when org-babel-post-tangle-hook
(mapc
(lambda (file)
- (with-temp-filebuffer file
+ (org-babel-with-temp-filebuffer file
(run-hooks 'org-babel-post-tangle-hook)))
path-collector))
path-collector)))
diff --git a/lisp/org.el b/lisp/org.el
index 779b2d5..e26c51b 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -17704,13 +17704,23 @@ Your bug report will be posted to the Org-mode mailing list.
With prefix arg UNCOMPILED, load the uncompiled versions."
(interactive "P")
(require 'find-func)
- (let* ((file-re "^\\(ob\\|org\\|orgtbl\\)\\(\\.el\\|-.*\\.el\\)")
+ (let* ((file-re "^\\(org\\|orgtbl\\)\\(\\.el\\|-.*\\.el\\)")
(dir-org (file-name-directory (org-find-library-name "org")))
(dir-org-contrib (ignore-errors
(file-name-directory
(org-find-library-name "org-contribdir"))))
+ (babel-files
+ (mapcar (lambda (el) (concat "ob" (when el (format "-%s" el)) ".el"))
+ (append (list nil "comint" "eval" "exp" "keys"
+ "lob" "ref" "table" "tangle")
+ (delq nil
+ (mapcar
+ (lambda (lang)
+ (when (cdr lang) (symbol-name (car lang))))
+ org-babel-load-languages)))))
(files
(append (directory-files dir-org t file-re)
+ babel-files
(and dir-org-contrib
(directory-files dir-org-contrib t file-re))))
(remove-re (concat (if (featurep 'xemacs)