--- name: "DateTime::Format::Flexible" section: "3pm" platform: "linux" package: "libdatetime-format-flexible-perl" version: "0.37-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/DateTime::Format::Flexible" --- # DateTime::Format::Flexible(3pm) DateTime::Format::Flexible - Flexibly parse strings and turn them into DateTime objects. ## NAME DateTime::Format::Flexible - DateTime::Format::Flexible - Flexibly parse strings and turn them into DateTime objects. ## SYNOPSIS ``` use DateTime::Format::Flexible; my $dt = DateTime::Format::Flexible->parse_datetime( 'January 8, 1999' ); # $dt = a DateTime object set at 1999-01-08T00:00:00 ``` ## DESCRIPTION If you have ever had to use a program that made you type in the date a certain way and thought "Why can't the computer just figure out what date I wanted?", this module is for you. *DateTime::Format::Flexible* attempts to take any string you give it and parse it into a DateTime object. ## USAGE This module uses *DateTime::Format::Builder* under the covers. ### parse\_datetime Give it a string and it attempts to parse it and return a DateTime object. If it cannot it will throw an exception. ``` my $dt = DateTime::Format::Flexible->parse_datetime( $date ); my $dt = DateTime::Format::Flexible->parse_datetime( $date, strip => [qr{\.\z}], # optional, remove a trailing period tz_map => {EDT => 'America/New_York'}, # optional, map the EDT timezone to America/New_York lang => ['es'], # optional, only parse using spanish european => 1, # optional, catch some cases of DD-MM-YY ); ``` - • `"base"` (optional) Does the same thing as the method `"base"`. Sets a base datetime for incomplete dates. Requires a valid DateTime object as an argument. example: ``` my $base_dt = DateTime->new( year => 2005, month => 2, day => 1 ); my $dt = DateTime::Format::Flexible->parse_datetime( '18 Mar', base => $base_dt, ); # $dt is now 2005-03-18T00:00:00 ``` - • `"strip"` (optional) Remove a substring from the string you are trying to parse. You can pass multiple regexes in an arrayref. example: ``` my $dt = DateTime::Format::Flexible->parse_datetime( '2011-04-26 00:00:00 (registry time)', strip => [qr{\(registry time\)\z}], ); # $dt is now 2011-04-26T00:00:00 ``` This is helpful if you have a load of dates you want to normalize and you know of some weird formatting beforehand. - • `"tz_map"` (optional) Map a given timezone to another recognized timezone Values are given as a hashref. example: ``` my $dt = DateTime::Format::Flexible->parse_datetime( '25-Jun-2009 EDT', tz_map => {EDT => 'America/New_York'}, ); # $dt is now 2009-06-25T00:00:00 with a timezone of America/New_York ``` This is helpful if you have a load of dates that have timezones that are not recognized by *DateTime::Timezone*. - • `"lang"` (optional) Specify the language map plugins to use. When DateTime::Format::Flexible parses a date with a string in it, it will search for a way to convert that string to a number. By default it will search through all the language plugins to search for a match. NOTE: as of 0.22, it will only do this search if it detects a string in the given date. Setting `"lang"` this lets you limit the scope of the search. example: ``` my $dt = DateTime::Format::Flexible->parse_datetime( 'Wed, Jun 10, 2009', lang => ['en'], ); # $dt is now 2009-06-10T00:00:00 ``` Currently supported languages are english (en), spanish (es) and german (de). Contributions, corrections, requests and examples are VERY welcome. See the *DateTime::Format::Flexible::lang::en*, *DateTime::Format::Flexible::lang::es*, and *DateTime::Format::Flexible::lang::de* for examples of the plugins. - • `"european"` (optional) If european is set to a true value, an attempt will be made to parse as a DD-MM-YYYY date instead of the default MM-DD-YYYY. There is a chance that this will not do the right thing due to ambiguity. example: ``` my $dt = DateTime::Format::Flexible->parse_datetime( '16/06/2010' , european => 1, ); # $dt is now 2010-06-16T00:00:00 ``` - • `"MMYY"` (optional) By default, this module will parse 12/10 as December 10th of the current year (MM/DD). If you want it to parse this as MM/YY instead, you can enable the `"MMYY"` option. example: ``` my $dt = DateTime::Format::Flexible->parse_datetime('12/10'); # $dt is now [current year]-12-10T00:00:00 my $dt = DateTime::Format::Flexible->parse_datetime( '12/10', MMYY => 1, ); # $dt is now 2010-12-01T00:00:00 ``` This is useful if you know you are going to be parsing a credit card expiration date. ### base gets/sets the base DateTime for incomplete dates. Requires a valid DateTime object as an argument when setting. This defaults to DateTime-\>now. example: ``` DateTime::Format::Flexible->base( DateTime->new( year => 2009, month => 6, day => 22 )); my $dt = DateTime::Format::Flexible->parse_datetime( '23:59' ); # $dt is now 2009-06-22T23:59:00 ``` ### build an alias for parse\_datetime ### Example formats A small list of supported formats: - YYYYMMDDTHHMMSS - YYYYMMDDTHHMM - YYYYMMDDTHH - YYYYMMDD - YYYYMM - MM-DD-YYYY - MM-D-YYYY - MM-DD-YY - M-DD-YY - YYYY/DD/MM - YYYY/M/DD - YYYY/MM/D - M-D - MM-D - M-D-Y - Month D, YYYY - Mon D, YYYY - Mon D, YYYY HH:MM:SS - ... thousands more there are 9000+ variations that are detected correctly in the test files (see t/data/\* for most of them). If you can think of any that I do not cover, please let me know. ## NOTES As of version 0.11 you will get a DateTime::Infinite::Future object if the passed in date is 'infinity' and a DateTime::Infinite::Past object if the passed in date is '-infinity'. If you are expecting these types of strings, you might want to check for '**is\_infinite()**' from the object returned. example: ``` my $dt = DateTime::Format::Flexible->parse_datetime( 'infinity' ); if ( $dt->is_infinite ) { # you have a Infinite object. } ``` ## BUGS/LIMITATIONS You cannot use a 1 or 2 digit year as the first field unless the year is \> 31: ``` YY-MM-DD # not supported if YY is <= 31 Y-MM-DD # not supported ``` It gets confused with MM-DD-YY ## AUTHOR Tom Heady \ ## COPYRIGHT & LICENSE Copyright 2007-2018 Tom Heady. This program is free software; you can redistribute it and/or modify it under the terms of either: - • the GNU General Public License as published by the Free\ Software Foundation; either version 1, or (at your option) any\ later version, or - • the Artistic License. ## SEE ALSO *DateTime::Format::Builder*, *DateTime::Timezone*, *DateTime::Format::Natural*