Perl in Org Mode

This document is a short introduction to using Perl within Org mode.

The only requirement is installed in the computer where Org Babel is executing the scripts.

(org-babel-do-load-languages
 'org-babel-load-languages
 '((lisp . t)))

These are two simple examples:

#+BEGIN_SRC perl :results value
"hello world";
#+END_SRC

#+RESULTS:
: hello world

10 * 20 + 5;

#+end_example

Perl scripts might generate data that is parsed by Org. Unfortunately its current support is not very powerful. Currently there is only one method to receive data: :results value. This is the default. The result of the code block (the value of the last expression evaluated) if returned to Org. If the result is an array (up to two dimensions) it is interpreted as a table. Some examples below:

#+BEGIN_SRC perl :results value
[[1,2],[2,4]]
#+END_SRC

#+RESULTS:
| 1 | 2 |
| 2 | 4 |

10 + 20

When returning an array, it is important to return a reference to the array. Otherwise it is interpreted as an scalar.

For example, this returns the size of the array:

#+BEGIN_SRC perl :results value
my @result ;
$i = 0;
for $j ('a'..'e')  {
   $result[$i] = $j;
   $i ++;
}
@result;
#+END_SRC

#+RESULTS:
: 5

But this returns the values of the array and creates the corresponding table

#+BEGIN_SRC perl :results value
my @result ;
$i = 0;
for $j ('a'..'e')  {
   $result[$i] = $j;
   $i ++;
}
\@result;
#+END_SRC

#+RESULTS:
| a |
| b |
| c |
| d |
| e |

#+BEGIN_SRC perl :results value
my @result ;
for $i (0..3) {
   for $j (0..2) {
      $result[$i][$j] = $j*$i+$j;
   }
}
\@result;
#+END_SRC

#+RESULTS:
| 0 | 1 | 2 |
| 0 | 2 | 4 |
| 0 | 3 | 6 |
| 0 | 4 | 8 |

The most useful feature of using Perl within Org is the ability to use tables as input to scripts.

Let us assume we have the following table:

#+NAME:exampletable
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |

We want to use this table as input. Org passes a table to Perl as a reference to an array of anonymous one-dimension arrays. In a nutshell, you can access an element of a table using $$nameTable[row][column]. Remember, in Perl indexes are zero based: For instance, this block simply returns the input table. Please note that because data is already a reference we can simply return it.

#+name: example1usingTable
#+begin_src perl :var data=exampletable :results table :type value
$data
#+end_src

#+RESULTS: example1usingTable
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |

One challenge, however, is to know how big the table is. Perl does not have native two dimensional arrays. Instead, it uses arrays of arrays (each sub-array can have any size). In the block below we use a function (org_table_size) to return the number of columns and rows in a table.

#+name: example2usingTable
#+begin_src perl :results value :var data=exampletable
# first we need to define two functions that will make our life easier
sub org_table_size
{
    # return the number of columns and rows in a table
    my ($table) = @_;
    my $y = $$table[0];
    return (scalar(@$y), scalar (@$table));
}

my @result ;

my ($cols, $rows) = org_table_size($data);

## transpose the input table

for my $i ($0..$cols-1) {
    for my $j (0 .. $rows-1) {
        $result[$i][$j] = $$data[$j][$i];
    }
}
\@result;
#+end_src

#+RESULTS: example2usingTable
| 1 | 2 | 3 | 4 |
| a | b | c | d |

The best resource for Perl is The Perl programming documentation project.