Function: org-export-expand-include-keyword

org-export-expand-include-keyword is a byte-compiled function defined in ox.el.gz.

Signature

(org-export-expand-include-keyword &optional INCLUDED DIR FOOTNOTES INCLUDER-FILE EXPAND-ENV)

Documentation

Expand every include keyword in buffer.

Optional argument INCLUDED is a list of included file names along with their line restriction, when appropriate. It is used to avoid infinite recursion.

Optional argument DIR is the current working directory. It is used to properly resolve relative paths.

Optional argument FOOTNOTES is a hash-table used for storing and resolving footnotes. It is created automatically.

Optional argument INCLUDER-FILE is the file path corresponding to the buffer contents being included. It is used when current buffer does not have buffer-file-name(var)/buffer-file-name(fun) assigned.

When optional argument EXPAND-ENV is non-nil, expand environment variables in include file names.

Source Code

;; Defined in /usr/src/emacs/lisp/org/ox.el.gz
(defun org-export-expand-include-keyword (&optional included dir footnotes includer-file expand-env)
  "Expand every include keyword in buffer.

Optional argument INCLUDED is a list of included file names along
with their line restriction, when appropriate.  It is used to
avoid infinite recursion.

Optional argument DIR is the current working directory.  It is used to
properly resolve relative paths.

Optional argument FOOTNOTES is a hash-table used for
storing and resolving footnotes.  It is created automatically.

Optional argument INCLUDER-FILE is the file path corresponding to the
buffer contents being included.  It is used when current buffer does
not have `buffer-file-name' assigned.

When optional argument EXPAND-ENV is non-nil, expand environment
variables in include file names."
  (let ((includer-file (or includer-file
                           (buffer-file-name (buffer-base-buffer))))
	(case-fold-search t)
	(file-prefix (make-hash-table :test #'equal))
	(footnotes (or footnotes (make-hash-table :test #'equal)))
	(include-re "^[ \t]*#\\+INCLUDE:"))
    ;; If :minlevel is not set the text-property
    ;; `:org-include-induced-level' will be used to determine the
    ;; relative level when expanding INCLUDE.
    ;; Only affects included Org documents.
    (goto-char (point-min))
    (while (re-search-forward include-re nil t)
      (put-text-property (line-beginning-position) (line-end-position)
			 :org-include-induced-level
			 (1+ (org-reduced-level (or (org-current-level) 0)))))
    ;; Expand INCLUDE keywords.
    (goto-char (point-min))
    (while (re-search-forward include-re nil t)
      (unless (org-in-commented-heading-p)
        (let ((element (org-element-at-point)))
          (when (org-element-type-p element 'keyword)
            (forward-line 0)
            ;; Extract arguments from keyword's value.
            (let* ((value (org-element-property :value element))
                   (parameters (org-export-parse-include-value value dir))
                   (file (if expand-env
                             (substitute-env-in-file-name
                              (plist-get parameters :file))
                           (plist-get parameters :file))))
              ;; Remove keyword.
              (delete-region (point) (line-beginning-position 2))
              (cond
               ((not file)) ; Do nothing.
               ((and (not (org-url-p file))
                     (not (file-readable-p file)))
                (error "Cannot include file %s" file))
               ;; Check if files has already been parsed.  Look after
               ;; inclusion lines too, as different parts of the same
               ;; file can be included too.
               ((member (list file (plist-get parameters :lines)) included)
                (error "Recursive file inclusion: %s" file))
               (t
                (org-export--blindly-expand-include
                 parameters
                 :includer-file includer-file
                 :file-prefix file-prefix
                 :footnotes footnotes
                 :already-included included
                 :expand-env expand-env)
                ;; Expand footnotes after all files have been
                ;; included.  Footnotes are stored at end of buffer.
                (unless included
                  (org-with-wide-buffer
                   (goto-char (point-max))
                   (maphash (lambda (k v)
                              (insert (format "\n[fn:%s] %s\n" k v)))
                            footnotes))))))))))))