Function: org-element-at-point

org-element-at-point is an autoloaded and byte-compiled function defined in org-element.el.gz.

Signature

(org-element-at-point &optional POM CACHED-ONLY)

Documentation

Determine closest element around point or POM.

Only check cached element when CACHED-ONLY is non-nil and return nil unconditionally when element at POM is not in cache.

Return value is a list like (TYPE PROPS) where TYPE is the type of the element and PROPS a plist of properties associated to the element.

Possible types are defined in org-element-all-elements. Properties depend on element or object type, but always include
:begin, :end, and :post-blank properties.

As a special case, if point is at the very beginning of the first item in a list or sub-list, returned element will be that list instead of the item. Likewise, if point is at the beginning of the first row of a table, returned element will be the table instead of the first row.

When point is at the end of the buffer, return the innermost element ending there.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-element.el.gz
;;; The Toolbox
;;
;; The first move is to implement a way to obtain the smallest element
;; containing point.  This is the job of `org-element-at-point'.  It
;; basically jumps back to the beginning of section containing point
;; and proceed, one element after the other, with
;; `org-element--current-element' until the container is found.  Note:
;; When using `org-element-at-point', secondary values are never
;; parsed since the function focuses on elements, not on objects.
;;
;; At a deeper level, `org-element-context' lists all elements and
;; objects containing point.
;;
;; `org-element-nested-p' and `org-element-swap-A-B' may be used
;; internally by navigation and manipulation tools.


;;;###autoload
(defun org-element-at-point (&optional pom cached-only)
  "Determine closest element around point or POM.

Only check cached element when CACHED-ONLY is non-nil and return nil
unconditionally when element at POM is not in cache.

Return value is a list like (TYPE PROPS) where TYPE is the type
of the element and PROPS a plist of properties associated to the
element.

Possible types are defined in `org-element-all-elements'.
Properties depend on element or object type, but always include
`:begin', `:end', and `:post-blank' properties.

As a special case, if point is at the very beginning of the first
item in a list or sub-list, returned element will be that list
instead of the item.  Likewise, if point is at the beginning of
the first row of a table, returned element will be the table
instead of the first row.

When point is at the end of the buffer, return the innermost
element ending there."
  (setq pom (or pom (point)))
  ;; Allow re-parsing when the command can benefit from it.
  (when (and cached-only
             (memq this-command org-element--cache-non-modifying-commands))
    (setq cached-only nil))
  (let (element)
    (when (org-element--cache-active-p)
      (if (not (org-with-base-buffer nil org-element--cache)) (org-element-cache-reset)
        (unless cached-only (org-element--cache-sync (current-buffer) pom))))
    (setq element (if cached-only
                      (when (and (org-element--cache-active-p)
                                 (or (not org-element--cache-sync-requests)
                                     (< pom
                                        (org-element--request-beg
                                         (car org-element--cache-sync-requests)))))
                        (org-element--cache-find pom))
                    (condition-case err
                        (org-element--parse-to pom)
                      (error
                       (org-element--cache-warn
                        "Org parser error in %s::%S. Resetting.\n The error was: %S\n Backtrace:\n%S\n Please report this to Org mode mailing list (M-x org-submit-bug-report)."
                        (buffer-name (current-buffer))
                        pom
                        err
                        (when (and (fboundp 'backtrace-get-frames)
                                   (fboundp 'backtrace-to-string))
                          (backtrace-to-string (backtrace-get-frames 'backtrace))))
                       (org-element-cache-reset)
                       (org-element--parse-to pom)))))
    (when (and (org-element--cache-active-p)
               element
               (org-element--cache-verify-element element))
      (setq element (org-element--parse-to pom)))
    (unless (eq 'org-data (org-element-type element))
      (unless (and cached-only
                   (not (and element
                             (or (= pom (org-element-property :begin element))
                                 (and (not (memq (org-element-type element) org-element-greater-elements))
                                      (>= pom (org-element-property :begin element))
                                      (< pom (org-element-property :end element)))
                                 (and (org-element-property :contents-begin element)
                                      (>= pom (org-element-property :begin element))
                                      (< pom (org-element-property :contents-begin element)))
                                 (and (not (org-element-property :contents-end element))
                                      (>= pom (org-element-property :begin element))
                                      (< pom (org-element-property :end element)))))))
        (if (not (eq (org-element-type element) 'section))
            element
          (org-element-at-point (1+ pom) cached-only))))))