lib/template/macro.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 # String templating using macros.
  16 #
  17 # There is plenty of macro/templating tools in the worl,
  18 # yet another one.
  19 #
  20 # See `TemplateString` for more details.
  21 module macro
  22
  23 import template
  24
  25 # Template with macros replacement.
  26 #
  27 # `TemplateString` provides a simple way to customize generic string templates
  28 # using macros and replacement.
  29 #
  30 # A macro is represented as a string identifier like `%MACRO%` in the template
  31 # string. Using `TemplateString`, macros can be replaced by any `Streamable` data:
  32 #
  33 #    var tpl = new TemplateString("Hello %NAME%!")
  34 #    tpl.replace("NAME", "Dave")
  35 #    assert tpl.write_to_string == "Hello Dave!"
  36 #
  37 # A macro identifier is valid if:
  38 #
  39 # * starts with an uppercase letter
  40 # * contains only numers, uppercase letters or '_'
  41 #
  42 # See `String::is_valid_macro_name` for more details.
  43 #
  44 # ## External template files
  45 #
  46 # When using large template files it's recommanded to use external template files.
  47 #
  48 # In external file `example.tpl`:
  49 #
  50 # ~~~html
  51 # <!DOCTYPE html>
  52 # <html lang="en">
  53 #  <head>
  54 #   <title>%TITLE%</title>
  55 #  </head>
  56 #  <body>
  57 #   <h1>%TITLE%</h1>
  58 #   <p>%ARTICLE%</p>
  59 #  </body>
  60 # </html>
  61 # ~~~
  62 #
  63 # Loading the template file using `TemplateString`:
  64 #
  65 #    var file = "example.tpl"
  66 #    if file.file_exists then
  67 #        tpl = new TemplateString.from_file("example.tpl")
  68 #        tpl.replace("TITLE", "Home Page")
  69 #        tpl.replace("ARTICLE", "Welcome on my site!")
  70 #    end
  71 #
  72 # ## Outputting
  73 #
  74 # Once macro replacement has been made, the `TemplateString` can be
  75 # output like any other `Template` using methods like `write_to`, `write_to_string`
  76 # or `write_to_file`.
  77 #
  78 #    tpl = new TemplateString("Hello %NAME%!")
  79 #    tpl.replace("NAME", "Dave")
  80 #    assert tpl.write_to_string == "Hello Dave!"
  81 #
  82 # ## Template correctness
  83 #
  84 # `TemplateString` can be outputed even if all macros were not replaced.
  85 # In this case, the name of the macro will be displayed wuthout any replacement.
  86 #
  87 #    tpl = new TemplateString("Hello %NAME%!")
  88 #    assert tpl.write_to_string == "Hello %NAME%!"
  89 #
  90 # The `check` method can be used to ensure that all macros were replaced before
  91 # performing the output. Warning messages will be stored in `warnings` and can
  92 # be used to locate unreplaced macros.
  93 #
  94 #    tpl = new TemplateString("Hello %NAME%!")
  95 #    if not tpl.check then
  96 #        assert not tpl.warnings.is_empty
  97 #        print "Cannot output unfinished template:"
  98 #        print tpl.warnings.join("\n")
  99 #        exit(0)
 100 #    else
 101 #        tpl.write_to sys.stdout
 102 #    end
 103 #    assert tpl.write_to_string == "Hello %NAME%!"
 104 class TemplateString
 105         super Template
 106
 107         # Template original text.
 108         private var tpl_text: String
 109
 110         # Macros contained in the template file.
 111         private var macros = new HashMap[String, Array[TemplateMacro]]
 112
 113         # Macro identifier delimiter char (`'%'` by default).
 114         #
 115         # To use a different delimiter you can subclasse `TemplateString` and defined the `marker`.
 116         #
 117         #    class DollarTemplate
 118         #        super TemplateString
 119         #        redef var marker = '$'
 120         #    end
 121         #    var tpl = new DollarTemplate("Hello $NAME$!")
 122         #    tpl.replace("NAME", "Dave")
 123         #    assert tpl.write_to_string == "Hello Dave!"
 124         protected var marker = '%'
 125
 126         # Creates a new template from a `text`.
 127         #
 128         #    var tpl = new TemplateString("Hello %NAME%!")
 129         #    assert tpl.write_to_string == "Hello %NAME%!"
 130         init(text: String) do
 131                 self.tpl_text = text
 132                 parse
 133         end
 134
 135         # Creates a new template from the contents of `file`.
 136         init from_file(file: String) do
 137                 init load_template_file(file)
 138         end
 139
 140         # Loads the template file contents.
 141         private fun load_template_file(tpl_file: String): String do
 142                 var file = new IFStream.open(tpl_file)
 143                 var text = file.read_all
 144                 file.close
 145                 return text
 146         end
 147
 148         # Finds all the macros contained in `text` and store them in `macros`.
 149         #
 150         # Also build `self` template parts using original template text.
 151         private fun parse do
 152                 var text = tpl_text
 153                 var pos = 0
 154                 var out = new FlatBuffer
 155                 var start_pos: Int
 156                 var end_pos: Int
 157                 while pos < text.length do
 158                         # lookup opening tag
 159                         start_pos = text.read_until_char(pos, marker, out)
 160                         if start_pos < 0 then
 161                                 text.read_until_pos(pos, text.length, out)
 162                                 add out.to_s
 163                                 break
 164                         end
 165                         add out.to_s
 166                         pos = start_pos + 1
 167                         # lookup closing tag
 168                         out.clear
 169                         end_pos = text.read_until_char(pos, marker, out)
 170                         if end_pos < 0 then
 171                                 text.read_until_pos(pos, text.length, out)
 172                                 add "%"
 173                                 add out.to_s
 174                                 break
 175                         end
 176                         pos = end_pos + 1
 177                         # check macro
 178                         var name = out.to_s
 179                         if name.is_valid_macro_name then
 180                                 add make_macro(name, start_pos, end_pos)
 181                         else
 182                                 add "%"
 183                                 add name
 184                                 add "%"
 185                         end
 186                         out.clear
 187                 end
 188         end
 189
 190         # Add a new macro to the list
 191         private fun make_macro(name: String, start_pos, end_pos: Int): TemplateMacro do
 192                 if not macros.has_key(name) then
 193                         macros[name] = new Array[TemplateMacro]
 194                 end
 195                 var macro = new TemplateMacro(name, start_pos, end_pos)
 196                 macros[name].add macro
 197                 return macro
 198         end
 199
 200         # Available macros in `self`.
 201         #
 202         #    var tpl = new TemplateString("Hello %NAME%!")
 203         #    assert tpl.macro_names.first == "NAME"
 204         fun macro_names: Collection[String] do return macros.keys
 205
 206         # Does `self` contain a macro with `name`.
 207         #
 208         #    var tpl = new TemplateString("Hello %NAME%")
 209         #    assert tpl.has_macro("NAME")
 210         fun has_macro(name: String): Bool do return macro_names.has(name)
 211
 212         # Replace a `macro` by a streamable `replacement`.
 213         #
 214         # REQUIRE `has_macro(name)`
 215         #
 216         #    var tpl = new TemplateString("Hello %NAME%!")
 217         #    tpl.replace("NAME", "Dave")
 218         #    assert tpl.write_to_string == "Hello Dave!"
 219         fun replace(name: String, replacement: Streamable) do
 220                 assert has_macro(name)
 221                 for macro in macros[name] do
 222                         macro.replacement = replacement
 223                 end
 224         end
 225
 226         # Check if all macros were replaced.
 227         #
 228         # Return false if a macro was not replaced and store message in `warnings`.
 229         #
 230         #    var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
 231         #    assert not tpl.check
 232         #    tpl.replace("FIRSTNAME", "Corben")
 233         #    tpl.replace("LASTNAME", "Dallas")
 234         #    assert tpl.check
 235         fun check: Bool do
 236                 warnings.clear
 237                 var all_ok = true
 238                 for name, macros in self.macros do
 239                         for macro in macros do
 240                                 if not macro.is_replaced then
 241                                         all_ok = false
 242                                         warnings.add "No replacement for macro %{macro.name}% at {macro.location}"
 243                                 end
 244                         end
 245                 end
 246                 return all_ok
 247         end
 248
 249         # Last `check` warnings.
 250         #
 251         #    var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
 252         #    tpl.check
 253         #    assert tpl.warnings.length == 2
 254         #    assert tpl.warnings[0] == "No replacement for macro %FIRSTNAME% at (6:16)"
 255         #    assert tpl.warnings[1] == "No replacement for macro %LASTNAME% at (19:28)"
 256         #    tpl.replace("FIRSTNAME", "Corben")
 257         #    tpl.replace("LASTNAME", "Dallas")
 258         #    tpl.check
 259         #    assert tpl.warnings.is_empty
 260         var warnings = new Array[String]
 261
 262         # Returns a view on `self` macros on the form `macro.name`/`macro.replacement`.
 263         #
 264         # Given that all macros with the same name are all replaced with the same
 265         # replacement, this view contains only one entry for each name.
 266         #
 267         #    var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
 268         #    for name, rep in tpl do assert rep == null
 269         #    tpl.replace("FIRSTNAME", "Corben")
 270         #    tpl.replace("LASTNAME", "Dallas")
 271         #    for name, rep in tpl do assert rep != null
 272         fun iterator: MapIterator[String, nullable Streamable] do
 273                 return new TemplateStringIterator(self)
 274         end
 275 end
 276
 277 # A macro is a special text command that is replaced by other content in a `TemplateString`.
 278 private class TemplateMacro
 279         super Template
 280         # Macro name as found in the template.
 281         var name: String
 282
 283         # Macro starting position in template.
 284         var start_pos: Int
 285
 286         # Macro ending position in template.
 287         var end_pos: Int
 288
 289         # Macro replacement if any.
 290         var replacement: nullable Streamable = null
 291
 292         # Does `self` already have a `replacement`?
 293         fun is_replaced: Bool do return replacement != null
 294
 295         # Render `replacement` or else `name`.
 296         redef fun rendering do
 297                 if is_replaced then
 298                         add replacement.as(not null)
 299                 else
 300                         add "%{name}%"
 301                 end
 302         end
 303
 304         # Human readable location.
 305         fun location: String do return "({start_pos}:{end_pos})"
 306 end
 307
 308 redef class String
 309         # Reads `self` from pos `from` to pos `to` and store result in `buffer`.
 310         private fun read_until_pos(from, to: Int, buffer: Buffer): Int do
 311                 if from < 0 or from >= length or
 312                    to < 0 or to >= length or
 313                from >= to then return -1
 314                 var pos = from
 315                 while pos < to do
 316                         buffer.add self[pos]
 317                         pos += 1
 318                 end
 319                 return pos
 320         end
 321
 322         # Reads `self` until `to` is encountered and store result in `buffer`.
 323         #
 324         # Returns `to` position or `-1` if not found.
 325         private fun read_until_char(from: Int, char: Char, buffer: Buffer): Int do
 326                 if from < 0 or from >= length then return -1
 327                 var pos = from
 328                 while pos > -1 and pos < length do
 329                         var c = self[pos]
 330                         if c == char then return pos
 331                         buffer.add c
 332                         pos += 1
 333                 end
 334                 return -1
 335         end
 336
 337         # Is `self` a valid macro identifier?
 338         #
 339         # A macro identifier is valid if:
 340         #
 341         # * starts with an uppercase letter
 342         # * contains only numers, uppercase letters or '_'
 343         #
 344         #    # valid
 345         #    assert "NAME".is_valid_macro_name
 346         #    assert "FIRST_NAME".is_valid_macro_name
 347         #    assert "BLOCK1".is_valid_macro_name
 348         #    # invalid
 349         #    assert not "1BLOCK".is_valid_macro_name
 350         #    assert not "_BLOCK".is_valid_macro_name
 351         #    assert not "FIRST NAME".is_valid_macro_name
 352         #    assert not "name".is_valid_macro_name
 353         fun is_valid_macro_name: Bool do
 354                 if not first.is_upper then return false
 355                 for c in self do
 356                         if not c.is_upper and c != '_' and not c.is_digit then return false
 357                 end
 358                 return true
 359         end
 360 end
 361
 362 private class TemplateStringIterator
 363         super MapIterator[String, nullable Streamable]
 364
 365         var subject: TemplateString
 366         var key_it: Iterator[String] is noinit
 367
 368         init do
 369                 self.key_it = subject.macro_names.iterator
 370         end
 371
 372         redef fun is_ok do return key_it.is_ok
 373         redef fun next do key_it.next
 374         redef fun key do return key_it.item
 375         redef fun item do return subject.macros[key].first.replacement
 376 end