There was progress made in that branch like one month ago. More is needed,
and hopefully will be done this month.
Now, there are a few dilemmas with this feature branch (FREEMARKER-35).
Here's one of them.
For a long time we have the datetime_format, date_format, and time_format
settings for java.util.Date-s. In the original contribution (the PR), new
format settings were added for each supported temporal type:
local_date_time_format, offset_date_time_format, zoned_date_time_format,
local_date_time_format, offset_date_time_format,
zoned_date_time_format, instant_format,
local_date_format, local_time_format, and offset_time_format (and
year_format, and year_month_format). These can have similar values like the
old format settings (except that patterns are interpreted with
DateTimeFromatter instead of with SimpleDateFormat). This is the obvious
approach from the perspective of the template engine developer, but I think
it's not practical for the users. Certainly, you just want to say that the
datetime_format is like "yyyy.MM.dd" (or is "iso", etc.), and then want all
kinds of date-time objects formatted like that. So you don't want to
consider if it's a java.util.Date, or a LocalDateTime, or an
OffsetDateTime, or a ZonedDateTime, or an Instant. Most of the time at
least, you don't want to present them differently. There I intend to remove
all these new settings, except year_format, and year_month_format.
Everything else will be governed by just datetime_format, date_format, and
time_format.
What do you guys think?
Now, there will be quite much magic going on with that:
- Dealing with formats that doesn't show offset or zone. These tricks
are already done with the new settings too, but it's even more important if
you have a single shared format string:
- If you format an OffsetDateTime or ZonedDateTime, and the
format doesn't show the offset or time zone, it's converted to the time
zone specified in the time_zone setting of FreeMarker.
- Formatting OffsetTime-s will fail if the format doesn't show the
offset, and time_zone has DST. (Currently that throws this:
freemarker.core.InvalidFormatParametersException: The format
must show the
time offset, as the current FreeMarker time zone, "Europe/Budapest", may
uses Daylight Saving Time, and thus it's not possible to convert
the value
to the local time in that zone, since we don't know the day.)
- The pattern syntax used for datetime_format, date_format, and
time_format will have to be extended (currently it simply uses
SimpleDateFormat to parse it):
- To optionally use DateTimeFormatter syntax. For example:
"HH/mm/ss[X];syntax=new". ("[" and "]" are output literally with the old
syntax, but with ";syntax=new" they indicate an optional section.) With
";syntax=new", even java.util.Date-s will be formatted
with DateTimeFormatter.
- To automatically translate SimpleDateFormat syntax to
DateTimeFormatter behind the scenes, when we have no ";syntax=new". This
will be done only if a Temporal has to be formatted, while
java.util.Date-s
will be still formatted with SimpleDateFormat, to ensure 100% backward
compatibility.
- To allow overriding the pattern for a specific type. For example
"yyyy-MM-dd HH:mm;instant=yyyy-MM-dd HH:mm:ss.S"
- Of course, the ";name=value" extension will be disabled by default
(we need a setting for that, like temporal_format_extensions=true/false),
if incompatible_improvements is set to <= 2.3.32
- Setting values like "short", "medium", "long", and "full" (i.e., Java
format styles) doesn't work well with Temporal-s, so having a shared format
setting becomes quite useless if you want to use these values, unless I
will pull some dirty tricks (which I intend to do of course). There are two
problems to counter. On Java 8 (but not on Java 9+), "long" or higher will
fail with temporals that have no offset or zone, as they mistakenly didn't
mark the zone/offset fields in the format patterns as optional (at least
for the locales I tried). Also, formatting OffsetTime with "medium" or less
will generally fail because of the DST issue I described earlier in this
mail (i.e., the format must show the offset). So, I think, I will add two
new settings: offset_time_style_lower_bound with default "long", and
local_temporal_style_upper_bound with default "medium". With an example, if
a LocalDateTime is formatted, and the datetime_format is "long", but
local_temporal_style_upper_bound is "medium", then because "long" is
greater than "medium", we will ignore it and just format with "medium"
style. Yeah, it's potentially quite confusing, but what better can I do?
Without these two style boundary settings, and extended format strings
being enabled, you could use this as datetime_format:
"full;localDateTime=medium". But I think in reality people will just
naively(?) use datetime_format="full", and time_format="medium", and then
burnt by it on runtime (maybe only in production).
- Who knows what else will come up... like when I add support for
parsing, which wasn't done yet. But if you agree that using the 3 old
format settings for everything is crucial, somehow I will have to get over
them.
On Thu, Dec 9, 2021 at 9:20 AM Geoffrey De Smet <ge0ffrey.s...@gmail.com>
wrote:
> Hi,
>
> This feature would really modernize Freemarker for us.
>
> Is there any news on LocalDate support for Freemarker?
> Anything we can do to speed things along?
>
> With kind regards,
> Geoffrey De Smet
>
> On 02/10/2021 20:24, Daniel Dekany wrote:
> > Hi,
> >
> > Not yet, but there's a FREEMARKER-35 branch that deals with all the
> > java.time types. It works at the first sight, but actually will need a
> > significant amount of work before it can be released. I plan to put
> > aside time for a "sprint" on it near the end of October. We will see.
> > And yes, I also want to add at least a few date operations built-ins.
> >
> > On Fri, Oct 1, 2021 at 9:59 AM Geoffrey De Smet <ge0ffrey.s...@gmail.com>
> wrote:
> >> Hi all,
> >>
> >> Does Freemarker have plans to support using java.time.LocalDate instead
> >> of java.util.Date?
> >>
> >> The latter is causing off-by-one errors for in our Freemarker templates
> >> if executed in certain timezones (and adjusting the timezone opens
> >> another can of worms).
> >> See https://github.com/jbake-org/jbake/issues/726
> >>
> >> Also, many java.time methods, such as plusDays(3) or next monday,
> >> would be very welcome in Freemarker templates.
> >>
> >> --
> >>
> >> With kind regards,
> >> Geoffrey De Smet
> >>
> >
>
--
Best regards,
Daniel Dekany
