Merge pull request andras-simonyi#113 from andras-simonyi/111-Add_pos…

…tprocessing_hooks

111 add postprocessing hooks

README.md

@@ -21,6 +21,7 @@ A CSL 1.0.2 Citation Processor for Emacs.
     - [Rendering citations and bibliographies](#rendering-citations-and-bibliographies)
 	- [Rendering isolated references](#rendering-isolated-references)
 	- [Supported output formats](#supported-output-formats)
+	- [Hooks](#hooks)
 - [License](#license)
 
 ## Introduction
@@ -273,6 +274,27 @@ export), `csl-test` (for the CSL test suite) and `raw` (internal rich-text
 format, for debugging) are supported as output formats. New ones can easily be
 added — see `citeproc-formatters.el` for examples.
 
+### Hooks
+
+citeproc-el provides the following hook variables:
+
+#### citeproc-citation-postprocess-functions
+A list of functions to postprocess rendered citations. Each function takes a
+single argument, a rich-text, and returns a post-processed rich-text value. The
+functions are applied in the order they appear in the list.
+
+#### citeproc-name-postprocess-functions
+A list of functions to postprocess rendered names.
+Each function takes three arguments:
+
+- the rich-text rendering of a name to be postprocessed,
+- the rendered name as an alist with CSL name-part
+  keys (`family`, `given` etc.), and
+- the rendering context, as a `citeproc-context` structure.
+
+The output of each function should be the postprocessed rich-text, and
+the functions are applied in the order they appear in the list.
+
 -------------------------------------------------------------------------------
 
 ## License

citeproc-cite.el

@@ -68,6 +68,12 @@ GROUPED is used internally to indicate whether the cites were
   "Alist mapping citation modes to corresponding cite-level
 key-value pair representations.")
 
+(defvar citeproc-citation-postprocess-functions nil
+  "A list of functions to postprocess rendered citations.
+Each function takes a single argument, a rich-text, and returns a
+post-processed rich-text value. The functions are applied in the
+order they appear in the list.")
+
 (defun citeproc-cite--varlist (cite)
   "Return the varlist belonging to CITE."
   (let* ((itd (alist-get 'itd cite))
@@ -193,8 +199,9 @@ For the optional INTERNAL-LINKS argument see
 	;; Prepend author to textual citations
 	(when (eq (citeproc-citation-mode c) 'textual)
 	  (let* ((first-elt (car cites)) ;; First elt is either a cite or a cite group.
-		 ;; If the latter then we need to locate the first cite as the
-		 ;; 2nd element of the first cite group.
+		 ;; If the latter then we need to locate the
+		 ;; first cite as the 2nd element of the first
+		 ;; cite group.
 		 (first-cite (if (eq 'group (car first-elt))
 				 (cadr first-elt)
 			       first-elt))
@@ -206,9 +213,12 @@ For the optional INTERNAL-LINKS argument see
 		       (alist-get 'stopped-rendering (car rendered-author)))
 	      (setq result `(nil ,rendered-author " " ,result)))))
 	;; Capitalize first
-	(if (citeproc-citation-capitalize-first c)
-	    (citeproc-rt-change-case result #'citeproc-s-capitalize-first)
-	  result)))))
+	(when (citeproc-citation-capitalize-first c)
+	  (setq result (citeproc-rt-change-case result #'citeproc-s-capitalize-first)))
+	;; Run the citation postprocessing hook
+	(dolist (fn citeproc-citation-postprocess-functions)
+	  (setq result (funcall fn result)))
+	result))))
 
 (defun citeproc-cites--collapse-indexed (cites index-getter no-span-pred)
   "Collapse continuously indexed cites in CITES.

citeproc-name.el

@@ -36,6 +36,17 @@
 (require 'citeproc-context)
 (require 'citeproc-term)
 
+(defvar citeproc-name-postprocess-functions nil
+  "A list of functions to postprocess rendered names.
+Each function takes three arguments:
+- the rich-text rendering of a name to be post-processed,
+- the rendered name as an alist with CSL name-part
+  keys (`family', `given' etc.), and
+- the rendering context, as a `citeproc-context' structure.
+The output of each function should be the post-processed
+rich-text, and the functions are applied in the order they appear
+in the list.")
+
 ;; OPTIMIZE: Name count could be sped up by only counting the names to be
 ;; rendered without actually rendering them
 (defun citeproc-name-render-vars
@@ -208,15 +219,18 @@ Nature."
 
 (defun citeproc-name--render (name attrs name-part-attrs sort-o context)
   "Render NAME according to the given attributes."
-  (let ((format-attrs
-	 (--filter (memq (car it) (-concat '(prefix suffix) citeproc-rt-format-attrs))
-		   attrs)))
-    (citeproc-rt-format-single
-     (cons `(name-id . ,(alist-get 'name-id name)) format-attrs)
-     (citeproc-name--render-formatted
-      (citeproc-name--format-nameparts name name-part-attrs context)
-      attrs sort-o context)
-     context)))
+  (let* ((format-attrs
+	  (--filter (memq (car it) (-concat '(prefix suffix) citeproc-rt-format-attrs))
+		    attrs))
+	 (result (citeproc-rt-format-single
+		  (cons `(name-id . ,(alist-get 'name-id name)) format-attrs)
+		  (citeproc-name--render-formatted
+		   (citeproc-name--format-nameparts name name-part-attrs context)
+		   attrs sort-o context)
+		  context)))
+    (dolist (fn citeproc-name-postprocess-functions)
+      (setq result (funcall fn result name context)))
+    result)) 
 
 (defun citeproc-name--parts-w-sep (c1 c2 sep context)
   "Join name-parts in lists C1 C2 with spaces and then with SEP."

test/expected_fails.lst

@@ -154,6 +154,7 @@ citeproc-suite-number-new-ordinals-with-gender-change
 citeproc-suite-number-ordinal-spacing
 citeproc-suite-number-plain-hyphen-or-en-dash-always-plural
 citeproc-suite-number-separate-ordinal-namespaces
+citeproc-suite-page-chicago16
 citeproc-suite-position-first-true-only-once
 citeproc-suite-position-ibid-in-text
 citeproc-suite-position-ibid-with-locator