Re: Proposed New Syntax For Calling Code Blocks was

From: Jambunathan K <kjambunathan@gmail.com>
To: Eric Schulte <schulte.eric@gmail.com>
Cc: Org Mode <emacs-orgmode@gnu.org>
Subject: Re: Proposed New Syntax For Calling Code Blocks was
Date: Sat, 11 Sep 2010 01:28:14 +0530	[thread overview]
Message-ID: <817hits755.fsf_-_@gmail.com> (raw)
In-Reply-To: <87vd6deafb.fsf@gmail.com> (Eric Schulte's message of "Fri, 10 Sep 2010 12:06:47 -0600")

Eric

In line with my earlier posts, I would like to think of Babel codeblocks
filters that take as a textual content and produce another textual
content. Think of babel codeblocks as indeed custom exporters.

Power of Babel is the flexibility that the user gets in associating
different code blocks with the same content and have different
representations produced for the same.

Let's revisit the original example. Let me walk through the whole
sequence ...

# Input Textual Content

# User need not say that the content is table. It is obvious. In other
# words babel is dynamically typed and tables are one of the primitive
# datatypes within Babel runtime environment. Name of the table is the
# name of the headline.

* tableTestBabel
  |   0 | 4.40 |
  |  30 | 4.54 |
  |  60 | 7.09 |
  |  90 | 9.40 |
  | 120 | 9.22 |
  | 150 | 6.65 |
  | 180 | 4.22 |

# Output Textual Content 
testBabel.pdf

# Babel block named 'charPolAngle' is the custom exporter which would
# act on the input text and produce an output text. 

# Note that the signature of the chartPolAngle and the use of a reserved
# babel keyword 'this' which stand for the input textual content.

#+srcname: chartPolAngle()
#+begin_src R
  angle <- this[,1]
  energy <- this[,2]
  plot(angle,energy)
  energy.model <-  nls (energy ~ a1 + a2 * (sin(pi / a3 *(angle-a4)))^2,
start=list(a1=3.0, a2=7.0, a3=180, a4=0.0))
  lines(spline(angle, fitted.values(energy.model)), lwd=2)
  summary(energy.model)
#+end_src

# To make a call, the user executes the headline and passes it the
# custom routine.

# Transform text
<<tableTestBabel (:fmt chartPolAngle)>>
  ^^^^^^^^^^^^^

With this shift in call syntax one could do these with obvious
interpretation.

<<tabletestBabel>> # identity mapping 
<<tabletestBabel (:fmt csv)>> # map to csv 
<<tabletestBabel (:fmt latex)>> # map to latex

To summarize Babel srcnames takes the following params as a must (they
could be implicit)

1. A 'this' parameterw which is input text content. An headline entry in
   the above example.

A babel invocation line takes a ':fmt ' param. It could be one of the
inbuilt exporters like text, org, latex, pdf etc or left unspecified if
the babel srcblock always produces only one format.

It would also be usefult to specify how the transformed text is handled
by a babel srcblock. Let's denote this param as :results

If :results is nil then the exporter creates a side-effect. i.e., it
produces a pdf file. 

If :results is inline then output text content is inserted inline i.e.,
wherever the macro invocation occurs.

If :results is a Org Headline then output text content is inserted in
that headline.

To summarize, Babel macros acts on text blocks and produces text
blocks. 

A babel macro with names outfmt is invoked as 
<<org headline (:fmt outfmt :results X)>>

or as 

[[outfmt][input text content]]

Let me know if you have questions.

My lack of understanding of Babel's internals prevents me from being
more specific or anticipate the issues involved. 

Nevertheless a shift in perspective from

babel-src(intxt)

to 

intxt(babel-src) is what is required.

I invite you to go through my earlier mails[1]. Each one of them takes
examples that have already surfaced in the mailing list and tries to
reconcile what the user likes to accomplish with Babel macros with what
the Org's existing world view is.

Let me know whether or not I make sense.

ps: I haven't really tried to address issues reported by the original
poster. I need to have a buyin from you on what I am proposing before I
am willing to put that effort.

[1] http://article.gmane.org/gmane.emacs.orgmode/30040

Jambunathan K.

>
> #+call: chartPolAngle[:session testBabel :file testBabel.pdf](pol=tableTestBabel)
>

> I'd be interested to hear what the community thinks of this new syntax.
>
> As an unrelated note, we also need to think of a natural way to allow
> the header argument portion of a code block to span multiple lines.
>
> Best -- Eric
>
> Christopher Witte <chris@witte.net.au> writes:
>
>> I'm having a bit of trouble with org bable and R. When I try to execute the
>> code below (C-c C-c on the call line), as you can see, I get the results
>> :nil
>>
>> ---------------------------------------
>> #+tblname: tableTestBabel
>> |   0 | 4.40 |
>> |  30 | 4.54 |
>> |  60 | 7.09 |
>> |  90 | 9.40 |
>> | 120 | 9.22 |
>> | 150 | 6.65 |
>> | 180 | 4.22 |
>>
>> #+srcname: chartPolAngle(pol)
>> #+begin_src R
>>   angle <- pol[,1]
>>   energy <- pol[,2]
>>   plot(angle,energy)
>>   energy.model <-  nls (energy ~ a1 + a2 * (sin(pi / a3 *(angle-a4)))^2,
>> start=list(a1=3.0, a2=7.0, a3=180, a4=0.0))
>>   lines(spline(angle, fitted.values(energy.model)), lwd=2)
>>   summary(energy.model)
>> #+end_src
>>
>> #+call: chartPolAngle(pol=tableTestBabel) :session testBabel :file testBabel.pdf
>>
>> #+results: chartPolAngle(pol=tableTestBabel)
>> : nil
>> ------------------------------------
>>
>> but If I move the header arguments to the source block, as in the code
>> below, everything works fine. I also get asked "ESS [S(R): R] starting data
>> directory? ~/doc/org/" which I don't get with the code above.
>>
>> ---------------------------------------
>> #+tblname: tableTestBabel
>> |   0 | 4.40 |
>> |  30 | 4.54 |
>> |  60 | 7.09 |
>> |  90 | 9.40 |
>> | 120 | 9.22 |
>> | 150 | 6.65 |
>> | 180 | 4.22 |
>>
>> #+call: chartPolAngle(pol=tableTestBabel)
>>
>> #+results: chartPolAngle(pol=tableTestBabel)
>> : testBabel.pdf
>>
>>
>> #+srcname: chartPolAngle(pol)
>> #+begin_src R :session testBabel :file testBabel.pdf
>>   angle <- pol[,1]
>>   energy <- pol[,2]
>>   plot(angle,energy)
>>   energy.model <-  nls (energy ~ a1 + a2 * (sin(pi / a3 *(angle-a4)))^2,
>> start=list(a1=3.0, a2=7.0, a3=180, a4=0.0))
>>   lines(spline(angle, fitted.values(energy.model)), lwd=2)
>>   summary(energy.model)
>> #+end_src
>> ---------------------------------------
>>
>> Org doesn't appear to respect the head arguments on the call. I pulled from
>> git a couple days ago. Any ideas why?
>>
>> Cheers
>> Chris Witte
>> _______________________________________________
>> Emacs-orgmode mailing list
>> Please use `Reply All' to send replies to the list.
>> Emacs-orgmode@gnu.org
>> http://lists.gnu.org/mailman/listinfo/emacs-orgmode
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode