view release on metacpan or  search on metacpan

lib/DateTimeX/Format/Ago.pm  view on Meta::CPAN

	}
	
	Carp::croak(sprintf("%s doesn't know about language '%s'", __PACKAGE__, $self->{language}));
}

__PACKAGE__
__END__

=pod

=encoding utf-8

=head1 NAME

DateTimeX::Format::Ago - I should have written this module "3 years ago"

=head1 SYNOPSIS

  my $then = DateTime->now->subtract(days => 3);
  say DateTimeX::Format::Ago->format_datetime($then); # "3 days ago"

=head1 DESCRIPTION

Ever wished DateTime::Format::Natural had a C<format_datetime>
method? This module provides human-friendly datetime formatting,
outputting strings like "3 days ago".

Primary use case: websites that show a list of a person's recent
activities.

=head2 Constructor

=over

=item C<< new(language => $lang) >>

Creates a formatter object for the given language (a BCP47 language code).
If the language is omitted, extracts it from C<< $ENV{LANG} >>.

Decent English ('en'), German ('de'), French ('fr'), Portuguese ('pt'),
Korean ('ko'), and Indonesian ('id') support is provided. Castillian
Spanish ('es') is also provided, but some of the strings were translated
with Google Translate, so they might not be perfect.

=back

=head2 Methods

=over

=item C<< format_datetime($dt) >>

Returns something like "3 days ago", "just now" or "hace un año".

=item C<< parse_datetime($string) >>

Croaks. Don't use this.

=back

=head1 BUGS AND LIMITATIONS

=head2 High resolution datetimes

Imagine the time is currently 2020-01-01T12:00:00.200. If you try to format
the time 2020-01-01T12:00:00.100 you'll get back the result "in the future".
So what's going on? DateTimeX::Format::Ago figures out when "now" is using
C<< DateTime->now >>, which rounds back to the nearest whole second.

If you know you're going to be dealing with high resolution datetimes, and
don't want to occasionally see "in the future" for times in the very recent
past, then use L<Time::HiRes>.

 use Time::HiRes qw();

That's all you need to do. Merely loading it will give DateTimeX::Format::Ago
an indication that you want it to use a more accurate idea of "now".

=head2 Translations

This module only supports a handful of languages. I'm seeking translations.
Feel free to attach patches for other languages as bug reports.

=head2 Reporting Bugs

Please report any bugs to
L<http://rt.cpan.org/Dist/Display.html?Queue=DateTimeX-Format-Ago>.

=head1 SEE ALSO

L<DateTime>, L<DateTime::Format::Natural>.

L<http://www.rfc-editor.org/rfc/bcp/bcp47.txt>.

=head1 AUTHOR

Toby Inkster E<lt>tobyink@cpan.orgE<gt>.

=head1 COPYRIGHT AND LICENCE

This software is copyright (c) 2011-2012, 2014 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=head1 DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.