Literate programming, org mode, function declaration - org-mode

I want to write a Literate Program with org-mode. Let's say I have the following function:
fn do_stuff()
{
// 200 lines of code go here.
}
I would write something like that in org-mode:
#+BEGIN_SRC rust :tangle /some/path
fn do_stuff()
{
#+END_SRC
// Many more blocks of `BEGIN_SRC` go here to exlpain 200 lines of code mentioned above.
// They will have formatting, and prose between them, and headings with different nesting levels.
// The whole shebang in short.
#+BEGIN_SRC rust :tangle /some/path
}
#+END_SRC
Now, here is the question. I hope I will explain it well, it's kinda hard to put in words.
What do I do with the first and last #+BEGIN_SRC blocks shown above?
How do I style the function declaration with org-mode and/or Literate Programming?
It seems kind of out of place with all the “formatting, prose, headings” of the 200 lines of code mentioned above.
I need ideas please :-)
Thanks in advance.

I would use noweb to tangle the full code without necessarily presenting it all in order. That is, I would do something like this:
The core code is
#+name: code1
#+begin_src rust :noweb yes :tangle no
...
#+end_src
More code etc. and then, at the end:
#+BEGIN_SRC rust :tangle /some/path
fn do_stuff()
{
<<code1>>
}
#+END_SRC
You may need :noweb yes on the full code block as well.

Related

What can cause org-auto-tangle to result nil for all noweb code block evaluations

I'm using literate programming for some configuration files and would like to have some parts from elisp code block evaluations. I tried evaluating named code blocks with :noweb tangle but they always results nil and I do not see any errors in the *Messages*. Here's a simplified hello world example and the results I got.
Org file
#+title: Hello
#+PROPERTY: header-args :tangle hello.txt :cache no :exports none
#+auto_tangle: t
#+name: hello-world-output
#+begin_src emacs-lisp :tangle no :eval no-export :results output
(print "Hello world")
#+end_src
#+name: hello-world-value
#+begin_src emacs-lisp :tangle no :eval no-export :results value
"Hello world"
#+end_src
#+begin_src text :noweb tangle
<<hello-world-output>> -> <<hello-world-output()>>
<<hello-world-value>> -> <<hello-world-value()>>
#+end_src
Tangled results
(print "Hello world") -> nil
"Hello world" -> nil
I also checked that org-link-elisp-confirm-function and org-confirm-babel-evaluate both have nil value, so they should not be preventing evaluation.
EDIT: I forgot to mention that I used org-auto-tangle. Issue doesn't occur when calling org-bable-tangle directly.
I had the same issue and below solved it for me.
According to the code of org-auto-tangle the code will not be evaluated by default. In order to have the code auto evaluated you need to add your org file to the org-auto-tangle-babel-safelist. I've posted the definition of the variable and a link to the README with an example of how to set the variable.
(defvar org-auto-tangle-babel-safelist '()
"List of full path of files for which code blocks need to be evaluated.
By default, code blocks are not evaluated during the auto-tangle to avoid
possible code execution from unstrusted source. To enable code blocks evaluation
for a specific file, add its full path to this list.")
https://github.com/yilkalargaw/org-auto-tangle#babel-auto-tangle-safelist

Org-mode: overwriting globals #+PROPERTIES: in block headers?

It is often the case that I want to have :results silent for all the code blocks in an Org-mode document. Do simplify my block headers, I define this in my Org-mode document:
#+PROPERTY: header-args :results silent
That works properly: all the codeblocks uses the :results silent option in the blocks' header.
However, if I specify :results output in one of the code block, it will still be silent. I would have expected that it would overwrite the global setting, but it doesn't seem so.
Am I right by saying that or is there something I am missing to get this behavior?
Here is an example of what I would like to do:
#+PROPERTY: header-args :results silent
...
#+BEGIN_SRC clojure
;; this one is silent
(def foo "bar)
#+END_SRC
...
#+BEGIN_SRC clojure :results output
;; this one is being outputted
(def foo "bar)
#+END_SRC
This seems to be a bug, present even in the most up-to-date version of org-mode. I've reported it on the org-mode mailing list.
EDIT: Charles Berry pointed out on the ML that this is not a bug. The opposite of "silent" is "replace", so the second source block should read:
#+BEGIN_SRC elisp :results output replace
;; this one is being outputted
(princ "foo")
#+END_SRC
See http://thread.gmane.org/gmane.emacs.orgmode/108001/focus=108008
and the :results section in the manual http://orgmode.org/org.html#results
Note that you get to pick one value for every section (collection, type, format, handling) - if you don't pick a value for a section, a default value is picked. In the above, there was no explicit value for "handling", so the default value from the property still controlled.

org-mode macros inside code blocks and using babel

Inspired by this great post, I'm trying to use the combination of org-mode and babel for issuing queries to elasticsearch. For example, counting the number of entries in an index:
#+BEGIN_SRC sh
curl -XGET 'http://my.uri.example:8080/index/_count'
#+END_SRC
The above code can be evaluated using C-c C-c when the point is in the block.1
On the other hand, one can define macros in the org document. My question is: is it possible to define a macro
#+MACRO: live-db http://my.uri.example:8080
and rewrite the code block as follow:
#+BEGIN_SRC sh
curl -XGET '{{{live-db}}}/index/_count'
#+END_SRC
Out of the box, for me, it didn't work... It seems like babel is not expanding the macro before the evaluation of the block. Ideas?
Edit
Now, once I learned that I can use es-mode, I won't to fine tune my question. Consider the following two requests:
#+BEGIN_SRC es :url http://mu.uri.stage:8080
GET /users/_search?pretty
{
"query": {
"match_all":{}
}
}
#+END_SRC
and
#+BEGIN_SRC es :url http://mu.uri.live:8080
GET /users/_search?pretty
{
"query": {
"match_all":{}
}
}
#+END_SRC
They merely differ in the URL. I would like to define two macros:
#+MACRO staging http://my.uri.stage:8080
#+MACRO live http://my.uri.live:8080
and then use the macros as the variables of the blocks. Is it possible?
1 Make sure you enable the evaluation of sh. Add something like:
(org-babel-do-load-languages
'org-babel-load-languages
'((sh . t)))
to your .emacs.
macro expansion is not natively supported when executing code blocks, but the Noweb reference syntax which is supported is much more powerful.
However, I doubt that it will work using es-mode, since it passes the url in a header argument and not a variable.
This is a simple example for a sh code block:
#+name: staging
: http://my.uri.stage:8080
#+name: live
: http://my.uri.live:8080
#+name: test
#+begin_src sh :var url=staging
echo $url
#+end_src
#+call: test(live)
#+RESULTS:
: http://my.uri.live:8080
#+call: test(staging)
#+RESULTS:
: http://my.uri.stage:8080

Any way to make org-babel properly indent noweb tangled code?

Tangling this:
#+BEGIN_SRC C :tangle no :noweb-ref begin
int main() {
printf("Line 1\n");
#+END_SRC
#+BEGIN_SRC C :tangle no :noweb-ref middle
printf("Second\n");
#+END_SRC
#+BEGIN_SRC C :tangle no :noweb-ref end
}
#+END_SRC
#+BEGIN_SRC C :tangle ~/test.c :noweb no-export
<<begin>>
<<middle>>
<<end>>
#+END_SRC
Yields this:
int main() {
printf("Line 1\n");
printf("Second\n");
}
I have org-src-preserve-indentation turned on, but it can't preserve what isn't there. The code editing windows can't set it correctly if it doesn't see the parts from the previous source code blocks. Finally, I don't want to have to go through all the previous snippets to figure out what the indentation should start at every time I start a new source code block.
Current hack is to tangle the source code, open the tangled file in a new buffer, select all and run c-indent-line-or-region, but I'm hoping there's something better than that.
Org-mode version: 8.2.5h
As mentioned, hooking into the org-babel-post-tangle-hook is the way to go. I use the following:
(defun tnez/src-cleanup ()
(indent-region (point-min) (point-max)))
(add-hook 'org-babel-post-tangle-hook 'tnez/src-cleanup)

Literate Programming using org-babel

I am on a literate program using org-babel. My source is structured like so,
-imports
-utility fns
-game structure
- detailed explanations
This is the normal structure of the code, what I would like to do is move explanations of the utility fns to the end so it does not show up first in the generated pdf file. Now this can be done with noweb extension, but the problem is when you have lots of little functions for each one I have to add a src_block with a unique name scroll down the file and add a reference to that in the file which is really annoying. Is there a way to name all the src_blocks in a section? say all code in this section goes into block A.
You can give multiple chunks the same name. For example, I generate my .emacs file with org-tangle, and at the top of the org file, I have a master template that looks something like this:
#+begin_src emacs-lisp :tangle "/path/to/.emacs" :comments both :noweb tangle
<<generated-file-warning>
<<includes>>
<<definitions>>
<<settings>>
<<generated-file-warning>
#+end_src
Underneath that, I have my outline with source blocks like so:
* extensions
** yasnippet
#+name: early-includes
#+begin_src emacs-lisp
(require 'yasnippet)
(yas/initialize)
#+end_src
#+name: settings
#+begin_src emacs-lisp
(yas/load/directory "/path/to/my/snippets")
#+end_src
Note: for older versions of org-mode, you may need to use #+srcname: instead of #+name:
You can also create a property called noweb-ref, which applies the same name to all source blocks in a sub-tree.