Add Extension.on_frontmatter_loaded handler.

docs/extensions.rst

@@ -18,6 +18,7 @@ Extensions are never directly called,
 but an extension can connect to one of handroll's :ref:`signals`.
 
 .. autoclass:: handroll.extensions.base.Extension
+   :members:
 
 Extension authors can include new extensions by adding to the
 ``handroll.extensions`` entry point. For example, handroll includes

handroll/extensions/base.py

@@ -1,5 +1,31 @@
 # Copyright (c) 2015, Matt Layman
 
+from handroll import signals
+
 
 class Extension(object):
     """A base extension which hooks handler methods to handroll's signals."""
+
+    handle_frontmatter_loaded = False
+
+    def __init__(self):
+        # Handler functions are put in a dictionary to keep references to them.
+        # Blinker behaves in strange ways without the references.
+        self._handlers = {}
+
+        if self.handle_frontmatter_loaded:
+            def _handle_frontmatter_loaded(source_file, **kwargs):
+                self.on_frontmatter_loaded(source_file, kwargs['frontmatter'])
+            self._handlers['frontmatter_loaded'] = _handle_frontmatter_loaded
+            signals.frontmatter_loaded.connect(_handle_frontmatter_loaded)
+
+    def on_frontmatter_loaded(self, source_file, frontmatter):
+        """Handle the ``frontmatter_loaded`` signal.
+
+        Activate this handler by setting ``handle_frontmatter_loaded``
+        to ``True`` in the extension subclass.
+
+        :param source_file: Absolute path of the source file
+        :param frontmatter: Dictionary of parsed frontmatter
+        """
+        raise NotImplementedError

handroll/tests/test_extensions.py

@@ -1,5 +1,9 @@
 # Copyright (c) 2015, Matt Layman
 
+import mock
+
+from handroll import signals
+from handroll.extensions.base import Extension
 from handroll.extensions.blog import BlogExtension
 from handroll.extensions.loader import ExtensionLoader
 from handroll.tests import TestCase
@@ -11,3 +15,19 @@ def test_loads_available_extensions(self):
         loader = ExtensionLoader()
         loader.load()
         self.assertEqual(BlogExtension, loader._available_extensions['blog'])
+
+
+class TestExtension(TestCase):
+
+    @mock.patch('handroll.extensions.base.signals.frontmatter_loaded')
+    def test_frontmatter_loaded_connection_default(self, frontmatter_loaded):
+        Extension()
+        self.assertFalse(frontmatter_loaded.connect.called)
+
+    def test_connects_to_frontmatter_loaded(self):
+        Extension.handle_frontmatter_loaded = True
+        Extension()
+        self.assertRaises(
+            NotImplementedError, signals.frontmatter_loaded.send,
+            'a_source_file', frontmatter={})
+        Extension.handle_frontmatter_loaded = False