lib/template/template.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #     http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # Basic template system
  16 #
  17 # The recommended usage of this framework is to define specific subclasses of
  18 # Template to provide structural elements on the final document
  19 module template
  20
  21 # Templates are simple hierarchical pieces of text used for efficient stream writing.
  22 #
  23 # # Efficient stream writing
  24 #
  25 # Templates are more efficient than ever-growing buffers with useless concatenation
  26 # and more usable and maintainable than manual arrays of strings.
  27 #
  28 # The `add` method (and its variations) is used to append new content (like string or
  29 # other templates) to a template object.
  30 #
  31 # Eventually, the `write_to` method (and its variations) is used to write the complete
  32 # content of a template in streams (and files, and strings).
  33 #
  34 #     var tmpl = new Template
  35 #     tmpl.add("A")
  36 #     tmpl.add("B")
  37 #     tmpl.add("C")
  38 #     assert tmpl.write_to_string == "ABC"
  39 #
  40 # # Non-linear system with sub-templates.
  41 #
  42 # A template is made of a mix of string, sub-templates and other `Writable` objects.
  43 # A sub-template can be constructed independently of its usages, thus simplifying
  44 # the high-level logic.
  45 # A single sub-template can be used more than once.
  46 #
  47 #     var main = new Template
  48 #     var sub = new Template
  49 #     sub.add("1")
  50 #     main.add("A")
  51 #     main.add(sub)
  52 #     main.add("B")
  53 #     main.add(sub)
  54 #     main.add("C")
  55 #     sub.add("2")
  56 #     assert main.write_to_string == "A12B12C"
  57 #
  58 # See also the `new_sub` method.
  59 #
  60 # # Specific high-level templates
  61 #
  62 # The advanced, and recommended way, is to subclass Template and provide an autonomous
  63 # structural template with its specific attributes and templating logic.
  64 #
  65 # In such a subclass, the full logic is provided by the `rendering` method that will
  66 # be automatically and lazily invoked.
  67 #
  68 #     class LnkTmpl
  69 #         super Template
  70 #         var text: Writable
  71 #         var title: nullable String
  72 #         var href: String
  73 #         redef fun rendering do
  74 #             add """<a href="{{{href.html_escape}}}""""
  75 #             if title != null then add """ title="{{{title.html_escape}}}""""
  76 #             add ">"
  77 #             add text
  78 #             add "</a>"
  79 #         end
  80 #         # ...
  81 #     end
  82 #     var l = new LnkTmpl("hello world", null, "hello.png")
  83 #     assert l.write_to_string == """<a href="hello.png">hello world</a>"""
  84 #
  85 class Template
  86         super Writable
  87
  88         # Service used to render the content of the template.
  89         #
  90         # Do nothing by default but subclasses should put all their specific
  91         # templating code in this method to regroup and simplify their logic
  92         #
  93         # Note: to avoid inconsistencies, the template is automatically frozen
  94         # (see `freeze`) after the invocation of `rendering`.
  95         protected fun rendering do end
  96
  97         # Append an element (`String`, other `Template`, etc.) at the end of the template.
  98         #
  99         # Should be either used externally to act on basic templates,
 100         # or internally in the `rendering` method of specific templates.
 101         #
 102         # Mixing the internal and external uses should be avoided because
 103         # the final behavior will depend on the lazy invocation of `rendering`.
 104         #
 105         #     var t = new Template
 106         #     t.add("1")
 107         #     t.add("2")
 108         #     assert t.write_to_string == "12"
 109         fun add(element: Writable) do
 110                 assert not is_frozen
 111                 content.add element
 112         end
 113
 114         # Append `element` and the end of the template then append a "\n".
 115         #
 116         #     var t = new Template
 117         #     t.addn("1")
 118         #     t.addn("2")
 119         #     assert t.write_to_string == "1\n2\n"
 120         fun addn(element: Writable) do
 121                 add element
 122                 add "\n"
 123         end
 124
 125         # Append a bunch of elements at the end of the template.
 126         # See `add`.
 127         #
 128         #     var t = new Template
 129         #     t.add_all(["1", "2"])
 130         #     assert t.write_to_string == "12"
 131         fun add_all(elements: Collection[Writable]) do content.add_all elements
 132
 133         # Append a bunch of elements at the end of the template with separations.
 134         # see `add`.
 135         #
 136         #      var t = new Template
 137         #      t.add_list(["1", "2", "3"], ", ", " and ")
 138         #      assert t.write_to_string == "1, 2 and 3"
 139         fun add_list(elements: Collection[Writable], sep, last_sep: Writable) do
 140                 var last = elements.length - 2
 141                 var i = 0
 142                 for e in elements do
 143                         content.add e
 144                         if i < last then
 145                                 content.add sep
 146                         else if i == last then
 147                                 content.add last_sep
 148                         end
 149                         i += 1
 150                 end
 151         end
 152
 153         # Is the template allowing more modification (`add`)
 154         var is_frozen = false
 155
 156         # Disable further modification: no more `add` is allowed
 157         fun freeze
 158         do
 159                 if is_frozen then return
 160                 is_frozen = true
 161         end
 162
 163         # Return a new basic template that is automatically added in `self` (using `add`)
 164         #
 165         # This is an easy way to provide a free insertion point in an existing template.
 166         #
 167         #     var t = new Template
 168         #     t.add("""void main(void) {""")
 169         #     var tdecl = t.new_sub # used to group declarations
 170         #     tdecl.add("int i; ")
 171         #     t.add("i = 1; ")
 172         #     tdecl.add("int j; ")
 173         #     t.add("j = i + 1; ")
 174         #     t.add("\}")
 175         #     assert t.write_to_string == """void main(void) {int i; int j; i = 1; j = i + 1; }"""
 176         fun new_sub: Template
 177         do
 178                 var res = new Template
 179                 add res
 180                 return res
 181         end
 182
 183         # Each sub-elements
 184         private var content = new Array[Writable]
 185
 186         # Flag to avoid multiple rendering
 187         private var render_done = false
 188
 189         # Call rendering, if not already done
 190         # Then freeze the template
 191         #
 192         # This method is only required in corner-cases since
 193         # `rendering` is automatically called when needed.
 194         fun force_render
 195         do
 196                 if render_done then return
 197                 render_done = true
 198                 rendering
 199                 freeze
 200         end
 201
 202         # Do the full rendering and write the final content to a stream
 203         redef fun write_to(stream: Writer)
 204         do
 205                 assert not is_writing
 206                 is_writing = true
 207                 force_render
 208                 for e in content do
 209                         e.write_to(stream)
 210                 end
 211                 is_writing = false
 212         end
 213
 214         # Flag to avoid infinite recursivity if a template contains itself
 215         private var is_writing = false
 216 end