[Orgmode] [babel] Org-babel updates: code block preview, body expand on tangling, row/col-names, and hlines

[Eric Schulte]

Hi,

Dan and I have been hard at work putting together the following two
updates to Org-babel.  They introduce both the ability to expand code
blocks according to their header arguments for both previewing and
tangling, and three new header arguments for the handling of column
names, row names, and hlines in tables.

More information is available at the following urls and below:
http://eschulte.github.com/babel-dev/DONE-code-block-body-expansion-for-table-and-preview.html
http://eschulte.github.com/babel-dev/DONE-Handling-of-table-column-names-and-hlines-across-languages-.html

Cheers -- Eric

code block body expansion for table and preview

In org-babel, code is "expanded" prior to evaluation. I.e. the code that is actually evaluated comprises the code block contents, augmented with the extra code which assigns the referenced data to variables. It is now possible to preview expanded contents, and also to expand code during during tangling. This expansion takes into account all header arguments, and variables.

preview

A new key-binding C-c M-b p bound to `org-babel-expand-src-block' can be used from inside of a source code block to preview its expanded contents (which can be very useful for debugging).

tangling

The expanded body can now be tangled, this includes variable values which may be the results of other source-code blocks, or stored in headline properties or tables. One possible use for this is to allow those using org-babel for their emacs initialization to store values (e.g. usernames, passwords, etc…) in headline properties or in tables.

Here is an example of a code block and its resulting expanded body.

The data in the file.

username	john-doe
password	abc123

The actual code block

setup-my-account(data="">

(setq my-special-username (first (first data)))
(setq my-special-password (first (second data)))

its expanded contents, as seen with C-c M-b p

(let ((data (quote (("john-doe") ("abc123")))))
(setq my-special-username (first (first data)))
(setq my-special-password (first (second data)))
)

Handling of table column names and hlines across languages

Org-babel now supports three new header arguments, and new default behavior for handling horizontal lines in tables (hlines), column names, and rownames across all languages. These are as follows

:hlines

Can take on the values of "yes" or "no", with a default value of "no". These values have the following effects.

"no"

results in all hlines being stripped from the input table. In most languages this is the desired effect, as a raw 'hline symbol generally is interpreted as an unbound variable and leads to and error. The following table would previously have lead to an error but is now processed as shown.

#+tblname: many-cols
| a | b | c |
|---+---+---|
| d | e | f |
|---+---+---|
| g | h | i |

#+source: echo-table
#+begin_src python :var tab=many-cols
  return tab
#+end_src

#+results: echo-table
| a | b | c |
| d | e | f |
| g | h | i |

"yes"

leaves 'hlines in the table. This is the default for emacs-lisp which may want to handle hline symbols explicitly.

:colnames

Can take on the values of "yes", "no", or nil for unassigned. The default value is nil. These values have the following effects

nil

If an input table looks like it has column names (meaning if it's second row is an hline), then the column names will be removed from the table by org-babel before processing, then reapplied to the results, so for example the following code block has the effect shown.

#+tblname: less-cols
| a |
|---|
| b |
| c |
  
#+srcname: echo-table-again
#+begin_src python :var tab=less-cols
  return [[val + '*' for val in row] for row in tab]
#+end_src

#+results: echo-table-again
| a  |
|----|
| b* |
| c* |

"no"

No column name pre-processing will take place.

"yes"

Column names are removed and reapplied as with nil even if the table does not look like it has column names (i.e. the second row is not an hline)

:rownames

Can take on the values of "yes" or "no", with a default value of "no". These values have the following effects.

"no"

No row name pre-processing will take place.

"yes"

The first column of the table is removed from the table by org-babel before processing, and is then reapplied to the results. This has the effect shown below.

#+tblname: with-rownames
| one | 1 | 2 | 3 | 4 |  5 |
| two | 6 | 7 | 8 | 9 | 10 | 

#+srcname: echo-table-once-again
#+begin_src python :var tab=with-rownames :rownames yes
  return [[val + 10 for val in row] for row in tab]            
#+end_src

#+results: echo-table-once-again
| one | 11 | 12 | 13 | 14 | 15 |
| two | 16 | 17 | 18 | 19 | 20 |

Thanks to Julien Barnier for adding rownames support in R.