[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / InflateColumn / DateTime.pm

package DBIx::Class::InflateColumn::DateTime;

use strict;
use warnings;
use base qw/DBIx::Class/;
use Carp::Clan qw/^DBIx::Class/;

=head1 NAME

DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns.

=head1 SYNOPSIS

Load this component and then declare one or more 
columns to be of the datetime, timestamp or date datatype.

  package Event;
  use base 'DBIx::Class::Core';

  __PACKAGE__->load_components(qw/InflateColumn::DateTime/);
  __PACKAGE__->add_columns(
    starts_when => { data_type => 'datetime' }
    create_date => { data_type => 'date' }
  );

Then you can treat the specified column as a L<DateTime> object.

  print "This event starts the month of ".
    $event->starts_when->month_name();

If you want to set a specific timezone and locale for that field, use:

  __PACKAGE__->add_columns(
    starts_when => { data_type => 'datetime', timezone => "America/Chicago", locale => "de_DE" }
  );

If you want to inflate no matter what data_type your column is,
use inflate_datetime or inflate_date:

  __PACKAGE__->add_columns(
    starts_when => { data_type => 'varchar', inflate_datetime => 1 }
  );

  __PACKAGE__->add_columns(
    starts_when => { data_type => 'varchar', inflate_date => 1 }
  );

It's also possible to explicitly skip inflation:

  __PACKAGE__->add_columns(
    starts_when => { data_type => 'datetime', inflate_datetime => 0 }
  );

NOTE: Don't rely on C<InflateColumn::DateTime> to parse date strings for you.
The column is set directly for any non-references and C<InflateColumn::DateTime>
is completely bypassed.  Instead, use an input parser to create a DateTime
object. For instance, if your user input comes as a 'YYYY-MM-DD' string, you can
use C<DateTime::Format::ISO8601> thusly:

  use DateTime::Format::ISO8601;
  my $dt = DateTime::Format::ISO8601->parse_datetime('YYYY-MM-DD');

=head1 DESCRIPTION

This module figures out the type of DateTime::Format::* class to 
inflate/deflate with based on the type of DBIx::Class::Storage::DBI::* 
that you are using.  If you switch from one database to a different 
one your code should continue to work without modification (though note
that this feature is new as of 0.07, so it may not be perfect yet - bug
reports to the list very much welcome).

If the data_type of a field is C<date>, C<datetime> or C<timestamp> (or
a derivative of these datatypes, e.g. C<timestamp with timezone>), this
module will automatically call the appropriate parse/format method for
deflation/inflation as defined in the storage class. For instance, for
a C<datetime> field the methods C<parse_datetime> and C<format_datetime>
would be called on deflation/inflation. If the storage class does not
provide a specialized inflator/deflator, C<[parse|format]_datetime> will
be used as a fallback. See L<DateTime::Format> for more information on
date formatting.

For more help with using components, see L<DBIx::Class::Manual::Component/USING>.

=cut

__PACKAGE__->load_components(qw/InflateColumn/);

=head2 register_column

Chains with the L<DBIx::Class::Row/register_column> method, and sets
up datetime columns appropriately.  This would not normally be
directly called by end users.

In the case of an invalid date, L<DateTime> will throw an exception.  To
bypass these exceptions and just have the inflation return undef, use
the C<datetime_undef_if_invalid> option in the column info:

    "broken_date",
    {
        data_type => "datetime",
        default_value => '0000-00-00',
        is_nullable => 1,
        datetime_undef_if_invalid => 1
    }

=cut

sub register_column {
  my ($self, $column, $info, @rest) = @_;
  $self->next::method($column, $info, @rest);
  return unless defined($info->{data_type});

  my $type;

  for (qw/date datetime timestamp/) {
    my $key = "inflate_${_}";

    next unless exists $info->{$key};
    return unless $info->{$key};

    $type = $_;
    last;
  }

  unless ($type) {
    $type = lc($info->{data_type});
    if ($type eq "timestamp with time zone" || $type eq "timestamptz") {
      $type = "timestamp";
      $info->{_ic_dt_method} ||= "timestamp_with_timezone";
    } elsif ($type eq "timestamp without time zone") {
      $type = "timestamp";
      $info->{_ic_dt_method} ||= "timestamp_without_timezone";
    } elsif ($type eq "smalldatetime") {
      $type = "datetime";
      $info->{_ic_dt_method} ||= "datetime";
    }
  }

  my $timezone;
  if ( defined $info->{extra}{timezone} ) {
    carp "Putting timezone into extra => { timezone => '...' } has been deprecated, ".
         "please put it directly into the '$column' column definition.";
    $timezone = $info->{extra}{timezone};
  }

  my $locale;
  if ( defined $info->{extra}{locale} ) {
    carp "Putting locale into extra => { locale => '...' } has been deprecated, ".
         "please put it directly into the '$column' column definition.";
    $locale = $info->{extra}{locale};
  }

  $locale   = $info->{locale}   if defined $info->{locale};
  $timezone = $info->{timezone} if defined $info->{timezone};

  my $undef_if_invalid = $info->{datetime_undef_if_invalid};

  if ($type eq 'datetime' || $type eq 'date' || $type eq 'timestamp') {
    # This shallow copy of %info avoids t/52_cycle.t treating
    # the resulting deflator as a circular reference.
    my %info = ( '_ic_dt_method' => $type , %{ $info } );

    if (defined $info->{extra}{floating_tz_ok}) {
      carp "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ".
           "please put it directly into the '$column' column definition.";
      $info{floating_tz_ok} = $info->{extra}{floating_tz_ok};
    }

    $self->inflate_column(
      $column =>
        {
          inflate => sub {
            my ($value, $obj) = @_;

            my $dt = eval { $obj->_inflate_to_datetime( $value, \%info ) };
            if (my $err = $@ ) {
              return undef if ($undef_if_invalid);
              $self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $err");
            }

            return $obj->_post_inflate_datetime( $dt, \%info );
          },
          deflate => sub {
            my ($value, $obj) = @_;

            $value = $obj->_pre_deflate_datetime( $value, \%info );
            $obj->_deflate_from_datetime( $value, \%info );
          },
        }
    );
  }
}

sub _flate_or_fallback
{
  my( $self, $value, $info, $method_fmt ) = @_;

  my $parser = $self->_datetime_parser;
  my $preferred_method = sprintf($method_fmt, $info->{ _ic_dt_method });
  my $method = $parser->can($preferred_method) ? $preferred_method : sprintf($method_fmt, 'datetime');
  return $parser->$method($value);
}

sub _inflate_to_datetime {
  my( $self, $value, $info ) = @_;
  return $self->_flate_or_fallback( $value, $info, 'parse_%s' );
}

sub _deflate_from_datetime {
  my( $self, $value, $info ) = @_;
  return $self->_flate_or_fallback( $value, $info, 'format_%s' );
}

sub _datetime_parser {
  shift->result_source->storage->datetime_parser (@_);
}

sub _post_inflate_datetime {
  my( $self, $dt, $info ) = @_;

  my $timezone;
  if (exists $info->{timezone}) {
    $timezone = $info->{timezone};
  }
  elsif (exists $info->{extra} and exists $info->{extra}{timezone}) {
    $timezone = $info->{extra}{timezone};
  }

  my $locale;
  if (exists $info->{locale}) {
    $locale = $info->{locale};
  }
  elsif (exists $info->{extra} and exists $info->{extra}{locale}) {
    $locale = $info->{extra}{locale};
  }

  $dt->set_time_zone($timezone) if $timezone;
  $dt->set_locale($locale) if $locale;

  return $dt;
}

sub _pre_deflate_datetime {
  my( $self, $dt, $info ) = @_;

  my $timezone;
  if (exists $info->{timezone}) {
    $timezone = $info->{timezone};
  }
  elsif (exists $info->{extra} and exists $info->{extra}{timezone}) {
    $timezone = $info->{extra}{timezone};
  }

  my $locale;
  if (exists $info->{locale}) {
    $locale = $info->{locale};
  }
  elsif (exists $info->{extra} and exists $info->{extra}{locale}) {
    $locale = $info->{extra}{locale};
  }

  if ($timezone) {
    carp "You're using a floating timezone, please see the documentation of"
      . " DBIx::Class::InflateColumn::DateTime for an explanation"
      if ref( $dt->time_zone ) eq 'DateTime::TimeZone::Floating'
          and not $info->{floating_tz_ok}
          and not $ENV{DBIC_FLOATING_TZ_OK};

    $dt->set_time_zone($timezone);
  }

  $dt->set_locale($locale) if $locale;

  return $dt;
}

1;
__END__

=head1 USAGE NOTES

If you have a datetime column with an associated C<timezone>, and subsequently
create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
timezone, you will get a warning (as there is a very good chance this will not have the
result you expect). For example:

  __PACKAGE__->add_columns(
    starts_when => { data_type => 'datetime', timezone => "America/Chicago" }
  );

  my $event = $schema->resultset('EventTZ')->create({
    starts_at => DateTime->new(year=>2007, month=>12, day=>31, ),
  });

The warning can be avoided in several ways:

=over

=item Fix your broken code

When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply
set to the requested value, and B<no time conversion takes place>. It is always a good idea
to be supply explicit times to the database:

  my $event = $schema->resultset('EventTZ')->create({
    starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
  });

=item Suppress the check on per-column basis

  __PACKAGE__->add_columns(
    starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 }
  );

=item Suppress the check globally

Set the environment variable DBIC_FLOATING_TZ_OK to some true value.

=back

Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been
B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>.
Instead put it directly into the columns definition like in the examples above. If you still
use the old way you'll see a warning - please fix your code then!

=head1 SEE ALSO

=over 4

=item More information about the add_columns method, and column metadata, 
      can be found in the documentation for L<DBIx::Class::ResultSource>.

=item Further discussion of problems inherent to the Floating timezone:
      L<Floating DateTimes|DateTime/Floating_DateTimes> 
      and L<< $dt->set_time_zone|DateTime/"Set" Methods >>

=back

=head1 AUTHOR

Matt S. Trout <mst@shadowcatsystems.co.uk>

=head1 CONTRIBUTORS

Aran Deltac <bluefeet@cpan.org>

=head1 LICENSE

You may distribute this code under the same terms as Perl itself.
Commit	Line	Data
445e5e31	1	package DBIx::Class::InflateColumn::DateTime;
	2
	3	use strict;
	4	use warnings;
	5	use base qw/DBIx::Class/;
341d5ede	6	use Carp::Clan qw/^DBIx::Class/;
445e5e31	7
0b375b68	8	=head1 NAME
0b375b68	9
5d0a2955	10	DBIx::Class::InflateColumn::DateTime - Auto-create DateTime objects from date and datetime columns.
0b375b68	11
	12	=head1 SYNOPSIS
	13
	14	Load this component and then declare one or more
679a304a	15	columns to be of the datetime, timestamp or date datatype.
0b375b68	16
0b375b68	17	package Event;
d88ecca6	18	use base 'DBIx::Class::Core';
	19
	20	__PACKAGE__->load_components(qw/InflateColumn::DateTime/);
0b375b68	21	__PACKAGE__->add_columns(
0b375b68	22	starts_when => { data_type => 'datetime' }
9c71b5e2	23	create_date => { data_type => 'date' }
0b375b68	24	);
	25
	26	Then you can treat the specified column as a L<DateTime> object.
	27
	28	print "This event starts the month of ".
	29	$event->starts_when->month_name();
	30
8d689133	31	If you want to set a specific timezone and locale for that field, use:
dda9af55	32
dda9af55	33	__PACKAGE__->add_columns(
92ed0695	34	starts_when => { data_type => 'datetime', timezone => "America/Chicago", locale => "de_DE" }
dda9af55	35	);
dda9af55	36
a97fe7e0	37	If you want to inflate no matter what data_type your column is,
	38	use inflate_datetime or inflate_date:
	39
	40	__PACKAGE__->add_columns(
	41	starts_when => { data_type => 'varchar', inflate_datetime => 1 }
	42	);
d4daee7b	43
a97fe7e0	44	__PACKAGE__->add_columns(
	45	starts_when => { data_type => 'varchar', inflate_date => 1 }
	46	);
	47
ff8a6e3b	48	It's also possible to explicitly skip inflation:
d4daee7b	49
ff8a6e3b	50	__PACKAGE__->add_columns(
	51	starts_when => { data_type => 'datetime', inflate_datetime => 0 }
	52	);
	53
8bf37b16	54	NOTE: Don't rely on C<InflateColumn::DateTime> to parse date strings for you.
	55	The column is set directly for any non-references and C<InflateColumn::DateTime>
	56	is completely bypassed. Instead, use an input parser to create a DateTime
	57	object. For instance, if your user input comes as a 'YYYY-MM-DD' string, you can
	58	use C<DateTime::Format::ISO8601> thusly:
d6aed638	59
	60	use DateTime::Format::ISO8601;
	61	my $dt = DateTime::Format::ISO8601->parse_datetime('YYYY-MM-DD');
	62
0b375b68	63	=head1 DESCRIPTION
	64
	65	This module figures out the type of DateTime::Format::* class to
	66	inflate/deflate with based on the type of DBIx::Class::Storage::DBI::*
	67	that you are using. If you switch from one database to a different
5d0a2955	68	one your code should continue to work without modification (though note
	69	that this feature is new as of 0.07, so it may not be perfect yet - bug
	70	reports to the list very much welcome).
0b375b68	71
9c71b5e2	72	If the data_type of a field is C<date>, C<datetime> or C<timestamp> (or
f59e543b	73	a derivative of these datatypes, e.g. C<timestamp with timezone>), this
9c71b5e2	74	module will automatically call the appropriate parse/format method for
	75	deflation/inflation as defined in the storage class. For instance, for
	76	a C<datetime> field the methods C<parse_datetime> and C<format_datetime>
	77	would be called on deflation/inflation. If the storage class does not
	78	provide a specialized inflator/deflator, C<[parse\|format]_datetime> will
	79	be used as a fallback. See L<DateTime::Format> for more information on
	80	date formatting.
	81
943f93f2	82	For more help with using components, see L<DBIx::Class::Manual::Component/USING>.
de78905b	83
0b375b68	84	=cut
0b375b68	85
445e5e31	86	__PACKAGE__->load_components(qw/InflateColumn/);
445e5e31	87
9b83fccd	88	=head2 register_column
	89
	90	Chains with the L<DBIx::Class::Row/register_column> method, and sets
	91	up datetime columns appropriately. This would not normally be
	92	directly called by end users.
	93
33a126ef	94	In the case of an invalid date, L<DateTime> will throw an exception. To
	95	bypass these exceptions and just have the inflation return undef, use
	96	the C<datetime_undef_if_invalid> option in the column info:
d4daee7b	97
33a126ef	98	"broken_date",
	99	{
	100	data_type => "datetime",
	101	default_value => '0000-00-00',
	102	is_nullable => 1,
	103	datetime_undef_if_invalid => 1
	104	}
	105
9b83fccd	106	=cut
9b83fccd	107
445e5e31	108	sub register_column {
	109	my ($self, $column, $info, @rest) = @_;
	110	$self->next::method($column, $info, @rest);
c209c4fd	111	return unless defined($info->{data_type});
bb90689c	112
	113	my $type;
	114
abc914bd	115	for (qw/date datetime timestamp/) {
bb90689c	116	my $key = "inflate_${_}";
	117
	118	next unless exists $info->{$key};
	119	return unless $info->{$key};
	120
	121	$type = $_;
	122	last;
	123	}
	124
	125	unless ($type) {
	126	$type = lc($info->{data_type});
6c99a3ee	127	if ($type eq "timestamp with time zone" \|\| $type eq "timestamptz") {
	128	$type = "timestamp";
	129	$info->{_ic_dt_method} \|\|= "timestamp_with_timezone";
65b386df	130	} elsif ($type eq "timestamp without time zone") {
	131	$type = "timestamp";
	132	$info->{_ic_dt_method} \|\|= "timestamp_without_timezone";
4a80eede	133	} elsif ($type eq "smalldatetime") {
	134	$type = "datetime";
	135	$info->{_ic_dt_method} \|\|= "datetime";
6c99a3ee	136	}
bb90689c	137	}
bb90689c	138
dda9af55	139	my $timezone;
8d689133	140	if ( defined $info->{extra}{timezone} ) {
341d5ede	141	carp "Putting timezone into extra => { timezone => '...' } has been deprecated, ".
6c9d0c63	142	"please put it directly into the '$column' column definition.";
dda9af55	143	$timezone = $info->{extra}{timezone};
	144	}
	145
8d689133	146	my $locale;
8d689133	147	if ( defined $info->{extra}{locale} ) {
341d5ede	148	carp "Putting locale into extra => { locale => '...' } has been deprecated, ".
6c9d0c63	149	"please put it directly into the '$column' column definition.";
8d689133	150	$locale = $info->{extra}{locale};
8d689133	151	}
d4daee7b	152
92ed0695	153	$locale = $info->{locale} if defined $info->{locale};
92ed0695	154	$timezone = $info->{timezone} if defined $info->{timezone};
8d689133	155
dceeddc7	156	my $undef_if_invalid = $info->{datetime_undef_if_invalid};
dceeddc7	157
abc914bd	158	if ($type eq 'datetime' \|\| $type eq 'date' \|\| $type eq 'timestamp') {
ab969dd4	159	# This shallow copy of %info avoids t/52_cycle.t treating
	160	# the resulting deflator as a circular reference.
	161	my %info = ( '_ic_dt_method' => $type , %{ $info } );
	162
92ed0695	163	if (defined $info->{extra}{floating_tz_ok}) {
341d5ede	164	carp "Putting floating_tz_ok into extra => { floating_tz_ok => 1 } has been deprecated, ".
6c9d0c63	165	"please put it directly into the '$column' column definition.";
b1e4a1df	166	$info{floating_tz_ok} = $info->{extra}{floating_tz_ok};
92ed0695	167	}
45147005	168
445e5e31	169	$self->inflate_column(
	170	$column =>
	171	{
	172	inflate => sub {
	173	my ($value, $obj) = @_;
40f75181	174
ab969dd4	175	my $dt = eval { $obj->_inflate_to_datetime( $value, \%info ) };
40f75181	176	if (my $err = $@ ) {
	177	return undef if ($undef_if_invalid);
	178	$self->throw_exception ("Error while inflating ${value} for ${column} on ${self}: $err");
	179	}
	180
f856fe01	181	return $obj->_post_inflate_datetime( $dt, \%info );
445e5e31	182	},
	183	deflate => sub {
	184	my ($value, $obj) = @_;
f856fe01	185
f856fe01	186	$value = $obj->_pre_deflate_datetime( $value, \%info );
ab969dd4	187	$obj->_deflate_from_datetime( $value, \%info );
445e5e31	188	},
	189	}
	190	);
	191	}
	192	}
	193
ab969dd4	194	sub _flate_or_fallback
	195	{
	196	my( $self, $value, $info, $method_fmt ) = @_;
	197
	198	my $parser = $self->_datetime_parser;
	199	my $preferred_method = sprintf($method_fmt, $info->{ _ic_dt_method });
	200	my $method = $parser->can($preferred_method) ? $preferred_method : sprintf($method_fmt, 'datetime');
	201	return $parser->$method($value);
	202	}
	203
	204	sub _inflate_to_datetime {
	205	my( $self, $value, $info ) = @_;
	206	return $self->_flate_or_fallback( $value, $info, 'parse_%s' );
	207	}
	208
	209	sub _deflate_from_datetime {
	210	my( $self, $value, $info ) = @_;
	211	return $self->_flate_or_fallback( $value, $info, 'format_%s' );
	212	}
abc914bd	213
445e5e31	214	sub _datetime_parser {
f568d83b	215	shift->result_source->storage->datetime_parser (@_);
445e5e31	216	}
445e5e31	217
f856fe01	218	sub _post_inflate_datetime {
	219	my( $self, $dt, $info ) = @_;
	220
	221	my $timezone;
	222	if (exists $info->{timezone}) {
	223	$timezone = $info->{timezone};
	224	}
	225	elsif (exists $info->{extra} and exists $info->{extra}{timezone}) {
	226	$timezone = $info->{extra}{timezone};
	227	}
	228
	229	my $locale;
	230	if (exists $info->{locale}) {
	231	$locale = $info->{locale};
	232	}
	233	elsif (exists $info->{extra} and exists $info->{extra}{locale}) {
	234	$locale = $info->{extra}{locale};
	235	}
	236
	237	$dt->set_time_zone($timezone) if $timezone;
	238	$dt->set_locale($locale) if $locale;
	239
	240	return $dt;
	241	}
	242
	243	sub _pre_deflate_datetime {
	244	my( $self, $dt, $info ) = @_;
	245
	246	my $timezone;
	247	if (exists $info->{timezone}) {
	248	$timezone = $info->{timezone};
	249	}
	250	elsif (exists $info->{extra} and exists $info->{extra}{timezone}) {
	251	$timezone = $info->{extra}{timezone};
	252	}
	253
	254	my $locale;
	255	if (exists $info->{locale}) {
	256	$locale = $info->{locale};
	257	}
	258	elsif (exists $info->{extra} and exists $info->{extra}{locale}) {
	259	$locale = $info->{extra}{locale};
	260	}
	261
	262	if ($timezone) {
	263	carp "You're using a floating timezone, please see the documentation of"
	264	. " DBIx::Class::InflateColumn::DateTime for an explanation"
	265	if ref( $dt->time_zone ) eq 'DateTime::TimeZone::Floating'
	266	and not $info->{floating_tz_ok}
	267	and not $ENV{DBIC_FLOATING_TZ_OK};
	268
	269	$dt->set_time_zone($timezone);
	270	}
	271
	272	$dt->set_locale($locale) if $locale;
	273
	274	return $dt;
	275	}
	276
445e5e31	277	1;
0b375b68	278	__END__
0b375b68	279
45147005	280	=head1 USAGE NOTES
45147005	281
97983826	282	If you have a datetime column with an associated C<timezone>, and subsequently
45147005	283	create/update this column with a DateTime object in the L<DateTime::TimeZone::Floating>
	284	timezone, you will get a warning (as there is a very good chance this will not have the
	285	result you expect). For example:
	286
	287	__PACKAGE__->add_columns(
92ed0695	288	starts_when => { data_type => 'datetime', timezone => "America/Chicago" }
45147005	289	);
	290
	291	my $event = $schema->resultset('EventTZ')->create({
	292	starts_at => DateTime->new(year=>2007, month=>12, day=>31, ),
	293	});
	294
	295	The warning can be avoided in several ways:
	296
	297	=over
	298
	299	=item Fix your broken code
	300
	301	When calling C<set_time_zone> on a Floating DateTime object, the timezone is simply
	302	set to the requested value, and B<no time conversion takes place>. It is always a good idea
	303	to be supply explicit times to the database:
	304
	305	my $event = $schema->resultset('EventTZ')->create({
	306	starts_at => DateTime->new(year=>2007, month=>12, day=>31, time_zone => "America/Chicago" ),
	307	});
	308
	309	=item Suppress the check on per-column basis
	310
	311	__PACKAGE__->add_columns(
92ed0695	312	starts_when => { data_type => 'datetime', timezone => "America/Chicago", floating_tz_ok => 1 }
45147005	313	);
	314
	315	=item Suppress the check globally
	316
	317	Set the environment variable DBIC_FLOATING_TZ_OK to some true value.
	318
	319	=back
	320
92ed0695	321	Putting extra attributes like timezone, locale or floating_tz_ok into extra => {} has been
	322	B<DEPRECATED> because this gets you into trouble using L<DBIx::Class::Schema::Versioned>.
	323	Instead put it directly into the columns definition like in the examples above. If you still
	324	use the old way you'll see a warning - please fix your code then!
45147005	325
0b375b68	326	=head1 SEE ALSO
	327
	328	=over 4
	329
	330	=item More information about the add_columns method, and column metadata,
	331	can be found in the documentation for L<DBIx::Class::ResultSource>.
	332
45147005	333	=item Further discussion of problems inherent to the Floating timezone:
	334	L<Floating DateTimes\|DateTime/Floating_DateTimes>
	335	and L<< $dt->set_time_zone\|DateTime/"Set" Methods >>
	336
0b375b68	337	=back
	338
	339	=head1 AUTHOR
	340
	341	Matt S. Trout <mst@shadowcatsystems.co.uk>
	342
	343	=head1 CONTRIBUTORS
	344
	345	Aran Deltac <bluefeet@cpan.org>
	346
	347	=head1 LICENSE
	348
	349	You may distribute this code under the same terms as Perl itself.
	350