Merge branch 'master' of git+ssh://repo.or.cz/srv/git/org-mode

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
-
-These values can be indexed in a manner similar to arrays---see the argument
+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
 ``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]
-@end example
+#+results: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
 
-Note: ranges are indexed using the @code{:} operator.
+#+begin_src emacs-lisp :var data=example-table[0,-1]
+  data
+#+end_src
 
-Note: indices are 0 based.
+#+results:
+: a
+@end example
 
-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.
+
+@example
+#+results: example-table
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
 
-For more information on indexing behavior see the documentation for the
-@code{org-babel-ref-index-list} function, provided below.
+#+begin_src emacs-lisp :var data=example-table[,0]
+  data
+#+end_src
 
-@deffn
-org-babel-ref-index-list is a Lisp function in `org-babel-ref.el'.
+#+results:
+| 1 | 2 | 3 | 4 |
+@end example
 
-(org-babel-ref-index-list index lis)
+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.
 
-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
+@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}

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.

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))
 

lisp/ob-sh.el

@@ -113,7 +113,11 @@ var of the same value."
 	(format "$(cat <<BABEL_TABLE\n%s\nBABEL_TABLE\n)"
 		(orgtbl-to-generic
 		 (deep-string var) (list :sep (or sep "\t")))))
-    (if (stringp var) (format "%s" var) (format "%S" var))))
+    (if (stringp var)
+	(if (string-match "[\n\r]" var)
+	    (format "$(cat <<BABEL_STRING\n%s\nBABEL_STRING\n)" var)
+	  (format "%s" var))
+      (format "%S" var))))
 
 (defun org-babel-sh-table-or-results (results)
   "Convert RESULTS to an appropriate elisp value.