freemarker-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Dekany <>
Subject [FM3] Syntax-related settings, and file extensions again.
Date Sun, 25 Mar 2018 16:51:47 GMT
In FM3 there's a configuration (ParsingConfiguration to be precise)
setting called "templateLanguage" (of type TemplateLanguage). This is
kind of a dummy ATM, but will be important in supporting multiple
template languages in FM3. For example, many prefer a syntax that's
closer to Velocity or WebMacro in some respects (myself included). I
expect that TemplateLanguage will be really just mean template syntax.
Surely I don't plan to support various language semantics, apart from
different set of core directives/functions (i.e., user-defined
dialects). So maybe "templateLanguage" is a misnomer, and it should be
"templateSyntax", or just "syntax". But dialects makes it less
clear... well I don't want to mix them in now, it's already a too
convoluted mail.

Please bear with me till the end, and then tell me if you have better
ideas, or if you will want to "veto" something for some reason.

1. Remove the tagSyntax and interpolationSyntax settings

The configuration setting "tagSyntax" and "interpolationSyntax" should
be inside the TemplateLanguage, because, for example, for a syntax
like #import(x = 'x.ftl') angleBracket and squareBracket tagSyntax is
clearly meaningless. (OK, "interpolationSyntax" happens to be
meaningful, there but for some other TemplateLanguage it maybe isn't.)
So "tagSyntax" and "interpolationSyntax" will be removed as top-level
settings, and then then a concrete TemplateLanguage subclass may
reintroduces them as its own language specific settings.

2. Restrict FM2-like syntax permutations

Currently we have two TemplateLangauge-s, TemplateLangauge.STATIC_TEXT
(it's like when in FM2 you get a template with the noParse option),
and TemplateLangauge.FTL. The behavior of FTL currently depends on the
top-level "tagSyntax" and "interpolationSyntax" settings (which will
be removed or moved as per 1.)

I will introduce (if nobody says no) StaticTextTemplateLanguage and
FreeMarker2LikeTemplateLanguage (ugh... better name?).
StaticTextTemplateLanguage will contain a single INSTANCE. But what
about FreeMarker2LikeTemplateLanguage? It could be publicly
instantiateable with a "tagSyntax" and an "interpolationSyntax"
parameter. But instead, I consider just adding ANGLE_BRACKET_INSTANCE
(uses <#> and ${}) and SQUARE_BRACKET_INSTANCE (uses [#] and [=]), and
there won't be other permutations possible (like [#] abd ${}). Bear
with me in point 3 to understand why not.

3. File extensions and language names

The main issue with using multiple syntaxes where all is a "FreeMarker
3 template" is the confusion it can cause. This includes what syntax
are you using in the official documentation? But I think it's a waste
when you already have an engine, yet if someone needs or even just
prefer a different syntax (people tend to be emotional about
look-and-feel), they need a whole another engine as well (or a fork).
If they need substantially different semantics, then's it's OK or even
preferable to have multiple engines, but just for the syntax? I don't
think so.

So, I think all TemplateLanguage-s need a short name that's identical
to its (preferred) file extension (well, apart from the last letter
for the output format, but see that later). Then, on the top of the
Manual you can have a dropdown component where you select which
language are you using, which is the same as what file extension you
have, so it should be easy to figure out for the user. As the
languages only differ in syntax, it's possible to safely translate
between them automatically.

Also, the one-to-one mapping between the exact syntax and the file
extension is important, as that's how most editors/IDE-s figure out
which syntax highlight rules (and such) to active.

So now it's hopefully clear why I don't want to support all 4
permutations of that tagSyntax-es and interpolationSyntax-es... We
already will have at least two funny file extensions.

But wait, all those have to be combined with the output format (as in
*.ftlx VS *.ftlh in FM2), which decides the auto-escaping applied. It
also influences how the static text parts should be syntax highlighted
in an editor/IDE, so we can't get away without a distinct file
extension for each. So we have to add a last letter to the extension,
which indicates the output format... h for HTML, x for XML, etc.

The consensus (kind of...) on file extensions last time was these,
because there were no interpolationSyntax yet: f3<a|s>, f3<a|s>x,
f3<a|s>h. Like, if you want angle bracket tag syntax and HTML output
format, then the file name will be "foo.f3ah", but if you want the
same with square bracket tagSyntax then it will be "foo.f3sh". As of
2.3.28 we also have interpolationSyntax, but if as per point 2 the
interpolationSyntax becomes square bracket together with the tag
syntax, the earlier extension remain usable, and we don't need
abominations like f3adh (Angle tag + Dollar interp.), f3ash (Angle tag
+ Square interp.), etc.

4. File extension *always* should end with the output format letter

In the case of f3<a|s>, where the output format is "undefined", it
should be f3<a|s>u. That is, the last letter of the extension should
always correspond to the output format. Because:

- Forgetting about the output format is a security risk (XSS
  attacks), or it can be sneaky bug as it bites rarely. So it's
  better if the user is more explicit/conscious about not doing

- Then the part of the file extension that indicates the template
  language and the part that indicates the output format can be
  unambiguously separated, even if someone one day will need
  multi-letter syntax indicators. (This can be especially useful for
  custom dialects, as they will need a separate set of file

 Daniel Dekany

View raw message