patch to worg: documenting perl support in babel blocks

patch to worg: documenting perl support in babel blocks

[dmg]

[-- Attachment #1: Type: text/plain, Size: 208 bytes --]

hi everybody,

I have a patch to contribute to the website. I have an account in the
git repo, but I cannot push.


I am attaching the patch.

thank you,



-- 
--dmg

---
D M German
http://turingmachine.org

[-- Attachment #2: 0001-First-crack-at-documenting-perl-in-Babel-blocks.patch --]
[-- Type: text/x-patch, Size: 7354 bytes --]

From f265fe36a1633dc9b43c98a93eabcb31607939e5 Mon Sep 17 00:00:00 2001
From: D German <dmg@uvic.ca>
Date: Wed, 27 Jun 2018 18:13:53 -0700
Subject: [PATCH] First crack at documenting perl in Babel blocks

* org-contrib/babel/languages/ob-doc-perl.org: Document perl in Babel

Created the file and documented how to use perl in Babel blocks,
Including how to pass parameters to the block and how to return
values (including tables).
---
 org-contrib/babel/languages/ob-doc-perl.org | 261 ++++++++++++++++++++
 1 file changed, 261 insertions(+)
 create mode 100644 org-contrib/babel/languages/ob-doc-perl.org

diff --git a/org-contrib/babel/languages/ob-doc-perl.org b/org-contrib/babel/languages/ob-doc-perl.org
new file mode 100644
index 00000000..52524c43
--- /dev/null
+++ b/org-contrib/babel/languages/ob-doc-perl.org
@@ -0,0 +1,261 @@
+#+OPTIONS:    H:3 num:nil toc:2 \n:nil ::t |:t ^:{} -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc
+#+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
+#+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
+#+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
+#+TITLE:      Perl in Org Mode
+#+AUTHOR:     Daniel M. German
+#+EMAIL:      dmg[at]uvic[dot]ca
+#+LANGUAGE:   en
+#+HTML_HEAD:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
+#+LINK_UP:    ../languages.html
+#+LINK_HOME:  https://orgmode.org/worg/
+#+EXCLUDE_TAGS: noexport
+
+#+name: banner
+#+begin_export html
+  <div id="subtitle" style="float: center; text-align: center;">
+  <p>
+  Org Mode support for <a href="http://www.perl.org/">Perl</a>
+  </p>
+  <p>
+  <a href="http://www.perl.org/">
+  <img src="./images/perl5raptor.png"/>
+  </a>
+  </p>
+  </div>
+#+end_export
+
+* Template Checklist [11/12]                                       :noexport:
+  - [X] Revise #+TITLE:
+  - [X] Indicate #+AUTHOR:
+  - [X] Add #+EMAIL:
+  - [X] Revise banner source block [3/3]
+    - [X] Add link to a useful language web site
+    - [X] Replace "Language" with language name
+    - [X] Find a suitable graphic and use it to link to the language
+      web site
+  - [X] Write an [[Introduction]]
+  - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
+  - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
+  - [X] Describe [[Header%20Arguments][Header Arguments]]
+  - [X] Describe support for [[Sessions]]
+  - [X] Describe [[Result%20Types][Result Types]]
+  - [ ] Describe [[Other]] differences from supported languages
+  - [X] Provide brief [[Examples%20of%20Use][Examples of Use]]
+* Introduction
+
+This document is a short introduction to using perl within org-mode. 
+
+
+* Requirements and Setup
+
+The only requirement is installed in the computer where org babel is executing the scripts.
+
+
+#+begin_src emacs-lisp :exports code
+  (org-babel-do-load-languages
+   'org-babel-load-languages
+   '((lisp . t)))
+#+end_src
+
+* Org Mode Features for Perl Code Blocks
+** Header Arguments
+
+The support of perl in Babel is basic. There 
+There are no language-specific arguments for perl code blocks.
+
+** Result Types
+
+The only supported type is ~value~
+
+** Support for sessions
+
+There is no support for sessions.
+
+** var
+
+It is possible ot pass several variables to perl, including table variables. See below.
+
+* Examples of Use
+
+These are two simple examples:
+
+#+BEGIN_EXAMPLE
+#+BEGIN_SRC perl :results value
+"hello world";
+#+END_SRC
+
+#+RESULTS:
+: hello world
+#+END_EXAMPLE
+
+#+begin_src perl 
+10 * 20 + 5;
+#+end_src
+
+#+RESULTS:
+: 205
+#+end_example
+
+#+RESULTS: countingTo10
+
+* Other types of output
+
+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_EXAMPLE
+#+BEGIN_SRC perl :results value
+[[1,2],[2,4]]
+#+END_SRC
+
+#+RESULTS:
+| 1 | 2 |
+| 2 | 4 |
+#+END_EXAMPLE
+
+#+BEGIN_SRC perl :results value
+10 + 20
+#+END_SRC
+
+#+RESULTS:
+#+begin_example
+30
+#+end_example
+
+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_EXAMPLE
+#+BEGIN_SRC perl :results value
+my @result ;
+$i = 0;
+for $j ('a'..'e')  {
+   $result[$i] = $j;
+   $i ++;
+}
+@result;
+#+END_SRC
+
+#+RESULTS:
+: 5
+#+END_EXAMPLE
+But this returns the values of the array and creates the corresponding table
+
+#+BEGIN_EXAMPLE
+#+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 |
+#+END_EXAMPLE
+
+#+BEGIN_EXAMPLE
+#+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 |
+#+END_EXAMPLE
+
+* Using tables as input
+
+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:
+
+#+BEGIN_EXAMPLE
+#+NAME:exampletable
+| 1 | a |
+| 2 | b |
+| 3 | c |
+| 4 | d |
+#+END_EXAMPLE
+
+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.
+
+#+BEGIN_EXAMPLE
+#+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 |
+#+END_EXAMPLE
+
+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.
+
+#+BEGIN_EXAMPLE
+#+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 |
+#+END_EXAMPLE
+
+
+
+* Links to Tutorials and Other Resources
+
+The best resource for perl is [[https://perldoc.perl.org][The Perl programming documentation]] project.
+
-- 
2.17.1

Re: patch to worg: documenting perl support in babel blocks

[Nicolas Goaziou]

Hello,

dmg <dmg@turingmachine.org> writes:

> I have a patch to contribute to the website. I have an account in the
> git repo, but I cannot push.
>
>
> I am attaching the patch.

I applied it, with minor tweaks, mainly related to case (org -> Org,
perl -> Perl) and whitespace issues.

Thank you.

Regards,

-- 
Nicolas Goaziou