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: https://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 https://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