✨ choose a template engine based on its file extension. fix #47 (#63)

* ✨ choose a template based on its file extension. fix #43

* 📚 update change log

* 🐛 fix the template names

* 📚 udpate readme

* ✨ default template engine will be jinja2 if template type(file extension) cannot be found

* 👕 address review feedback. #61

* 🎨 keep cli --template_type option

* ✨ allow template_type in moban file to indicate default template engine. i.e. if unknown template type(file suffix) is found, the default template engine is used. So if mako engine is specified via template_type, an unknown template file such as strange.template will be rendered by mako engine

* ✨ allow jinja2 become template suffix too, meaning a.jj2 and b.jinja2 will be rendered by the same engine. however, for now, the engine instance will not be the same. later on, this can be consolidated

* 📚 update change log. #58

* ✨ associate jinja2 engine with more file types, j2, jinja and retore the default template engine name as jinja2

* 📚 documentation update

.moban.cd/changelog.yml

@@ -2,11 +2,13 @@ name: moban
 organisation: moremoban
 releases:
 - changes:
-  - action: Updated
+  - action: Added
     details:
     - '`#18`: file exists test'
     - "`#23`: custom jinja plugins"
     - '`#26`: repr filter'
+    - "`#47`: allow the expansion of template engine"
+    - "`#58`: allow template type per template"
   date: unreleased
   version: 0.2.0
 - changes:

CHANGELOG.rst

@@ -4,12 +4,16 @@ Change log
 0.2.0 - unreleased
 --------------------------------------------------------------------------------
 
-Updated
+Added
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 #. `#18 <https://github.com/moremoban/moban/issues/18>`_: file exists test
 #. `#23 <https://github.com/moremoban/moban/issues/23>`_: custom jinja plugins
 #. `#26 <https://github.com/moremoban/moban/issues/26>`_: repr filter
+#. `#47 <https://github.com/moremoban/moban/issues/47>`_: allow the expansion of
+   template engine
+#. `#58 <https://github.com/moremoban/moban/issues/58>`_: allow template type
+   per template
 
 0.1.4 - 29-May-2018
 --------------------------------------------------------------------------------

README.rst

@@ -74,35 +74,34 @@ moban.output will contain::
 Usage
 ================================================================================
 
-usage: moban [-h] [-cd CONFIGURATION_DIR] [-c CONFIGURATION]
-             [-td [TEMPLATE_DIR [TEMPLATE_DIR ...]]] [-t TEMPLATE]
-             [--template_type TEMPLATE_TYPE] [-o OUTPUT] [-f] [-m MOBANFILE]
-
-Yet another jinja2 cli command for static text generation
-
-
-optional arguments
---------------------------------------------------------------------------------
-
-* `-h, --help`
-  show this help message and exit
-* `-cd CONFIGURATION_DIR --configuration_dir CONFIGURATION_DIR`
-  the directory for configuration file lookup
-* `-c CONFIGURATION, --configuration CONFIGURATION`
-  the dictionary file
-* `-td [TEMPLATE_DIR [TEMPLATE_DIR ...]], --template_dir [TEMPLATE_DIR [TEMPLATE_DIR ...]]`
-  the directories for template file lookup
-* `-t TEMPLATE, --template TEMPLATE`
-  the template file
-* `--template_type TEMPLATE_TYPE`
-  the template type, default is jinja2
-* `-o OUTPUT, --output OUTPUT`
-  the output file
-* `-f`
-  force moban to template all files despite of .moban.hashes
-* `-m MOBANFILE, --mobanfile MOBANFILE`
-  custom moban file
-
+::
+
+
+   usage: moban [-h] [-cd CONFIGURATION_DIR] [-c CONFIGURATION]
+                [-td [TEMPLATE_DIR [TEMPLATE_DIR ...]]] [-t TEMPLATE] [-o OUTPUT]
+                [-f] [-m MOBANFILE]
+   
+   Yet another jinja2 cli command for static text generation
+   
+   optional arguments:
+     -h, --help            show this help message and exit
+     -cd CONFIGURATION_DIR, --configuration_dir CONFIGURATION_DIR
+                           the directory for configuration file lookup
+     -c CONFIGURATION, --configuration CONFIGURATION
+                           the dictionary file
+     -td [TEMPLATE_DIR [TEMPLATE_DIR ...]], --template_dir [TEMPLATE_DIR [TEMPLATE_DIR ...]]
+                           the directories for template file lookup
+     -t TEMPLATE, --template TEMPLATE
+                           the template file
+     -o OUTPUT, --output OUTPUT
+                           the output file
+     --template_type TEMPLATE_TYPE
+                           the template type, default is jinja2
+     -f                    force moban to template all files despite of
+                           .moban.hashes
+     -m MOBANFILE, --mobanfile MOBANFILE
+                           custom moban file
+   
 
 exit codes
 --------------------------------------------------------------------------------
@@ -111,7 +110,7 @@ exit codes
 - 1 : has changes
 - 2 : error occured
 
-Special Filters
+Built-in Filters
 ================================================================================
 
 split_length
@@ -152,3 +151,16 @@ Here is Grammar in the changelog.yml::
 
 More details can be found in `moban's changelog.yml <https://github.com/moremoban/moban/blob/master/.moban.cd/changelog.yml#L10>`_
 
+`repr`
+--------------------------------------------------------------------------------
+
+Returns a single quoted string in the templated file
+
+
+Built-in Tests
+================================================================================
+
+`exists`
+--------------------------------------------------------------------------------
+
+Test if a file exists or not

docs/engine.uml

@@ -0,0 +1,23 @@
+@startuml
+
+package "moban" {
+[engine factory]
+[jinja2 engine]
+}
+
+[lml]
+
+package "moban-mako" {
+[mako engine]
+}
+
+package "moban-haml" {
+[haml engine]
+}
+
+[engine factory] -> [lml] : get all engines
+[lml] <-- [jinja2 engine] : register
+[lml] <.. [mako engine] : register
+[lml] <.. [haml engine] : register
+
+@enduml

docs/extension.rst

@@ -1,6 +1,6 @@
 Development guide
 =======================
-
+                   
 Jinja2 extensions for Moban
 ------------------------------
 
@@ -14,19 +14,39 @@ your plugins will NOT be loaded.
 Jinja2 Filter
 *******************
 
-.. literalinclude:: ../../moban/filters/repr.py
+.. literalinclude:: ../moban/filters/repr.py
 
 
 Jinja2 Test
 *******************
 
-.. literalinclude:: ../../moban/tests/files.py
+.. literalinclude:: ../moban/tests/files.py
 
 Jinja2 Globals
 *******************
 
-.. literalinclude:: ../../tests/test_engine.py
+.. literalinclude:: ../tests/test_engine.py
    :lines: 49-61
 
 It is possible to write an installable package including your own jinja2
 filters, tests and globals. Please email me for more details.
+
+Template engine extension for Moban
+--------------------------------------------------------------------------------
+
+moban version 0.2 started using `lml`_ to employ loose couple plugins. Other
+template engines, such as marko, haml can be plugged into moban seamless.
+
+.. image:: engine.png
+
+In order plugin other template engines, it is to write a lml plugin. The following
+is an example starting point for any template engine.
+
+.. literalinclude:: ../tests/moban-mako/moban_mako/__init__.py
+
+After you will have finished the engine plugin, you can either place it in `plugin_dir`
+in order to get it loaded, or make an installable python package. In the latter case,
+please refer to `yehua`_: doing that in less than 5 minutes.
+
+.. _lml: http://lml.readthedocs.io
+.. _yehua: http://yehua.readthedocs.io

docs/level-4-single-command/.moban.yml

@@ -1,2 +1,2 @@
 targets:
-  - a.output: a.template
+  - a.output: a.template.jj2

docs/level-5-custom-configuration/.moban.yml

@@ -5,4 +5,4 @@ configuration:
     - cool-templates
     - '.'
 targets:
-  - a.output: a.template
+  - a.output: a.template.jj2

docs/level-6-complex-configuration/.moban.yml

@@ -4,9 +4,9 @@ configuration:
     - custom-templates
     - cool-templates
     - '.'
-  template: a.template
+  template: a.template.jj2
 targets:
   - output: a.output
     configuration: data.yml
   - output: a.output2
-    configuration: data2.yml
+    configuration: data2.yml

docs/level-6-complex-configuration/cool-templates/base.jj2

@@ -5,7 +5,7 @@
 
 {{nihao}}
 
-{%include 'cool.template'%}
+{%include 'cool.template.jj2'%}
 
 {%block footer %}
-{%endblock%}
+{%endblock%}

docs/level-7-use-custom-jinja2-filter-test-n-global/.moban.yml

@@ -7,4 +7,4 @@ configuration:
 targets:
   - filter.output: filter.jj2
   - test.output: test.jj2
-  - global.output: global.jj2
+  - global.output: global.jj2

docs/level-7-use-custom-jinja2-filter-test-n-global/README.rst

@@ -4,7 +4,6 @@ Level 7: Custom jinja filters, tests and globals
 Level 7 example demonstrates advanced plugin capabilities of moban. The following
 moban file had `plugin_dir` specified::
 
-
     configuration:
       template_dir:
         - my-templates
@@ -42,4 +41,3 @@ Here is the command to launch it:
    Everything is up to date!
 
 Please examine individual template and its associated plugin for more details.
-

docs/level-7-use-custom-jinja2-filter-test-n-global/filter.output

@@ -1 +1 @@
-YWJj
+YWJj

docs/level-7-use-custom-jinja2-filter-test-n-global/my-templates/filter.jj2

@@ -1 +1 @@
-{{ 'abc' | base64encode }}
+{{ 'abc' | base64encode }}

docs/level-7-use-custom-jinja2-filter-test-n-global/my-templates/test.jj2

@@ -8,4 +8,4 @@ Hello, you are not in {{level}}
 Hello, you are in level 7 example
 {% else %}
 Hello, you are not in level 7
-{% endif %}
+{% endif %}

moban/constants.py

@@ -75,3 +75,5 @@
 JINJA_FILTER_EXTENSION = "jinja_filter"
 JINJA_TEST_EXTENSION = "jinja_test"
 JINJA_GLOBALS_EXTENSION = "jinja_globals"
+
+TEMPLATE_ENGINE_EXTENSION = "template_engine"

moban/engine.py

@@ -3,6 +3,7 @@
 from collections import defaultdict
 from jinja2 import Environment, FileSystemLoader
 
+from lml.plugin import PluginManager, PluginInfo
 from lml.loader import scan_plugins
 
 from moban.hashstore import HashStore
@@ -24,25 +25,33 @@
 _FILTERS = JinjaFilterManager()
 _TESTS = JinjaTestManager()
 _GLOBALS = JinjaGlobalsManager()
-scan_plugins("moban_", "moban", None, BUILTIN_EXENSIONS)
 
 
-class EngineFactory(object):
+class EngineFactory(PluginManager):
+    def __init__(self):
+        super(EngineFactory, self).__init__(
+            constants.TEMPLATE_ENGINE_EXTENSION
+        )
 
-    @staticmethod
-    def get_engine(template_type):
-        if template_type == constants.DEFAULT_TEMPLATE_TYPE:
-            return Engine
-        else:
-            try:
-                external_engine = utils.load_external_engine(template_type)
-            except ImportError:
-                raise exceptions.NoThirdPartyEngine(
-                    constants.MESSAGE_NO_THIRD_PARTY_ENGINE
-                )
-            return external_engine.get_engine(template_type)
+    def get_engine(self, template_type):
+        return self.load_me_now(template_type)
+
+    def all_types(self):
+        return list(self.registry.keys())
+
+    def raise_exception(self, key):
+        raise exceptions.NoThirdPartyEngine(key)
+
+
+ENGINES = EngineFactory()
+
+scan_plugins("moban_", "moban", None, BUILTIN_EXENSIONS)
 
 
+@PluginInfo(
+    constants.TEMPLATE_ENGINE_EXTENSION,
+    tags=['jinja2', 'jinja', 'jj2', 'j2']
+)
 class Engine(object):
 
     def __init__(self, template_dirs, context_dirs):

moban/main.py

@@ -14,7 +14,7 @@
 
 from moban.utils import merge, open_yaml
 from moban.hashstore import HashStore
-from moban.engine import EngineFactory
+from moban.engine import ENGINES
 import moban.constants as constants
 import moban.mobanfile as mobanfile
 import moban.exceptions as exceptions
@@ -131,7 +131,7 @@ def handle_command_line(options):
     options = merge(options, constants.DEFAULT_OPTIONS)
     if options[constants.LABEL_TEMPLATE] is None:
         raise exceptions.NoTemplate(constants.ERROR_NO_TEMPLATE)
-    engine_class = EngineFactory.get_engine(
+    engine_class = ENGINES.get_engine(
         options[constants.LABEL_TEMPLATE_TYPE]
     )
     engine = engine_class(