OK, I have done these. For the class name for the FM2-like language
(the default syntax) I have chosen DefaultTemplateLanguage, with
similar logic as the default ObjectWrapper is DefaultObjectWrapper...

For the TemplateLangauge class, I have renamed the "name" property to
simply "fileExtension". The reason is that we have several variations,
like f3ah, f3sh, f3ax, etc., and I think the least confusing is if the
default file extension is just the name of the template language.

I have banned creating custom TemplateLanguage-s where the
fileExtension starts with "f", so that such file extensions can be
added later without breaking backward compatibility, or at least
causing confusion.

I wonder what the next thing should be... I though of null handling
earlier, but now that I have did into it, I think maybe the new parses
would be better to do next. BTW, that's why I haven't yet removed the
FM2 feature where starting the file with [#ftl] VS <#ftl> will set the
tagSyntax, because if I write a new parser, that work would be
wasted.


Wednesday, April 4, 2018, 5:15:05 PM, Woonsan Ko wrote:

> On Mon, Apr 2, 2018 at 2:04 PM, Daniel Dekany <ddek...@apache.org> wrote:
>> 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 <ddek...@apache.org> 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.
> Right. Good point!
>
>>
>>>> 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).
> I see.
> Thanks for your explanations!
>
>>
>>>> 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.
> I see.
>
>>
>>> 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...)
> Cool! Looking forward to it.
>
> Regards,
>
> Woonsan
>
>>
>>> Regards,
>>>
>>> Woonsan
>>>
>>>>
>>>> --
>>>> Thanks,
>>>>  Daniel Dekany
>>
>> --
>> Thanks,
>>  Daniel Dekany
>>
>

-- 
Thanks,
 Daniel Dekany

Reply via email to