diff --git a/doc/org.texi b/doc/org.texi index 27d1874b8..d73571046 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -11144,29 +11144,23 @@ of tangled code files. @cindex code block, evaluating @cindex source code, evaluating -@quotation -Whenever code is evaluated there is a potential for that code to do harm. -Org-mode provides a number of safeguards to ensure that it only evaluates -code with explicit confirmation from the user. For information on these -safeguards (and on how to disable them) see @ref{Code evaluation security}. -@end quotation - -Code blocks can be evaluated and the results placed 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. See +Code blocks can be evaluated@footnote{Whenever code is evaluated there is a +potential for that code to do harm. Org-mode provides a number of safeguards +to ensure that it only evaluates code with explicit confirmation from the +user. For information on these safeguards (and on how to disable them) see +@ref{Code evaluation security}.} and the results placed 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. See @ref{Languages} for a list of supported languages. See @ref{Structure of code blocks} for information on the syntax used to define a code block. @kindex C-c C-c -There are a number of ways to evaluate code blocks. The simplest is to -press @kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block. This -will call the @code{org-babel-execute-src-block} function to evaluate the -block and insert its results into the Org-mode buffer. - -@quotation -The @code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove -code evaluation from the @kbd{C-c C-c} key binding. -@end quotation +There are a number of ways to evaluate code blocks. The simplest is to press +@kbd{C-c C-c} or @kbd{C-c C-v e} with the point on a code block@footnote{The +@code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code +evaluation from the @kbd{C-c C-c} key binding.}. This will call the +@code{org-babel-execute-src-block} function to evaluate the block and insert +its results into the Org-mode buffer. It is also possible to evaluate named code blocks from anywhere in an Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously @@ -11223,7 +11217,7 @@ Code blocks in the following languages are supported. @multitable @columnfractions 0.28 0.3 0.22 0.2 @item @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier} @item Asymptote @tab asymptote @tab C @tab C -@item C @tab C++ @tab Clojure @tab clojure +@item C++ @tab C++ @tab Clojure @tab clojure @item css @tab css @tab ditaa @tab ditaa @item Graphviz @tab dot @tab Emacs Lisp @tab emacs-lisp @item gnuplot @tab gnuplot @tab Haskell @tab haskell @@ -11237,7 +11231,7 @@ Code blocks in the following languages are supported. @item Sqlite @tab sqlite @end multitable -Language specific documentation is available for some languages. If +Language-specific documentation is available for some languages. If available, it can be found at @uref{http://orgmode.org/worg/org-contrib/babel/languages}. @@ -11451,19 +11445,14 @@ The following header arguments are defined: @node var, results, Specific header arguments, Specific header arguments @subsubsection @code{:var} -The @code{:var} header argument is used to pass arguments to -code blocks. The specifics of how arguments are included -in a code block vary by language; these are -addressed in the language-specific documentation. However, the -syntax used to specify arguments is the same across all -languages. The values passed to arguments can be -@itemize @bullet -@item literal values -@item values from org-mode tables -@item the results of other code blocks -@end itemize +The @code{:var} header argument is used to pass arguments to code blocks. +The specifics of how arguments are included in a code block vary by language; +these are addressed in the language-specific documentation. However, the +syntax used to specify arguments is the same across all languages. The +values passed to arguments can be literal values, values from org-mode tables +and literal example blocks, or the results of other code blocks. -These values can be indexed in a manner similar to arrays---see the argument +These values can be indexed in a manner similar to arrays---see the ``indexable variable values'' heading below. The following syntax is used to pass arguments to code blocks using the @@ -11546,43 +11535,90 @@ following the source name. @end example @subsubheading Indexable variable values -It is possible to assign a portion of a value to a variable in a source -block. The following example assigns the second and third rows of the table +It is possible to reference portions of variable values by ``indexing'' into +the variables. Indexes are 0 based with negative values counting back from +the end. If an index is separated by @code{,}s then each subsequent section +will index into the next deepest nesting or dimension of the value. The +following example assigns the last cell of the first row the table @code{example-table} to the variable @code{data}: @example -:var data=example-table[1:2] +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | + +#+begin_src emacs-lisp :var data=example-table[0,-1] + data +#+end_src + +#+results: +: a @end example -Note: ranges are indexed using the @code{:} operator. - -Note: indices are 0 based. - -The following example assigns the second column of the first row of -@code{example-table} to @code{data}: +Ranges of variable values can be referenced using two integers separated by a +@code{:}, in which case the entire inclusive range is referenced. For +example the following assigns the middle three rows of @code{example-table} +to @code{data}. @example -:var data=example-table[0,1] +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | +| 5 | 3 | + +#+begin_src emacs-lisp :var data=example-table[1:3] + data +#+end_src + +#+results: +| 2 | b | +| 3 | c | +| 4 | d | @end example -It is possible to index into the results of code blocks as well as -tables. Any number of dimensions can be indexed. Dimensions are separated -from one another by commas. +Additionally, an empty index, or the single character @code{*}, are both +interpreted to mean the entire range and as such are equivalent to +@code{0:-1}, as shown in the following example in which the entire first +column is referenced. -For more information on indexing behavior see the documentation for the -@code{org-babel-ref-index-list} function, provided below. +@example +#+results: example-table +| 1 | a | +| 2 | b | +| 3 | c | +| 4 | d | -@deffn -org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'. +#+begin_src emacs-lisp :var data=example-table[,0] + data +#+end_src -(org-babel-ref-index-list index lis) +#+results: +| 1 | 2 | 3 | 4 | +@end example -Return the subset of LIS indexed by INDEX. If INDEX is -separated by ,s then each PORTION is assumed to index into the -next deepest nesting or dimension. A valid PORTION can consist -of either an integer index, or two integers separated by a : in -which case the entire range is returned. -@end deffn +It is possible to index into the results of code blocks as well as tables. +Any number of dimensions can be indexed. Dimensions are separated from one +another by commas, as shown in the following example. + +@example +#+source: 3D +#+begin_src emacs-lisp + '(((1 2 3) (4 5 6) (7 8 9)) + ((10 11 12) (13 14 15) (16 17 18)) + ((19 20 21) (22 23 24) (25 26 27))) +#+end_src + +#+begin_src emacs-lisp :var data=3D[1,,1] + data +#+end_src + +#+results: +| 11 | 14 | 17 | +@end example @node results, file, var, Specific header arguments @subsubsection @code{:results} diff --git a/lisp/ob-python.el b/lisp/ob-python.el index 8d2a3b437..1be8a33f7 100644 --- a/lisp/ob-python.el +++ b/lisp/ob-python.el @@ -110,7 +110,11 @@ Convert an elisp value, VAR, into a string of python source code specifying a variable of the same value." (if (listp var) (concat "[" (mapconcat #'org-babel-python-var-to-python var ", ") "]") - (if (equal var 'hline) "None" (format "%S" var)))) + (if (equal var 'hline) + "None" + (format + (if (and (stringp var) (string-match "[\n\r]" var)) "\"\"%S\"\"" "%S") + var)))) (defun org-babel-python-table-or-string (results) "Convert RESULTS into an appropriate elisp value. diff --git a/lisp/ob-ref.el b/lisp/ob-ref.el index 148dafb2e..4ed70be36 100644 --- a/lisp/ob-ref.el +++ b/lisp/ob-ref.el @@ -177,28 +177,36 @@ return nil." (defun org-babel-ref-index-list (index lis) "Return the subset of LIS indexed by INDEX. -If INDEX is separated by ,s then each PORTION is assumed to index -into the next deepest nesting or dimension. A valid PORTION can -consist of either an integer index, or two integers separated by -a : in which case the entire range is returned." - (if (string-match "^,?\\([^,]+\\)" index) - (let ((length (length lis)) + +Indices are 0 based and negative indices count from the end of +LIS, so 0 references the first element of LIS and -1 references +the last. If INDEX is separated by \",\"s then each \"portion\" +is assumed to index into the next deepest nesting or dimension. + +A valid \"portion\" can consist of either an integer index, two +integers separated by a \":\" in which case the entire range is +returned, or an empty string or \"*\" both of which are +interpreted to mean the entire range and as such are equivalent +to \"0:-1\"." + (if (and (> (length index) 0) (string-match "^\\([^,]*\\),?" index)) + (let ((ind-re "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)") + (length (length lis)) (portion (match-string 1 index)) (remainder (substring index (match-end 0)))) (flet ((wrap (num) (if (< num 0) (+ length num) num)) - (open (lis) (if (and (listp lis) (= (length lis) 1)) (car lis) lis))) + (open (ls) (if (and (listp ls) (= (length ls) 1)) (car ls) ls))) (open (mapcar (lambda (sub-lis) (org-babel-ref-index-list remainder sub-lis)) - (if (string-match "\\(\\([-[:digit:]]+\\):\\([-[:digit:]]+\\)\\|\*\\)" - portion) - (mapcar (lambda (n) (nth n lis)) - (apply 'number-sequence - (if (match-string 2 portion) - (list - (wrap (string-to-number (match-string 2 portion))) - (wrap (string-to-number (match-string 3 portion)))) - (list (wrap 0) (wrap -1))))) + (if (or (= 0 (length portion)) (string-match ind-re portion)) + (mapcar + (lambda (n) (nth n lis)) + (apply 'number-sequence + (if (and (> (length portion) 0) (match-string 2 portion)) + (list + (wrap (string-to-number (match-string 2 portion))) + (wrap (string-to-number (match-string 3 portion)))) + (list (wrap 0) (wrap -1))))) (list (nth (wrap (string-to-number portion)) lis))))))) lis)) diff --git a/lisp/ob-sh.el b/lisp/ob-sh.el index f327d2221..fb9dd535d 100644 --- a/lisp/ob-sh.el +++ b/lisp/ob-sh.el @@ -113,7 +113,11 @@ var of the same value." (format "$(cat <