Re: Parsing/Formatting API

[Matthew Simon Cavalletto]

On Tuesday, January 14, 2003, at 03:03  PM, Dave Rolsky wrote:

  use DateTime::Parse::MySQL; # this needs a better name

I've suggested "DateTime::Format::MySQL".

Actually, I'm leaning towards DateTime::Representation::* at the moment. Format is correct if read as a noun, but confusing if read as a verb.

Representation is kind of long-winded, and I'm not sure it communicates the text-centric nature of the code in question, but I could live with it.

Here are a few other candidate namespace options -- do any stand out?
DateTime::Format::MySQL->parse( ... )
DateTime::Representation::MySQL->parse( ... )
DateTime::String::MySQL->parse( ... )
DateTime::Text::MySQL->parse( ... )

So, here's the option I'm proposing: [...]
   print DateTime::Format::MySQL->format_string( $dt );

MySQL has quite a number of possible formats, including:
  DATETIME column - "YYYY-MM-DD HH:MM:SS"
  DATE column     - "YYYY-MM-DD"
  TIME column     - "HH:MM::S"
  TIMESPAN column - "YYYYMMDDHHMMSS" and about 6-7 others

So the method names will have to distinguish between these.
It's possible to simply offer one method per data type.

Alright -- so we've got one format method per type:

DateTime::Format::MySQL->format_datetime( $dt );
DateTime::Format::MySQL->format_date( $dt );
DateTime::Format::MySQL->format_time( $dt );
DateTime::Format::MySQL->format_timespan( $dt );

Then in front of that, we put a dynamic dispatch method:

DateTime::Format::MySQL->format_string( $dt, $fmt );

This calls DateTime::Format::MySQL->format_$fmt( $dt ), with $fmt defaulting to "datetime", or dies if no such method exists.

I don't actually like having parsing done with one method, because it
encourages user mistakes like passing in just a date, but thinking you
have a datetime.  Then you're confused as to why the time is always
"00:00:00".

On the parser side, we might want to mirror this structure, with one parser method per data type, and a general-purpose parse_string() method that examines its arguments and then delegates to whichever parser is appropriate.

I'm also proposing the addition of gateway methods where appropriate; these are just dynamic dispatch methods for convenience, hopefully only a few lines of code each.
my $dt = DateTime->new_from_format( 'MySQL', $mysql_dt );
print $dt->format_string( 'MySQL' );

Make a proposal that handles multiple formats per module, and I'll consider it. Obviously, what you propose above doesn't work without some sort of extension.

Actually, I don't think the gateway interface needs to be changed at all, you just pass the data type as another argument:

print $dt->format_string( 'MySQL', 'date' );
print $dt->format_string( 'MySQL', 'time' );

This makes it very nicely parallel to strftime:

print $dt->format_string( 'strftime', '%Y/%m/%d' );

If we adopted the suggestion from Antonios Christofides about supporting a list-context calling convention for obtaining several values at once, it could be used with any of these formatter modules:

my ($y, $m, $d) = $dt->format_string( 'strftime', '%Y', '%m', '%d' );
my @dbi_params = $dt->format_string( 'MySQL', 'date', 'time' );

-Simon