NAME

XML::SRS::TimeStamp::Role - composable timestamp attributes

SYNOPSIS

 package XML::SRS::Some::Class;
 use Moose;

 with 'XML::SRS::TimeStamp::Role', 'XML::SRS::Node';

DESCRIPTION

Sometimes, in the SRS schema, a timestamp is represented with its own node, <TimeStamp>;

  <TimeStamp Hour="12" Minute="24" Second="0"
             Day="31" Month="1" Year="2010"
             TZOffset="+12:00" />

For this purpose, the concrete class XML::SRS::TimeStamp is used.

However, when the attributes which represent the also appear alongside other child elements or attributes, a concrete class would not be appropriate to re-use. In that case, the role XML::SRS::TimeStamp::Role must be composed.

An example of this is the XML::SRS::Domain::Transferred class, as in:

  <DomainTransfer
             Hour="12" Minute="24" Second="0"
             Day="31" Month="1" Year="2010"
             TZOffset="+12:00">
    <TransferredDomain>foo.co.nz</TransferredDomain>
  </DomainTransfer>

To avoid repetition, this class exists.

It also adds various properties and psuedo-properties for convenience, such as:

timestamptz

(cached, derived, psuedo) this is a psuedo-property, which returns the value of the timestamp within as an ISO-8601 timestamp, without the T, and with a timezone offset (defaulting to the offset of this time according to local rules). The XML::SRS::TimeStamp class has a BUILDARGS class method which allows this to be a "psuedo-property"; you can pass it to XML::SRS::TimeStamp->new, and it will fill in all the other required accessors.

eg

   XML::SRS::TimeStamp->new(
        timestamptz => "2010-12-12 12:12:12+12:00",
   );

Will create an object:

   bless(
       {
           'hour' => '12',
           'month' => '12',
           'second' => '12',
           'tz_offset' => '+1200',
           'minute' => '12',
           'day' => '12',
           'timestamptz' => '2010-12-12 12:12:12+1200',
           'year' => '2010'
       },
       'XML::SRS::TimeStamp'
   );

timestamp

(cached, derived, psuedo) Like timestamp, but you don't end up setting the tz_offset property if passed in for construction, and it does not have a time zone.

epoch

(cached, derived, psuedo) Like timestamptz, but the time is expressed as a unix epoch time without a timezone.

in construction it will also use the local time rules:

    perl -MXML::SRS::TimeStamp -MYAML -E 'say XML::SRS::TimeStamp->new(
            epoch => time(),
       )->dump;'
    $VAR1 = bless( {
                     'hour' => '21',
                     'epoch' => 1283200164,
                     'month' => '08',
                     'second' => '24',
                     'tz_offset' => '+0100',
                     'minute' => '29',
                     'day' => '30',
                     'year' => '2010'
                   }, 'XML::SRS::TimeStamp' );

(Above is a summer time time)

   perl -MXML::SRS::TimeStamp -MYAML -E 'say XML::SRS::TimeStamp->new(
           epoch => time()+6*30*86400,
      )->dump;'
   $VAR1 = bless( {
                    'hour' => '20',
                    'epoch' => 1298752226,
                    'month' => '02',
                    'second' => '26',
                    'tz_offset' => '+0000',
                    'minute' => '30',
                    'day' => '26',
                    'year' => '2011'
                  }, 'XML::SRS::TimeStamp' );

(and for comparison, a non-daylight savings time)

XML::SRS::Time and XML::SRS::Date

These roles contain the component parts of Date and Time, to keep them independent. XML::SRS::TimeStamp::Role composes both of these. They are not used by any other classes.

SEE ALSO

XML::SRS

AUTHOR AND LICENCE

Development commissioned by NZ Registry Services, and carried out by Catalyst IT - http://www.catalyst.net.nz/

Copyright 2009, 2010, NZ Registry Services. This module is licensed under the Artistic License v2.0, which permits relicensing under other Free Software licenses.