org-element: Implement `org-element-extract-element'

* lisp/org-element.el (org-element-extract-element): New function.
* testing/lisp/test-org-element.el (test-org-element/extract-element):
  New test.

lisp/org-element.el

@@ -459,6 +459,22 @@ Return parent element."
   ;; Return modified PARENT element.
   (or parent children))
 
+(defun org-element-extract-element (element)
+  "Extract ELEMENT from parse tree.
+Remove element from the parse tree by side-effect, and return it
+with its `:parent' property stripped out."
+  (let ((parent (org-element-property :parent element))
+	(secondary (org-element-secondary-p element)))
+    (if secondary
+        (org-element-put-property
+	 parent secondary
+	 (delq element (org-element-property secondary parent)))
+      (apply #'org-element-set-contents
+	     parent
+	     (delq element (org-element-contents parent))))
+    ;; Return ELEMENT with its :parent removed.
+    (org-element-put-property element :parent nil)))
+
 
 
 ;;; Greater elements

testing/lisp/test-org-element.el

@@ -179,6 +179,54 @@ Some other text
 	      (org-element-contents
 	       (org-element-map tree 'bold 'identity nil t)))))))
 
+(ert-deftest test-org-element/extract-element ()
+  "Test `org-element-extract-element' specifications."
+  ;; Extract a greater element.
+  (should
+   (equal '(org-data nil)
+	  (org-test-with-temp-text "* Headline"
+	    (let* ((tree (org-element-parse-buffer))
+		   (element (org-element-map tree 'headline 'identity nil t)))
+	      (org-element-extract-element element)
+	      tree))))
+  ;; Extract an element.
+  (should-not
+   (org-element-map
+       (org-test-with-temp-text "Paragraph"
+	 (let* ((tree (org-element-parse-buffer))
+		(element (org-element-map tree 'paragraph 'identity nil t)))
+	   (org-element-extract-element element)
+	   tree))
+       'paragraph
+     'identity))
+  ;; Extract an object, even in a secondary string.
+  (should-not
+   (org-element-map
+       (org-test-with-temp-text "*bold*"
+	 (let* ((tree (org-element-parse-buffer))
+		(element (org-element-map tree 'bold 'identity nil t)))
+	   (org-element-extract-element element)
+	   tree))
+       'bold
+     'identity))
+  (should-not
+   (org-element-map
+       (org-test-with-temp-text "* Headline *bold*"
+	 (let* ((tree (org-element-parse-buffer))
+		(element (org-element-map tree 'bold 'identity nil t)))
+	   (org-element-extract-element element)
+	   tree))
+       'bold
+     'identity))
+  ;; Return value doesn't have any :parent set.
+  (should-not
+   (org-element-property
+    :parent
+    (org-test-with-temp-text "* Headline\n  Paragraph with *bold* text."
+      (let* ((tree (org-element-parse-buffer))
+	     (element (org-element-map tree 'bold 'identity nil t)))
+	(org-element-extract-element element))))))
+
 
 
 ;;; Test Parsers