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?

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"))))

Answer 2

(org-collect-keywords '("PROPERTY")) could also be helpful, as mentioned in https://emacs.stackexchange.com/a/63102/31740.

The org-collect-keywords doc string states:

Return values for KEYWORDS in current buffer, as an alist.

KEYWORDS is a list of strings. Return value is a list of elements with the pattern:

(NAME . LIST-OF-VALUES)

where NAME is the upcase name of the keyword, and LIST-OF-VALUES is a list of non-empty values, as strings, in order of appearance in the buffer.

This allows one to get the property values, but it does not allow setting them. In fact, Org mode does not provide any way of setting them, so @Tobias's answer still stands for the setting part: you basically have to edit the file, either by hand or programatically.