ox: Add generic function to retrieve the date of a document

* lisp/ox.el (org-export-date-timestamp-format): New variable.
(org-export-get-date): New function.
* testing/lisp/test-ox.el: Add tests.

2 files changed, 71 insertions, 0 deletions

diff --git a/lisp/ox.el b/lisp/ox.el
index a2aa33d..ac76e50 100644
--- a/lisp/ox.el
+++ b/lisp/ox.el
@@ -369,6 +369,19 @@ If the value is `comment' insert it as a comment."
 This options can also be set with the OPTIONS keyword,
 e.g. \"date:nil\".")
 
+(defcustom org-export-date-timestamp-format nil
+  "Time-stamp format string to use for DATE keyword.
+
+The format string, when specified, only applies if date consists
+in a single time-stamp.  Otherwise its value will be ignored.
+
+See `format-time-string' for details on how to build this
+string."
+  :group 'org-export-general
+  :type '(choice
+	  (string :tag "Time-stamp format string")
+	  (const :tag "No format string" nil)))
+
 (defcustom org-export-creator-string
   (format "Generated by Org mode %s in Emacs %s."
 	  (if (fboundp 'org-version) (org-version) "(Unknown)")
@@ -3670,6 +3683,32 @@ INFO is a plist used as a communication channel."
   (not (org-export-get-next-element headline info)))
 
 
+;;;; For Keywords
+;;
+;; `org-export-get-date' returns a date appropriate for the document
+;;  to about to be exported.  In particular, it takes care of
+;;  `org-export-date-timestamp-format'.
+
+(defun org-export-get-date (info &optional fmt)
+  "Return date value for the current document.
+
+INFO is a plist used as a communication channel.  FMT, when
+non-nil, is a time format string that will be applied on the date
+if it consists in a single timestamp object.  It defaults to
+`org-export-date-timestamp-format' when nil.
+
+A proper date can be a secondary string, a string or nil.  It is
+meant to be translated with `org-export-data' or alike."
+  (let ((date (plist-get info :date))
+	(fmt (or fmt org-export-date-timestamp-format)))
+    (cond ((not date) nil)
+	  ((and fmt
+		(not (cdr date))
+		(eq (org-element-type (car date)) 'timestamp))
+	   (org-timestamp-format (car date) fmt))
+	  (t date))))
+
+
 ;;;; For Links
 ;;
 ;; `org-export-solidify-link-text' turns a string into a safer version
diff --git a/testing/lisp/test-ox.el b/testing/lisp/test-ox.el
index 46f36eb..1acc4e1 100644
--- a/testing/lisp/test-ox.el
+++ b/testing/lisp/test-ox.el
@@ -1292,6 +1292,38 @@ Paragraph[fn:1]"
 
 
 
+;;; Keywords
+
+(ert-deftest test-org-export/get-date ()
+  "Test `org-export-get-date' specifications."
+  ;; Return a properly formatted string when
+  ;; `org-export-date-timestamp-format' is non-nil and DATE keyword
+  ;; consists in a single timestamp.
+  (should
+   (equal "29 03 2012"
+	  (let ((org-export-date-timestamp-format "%d %m %Y"))
+	    (org-test-with-parsed-data "#+DATE: <2012-03-29 Thu>"
+	      (org-export-get-date info)))))
+  ;; Return a secondary string otherwise.
+  (should-not
+   (stringp
+    (let ((org-export-date-timestamp-format nil))
+      (org-test-with-parsed-data "#+DATE: <2012-03-29 Thu>"
+	(org-export-get-date info)))))
+  (should
+   (equal '("Date")
+	  (org-test-with-parsed-data "#+DATE: Date"
+	    (org-export-get-date info))))
+  ;; Optional argument has precedence over
+  ;; `org-export-date-timestamp-format'.
+  (should
+   (equal "29 03"
+	  (let ((org-export-date-timestamp-format "%d %m %Y"))
+	    (org-test-with-parsed-data "#+DATE: <2012-03-29 Thu>"
+	      (org-export-get-date info "%d %m"))))))
+
+
+
 ;;; Links
 
 (ert-deftest test-org-export/get-coderef-format ()