emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
blob 828c5e9e3d607215ea44c86ba405b411bb1be6ee 13052 bytes (raw)
name: lisp/org-macro.el 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
;;; org-macro.el --- Macro Replacement Code for Org  -*- lexical-binding: t; -*-

;; Copyright (C) 2013-2017 Free Software Foundation, Inc.

;; Author: Nicolas Goaziou <n.goaziou@gmail.com>
;; Keywords: outlines, hypermedia, calendar, wp

;; This file is part of GNU Emacs.

;; GNU Emacs is free software: you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.

;;; Commentary:

;; Macros are expanded with `org-macro-replace-all', which relies
;; internally on `org-macro-expand'.

;; Default templates for expansion are stored in the buffer-local
;; variable `org-macro-templates'.  This variable is updated by
;; `org-macro-initialize-templates', which recursively calls
;; `org-macro--collect-macros' in order to read setup files.

;; Argument in macros are separated with commas. Proper escaping rules
;; are implemented in `org-macro-escape-arguments' and arguments can
;; be extracted from a string with `org-macro-extract-arguments'.

;; Along with macros defined through #+MACRO: keyword, default
;; templates include the following hard-coded macros:
;;   {{{time(format-string)}}},
;;   {{{property(node-property)}}},
;;   {{{input-file}}},
;;   {{{modification-time(format-string)}}},
;;   {{{n(counter,reset}}}.

;; Upon exporting, "ox.el" will also provide {{{author}}}, {{{date}}},
;; {{{email}}} and {{{title}}} macros.

;;; Code:
(require 'cl-lib)
(require 'org-macs)
(require 'org-compat)

(declare-function org-element-at-point "org-element" ())
(declare-function org-element-context "org-element" (&optional element))
(declare-function org-element-macro-parser "org-element" ())
(declare-function org-element-property "org-element" (property element))
(declare-function org-element-type "org-element" (element))
(declare-function org-file-contents "org" (file &optional noerror nocache))
(declare-function org-file-url-p "org" (file))
(declare-function org-in-commented-heading-p "org" (&optional no-inheritance))
(declare-function org-mode "org" ())
(declare-function vc-backend "vc-hooks" (f))
(declare-function vc-call "vc-hooks" (fun file &rest args) t)
(declare-function vc-exec-after "vc-dispatcher" (code))

;;; Variables

(defvar-local org-macro-templates nil
  "Alist containing all macro templates in current buffer.
Associations are in the shape of (NAME . TEMPLATE) where NAME
stands for macro's name and template for its replacement value,
both as strings.  This is an internal variable.  Do not set it
directly, use instead:

  #+MACRO: name template")

;;; Functions

(defun org-macro--collect-macros ()
  "Collect macro definitions in current buffer and setup files.
Return an alist containing all macro templates found."
  (letrec ((collect-macros
	    (lambda (files templates)
	      ;; Return an alist of macro templates.  FILES is a list
	      ;; of setup files names read so far, used to avoid
	      ;; circular dependencies.  TEMPLATES is the alist
	      ;; collected so far.
	      (let ((case-fold-search t))
		(org-with-wide-buffer
		 (goto-char (point-min))
		 (while (re-search-forward
			 "^[ \t]*#\\+\\(MACRO\\|SETUPFILE\\):" nil t)
		   (let ((element (org-element-at-point)))
		     (when (eq (org-element-type element) 'keyword)
		       (let ((val (org-element-property :value element)))
			 (if (equal (org-element-property :key element) "MACRO")
			     ;; Install macro in TEMPLATES.
			     (when (string-match
				    "^\\(.*?\\)\\(?:\\s-+\\(.*\\)\\)?\\s-*$" val)
			       (let* ((name (match-string 1 val))
				      (template (or (match-string 2 val) ""))
				      (old-cell (assoc name templates)))
				 (if old-cell (setcdr old-cell template)
				   (push (cons name template) templates))))
			   ;; Enter setup file.
			   (let* ((uri (org-unbracket-string "\"" "\"" (org-trim val)))
				  (uri-is-url (org-file-url-p uri))
				  (uri (if uri-is-url
					   uri
					 (expand-file-name uri))))
			     ;; Avoid circular dependencies.
			     (unless (member uri files)
			       (with-temp-buffer
				 (unless uri-is-url
				   (setq default-directory
					 (file-name-directory uri)))
				 (org-mode)
				 (insert (org-file-contents uri 'noerror))
				 (setq templates
				       (funcall collect-macros (cons uri files)
						templates)))))))))))
		templates))))
    (funcall collect-macros nil nil)))

(defun org-macro-initialize-templates ()
  "Collect macro templates defined in current buffer.
Templates are stored in buffer-local variable
`org-macro-templates'.  In addition to buffer-defined macros, the
function installs the following ones: \"property\",
\"time\". and, if the buffer is associated to a file,
\"input-file\" and \"modification-time\"."
  (let* ((templates (org-macro--collect-macros))
	 (update-templates
	  (lambda (cell)
	    (let ((old-template (assoc (car cell) templates)))
	      (if old-template (setcdr old-template (cdr cell))
		(push cell templates))))))
    ;; Install "property", "time" macros.
    (mapc update-templates
	  (list (cons "property"
		      "(eval (save-excursion
        (let ((l \"$2\"))
          (when (org-string-nw-p l)
            (condition-case _
                (let ((org-link-search-must-match-exact-headline t))
                  (org-link-search l nil t))
              (error
               (error \"Macro property failed: cannot find location %s\"
                      l)))))
        (org-entry-get nil \"$1\" 'selective)))")
		(cons "time" "(eval (format-time-string \"$1\"))")))
    ;; Install "input-file", "modification-time" macros.
    (let ((visited-file (buffer-file-name (buffer-base-buffer))))
      (when (and visited-file (file-exists-p visited-file))
	(mapc update-templates
	      (list (cons "input-file" (file-name-nondirectory visited-file))
		    (cons "modification-time"
			  (format "(eval (format-time-string \"$1\" (or (and (org-string-nw-p \"$2\") (org-macro--vc-modified-time %s)) '%s)))"
				  (prin1-to-string visited-file)
				  (prin1-to-string
				   (nth 5 (file-attributes visited-file)))))))))
    ;; Initialize and install "n" macro.
    (org-macro--counter-initialize)
    (funcall update-templates
	     (cons "n" "(eval (org-macro--counter-increment \"$1\" \"$2\"))"))
    (setq org-macro-templates templates)))

(defun org-macro-expand (macro templates)
  "Return expanded MACRO, as a string.
MACRO is an object, obtained, for example, with
`org-element-context'.  TEMPLATES is an alist of templates used
for expansion.  See `org-macro-templates' for a buffer-local
default value.  Return nil if no template was found."
  (let ((template
	 ;; Macro names are case-insensitive.
	 (cdr (assoc-string (org-element-property :key macro) templates t))))
    (when template
      (let ((value (replace-regexp-in-string
                    "\\$[0-9]+"
                    (lambda (arg)
                      (or (nth (1- (string-to-number (substring arg 1)))
                               (org-element-property :args macro))
                          ;; No argument: remove place-holder.
                          ""))
                    template nil 'literal)))
        ;; VALUE starts with "(eval": it is a s-exp, `eval' it.
        (when (string-match "\\`(eval\\>" value)
          (setq value (eval (read value))))
        ;; Return string.
        (format "%s" (or value ""))))))

(defun org-macro-replace-all (templates &optional finalize keywords)
  "Replace all macros in current buffer by their expansion.

TEMPLATES is an alist of templates used for expansion.  See
`org-macro-templates' for a buffer-local default value.

If optional arg FINALIZE is non-nil, raise an error if a macro is
found in the buffer with no definition in TEMPLATES.

Optional argument KEYWORDS, when non-nil is a list of keywords,
as strings, where macro expansion is allowed."
  (save-excursion
    (goto-char (point-min))
    (let ((properties-regexp
	   (format "\\`EXPORT_%s\\+?\\'" (regexp-opt keywords)))
	  record)
      (while (re-search-forward "{{{[-A-Za-z0-9_]" nil t)
	(unless (save-match-data (org-in-commented-heading-p))
	  (let* ((datum (save-match-data (org-element-context)))
		 (type (org-element-type datum))
		 (macro
		  (cond
		   ((eq type 'macro) datum)
		   ;; In parsed keywords and associated node
		   ;; properties, force macro recognition.
		   ((or (and (eq type 'keyword)
			     (member (org-element-property :key datum)
				     keywords))
			(and (eq type 'node-property)
			     (string-match-p properties-regexp
					     (org-element-property :key
								   datum))))
		    (save-excursion
		      (goto-char (match-beginning 0))
		      (org-element-macro-parser))))))
	    (when macro
	      (let* ((value (org-macro-expand macro templates))
		     (begin (org-element-property :begin macro))
		     (signature (list begin
				      macro
				      (org-element-property :args macro))))
		;; Avoid circular dependencies by checking if the same
		;; macro with the same arguments is expanded at the
		;; same position twice.
		(cond ((member signature record)
		       (error "Circular macro expansion: %s"
			      (org-element-property :key macro)))
		      (value
		       (push signature record)
		       (delete-region
			begin
			;; Preserve white spaces after the macro.
			(progn (goto-char (org-element-property :end macro))
			       (skip-chars-backward " \t")
			       (point)))
		       ;; Leave point before replacement in case of
		       ;; recursive expansions.
		       (save-excursion (insert value)))
		      (finalize
		       (error "Undefined Org macro: %s; aborting"
			      (org-element-property :key macro))))))))))))

(defun org-macro-escape-arguments (&rest args)
  "Build macro's arguments string from ARGS.
ARGS are strings.  Return value is a string with arguments
properly escaped and separated with commas.  This is the opposite
of `org-macro-extract-arguments'."
  (let ((s ""))
    (dolist (arg (reverse args) (substring s 1))
      (setq s
	    (concat
	     ","
	     (replace-regexp-in-string
	      "\\(\\\\*\\),"
	      (lambda (m)
		(concat (make-string (1+ (* 2 (length (match-string 1 m)))) ?\\)
			","))
	      ;; If a non-terminal argument ends on backslashes, make
	      ;; sure to also escape them as they will be followed by
	      ;; a comma.
	      (concat arg (and (not (equal s ""))
			       (string-match "\\\\+\\'" arg)
			       (match-string 0 arg)))
	      nil t)
	     s)))))

(defun org-macro-extract-arguments (s)
  "Extract macro arguments from string S.
S is a string containing comma separated values properly escaped.
Return a list of arguments, as strings.  This is the opposite of
`org-macro-escape-arguments'."
  ;; Do not use `org-split-string' since empty strings are
  ;; meaningful here.
  (split-string
   (replace-regexp-in-string
    "\\(\\\\*\\),"
    (lambda (str)
      (let ((len (length (match-string 1 str))))
	(concat (make-string (/ len 2) ?\\)
		(if (zerop (mod len 2)) "\000" ","))))
    s nil t)
   "\000"))

\f
;;; Helper functions and variables for internal macros

(defun org-macro--vc-modified-time (file)
  (save-window-excursion
    (when (vc-backend file)
      (let ((buf (get-buffer-create " *org-vc*"))
	    (case-fold-search t)
	    date)
	(unwind-protect
	    (progn
	      (vc-call print-log file buf nil nil 1)
	      (with-current-buffer buf
		(vc-exec-after
		 (lambda ()
		   (goto-char (point-min))
		   (when (re-search-forward "Date:?[ \t]*" nil t)
		     (let ((time (parse-time-string
				  (buffer-substring
				   (point) (line-end-position)))))
		       (when (cl-some #'identity time)
			 (setq date (apply #'encode-time time))))))))
	      (let ((proc (get-buffer-process buf)))
		(while (and proc (accept-process-output proc .5 nil t)))))
	  (kill-buffer buf))
	date))))

(defvar org-macro--counter-table nil
  "Hash table containing counter value per name.")

(defun org-macro--counter-initialize ()
  "Initialize `org-macro--counter-table'."
  (setq org-macro--counter-table (make-hash-table :test #'equal)))

(defun org-macro--counter-increment (name &optional reset)
  "Increment counter NAME.
NAME is a string identifying the counter.  When non-nil, optional
argument RESET is a string.  If it represents an integer, set the
counter to this number.  Any other non-empty string resets the
counter to 1."
  (puthash name
	   (cond ((not (org-string-nw-p reset))
		  (1+ (gethash name org-macro--counter-table 0)))
		 ((string-match-p "\\`[ \t]*[0-9]+[ \t]*\\'" reset)
		  (string-to-number reset))
		 (t 1))
	   org-macro--counter-table))


(provide 'org-macro)
;;; org-macro.el ends here

debug log:

solving 828c5e9e3d ...
found 828c5e9e3d in https://git.savannah.gnu.org/cgit/emacs/org-mode.git

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).