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 `Writable` 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 numbers, 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         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 do
 131                 parse
 132         end
 133
 134         # Creates a new template from the contents of `file`.
 135         init from_file(file: String) do
 136                 init load_template_file(file)
 137         end
 138
 139         # Loads the template file contents.
 140         private fun load_template_file(tpl_file: String): String do
 141                 var file = new FileReader.open(tpl_file)
 142                 var text = file.read_all
 143                 file.close
 144                 return text
 145         end
 146
 147         # Finds all the macros contained in `text` and store them in `macros`.
 148         #
 149         # Also build `self` template parts using original template text.
 150         private fun parse do
 151                 var text = tpl_text
 152                 var pos = 0
 153                 var out = new FlatBuffer
 154                 var start_pos: Int
 155                 var end_pos: Int
 156                 while pos < text.length do
 157                         # lookup opening tag
 158                         start_pos = text.read_until_char(pos, marker, out)
 159                         if start_pos < 0 then
 160                                 text.read_until_pos(pos, text.length, out)
 161                                 add out.to_s
 162                                 break
 163                         end
 164                         add out.to_s
 165                         pos = start_pos + 1
 166                         # lookup closing tag
 167                         out.clear
 168                         end_pos = text.read_until_char(pos, marker, out)
 169                         if end_pos < 0 then
 170                                 text.read_until_pos(pos, text.length, out)
 171                                 add "%"
 172                                 add out.to_s
 173                                 break
 174                         end
 175                         pos = end_pos + 1
 176                         # check macro
 177                         var name = out.to_s
 178                         if name.is_valid_macro_name then
 179                                 add make_macro(name, start_pos, end_pos)
 180                         else
 181                                 add "%"
 182                                 add name
 183                                 add "%"
 184                         end
 185                         out.clear
 186                 end
 187         end
 188
 189         # Add a new macro to the list
 190         private fun make_macro(name: String, start_pos, end_pos: Int): TemplateMacro do
 191                 if not macros.has_key(name) then
 192                         macros[name] = new Array[TemplateMacro]
 193                 end
 194                 var macro = new TemplateMacro(name, start_pos, end_pos)
 195                 macros[name].add macro
 196                 return macro
 197         end
 198
 199         # Available macros in `self`.
 200         #
 201         #     var tpl = new TemplateString("Hello %NAME%!")
 202         #     assert tpl.macro_names.first == "NAME"
 203         fun macro_names: Collection[String] do return macros.keys
 204
 205         # Does `self` contain a macro with `name`.
 206         #
 207         #     var tpl = new TemplateString("Hello %NAME%")
 208         #     assert tpl.has_macro("NAME")
 209         fun has_macro(name: String): Bool do return macro_names.has(name)
 210
 211         # Replace a `macro` by a streamable `replacement`.
 212         #
 213         # REQUIRE `has_macro(name)`
 214         #
 215         #     var tpl = new TemplateString("Hello %NAME%!")
 216         #     tpl.replace("NAME", "Dave")
 217         #     assert tpl.write_to_string == "Hello Dave!"
 218         fun replace(name: String, replacement: Writable) do
 219                 assert has_macro(name)
 220                 for macro in macros[name] do
 221                         macro.replacement = replacement
 222                 end
 223         end
 224
 225         # Check if all macros were replaced.
 226         #
 227         # Return false if a macro was not replaced and store message in `warnings`.
 228         #
 229         #     var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
 230         #     assert not tpl.check
 231         #     tpl.replace("FIRSTNAME", "Corben")
 232         #     tpl.replace("LASTNAME", "Dallas")
 233         #     assert tpl.check
 234         fun check: Bool do
 235                 warnings.clear
 236                 var all_ok = true
 237                 for name, macros in self.macros do
 238                         for macro in macros do
 239                                 if not macro.is_replaced then
 240                                         all_ok = false
 241                                         warnings.add "No replacement for macro %{macro.name}% at {macro.location}"
 242                                 end
 243                         end
 244                 end
 245                 return all_ok
 246         end
 247
 248         # Last `check` warnings.
 249         #
 250         #     var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
 251         #     tpl.check
 252         #     assert tpl.warnings.length == 2
 253         #     assert tpl.warnings[0] == "No replacement for macro %FIRSTNAME% at (6:16)"
 254         #     assert tpl.warnings[1] == "No replacement for macro %LASTNAME% at (19:28)"
 255         #     tpl.replace("FIRSTNAME", "Corben")
 256         #     tpl.replace("LASTNAME", "Dallas")
 257         #     tpl.check
 258         #     assert tpl.warnings.is_empty
 259         var warnings = new Array[String]
 260
 261         # Returns a view on `self` macros on the form `macro.name`/`macro.replacement`.
 262         #
 263         # Given that all macros with the same name are all replaced with the same
 264         # replacement, this view contains only one entry for each name.
 265         #
 266         #     var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
 267         #     for name, rep in tpl do assert rep == null
 268         #     tpl.replace("FIRSTNAME", "Corben")
 269         #     tpl.replace("LASTNAME", "Dallas")
 270         #     for name, rep in tpl do assert rep != null
 271         fun iterator: MapIterator[String, nullable Writable] do
 272                 return new TemplateStringIterator(self)
 273         end
 274 end
 275
 276 # A macro is a special text command that is replaced by other content in a `TemplateString`.
 277 private class TemplateMacro
 278         super Template
 279         # Macro name as found in the template.
 280         var name: String
 281
 282         # Macro starting position in template.
 283         var start_pos: Int
 284
 285         # Macro ending position in template.
 286         var end_pos: Int
 287
 288         # Macro replacement if any.
 289         var replacement: nullable Writable = null
 290
 291         # Does `self` already have a `replacement`?
 292         fun is_replaced: Bool do return replacement != null
 293
 294         # Render `replacement` or else `name`.
 295         redef fun rendering do
 296                 if is_replaced then
 297                         add replacement.as(not null)
 298                 else
 299                         add "%{name}%"
 300                 end
 301         end
 302
 303         # Human readable location.
 304         fun location: String do return "({start_pos}:{end_pos})"
 305 end
 306
 307 redef class String
 308         # Reads `self` from pos `from` to pos `to` and store result in `buffer`.
 309         private fun read_until_pos(from, to: Int, buffer: Buffer): Int do
 310                 if from < 0 or from >= length or
 311                    to < 0 or to >= length or
 312                from >= to then return -1
 313                 var pos = from
 314                 while pos < to do
 315                         buffer.add self[pos]
 316                         pos += 1
 317                 end
 318                 return pos
 319         end
 320
 321         # Reads `self` until `to` is encountered and store result in `buffer`.
 322         #
 323         # Returns `to` position or `-1` if not found.
 324         private fun read_until_char(from: Int, char: Char, buffer: Buffer): Int do
 325                 if from < 0 or from >= length then return -1
 326                 var pos = from
 327                 while pos > -1 and pos < length do
 328                         var c = self[pos]
 329                         if c == char then return pos
 330                         buffer.add c
 331                         pos += 1
 332                 end
 333                 return -1
 334         end
 335
 336         # Is `self` a valid macro identifier?
 337         #
 338         # A macro identifier is valid if:
 339         #
 340         # * starts with an uppercase letter
 341         # * contains only numers, uppercase letters or '_'
 342         #
 343         #     # valid
 344         #     assert "NAME".is_valid_macro_name
 345         #     assert "FIRST_NAME".is_valid_macro_name
 346         #     assert "BLOCK1".is_valid_macro_name
 347         #     # invalid
 348         #     assert not "1BLOCK".is_valid_macro_name
 349         #     assert not "_BLOCK".is_valid_macro_name
 350         #     assert not "FIRST NAME".is_valid_macro_name
 351         #     assert not "name".is_valid_macro_name
 352         fun is_valid_macro_name: Bool do
 353                 if not first.is_upper then return false
 354                 for c in self do
 355                         if not c.is_upper and c != '_' and not c.is_digit then return false
 356                 end
 357                 return true
 358         end
 359 end
 360
 361 private class TemplateStringIterator
 362         super MapIterator[String, nullable Writable]
 363
 364         var subject: TemplateString
 365         var key_it: Iterator[String] is noinit
 366
 367         init do
 368                 self.key_it = subject.macro_names.iterator
 369         end
 370
 371         redef fun is_ok do return key_it.is_ok
 372         redef fun next do key_it.next
 373         redef fun key do return key_it.item
 374         redef fun item do return subject.macros[key].first.replacement
 375 end