Fix URL for file in the Git repository of org-mode
[worg.git] / org-contrib / babel / ob-template.el
1 ;;; ob-template.el --- org-babel functions for template evaluation
2
3 ;; Copyright (C) your name here
4
5 ;; Author: your name here
6 ;; Keywords: literate programming, reproducible research
7 ;; Homepage: http://orgmode.org
8 ;; Version: 0.01
9
10 ;;; License:
11
12 ;; This program is free software; you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation; either version 3, or (at your option)
15 ;; any later version.
16 ;;
17 ;; This program is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20 ;; GNU General Public License for more details.
21 ;;
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
24 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
25 ;; Boston, MA 02110-1301, USA.
26
27 ;;; Commentary:
28
29 ;; This file is not intended to ever be loaded by org-babel, rather it
30 ;; is a template for use in adding new language support to Org-babel.
31 ;; Good first steps are to copy this file to a file named by the
32 ;; language you are adding, and then use `query-replace' to replace
33 ;; all strings of "template" in this file with the name of your new
34 ;; language.
35 ;;
36 ;; If you have questions as to any of the portions of the file defined
37 ;; below please look to existing language support for guidance.
38 ;;
39 ;; If you are planning on adding a language to org-babel we would ask
40 ;; that if possible you fill out the FSF copyright assignment form
41 ;; available at http://orgmode.org/request-assign-future.txt as this
42 ;; will make it possible to include your language support in the core
43 ;; of Org-mode, otherwise unassigned language support files can still
44 ;; be included in the contrib/ directory of the Org-mode repository.
45
46 ;;; Requirements:
47
48 ;; Use this section to list the requirements of this language.  Most
49 ;; languages will require that at least the language be installed on
50 ;; the user's system, and the Emacs major mode relevant to the
51 ;; language be installed as well.
52
53 ;;; Code:
54 (require 'ob)
55 (require 'ob-ref)
56 (require 'ob-comint)
57 (require 'ob-eval)
58 ;; possibly require modes required for your language
59
60 ;; optionally define a file extension for this language
61 (add-to-list 'org-babel-tangle-lang-exts '("template" . "tmp"))
62
63 ;; optionally declare default header arguments for this language
64 (defvar org-babel-default-header-args:template '())
65
66 ;; This function expands the body of a source code block by doing
67 ;; things like prepending argument definitions to the body, it should
68 ;; be called by the `org-babel-execute:template' function below.
69 (defun org-babel-expand-body:template (body params &optional processed-params)
70   "Expand BODY according to PARAMS, return the expanded body."
71   (require 'inf-template)
72   (let ((vars (nth 1 (or processed-params (org-babel-process-params params)))))
73     (concat
74      (mapconcat ;; define any variables
75       (lambda (pair)
76         (format "%s=%S"
77                 (car pair) (org-babel-template-var-to-template (cdr pair))))
78       vars "\n") "\n" body "\n")))
79
80 ;; This is the main function which is called to evaluate a code
81 ;; block.
82 ;;
83 ;; This function will evaluate the body of the source code and
84 ;; return the results as emacs-lisp depending on the value of the
85 ;; :results header argument
86 ;; - output means that the output to STDOUT will be captured and
87 ;;   returned
88 ;; - value means that the value of the last statement in the
89 ;;   source code block will be returned
90 ;;
91 ;; The most common first step in this function is the expansion of the
92 ;; PARAMS argument using `org-babel-process-params'.
93 ;;
94 ;; Please feel free to not implement options which aren't appropriate
95 ;; for your language (e.g. not all languages support interactive
96 ;; "session" evaluation).  Also you are free to define any new header
97 ;; arguments which you feel may be useful -- all header arguments
98 ;; specified by the user will be available in the PARAMS variable.
99 (defun org-babel-execute:template (body params)
100   "Execute a block of Template code with org-babel.
101 This function is called by `org-babel-execute-src-block'"
102   (message "executing Template source code block")
103   (let* ((processed-params (org-babel-process-params params))
104          ;; set the session if the session variable is non-nil
105          (session (org-babel-template-initiate-session (first processed-params)))
106          ;; variables assigned for use in the block
107          (vars (second processed-params))
108          (result-params (third processed-params))
109          ;; either OUTPUT or VALUE which should behave as described above
110          (result-type (fourth processed-params))
111          ;; expand the body with `org-babel-expand-body:template'
112          (full-body (org-babel-expand-body:template
113                      body params processed-params)))
114     ;; actually execute the source-code block either in a session or
115     ;; possibly by dropping it to a temporary file and evaluating the
116     ;; file.
117     ;; 
118     ;; for session based evaluation the functions defined in
119     ;; `org-babel-comint' will probably be helpful.
120     ;;
121     ;; for external evaluation the functions defined in
122     ;; `org-babel-eval' will probably be helpful.
123     ;;
124     ;; when forming a shell command, or a fragment of code in some
125     ;; other language, please preprocess any file names involved with
126     ;; the function `org-babel-process-file-name'. (See the way that
127     ;; function is used in the language files)
128     ))
129
130 ;; This function should be used to assign any variables in params in
131 ;; the context of the session environment.
132 (defun org-babel-prep-session:template (session params)
133   "Prepare SESSION according to the header arguments specified in PARAMS."
134   )
135
136 (defun org-babel-template-var-to-template (var)
137   "Convert an elisp var into a string of template source code
138 specifying a var of the same value."
139   (format "%S" var))
140
141 (defun org-babel-template-table-or-string (results)
142   "If the results look like a table, then convert them into an
143 Emacs-lisp table, otherwise return the results as a string."
144   )
145
146 (defun org-babel-template-initiate-session (&optional session)
147   "If there is not a current inferior-process-buffer in SESSION then create.
148 Return the initialized session."
149   (unless (string= session "none")
150     ))
151
152 (provide 'ob-template)
153 ;;; ob-template.el ends here