1 # This file is part of NIT ( http://www.nitlanguage.org ).
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
7 # http://www.apache.org/licenses/LICENSE-2.0
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.
15 # String templating using macros.
17 # There is plenty of macro/templating tools in the worl,
20 # See `TemplateString` for more details.
25 # Template with macros replacement.
27 # `TemplateString` provides a simple way to customize generic string templates
28 # using macros and replacement.
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:
33 # var tpl = new TemplateString("Hello %NAME%!")
34 # tpl.replace("NAME", "Dave")
35 # assert tpl.write_to_string == "Hello Dave!"
37 # A macro identifier is valid if:
39 # * starts with an uppercase letter
40 # * contains only numbers, uppercase letters or '_'
42 # See `String::is_valid_macro_name` for more details.
44 # ## External template files
46 # When using large template files it's recommanded to use external template files.
48 # In external file `example.tpl`:
54 # <title>%TITLE%</title>
63 # Loading the template file using `TemplateString`:
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!")
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`
78 # tpl = new TemplateString("Hello %NAME%!")
79 # tpl.replace("NAME", "Dave")
80 # assert tpl.write_to_string == "Hello Dave!"
82 # ## Template correctness
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.
87 # tpl = new TemplateString("Hello %NAME%!")
88 # assert tpl.write_to_string == "Hello %NAME%!"
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.
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")
101 # tpl.write_to sys.stdout
103 # assert tpl.write_to_string == "Hello %NAME%!"
107 # Template original text.
110 # Macros contained in the template file.
111 private var macros
= new HashMap[String, Array[TemplateMacro]]
113 # Macro identifier delimiter char (`'%'` by default).
115 # To use a different delimiter you can subclasse `TemplateString` and defined the `marker`.
117 # class DollarTemplate
118 # super TemplateString
119 # redef var marker = '$'
121 # var tpl = new DollarTemplate("Hello $NAME$!")
122 # tpl.replace("NAME", "Dave")
123 # assert tpl.write_to_string == "Hello Dave!"
124 protected var marker
= '%'
126 # Creates a new template from a `text`.
128 # var tpl = new TemplateString("Hello %NAME%!")
129 # assert tpl.write_to_string == "Hello %NAME%!"
134 # Creates a new template from the contents of `file`.
135 init from_file
(file
: String) do
136 init load_template_file
(file
)
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
147 # Finds all the macros contained in `text` and store them in `macros`.
149 # Also build `self` template parts using original template text.
153 var out
= new FlatBuffer
156 while pos
< text
.length
do
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
)
168 end_pos
= text
.read_until_char
(pos
, marker
, out
)
170 text
.read_until_pos
(pos
, text
.length
, out
)
178 if name
.is_valid_macro_name
then
179 add make_macro
(name
, start_pos
, end_pos
)
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]
194 var macro
= new TemplateMacro(name
, start_pos
, end_pos
)
195 macros
[name
].add macro
199 # Available macros in `self`.
201 # var tpl = new TemplateString("Hello %NAME%!")
202 # assert tpl.macro_names.first == "NAME"
203 fun macro_names
: Collection[String] do return macros
.keys
205 # Does `self` contain a macro with `name`.
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
)
211 # Replace a `macro` by a streamable `replacement`.
213 # REQUIRE `has_macro(name)`
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
225 # Check if all macros were replaced.
227 # Return false if a macro was not replaced and store message in `warnings`.
229 # var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
230 # assert not tpl.check
231 # tpl.replace("FIRSTNAME", "Corben")
232 # tpl.replace("LASTNAME", "Dallas")
237 for name
, macros
in self.macros
do
238 for macro
in macros
do
239 if not macro
.is_replaced
then
241 warnings
.add
"No replacement for macro %{macro.name}% at {macro.location}"
248 # Last `check` warnings.
250 # var tpl = new TemplateString("Hello %FIRSTNAME%, %LASTNAME%!")
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")
258 # assert tpl.warnings.is_empty
259 var warnings
= new Array[String]
261 # Returns a view on `self` macros on the form `macro.name`/`macro.replacement`.
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.
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)
276 # A macro is a special text command that is replaced by other content in a `TemplateString`.
277 private class TemplateMacro
279 # Macro name as found in the template.
282 # Macro starting position in template.
285 # Macro ending position in template.
288 # Macro replacement if any.
289 var replacement
: nullable Writable = null
291 # Does `self` already have a `replacement`?
292 fun is_replaced
: Bool do return replacement
!= null
294 # Render `replacement` or else `name`.
295 redef fun rendering
do
297 add replacement
.as(not null)
303 # Human readable location.
304 fun location
: String do return "({start_pos}:{end_pos})"
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
321 # Reads `self` until `to` is encountered and store result in `buffer`.
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
327 while pos
> -1 and pos
< length
do
329 if c
== char
then return pos
336 # Is `self` a valid macro identifier?
338 # A macro identifier is valid if:
340 # * starts with an uppercase letter
341 # * contains only numers, uppercase letters or '_'
344 # assert "NAME".is_valid_macro_name
345 # assert "FIRST_NAME".is_valid_macro_name
346 # assert "BLOCK1".is_valid_macro_name
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
355 if not c
.is_upper
and c
!= '_' and not c
.is_digit
then return false
361 private class TemplateStringIterator
362 super MapIterator[String, nullable Writable]
364 var subject
: TemplateString
365 var key_it
: Iterator[String] is noinit
368 self.key_it
= subject
.macro_names
.iterator
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