Format Modules

A module belongs under the DateTime::Format namespace if it implements datetime parsing or formatting. In the namespace the word "Format" is being used as a noun, not a verb, so a module in this namespace can perform formatting, parsing, or both.

API

The API will be shaped by the complexity of the format that the module handles. If possible, all DateTime::Format modules should include the following methods:

parse_datetime($string)

Given a string, this method should return a new DateTime.pm object.

format_datetime($dt)

Given a DateTime.pm object, this method should return a string.

The module may also implement additional methods, such as parse_date()/format_date() or parse_duration()/format_duration(), depending on what the format can be used to represent.

For simple formats, these methods can be class methods. If multiple parameters are required, then the methods should accept named parameters, so that they look something like this:

DateTime::Format::Foo->parse_datetime( datetime => '...', param => 'foo', ... );

If the parameters are complex enough, it may be better to simply require that the user the user create a new object encapsulating various parameters and then call methods on it. TIME ZONES

If the time zone for a parsed datetime is not known, then the returned DateTime.pm object should be in the floating time zone. If the format includes an Olson named time zone, the returned DateTime.pm object should be in that time zone. If the format includes a less precise time zone, like "EST" or "-05:00", use your best judgement. It may be best to simply return an object in the UTC time zone (with the correct UTC datetime, of course).

If the format mandates that you default to the system's local time zone, write your code and tests carefully, because DateTime::TimeZone will throw an exception if it cannot find the local time zone on a system. Make sure to document that parsing can fail because of this, and make sure that your tests pass even if the local time zone cannot be determined.