Org mode & "literate programming": including files

Org mode & "literate programming": including files

[Bob Heffernan]

Dear all,

I am new to Emacs (as a long-time vim user) so apologies if this
question has an easy answer, but I've done a bit of searching before
asking.

I am looking at using org-mode for (a fairly simplistic version of)
literate programming.  The programming language I'm using is Scheme,
although this probably doesn't matter.  I've set things up so that
code blocks share a session:

#+PROPERTY: header-args :session *scheme*

and I can then have several code blocks that work nicely together
(these would usually be sprinkled throughout the document, of course,
with text in between):

#+begin_src scheme :results silent                                                                                                                                      (define (f n) (+ n 1))                                                                                                                                              #+end_src
#+begin_src scheme
  (f 1)
#+end_src

If I run the code in each block in turn with C-c C-c, which I guess
calls org-babel-execute-src-block, I get

#+RESULTS:
: 2

So far so good and this is perfect for simple programs.

However, once things get more complicated I will want to include
another such org file, as a library as it were. For example, I'd like
to be able to write a second org file that includes the stuff above
and now knows what the definition of the procedure f is. I know that
there is #+INCLUDE but I guess what I really need is to include a file
and, at the same time, execute all src blocks in that file so that
they are present in the same session as that of my current file.

To give an example, let's say I'm working on writing solutions to
Project Euler problems.  After a while, I'll want a little library of
procedures relating to prime numbers (since these come up a lot) which
I can include as needed.  It would be nice for this to also be written
up nicely in org mode.

I asked this question on the emacs subreddit and the library of babel
was mentioned.  This would work, I guess, but isn't quite what I'm
looking for.  Somebody else mentioned "transclusion" which seems
perhaps more powerful than what I'm looking for.  It seems like this
should be a common problem to solve, but Google hasn't found anything
for me.

Thank you & best regards,
Bob Heffernan

Re: Org mode & "literate programming": including files

[Nikolay Kudryavtsev]

Hello Bob.

In org mode you can extract your source code from the org file into a 
proper language specific file. The general idea is that you write your 
library in org, then you tangle it into a proper scheme file and then 
just import that. See this part of the manual for more info (info "(org) 
Extracting Source Code") 
<https://orgmode.org/manual/Extracting-Source-Code.html#Extracting-Source-Code>.

Also, while you can expect people on this list to have a reasonable 
amount of org knowledge, the best place to ask org questions is actually 
emacs-orgmode@gnu.org mailing list.

Re: Org mode & "literate programming": including files

[Bob Heffernan]

On 21-04-06 23:18, Nikolay Kudryavtsev wrote:
> In org mode you can extract your source code from the org file into a proper
> language specific file. The general idea is that you write your library in
> org, then you tangle it into a proper scheme file and then just import that.
> See this part of the manual for more info (info "(org) Extracting Source
> Code") <https://orgmode.org/manual/Extracting-Source-Code.html#Extracting-Source-Code>.

Nikolay,

Thank you for your help.  Something like the following isn't
particularly elegant, but it works.  Perhaps as I learn more I'll be
able to clean it up.

#+name: lib
#+begin_src emacs-lisp :results silent
(car (org-babel-tangle-file "/home/bob/projects/literate/foo.org"))
#+end_src
#+begin_src scheme :var input=lib :results silent
(load input)
#+end_src
#+begin_src scheme
(f 1)
#+end_src

#+RESULTS[7f10...]:

: 2

> Also, while you can expect people on this list to have a reasonable amount
> of org knowledge, the best place to ask org questions is actually
> emacs-orgmode@gnu.org mailing list.

I'll bear this in mind.  Thanks.

Regards,
Bob

Re: Org mode & "literate programming": including files

[Arthur Miller]

Bob Heffernan <bob.heffernan@gmail.com> writes:

> Dear all,
>
> I am new to Emacs (as a long-time vim user) so apologies if this
> question has an easy answer, but I've done a bit of searching before
> asking.
>
> I am looking at using org-mode for (a fairly simplistic version of)
> literate programming.  The programming language I'm using is Scheme,
> although this probably doesn't matter.  I've set things up so that
> code blocks share a session:
>
> #+PROPERTY: header-args :session *scheme*
>
> and I can then have several code blocks that work nicely together
> (these would usually be sprinkled throughout the document, of course,
> with text in between):
>
> #+begin_src scheme :results silent                                                                                                                                      (define (f n) (+ n 1))                                                                                                                                              #+end_src
> #+begin_src scheme
>   (f 1)
> #+end_src
>
> If I run the code in each block in turn with C-c C-c, which I guess
> calls org-babel-execute-src-block, I get
>
> #+RESULTS:
> : 2
>
> So far so good and this is perfect for simple programs.
>
> However, once things get more complicated I will want to include
> another such org file, as a library as it were. For example, I'd like
> to be able to write a second org file that includes the stuff above
> and now knows what the definition of the procedure f is. I know that
> there is #+INCLUDE but I guess what I really need is to include a file
> and, at the same time, execute all src blocks in that file so that
> they are present in the same session as that of my current file.
>
> To give an example, let's say I'm working on writing solutions to
> Project Euler problems.  After a while, I'll want a little library of
> procedures relating to prime numbers (since these come up a lot) which
> I can include as needed.  It would be nice for this to also be written
> up nicely in org mode.
>
> I asked this question on the emacs subreddit and the library of babel
> was mentioned.  This would work, I guess, but isn't quite what I'm
> looking for.  Somebody else mentioned "transclusion" which seems
> perhaps more powerful than what I'm looking for.  It seems like this
> should be a common problem to solve, but Google hasn't found anything
> for me.

I saw your question on reddit, and I saw somebody already posted you an
answer. You are looking for `org-babel-lob-ingest`.

Check the SX link posted to you on Reddit, it has what you are asking for:

https://emacs.stackexchange.com/questions/31999/config-examples-and-use-cases-of-library-of-babel

Hope it works for you and don't forgett to say thanks to the guy on Reddit.

Re: Org mode & "literate programming": including files

[Bob Heffernan]

On 21-04-07 05:54, Arthur Miller wrote:
> I saw your question on reddit, and I saw somebody already posted you an
> answer. You are looking for `org-babel-lob-ingest`.
>
> Check the SX link posted to you on Reddit, it has what you are asking for:
>
> https://emacs.stackexchange.com/questions/31999/config-examples-and-use-cases-of-library-of-babel

Arthur,

From what I understand, the library of babel is a feature to glob
regularly used (named) code blocks into a single file, for use in
other org files.  While this looks as if it could be used to achieve
what I want (first, ingest some code into the library, then use it
elsewhere) I was hoping for something similar to the sort of thing
that is present in most programming language REPLs: load whatever
source file you want, then use the procedures therein.

> Hope it works for you and don't forgett to say thanks to the guy on Reddit.

I'll take a closer look at it and thanks for your help.
(& you're right, I need to go back to reddit and respond!)

Regards,
Bob

Re: Org mode & "literate programming": including files

[Arthur Miller]

Bob Heffernan <bob.heffernan@gmail.com> writes:

> On 21-04-07 05:54, Arthur Miller wrote:
>> I saw your question on reddit, and I saw somebody already posted you an
>> answer. You are looking for `org-babel-lob-ingest`.
>>
>> Check the SX link posted to you on Reddit, it has what you are asking for:
>>
>> https://emacs.stackexchange.com/questions/31999/config-examples-and-use-cases-of-library-of-babel
>
> Arthur,
>
> From what I understand, the library of babel is a feature to glob
> regularly used (named) code blocks into a single file, for use in
> other org files.  While this looks as if it could be used to achieve
> what I want (first, ingest some code into the library, then use it
> elsewhere) I was hoping for something similar to the sort of thing
> that is present in most programming language REPLs: load whatever
> source file you want, then use the procedures therein.

I found the org-babel to be much better option since it will save you
exporting (tangle) and evaluate org files everytime you load them. It is
more efficient. It also let's you use named blocks, so you potentially
don't need to load everything, just what you need.

If you really wish to do this in style oc #include <someheader.h>,
look at the org-babel-load-file. It will do what you ask, but it is
slow. It will export your .org file (tangle it) to .el and then load the
produced lisp file. As a note, you can look up any elisp function in
Emacs with C-h f RET function-name. Now imagine doing that for many
files. The applications will load quite slow if they include many files
and load them that way.

Somebody above already posted you an answer that you
are rather supposed to export your org files to el, and import those el
files. So it is probably better to either export your code to .el files
and byte/native compile them and use orinary `require' or `load' or use
`library-of-babel'.

I am not an expert, but that is how I understand it to be in Emacs. I am
sure if I am wrong someone here will correct me :-).

>> Hope it works for you and don't forgett to say thanks to the guy on Reddit.
>
> I'll take a closer look at it and thanks for your help.
> (& you're right, I need to go back to reddit and respond!)

> Regards,
> Bob

Best regards
/a