Re: Parser/Backend API proposals

[John Peacock]

Dave Rolsky wrote:
> I should also point out I'm moving the ical-specific bits to
> DateTime::Formats::ICal.

As soon as SF gets their servers back in operation (what's up with that?), I'll
take a look at what you have. My quicky module is not meant to be an example of
anything practical, just something to toy with. In particular, you (in
particular) will blanche at the fact I used Autoloader (since that is what
h2xs normally includes), which is not friendly towards mod_perl code.

> How about this instead:
>
> my $formatter =
> DateTime::Formats::ISO8601->new
> ( class => 'DateTime::Implementation::TAI64' );
>
> my $dt = $formatter->parse( ... );

That's OK, but too verbose for the average user, IMHO. It also leaps too deeply
into the API for my taste. I would suggest that the average user shouldn't need
to do anything more than

my $dt = DateTime->new($datestring);

and have that do something useful for the majority of the trivial cases. I hate
to keep bringing up Math::BigInt, but the model is very close to what I think is
ideal. The base package works out of the box, but if you want better
performance, you add one line and your existing code works just the same, only
faster:

use Math::BigInt; # implicitly uses Math::BigInt::Calc
use Math::BigInt lib => 'BitVect'; # faster backend

and there is no need to change your existing code; I think it unlikely that anyone would want to use more than one storage/backend module at the same time.

I also think I didn't explain my proposal sufficiently. I would argue that the parser modules should be extremely thin and not full fledged constructors. All that the parser would do is parse into a common format and leave the object creation to the storage module.

>
> The assumption here is that there is a standard set of arguments which can
> be given to the constructor, which follows from the assumption that all
> DateTime "core object" implementations share an API. These constructor
> arguments would probably be:
>
> year, month, day
> hour, minute, second
> time_zone

which is exactly my $obj->as_array method would return. The reason that I
suggested multiple possible parses is that some backends (like TAI) already have
a conversion from a specific external representation to their internal
representation. If the array of arguments is agreed to be the most likely
"normalized" representation, I would actually have the Formats modules include
only a single function Parse() which would return the normalized relationship (or undef if this parser cannot handle that date string).

>
> I think we should assume that creating a format/parse object will be
> one step, and actual parsing/formatting will be a different one.

Why? It requires the average user to know far more about the internals than is strictly necessary. Sure, it has to be available for those who need it, but it shouldn't be the default interface.

>
> I don't think the parser should be directly responsible for producing
> anything other than "DateTime.pm API-compliant object", which may or may
> not actually _be_ a DateTime.pm object.

Well then we may be saying the same thing; I want the parser to generate a normalized date format. I'm just saying that making the parser itself an object is not _required_ to do that.

>
> So what's implemented in DateTime.pm in this idea? Nothing? If nothing,
> it might as well just return an object in a different class. I don't
> think I understand what you're suggesting.

Not at all. DateTime is the gatekeeper class; it contains any overloading code (which you haven't really mentioned yet, have you?) as well as all of the exposed API. But it doesn't need to contain the actual code to implement the API, and I would argue, shouldn't. See below

>
>
>>I have DateTime::Formats::ISO8601 done (well formed ISO dates only); I attach it
>>for your pleasure. I can work on DateTime::Formats::Date_Parse for the more
>
>
> By "Date_Parse" do you mean complex Date::Manip style parsing?

No, actually I meant Graham Barr's Date::Parse (part of Time::Date). Someone will likely want the Date::Manip parsing available as well.

>
> As to DateTime::Thingy::TAI64, I think it needs to do the following:
>
> - implement the same API as DateTime.pm, possibly adding some TAI64
> methods if that's useful
>
> - inherit from DateTime.pm - this follows from the former. There's no
> reason to implement a method like "year_0", which is defined in
> DateTime.pm as:
>
> sub year_0 { $_[0]->year - 1 }
>
> There's a number of other methods in DateTime.pm it'd be pointless to
> override as well, along these same lines.
>

No question. Any implemention class will inherit all of the derivable methods and only implement/override the minority of primitive methods (like $obj->year for example).

John

--
John Peacock
Director of Information Research and Technology
Rowman & Littlefield Publishing Group
4720 Boston Way
Lanham, MD 20706
301-459-3366 x.5010
fax 301-429-5747