Proposal: strftime-based calendar/datetime formatting

I definitely like this more than Unicode’s Locale Date Markup Language, and I formatter module dependency injection.

AFAICT, there are no time partials in the world but :am | :pm.

AFAIK, AM/PM, which split the day in two halves, is mainly used in the Gregorian/Julian style calendars. Calendars that subdivide the day in different ways (the decimal calendar, some hindu calendars) split the day in many more chunks that are often more analogous to hours. In any case, because this would greatly complicate the logic for everyone who is using it, and not be super important to have for the smaller group of people using the handful of calendars that follow wildly different formatting rules (because they could use a dedicated custom formatting module in that case), I am for keeping the API simple and working with :am | :pm.

Do you plan on adding English day postfixes? I.e. st/nd/rd/th.

I’m not quite sure about the parsing being missing, even though I can appreciate the technical arguments. If the aim is to make Elixir seem like more “complete” to a user, as apparently some are surprise by the lack of formatting/parsing/TZ stuff in the core, then this will just move it to being surprised about parsing being missing. Many users will just have to go for some calendar library anyway if they want parsing. Add to this the TZ stuff being added into core, the UX will soon be that Elixir contains sort of half of a datetime library and for some reason the user will have to get a package to fill in the rest. This is just a first impression though, so don’t take it too strongly.

I don’t think so, no. Is it part of any strftime implementation?

Plus this is something that may change with time. For example, if we adopt strftime, then parsing becomes simpler, simply because the syntax is not as complicated as in the previous proposal, but I still think it would require some break-throughs. We will see.

I like the reduced scope! I think it will cover the majority of use-cases very well.

Is there a chance of providing a means for developers to flexibly provide their own custom formatting? It could be used to provide the ordinal formatting that @Nicd is requesting.

Here’s one example syntax:

iex> Calendar.format(now, `"%B %{d_ord}"`, MyApp.OrdinalFormatter)
December 14th

Another syntax might be more like %B %Cd where the C indicates that the next character represents a custom formatting directive.

Of course a setup like this would mean that you’d always have to pass in your formatter when formatting your date strings, but you could relatively easily create a MyApp.calendar_format/2 that would bake it in.

There are other concepts for parts of the day which CLDR supports but which would not seem relevant for this proposal.

@josevalim very practical proposal and probably easier to consume in most use cases than the CLDR encoding I’d agree.

No surprise that I look at this and consider how this could be used in a locale-specific way. Injecting a formatter is great. But I think it would be even better if there is an option to inject an ma tuple instead of just the module. That way a locale could also be injected (or any other parameter). Otherwise for a locale aware application one would need to either:

1. Set a locale prior to calling strftime which seems very brittle and not very clear.
2. Or, as your original example illustrates, there would need to be one module per locale and a lookup table to translate a locale into a module name which is a lot of scaffolding just to inject the right formatter for a locale.

An example of the ma approach would be:

 Calendar.format(date_or_time_or_datetime, "%Y-%m-%d %H:%M:%S.%f", {MyApp, ["pt-BR"]})

This would make the intent clearer and be easier to adapt for Gettext and Cldr and any other locale-specific library. Implementation is just another function head that can easily be pattern matched. The actual date being formatted would be prepended to the other tuple arguments.

Can you use string interpolation in those cases?

original = compute_ordinal(now)
iex> Calendar.format(now, "%B #{ordinal}")
December 14th

And if you want this to be extensible too you can have your own behaviour that builds on top of the existing one. The only trouble with interpolation is if the returned string also contains a %, but that is rare and you can always escape it. Or you can call format twice and inject your contents between them.

This is exactly what I was looking for, thank you. One of the issues mentioned there though is that in Japan they consider the AM/PM boundaries to differ from western ones. So I am wondering if we should instead pass the whole hour, minute and second to the formatter and make the AM/PM completely a formatter concern. I would say this is preferable because having to build a calendar only for localization is quite annoying.

The other place where you may need a custom calendar for localization is day_of_week (many start on sunday while ISO is monday) and week_of_year but we could move this to the formatter too in the future if we want to.

This looks good to me. Although I would make it a regular tuple where the second element is always passed last to the formatter functions. Since this is a behaviour, we want the definitions to be static, so all of the formatter callbacks will receive a config which may be given as input. If they are not available in the input, we pass a default value.

The other option is to support a fourth argument but I think that’s worst. Thoughts @michalmuskala?

In the previous discussion about the additions to Calendar, your implementation elected to not include arguments that would allow customisation of the day_of_week, or indeed min_days and first_day for variant Gregorian calendars. I think you were right - thats a characteristic of the calendar and an implementation detail there.

I haven’t yet worked out the optimal way to generate calendar modules at runtime (required in order to define user calendars that might have these variants) but thats not a concern here.

That makes sense to me. In fact I assumed that that the entire date_or_time_or_datetime struct would be passed to the formatter since all of that information might be required depending on the calendar.

That’s the part I am struggling with. The flow I have in mind is this: we have the struct, we pass the information to the calendar, and then the formatter receives the calendar result.

However, this often ties the formatter to a given calendar. For example, the Formatter.pads function could say that year has a 4 digit padding but that is actually specific to ISO. Even things like month_name, if you assume that 1 is january, than that information is specific to certain calendars.

The opposite is also true, the calendar is bound to some localization rules. As you said, day_of_week and week_of_year can be localized.

It may be that the best option forward is to actually move names to the calendar because we need to have a canonical source. For example, we shouldn’t pass 1 representing a monday to the formatter, we should pass the atom :monday. Then the formatter can truly care only about localization and translation and also be calendar independent.

However, that still leaves week_of_year in a very awkward position. Maybe it is best to remove it from Elixir for now (or keep it formatter specific) until we are able to revisit this. In any case, @kip, to answer you more precisely, I don’t think you should create different calendars if the difference is the day of week or week of year. It is rather something to build on top.