Next:Results of Evaluation, Previous:Environment of a Code Block, Up:Working with Source Code [Contents][Index]
A note about security: With code evaluation comes the risk of harm.Org safeguards by prompting for user’s permission before executing anycode in the source block. To customize this safeguard, or disable it,seeCode Evaluation and Security Issues.
Org captures the results of the code block evaluation and inserts themin the Org file, right after the code block. The insertion point isafter a newline and the ‘RESULTS’ keyword. Org creates the ‘RESULTS’keyword if one is not already there. More details inResults of Evaluation.
By default, Org enables only Emacs Lisp code blocks for execution.SeeLanguages to enable other languages.
Org provides many ways to execute code blocks.C-c C-c orC-c C-v e with the point on a code block151 calls theorg-babel-execute-src-block function, which executes the code in theblock, collects the results, and inserts them in the buffer.
By calling a named code block152 from an Org mode buffer ora table. Org can call the named code blocks from the current Org modebuffer or from the “Library of Babel” (seeLibrary of Babel).
The syntax for ‘CALL’ keyword is:
#+CALL: <name>(<arguments>)#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
The syntax for inline named code blocks is:
... call_<name>(<arguments>) ...... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
When inline syntax is used, the result is wrapped based on thevariableorg-babel-inline-result-wrap, which by default is set to"=%s=" to produce verbatim text suitable for markup.
This is the name of the code block (seeStructure of Code Blocks)to be evaluated in the current document. If the block is located inanother file, start ‘<name>’ with the file name followed bya colon. For example, in order to execute a block named ‘clear-data’in ‘file.org’, you can write the following:
#+CALL: file.org:clear-data()
Org passes arguments to the code block using standard function callsyntax. For example, a ‘#+CALL:’ line that passes ‘4’ to a codeblock named ‘double’, which declares the header argument ‘:var n=2’,would be written as:
#+CALL: double(n=4)
Note how this function call syntax is different from the headerargument syntax.
Org passes inside header arguments to the named code block using theheader argument syntax. Inside header arguments apply to code blockevaluation. For example, ‘[:results output]’ collects resultsprinted to stdout during code execution of that block. Note howthis header argument syntax is different from the function callsyntax.
End header arguments affect the results returned by the code block.For example, ‘:results html’ wraps the results in a ‘#+BEGIN_EXPORT html’ block before inserting the results in the Org buffer.
The ‘eval’ header argument can limit evaluation of specific codeblocks and ‘CALL’ keyword. It is useful for protection againstevaluating untrusted code blocks by prompting for a confirmation.
Org evaluates the source code, possibly asking permission accordingtoorg-confirm-babel-evaluate.
Org never evaluates the source code.
Org prompts the user for permission to evaluate the source code.
Org does not evaluate the source code when exporting, yet the usercan evaluate it interactively.
Org prompts the user for permission to evaluate the source codeduring export.
If ‘eval’ header argument is not set, then Org determines whether toevaluate the source code from theorg-confirm-babel-evaluatevariable (seeCode Evaluation and Security Issues).
The ‘cache’ header argument is for caching results of evaluating codeblocks. Caching results can avoid re-evaluating a code block thathave not changed since the previous run. To benefit from the cacheand avoid redundant evaluations, the source block must have a resultalready present in the buffer, and neither the headerarguments—including the value of ‘var’ references—nor the text ofthe block itself has changed since the result was last computed. Thisfeature greatly helps avoid long-running calculations. For some edgecases, however, the cached results may not be reliable.
The caching feature is best for when code blocks are pure functions,that is functions that return the same value for the same inputarguments (seeEnvironment of a Code Block), and that do not haveside effects, and do not rely on external variables other than theinput arguments. Functions that depend on a timer, file systemobjects, and random number generators are clearly unsuitable forcaching.
A note of warning: when ‘cache’ is used in a session, caching maycause unexpected results.
When the caching mechanism tests for any source code changes, it doesnot expand noweb style references (seeNoweb Reference Syntax).
The ‘cache’ header argument can have one of two values: ‘yes’ or ‘no’.
Default. No caching of results; code block evaluated every time.
Whether to run the code or return the cached results is determinedby comparing the SHA1 hash value of the combined code block andarguments passed to it. This hash value is packed on the‘#+RESULTS:’ line from previous evaluation. When hash values match,Org does not evaluate the code block. When hash values mismatch,Org evaluates the code block, inserts the results, recalculates thehash value, and updates ‘#+RESULTS:’ line.
In this example, both functions are cached. But ‘caller’ runs only ifthe result from ‘random’ has changed since the last run.
#+NAME: random#+BEGIN_SRC R :cache yes runif(+1)#+END_SRC#+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random0.4659510825295#+NAME: caller#+BEGIN_SRC emacs-lisp :var x=random :cache yes x#+END_SRC#+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller0.254227238707244
The optionorg-babel-no-eval-on-ctrl-c-ctrl-c can be used to remove codeevaluation from theC-c C-c key binding.
Actually, the constructs ‘call_<name>()’ and ‘src_<lang>{}’are not evaluated when they appear in a keyword (seeSummary of In-Buffer Settings).
Next:Results of Evaluation, Previous:Environment of a Code Block, Up:Working with Source Code [Contents][Index]