Programmatically read and set buffer-wide org-mode property

Question

How one can programmatically read and set a buffer-wide org-mode property?

I am aware of this, which points to

(org-entry-put POM "PWE-1" "47")

but it does not seem useful in case of buffer global properties.

Details:

If a file has buffer global properties, like,

#+PROPERTY: PWE-1 42
#+PROPERTY: Cite "Silmarillon 1984"
#+PROPERTY: my/common-list (1 "two" (1 2 3 5 7))

How could one fetch, for example, the buffer-wide property PWE-1, or any other?

How would one set it, ie, write a different value, say

#+PROPERTY: PWE-1 2197

so that the buffer will keep the updated value as stored in the file, available at next load?

Where could I look up similar information in detail? Is there a detailed list of org-mode's API?

Thank you in advance.

Answer 1

You could just do a text search for #+PROPERTY: ....

Alternatively, you can use the following functions. These functions take into account that values can be accumulated via + and it is an error if the first PROPERTY key has a +. (Is that true?)

(require 'cl-lib)

(defun org-global-props-key-re (key)
  "Construct a regular expression matching key and an optional plus and eating the spaces behind.
Test for existence of the plus: (match-beginning 1)"
  (concat "^" (regexp-quote key) "\\(\\+\\)?[[:space:]]+"))

(defun org-global-props (&optional buffer)
  "Get the plists of global org properties of current buffer."
  (with-current-buffer (or buffer (current-buffer))
    (org-element-map (org-element-parse-buffer) 'keyword (lambda (el) (when (string-equal (org-element-property :key el) "PROPERTY") (nth 1 el))))))

(defun org-global-prop-value (key)
  "Get global org property KEY of current buffer.
Adding up values for one key is supported."
  (let ((key-re (org-global-props-key-re key))
    (props (org-global-props))
    ret)
    (cl-loop with val for prop in props
         when (string-match key-re (setq val (plist-get prop :value))) do
         (setq
          val (substring val (match-end 0))
          ret (if (match-beginning 1)
              (concat ret " " val)
            val)))
    ret))

(defun org-global-prop-set (key value)
  "Set the value of the first occurence of
#+PROPERTY: KEY
add it at the beginning of file if there is none."
  (save-excursion
    (let* ((key-re (org-global-props-key-re key))
       (prop (cl-find-if (lambda (prop)
                   (string-match key-re (plist-get prop :value)))
                 (org-global-props))))
      (if prop
      (progn
        (assert (null (match-beginning 1)) "First occurence of key %s is followed by +." key)
        (goto-char (plist-get prop :begin))
        (kill-region (point) (plist-get prop :end)))
    (goto-char 1))
      (insert "#+PROPERTY: " key " " value "\n"))))