diff options
author | Carsten Dominik <carsten.dominik@gmail.com> | 2010-07-18 07:33:53 +0200 |
---|---|---|
committer | Carsten Dominik <carsten.dominik@gmail.com> | 2010-07-18 07:33:53 +0200 |
commit | c3cfb22fcc9dcb06636d20bf891e6b0e8a31c357 (patch) | |
tree | 964ff274679570c3324612a678f421044faf0fa3 | |
parent | d5810cf41ca66a749609a49f8d76d8709b3ddcfa (diff) | |
parent | 4a64aa51c9db0ffa2c9398aef4fa5a2cd0188065 (diff) | |
download | org-mode-c3cfb22fcc9dcb06636d20bf891e6b0e8a31c357.tar.gz |
Merge branch 'master' of git+ssh://repo.or.cz/srv/git/org-mode
-rw-r--r-- | doc/org.texi | 15 | ||||
-rw-r--r-- | doc/orgguide.texi | 109 | ||||
-rw-r--r-- | lisp/ob-exp.el | 16 | ||||
-rw-r--r-- | lisp/ob-ocaml.el | 47 | ||||
-rw-r--r-- | lisp/ob-tangle.el | 17 | ||||
-rw-r--r-- | lisp/org.el | 12 |
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) |