ob-tangle.el 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481
  1. ;;; ob-tangle.el --- extract source code from org-mode files
  2. ;; Copyright (C) 2009, 2010 Free Software Foundation, Inc.
  3. ;; Author: Eric Schulte
  4. ;; Keywords: literate programming, reproducible research
  5. ;; Homepage: http://orgmode.org
  6. ;; Version: 7.5
  7. ;; This file is part of GNU Emacs.
  8. ;; GNU Emacs is free software: you can redistribute it and/or modify
  9. ;; it under the terms of the GNU General Public License as published by
  10. ;; the Free Software Foundation, either version 3 of the License, or
  11. ;; (at your option) any later version.
  12. ;; GNU Emacs is distributed in the hope that it will be useful,
  13. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15. ;; GNU General Public License for more details.
  16. ;; You should have received a copy of the GNU General Public License
  17. ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
  18. ;;; Commentary:
  19. ;; Extract the code from source blocks out into raw source-code files.
  20. ;;; Code:
  21. (require 'ob)
  22. (require 'org-src)
  23. (eval-when-compile
  24. (require 'cl))
  25. (declare-function org-link-escape "org" (text &optional table))
  26. (declare-function org-heading-components "org" ())
  27. (declare-function org-back-to-heading "org" (invisible-ok))
  28. (declare-function org-fill-template "org" (template alist))
  29. (declare-function org-babel-update-block-body "org" (new-body))
  30. (declare-function make-directory "files" (dir &optional parents))
  31. ;;;###autoload
  32. (defcustom org-babel-tangle-lang-exts
  33. '(("emacs-lisp" . "el"))
  34. "Alist mapping languages to their file extensions.
  35. The key is the language name, the value is the string that should
  36. be inserted as the extension commonly used to identify files
  37. written in this language. If no entry is found in this list,
  38. then the name of the language is used."
  39. :group 'org-babel-tangle
  40. :type '(repeat
  41. (cons
  42. (string "Language name")
  43. (string "File Extension"))))
  44. (defcustom org-babel-post-tangle-hook nil
  45. "Hook run in code files tangled by `org-babel-tangle'."
  46. :group 'org-babel
  47. :type 'hook)
  48. (defcustom org-babel-pre-tangle-hook '(save-buffer)
  49. "Hook run at the beginning of `org-babel-tangle'."
  50. :group 'org-babel
  51. :type 'hook)
  52. (defcustom org-babel-tangle-pad-newline t
  53. "Switch indicating whether to pad tangled code with newlines."
  54. :group 'org-babel
  55. :type 'boolean)
  56. (defcustom org-babel-tangle-comment-format-beg "[[%link][%source-name]]"
  57. "Format of inserted comments in tangled code files.
  58. The following format strings can be used to insert special
  59. information into the output using `org-fill-template'.
  60. %start-line --- the line number at the start of the code block
  61. %file --------- the file from which the code block was tangled
  62. %link --------- Org-mode style link to the code block
  63. %source-name -- name of the code block
  64. Whether or not comments are inserted during tangling is
  65. controlled by the :comments header argument."
  66. :group 'org-babel
  67. :type 'string)
  68. (defcustom org-babel-tangle-comment-format-end "%source-name ends here"
  69. "Format of inserted comments in tangled code files.
  70. The following format strings can be used to insert special
  71. information into the output using `org-fill-template'.
  72. %start-line --- the line number at the start of the code block
  73. %file --------- the file from which the code block was tangled
  74. %link --------- Org-mode style link to the code block
  75. %source-name -- name of the code block
  76. Whether or not comments are inserted during tangling is
  77. controlled by the :comments header argument."
  78. :group 'org-babel
  79. :type 'string)
  80. (defun org-babel-find-file-noselect-refresh (file)
  81. "Find file ensuring that the latest changes on disk are
  82. represented in the file."
  83. (find-file-noselect file)
  84. (with-current-buffer (get-file-buffer file)
  85. (revert-buffer t t t)))
  86. (defmacro org-babel-with-temp-filebuffer (file &rest body)
  87. "Open FILE into a temporary buffer execute BODY there like
  88. `progn', then kill the FILE buffer returning the result of
  89. evaluating BODY."
  90. (declare (indent 1))
  91. (let ((temp-result (make-symbol "temp-result"))
  92. (temp-file (make-symbol "temp-file"))
  93. (visited-p (make-symbol "visited-p")))
  94. `(let (,temp-result ,temp-file
  95. (,visited-p (get-file-buffer ,file)))
  96. (org-babel-find-file-noselect-refresh ,file)
  97. (setf ,temp-file (get-file-buffer ,file))
  98. (with-current-buffer ,temp-file
  99. (setf ,temp-result (progn ,@body)))
  100. (unless ,visited-p (kill-buffer ,temp-file))
  101. ,temp-result)))
  102. ;;;###autoload
  103. (defun org-babel-load-file (file)
  104. "Load Emacs Lisp source code blocks in the Org-mode FILE.
  105. This function exports the source code using
  106. `org-babel-tangle' and then loads the resulting file using
  107. `load-file'."
  108. (interactive "fFile to load: ")
  109. (flet ((age (file)
  110. (float-time
  111. (time-subtract (current-time)
  112. (nth 5 (or (file-attributes (file-truename file))
  113. (file-attributes file)))))))
  114. (let* ((base-name (file-name-sans-extension file))
  115. (exported-file (concat base-name ".el")))
  116. ;; tangle if the org-mode file is newer than the elisp file
  117. (unless (and (file-exists-p exported-file)
  118. (> (age file) (age exported-file)))
  119. (org-babel-tangle-file file exported-file "emacs-lisp"))
  120. (load-file exported-file)
  121. (message "loaded %s" exported-file))))
  122. ;;;###autoload
  123. (defun org-babel-tangle-file (file &optional target-file lang)
  124. "Extract the bodies of source code blocks in FILE.
  125. Source code blocks are extracted with `org-babel-tangle'.
  126. Optional argument TARGET-FILE can be used to specify a default
  127. export file for all source blocks. Optional argument LANG can be
  128. used to limit the exported source code blocks by language."
  129. (interactive "fFile to tangle: \nP")
  130. (let ((visited-p (get-file-buffer (expand-file-name file)))
  131. to-be-removed)
  132. (save-window-excursion
  133. (find-file file)
  134. (setq to-be-removed (current-buffer))
  135. (org-babel-tangle target-file lang))
  136. (unless visited-p
  137. (kill-buffer to-be-removed))))
  138. (defun org-babel-tangle-publish (_ filename pub-dir)
  139. "Tangle FILENAME and place the results in PUB-DIR."
  140. (mapc (lambda (el) (copy-file el pub-dir t)) (org-babel-tangle-file filename)))
  141. ;;;###autoload
  142. (defun org-babel-tangle (&optional target-file lang)
  143. "Write code blocks to source-specific files.
  144. Extract the bodies of all source code blocks from the current
  145. file into their own source-specific files. Optional argument
  146. TARGET-FILE can be used to specify a default export file for all
  147. source blocks. Optional argument LANG can be used to limit the
  148. exported source code blocks by language."
  149. (interactive)
  150. (run-hooks 'org-babel-pre-tangle-hook)
  151. (save-excursion
  152. (let ((block-counter 0)
  153. (org-babel-default-header-args
  154. (if target-file
  155. (org-babel-merge-params org-babel-default-header-args
  156. (list (cons :tangle target-file)))
  157. org-babel-default-header-args))
  158. path-collector)
  159. (mapc ;; map over all languages
  160. (lambda (by-lang)
  161. (let* ((lang (car by-lang))
  162. (specs (cdr by-lang))
  163. (ext (or (cdr (assoc lang org-babel-tangle-lang-exts)) lang))
  164. (lang-f (intern
  165. (concat
  166. (or (and (cdr (assoc lang org-src-lang-modes))
  167. (symbol-name
  168. (cdr (assoc lang org-src-lang-modes))))
  169. lang)
  170. "-mode")))
  171. she-banged)
  172. (mapc
  173. (lambda (spec)
  174. (flet ((get-spec (name)
  175. (cdr (assoc name (nth 4 spec)))))
  176. (let* ((tangle (get-spec :tangle))
  177. (she-bang ((lambda (sheb) (when (> (length sheb) 0) sheb))
  178. (get-spec :shebang)))
  179. (base-name (cond
  180. ((string= "yes" tangle)
  181. (file-name-sans-extension
  182. (buffer-file-name)))
  183. ((string= "no" tangle) nil)
  184. ((> (length tangle) 0) tangle)))
  185. (file-name (when base-name
  186. ;; decide if we want to add ext to base-name
  187. (if (and ext (string= "yes" tangle))
  188. (concat base-name "." ext) base-name))))
  189. (when file-name
  190. ;; possibly create the parent directories for file
  191. (when ((lambda (m) (and m (not (string= m "no"))))
  192. (get-spec :mkdirp))
  193. (make-directory (file-name-directory file-name) 'parents))
  194. ;; delete any old versions of file
  195. (when (and (file-exists-p file-name)
  196. (not (member file-name path-collector)))
  197. (delete-file file-name))
  198. ;; drop source-block to file
  199. (with-temp-buffer
  200. (when (fboundp lang-f) (funcall lang-f))
  201. (when (and she-bang (not (member file-name she-banged)))
  202. (insert (concat she-bang "\n"))
  203. (setq she-banged (cons file-name she-banged)))
  204. (org-babel-spec-to-string spec)
  205. ;; We avoid append-to-file as it does not work with tramp.
  206. (let ((content (buffer-string)))
  207. (with-temp-buffer
  208. (if (file-exists-p file-name)
  209. (insert-file-contents file-name))
  210. (goto-char (point-max))
  211. (insert content)
  212. (write-region nil nil file-name))))
  213. ;; if files contain she-bangs, then make the executable
  214. (when she-bang (set-file-modes file-name #o755))
  215. ;; update counter
  216. (setq block-counter (+ 1 block-counter))
  217. (add-to-list 'path-collector file-name)))))
  218. specs)))
  219. (org-babel-tangle-collect-blocks lang))
  220. (message "tangled %d code block%s from %s" block-counter
  221. (if (= block-counter 1) "" "s")
  222. (file-name-nondirectory (buffer-file-name (current-buffer))))
  223. ;; run `org-babel-post-tangle-hook' in all tangled files
  224. (when org-babel-post-tangle-hook
  225. (mapc
  226. (lambda (file)
  227. (org-babel-with-temp-filebuffer file
  228. (run-hooks 'org-babel-post-tangle-hook)))
  229. path-collector))
  230. path-collector)))
  231. (defun org-babel-tangle-clean ()
  232. "Remove comments inserted by `org-babel-tangle'.
  233. Call this function inside of a source-code file generated by
  234. `org-babel-tangle' to remove all comments inserted automatically
  235. by `org-babel-tangle'. Warning, this comment removes any lines
  236. containing constructs which resemble org-mode file links or noweb
  237. references."
  238. (interactive)
  239. (goto-char (point-min))
  240. (while (or (re-search-forward "\\[\\[file:.*\\]\\[.*\\]\\]" nil t)
  241. (re-search-forward "<<[^[:space:]]*>>" nil t))
  242. (delete-region (save-excursion (beginning-of-line 1) (point))
  243. (save-excursion (end-of-line 1) (forward-char 1) (point)))))
  244. (defvar org-stored-links)
  245. (defun org-babel-tangle-collect-blocks (&optional language)
  246. "Collect source blocks in the current Org-mode file.
  247. Return an association list of source-code block specifications of
  248. the form used by `org-babel-spec-to-string' grouped by language.
  249. Optional argument LANG can be used to limit the collected source
  250. code blocks by language."
  251. (let ((block-counter 1) (current-heading "") blocks)
  252. (org-babel-map-src-blocks (buffer-file-name)
  253. ((lambda (new-heading)
  254. (if (not (string= new-heading current-heading))
  255. (progn
  256. (setq block-counter 1)
  257. (setq current-heading new-heading))
  258. (setq block-counter (+ 1 block-counter))))
  259. (replace-regexp-in-string "[ \t]" "-"
  260. (condition-case nil
  261. (nth 4 (org-heading-components))
  262. (error (buffer-file-name)))))
  263. (let* ((start-line (save-restriction (widen)
  264. (+ 1 (line-number-at-pos (point)))))
  265. (file (buffer-file-name))
  266. (info (org-babel-get-src-block-info 'light))
  267. (src-lang (nth 0 info)))
  268. (unless (string= (cdr (assoc :tangle (nth 2 info))) "no")
  269. (unless (and language (not (string= language src-lang)))
  270. (let* ((info (org-babel-get-src-block-info))
  271. (params (nth 2 info))
  272. (link (progn (call-interactively 'org-store-link)
  273. (org-babel-clean-text-properties
  274. (car (pop org-stored-links)))))
  275. (source-name
  276. (intern (or (nth 4 info)
  277. (format "%s:%d"
  278. current-heading block-counter))))
  279. (expand-cmd
  280. (intern (concat "org-babel-expand-body:" src-lang)))
  281. (assignments-cmd
  282. (intern (concat "org-babel-variable-assignments:" src-lang)))
  283. (body
  284. ((lambda (body)
  285. (if (assoc :no-expand params)
  286. body
  287. (if (fboundp expand-cmd)
  288. (funcall expand-cmd body params)
  289. (org-babel-expand-body:generic
  290. body params
  291. (and (fboundp assignments-cmd)
  292. (funcall assignments-cmd params))))))
  293. (if (and (cdr (assoc :noweb params))
  294. (let ((nowebs (split-string
  295. (cdr (assoc :noweb params)))))
  296. (or (member "yes" nowebs)
  297. (member "tangle" nowebs))))
  298. (org-babel-expand-noweb-references info)
  299. (nth 1 info))))
  300. (comment
  301. (when (or (string= "both" (cdr (assoc :comments params)))
  302. (string= "org" (cdr (assoc :comments params))))
  303. ;; from the previous heading or code-block end
  304. (buffer-substring
  305. (max (condition-case nil
  306. (save-excursion
  307. (org-back-to-heading t) (point))
  308. (error 0))
  309. (save-excursion
  310. (re-search-backward
  311. org-babel-src-block-regexp nil t)
  312. (match-end 0)))
  313. (point))))
  314. by-lang)
  315. ;; add the spec for this block to blocks under it's language
  316. (setq by-lang (cdr (assoc src-lang blocks)))
  317. (setq blocks (delq (assoc src-lang blocks) blocks))
  318. (setq blocks (cons
  319. (cons src-lang
  320. (cons (list start-line file link
  321. source-name params body comment)
  322. by-lang)) blocks)))))))
  323. ;; ensure blocks in the correct order
  324. (setq blocks
  325. (mapcar
  326. (lambda (by-lang) (cons (car by-lang) (reverse (cdr by-lang))))
  327. blocks))
  328. blocks))
  329. (defun org-babel-spec-to-string (spec)
  330. "Insert SPEC into the current file.
  331. Insert the source-code specified by SPEC into the current
  332. source code file. This function uses `comment-region' which
  333. assumes that the appropriate major-mode is set. SPEC has the
  334. form
  335. (start-line file link source-name params body comment)"
  336. (let* ((start-line (nth 0 spec))
  337. (file (nth 1 spec))
  338. (link (org-link-escape (nth 2 spec)))
  339. (source-name (nth 3 spec))
  340. (body (nth 5 spec))
  341. (comment (nth 6 spec))
  342. (comments (cdr (assoc :comments (nth 4 spec))))
  343. (link-p (or (string= comments "both") (string= comments "link")
  344. (string= comments "yes") (string= comments "noweb")))
  345. (link-data (mapcar (lambda (el)
  346. (cons (symbol-name el)
  347. ((lambda (le)
  348. (if (stringp le) le (format "%S" le)))
  349. (eval el))))
  350. '(start-line file link source-name))))
  351. (flet ((insert-comment (text)
  352. (let ((text (org-babel-trim text)))
  353. (when (and comments (not (string= comments "no"))
  354. (> (length text) 0))
  355. (when org-babel-tangle-pad-newline (insert "\n"))
  356. (comment-region (point) (progn (insert text) (point)))
  357. (end-of-line nil) (insert "\n")))))
  358. (when comment (insert-comment comment))
  359. (when link-p
  360. (insert-comment
  361. (org-fill-template org-babel-tangle-comment-format-beg link-data)))
  362. (when org-babel-tangle-pad-newline (insert "\n"))
  363. (insert
  364. (format
  365. "%s\n"
  366. (replace-regexp-in-string
  367. "^," ""
  368. (org-babel-trim body (if org-src-preserve-indentation "[\f\n\r\v]")))))
  369. (when link-p
  370. (insert-comment
  371. (org-fill-template org-babel-tangle-comment-format-end link-data))))))
  372. (defun org-babel-tangle-comment-links ( &optional info)
  373. "Return a list of begin and end link comments for the code block at point."
  374. (let* ((start-line (org-babel-where-is-src-block-head))
  375. (file (buffer-file-name))
  376. (link (org-link-escape (progn (call-interactively 'org-store-link)
  377. (org-babel-clean-text-properties
  378. (car (pop org-stored-links))))))
  379. (source-name (nth 4 (or info (org-babel-get-src-block-info 'light))))
  380. (link-data (mapcar (lambda (el)
  381. (cons (symbol-name el)
  382. ((lambda (le)
  383. (if (stringp le) le (format "%S" le)))
  384. (eval el))))
  385. '(start-line file link source-name))))
  386. (list (org-fill-template org-babel-tangle-comment-format-beg link-data)
  387. (org-fill-template org-babel-tangle-comment-format-end link-data))))
  388. ;; de-tangling functions
  389. (defvar org-bracket-link-analytic-regexp)
  390. (defun org-babel-detangle (&optional source-code-file)
  391. "Propagate changes in source file back original to Org-mode file.
  392. This requires that code blocks were tangled with link comments
  393. which enable the original code blocks to be found."
  394. (interactive)
  395. (save-excursion
  396. (when source-code-file (find-file source-code-file))
  397. (goto-char (point-min))
  398. (let ((counter 0) new-body end)
  399. (while (re-search-forward org-bracket-link-analytic-regexp nil t)
  400. (when (re-search-forward
  401. (concat " " (regexp-quote (match-string 5)) " ends here"))
  402. (setq end (match-end 0))
  403. (forward-line -1)
  404. (save-excursion
  405. (when (setq new-body (org-babel-tangle-jump-to-org))
  406. (org-babel-update-block-body new-body)))
  407. (setq counter (+ 1 counter)))
  408. (goto-char end))
  409. (prog1 counter (message "detangled %d code blocks" counter)))))
  410. (defun org-babel-tangle-jump-to-org ()
  411. "Jump from a tangled code file to the related Org-mode file."
  412. (interactive)
  413. (let ((mid (point))
  414. start end done
  415. target-buffer target-char link path block-name body)
  416. (save-window-excursion
  417. (save-excursion
  418. (while (and (re-search-backward org-bracket-link-analytic-regexp nil t)
  419. (not ; ever wider searches until matching block comments
  420. (and (setq start (point-at-eol))
  421. (setq link (match-string 0))
  422. (setq path (match-string 3))
  423. (setq block-name (match-string 5))
  424. (save-excursion
  425. (save-match-data
  426. (re-search-forward
  427. (concat " " (regexp-quote block-name)
  428. " ends here") nil t)
  429. (setq end (point-at-bol))))))))
  430. (unless (and start (< start mid) (< mid end))
  431. (error "not in tangled code"))
  432. (setq body (org-babel-trim (buffer-substring start end))))
  433. (when (string-match "::" path)
  434. (setq path (substring path 0 (match-beginning 0))))
  435. (find-file path) (setq target-buffer (current-buffer))
  436. (goto-char start) (org-open-link-from-string link)
  437. (if (string-match "[^ \t\n\r]:\\([[:digit:]]+\\)" block-name)
  438. (org-babel-next-src-block
  439. (string-to-number (match-string 1 block-name)))
  440. (org-babel-goto-named-src-block block-name))
  441. (setq target-char (point)))
  442. (pop-to-buffer target-buffer)
  443. (prog1 body (goto-char target-char))))
  444. (provide 'ob-tangle)
  445. ;; arch-tag: 413ced93-48f5-4216-86e4-3fc5df8c8f24
  446. ;;; ob-tangle.el ends here