Monday, April 2, 2018, 3:40:09 PM, Woonsan Ko wrote:
> Hi Daniel,
>
> Sorry for late response. I appreciate for your thorough thoughts and
> ideas. See my comments inline.
>
> On Sun, Mar 25, 2018 at 12:51 PM, Daniel Dekany <[email protected]> wrote:
>> 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.
> Yeah, just "Syntax" sounds clearer and simpler to me, too.
If it will be just syntax... but, we will see as things evolve anyway.
>> 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.
> +1
>
>>
>>
>> 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?).
> Perhaps FM2LegacyTemplateLanguage (FM2LegacySyntax if we rename it)?
But it won't be the legacy syntax, just has a similar look-and-feel.
Apart from cleaning up trivial legacy mistakes, note the following
planned major changes (also mentioned on the Wiki page):
- Regular directive call syntax. There's won't be such thing as
#import or #if on the parser-level, because the syntax of all
directives is the same, and the TemplateDirectiveModel (or such)
behind tells what parameters are accepted, etc. Thus, for example
<#include 'x.f3ah' as ns> becomes to <#import ns='x.f3ah'>. This
is crucial both for tooling, but to support custom dialects.
- #assign/#local/#global will be gone. There will be #var (block-scope
declaration) and #set. (Also maybe #val too, I'm not yet sure). BTW,
Java 10 has also chosen `val` as the keyword for this (so it will be
more familiar).
>> 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.
> +1
>
> I like this reduced set of syntaxes in a template language as this is
> not a generic interpolation library.
Or rather, a "templating" library. Is there a such word? Now there is.
>> 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.
> +1
>
>>
>>
>> 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
>> auto-escaping.
> +1
>
>>
>> - 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
>> extensions.)
> +1
>
> So, file extension comprise prefix ("f3"), syntax indicator(s) and
> output format indicator, and the syntax indicator(s) justifies itself
> as it is very useful in IDE and tools for example.
> I don't think those single character indicator would be a problem in
> the future practically, so all sound like reasonable choices.
> As you mentioned above, we will have many funny extensions, but I
> think it would be useful in the end and easy to understand based on
> this convention.
>
> I suppose if someone wants to loads template sources with a specific
> syntax from one of the pre-defined static TemplateLanguage instance
> programmatically, regardless of the template name and extensions, it
> should be still possible, right?
Kind of. It would work similarly as in FM2. That is, you can provide a
ParsingConfiguration to the Template constructor (or for Template-s
managed by FreeMarker itself, you can use TemplateConfiguration-s for
similar purse). Also, the Configuration itself is the default
ParsingConfiguration. After all that, if the file extension is
recognized, it will override the templateLanguage and outputFormat
settings in the ParsingConfiguration. So you can't specify things
"regardless" of the file extension, because when the file extension is
recognized, its meaning is enforced (to avoid confusion). If it's not
recognized, then you have full control.
> e.g, embedding FM3 engine to use specific expressional templating.
> Then I think everything seems very reasonable to me.
Great, and thanks for the feedback! So now... I will still have to get
rid of syntax auto-detection with the #ftl header, and then I guess I
can implement this. (And then probably null handling. And then I guess
#var/#set...)
> Regards,
>
> Woonsan
>
>>
>> --
>> Thanks,
>> Daniel Dekany
--
Thanks,
Daniel Dekany
