Function: org-element-create

org-element-create is a byte-compiled function defined in org-element-ast.el.gz.

Signature

(org-element-create TYPE &optional PROPS &rest CHILDREN)

Documentation

Create a new syntax node of TYPE.

Optional argument PROPS, when non-nil, is a plist defining the properties of the node. CHILDREN can be elements, objects or strings.

When CHILDREN is a single anonymous node, use its contents as children nodes. This way,
   (org-element-create 'section nil (org-element-contents node))
will yield expected results with contents of another node adopted into a newly created one.

When TYPE is plain-text, CHILDREN must contain a single node - string. Alternatively, TYPE can be a string. When TYPE is nil or anonymous, PROPS must be nil.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-element-ast.el.gz
;;;; Constructor and copier

(defun org-element-create (type &optional props &rest children)
  "Create a new syntax node of TYPE.
Optional argument PROPS, when non-nil, is a plist defining the
properties of the node.  CHILDREN can be elements, objects or
strings.

When CHILDREN is a single anonymous node, use its contents as children
nodes.  This way,
   (org-element-create \\='section nil (org-element-contents node))
will yield expected results with contents of another node adopted into
a newly created one.

When TYPE is `plain-text', CHILDREN must contain a single node -
string.  Alternatively, TYPE can be a string.  When TYPE is nil or
`anonymous', PROPS must be nil."
  (cl-assert (if (fboundp 'plistp) ; Emacs 29.1
                 (plistp props)
               (let ((len (proper-list-p props)))
                 (and len (cl-evenp len)))))
  ;; Assign parray.
  (when (and props (not (stringp type)) (not (eq type 'plain-text)))
    (let ((node (list 'dummy props)))
      (org-element--put-parray node)
      (setq props (nth 1 node))
      ;; Remove standard properties from PROPS plist by side effect.
      (let ((ptail props))
        (while ptail
          (if (not (and (keywordp (car ptail))
                        (org-element--property-idx (car ptail))))
              (setq ptail (cddr ptail))
            (if (null (cddr ptail)) ; last property
                (setq props (nbutlast props 2)
                      ptail nil)
              (setcar ptail (nth 2 ptail))
              (setcdr ptail (seq-drop ptail 3))))))))
  (pcase type
    ((or `nil `anonymous)
     (cl-assert (null props))
     (apply #'org-element-adopt nil children))
    (`plain-text
     (cl-assert (= (length children) 1))
     (org-add-props (car children) props))
    ((pred stringp)
     (if props (org-add-props type props) type))
    (_
     (if (and (= 1 (length children))
              (org-element-type-p (car children) 'anonymous))
         (apply #'org-element-adopt (list type props) (car children))
       (apply #'org-element-adopt (list type props) children)))))