Implement `org-export-excluded-from-toc-p'

* lisp/ox.el (org-export-excluded-from-toc-p): New function.

* testing/lisp/test-ox.el (test-org-export/excluded-from-toc-p): New
  test.

3 files changed, 38 insertions, 0 deletions

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 86c253d..1076dd9 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -108,6 +108,12 @@ you should expect to see something like:
   ,#+STARTUP: shrink
 #+END_EXAMPLE
 
+** New functions
+
+*** ~org-export-excluded-from-toc-p~
+
+See docstring for details.
+
 ** Miscellaneous
 
 *** ~org-publish-resolve-external-link~ accepts a new optional argument.
diff --git a/lisp/ox.el b/lisp/ox.el
index 739c084..953a723 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -5288,6 +5288,21 @@ INFO is a plist used as a communication channel.
 Return a list of src-block elements with a caption."
   (org-export-collect-elements 'src-block info))
 
+(defun org-export-excluded-from-toc-p (headline info)
+  "Non-nil if HEADLINE should be excluded from tables of contents.
+
+INFO is a plist used as a communication channel.
+
+Note that such headlines are already excluded from
+`org-export-collect-headlines'.  Therefore, this function is not
+necessary if you only need to list headlines in the table of
+contents.  However, it is useful if some additional processing is
+required on headlines excluded from table of contents."
+  (or (org-element-property :footnote-section-p headline)
+      (org-export-low-level-p headline info)
+      (cl-some (lambda (h) (equal "notoc" (org-element-property :UNNUMBERED h)))
+	       (org-element-lineage headline nil t))))
+
 (defun org-export-toc-entry-backend (parent &rest transcoders)
   "Return an export back-end appropriate for table of contents entries.
 
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 0906d18..fa5ee6a 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -4344,6 +4344,23 @@ Another text. (ref:text)
 	      (mapcar (lambda (h) (org-element-property :raw-value h))
 		      (org-export-collect-headlines info 1 scope)))))))
 
+(ert-deftest test-org-export/excluded-from-toc-p ()
+  "Test `org-export-excluded-from-toc-p' specifications."
+  (should-not
+   (org-test-with-parsed-data "* H1"
+     (org-element-map tree 'headline
+       (lambda (h) (org-export-excluded-from-toc-p h info)) info t)))
+  (should
+   (org-test-with-parsed-data "* H1\n:PROPERTIES:\n:UNNUMBERED: notoc\n:END:"
+     (org-element-map tree 'headline
+       (lambda (h) (org-export-excluded-from-toc-p h info)) info t)))
+  (should
+   (equal '(in out)
+	  (org-test-with-parsed-data "#+OPTIONS: H:1\n* H1\n** H2"
+	    (org-element-map tree 'headline
+	      (lambda (h) (if (org-export-excluded-from-toc-p h info) 'out 'in))
+	      info)))))
+
 (ert-deftest test-org-export/toc-entry-backend ()
   "Test `org-export-toc-entry-backend' specifications."
   ;; Ignore targets.