NAME

Advanced::Config::Date - Module for parsing dates for Advanced::Config.

SYNOPSIS

use Advanced::Config::Date;
or 
require Advanced::Config::Date;

DESCRIPTION

Advanced::Config::Date is a helper module to Advanced::Config. So it should be very rare to directly call any methods defined by this module. But it's perfectly OK to use this module directly if you wish.

It's main job is to handle parsing dates passed in various formats and languages while returning it in the standardized format of: YYYY-MM-DD. Hiding all the messy logic of how to interprit any given date string.

MULTI-LANGUAGE SUPPORT

By default this module only supports parsing English language dates.

But if you have the Date::Language and/or Date::Manip modules installed you can ask for it to use another language supported by either of these modules instead.

You have to explicitly allow languages that require the use of Wide Chars. Otherwise they are not supported.

If a language is defined in both modules, it will merge the data together. Since both modules sometimes give extra information that can be usefull in parsing a date..

FOUR-DIGIT VS TWO-DIGIT YEARS IN A DATE

This module will accept both 4-digit and 2-digit years in the dates it parses. But two-digit years are inheritly ambiguous if you aren't given the expected format up front. So 2-digit years generate more unreliability in the parsing of any dates by this module.

So when used by the Advanced::Config module, that module gives you the ability to turn two-digit years on or off. This is done via the Get Option "date_enable_yy" which defaults to 0, not allowing two-digit years.

To help resolve ambiguity with numeric dates, there is an option "date_format" that tells the Advanced::Config how to parse these dates. See the order argument for parse_6_digit_date() and parse_8_digit_date() for how this is done.

Finally if you use "date_dl_conversion" and module Date::Language is installed, it will enhance parse_date() with that module's str2time() parser. So if this option was used, it doesn't make much sense to disable 2-digit years. Since we can't turn off 2-digit year support for str2time().

See Advanced::Config::Options for more options telling how that module controls how Advanced::Config uses this module for parsing dates.

Those options have no effect if you are calling these methods directly.

FUNCTIONS

@languages = get_languages ( );

This module returns a sorted list of languages supported by this module for the parsing of date strings.

If neither Date::Language and/or Date::Manip are installed, only English is supported and you'll be unable to swap languages.

Both modules are used since each language module supports a different set of languages with a lot of overlap between them.

Also Date::Manip supports common aliases for some languages. These aliases appear in lower case. When these aliases are used by swap_language, it returns the real underlying language instead of the alias.

$lang = swap_language ( $language[, $give_warning[, $wide]] );

This method allows you to change the $language used when this module parses a date string if you have modules Date::Language and/or Date::Manip installled. But if neiher are installed, only dates in English are supported. If a language is defined in both places the results are merged.

It always returns the active language. So if $language is undef or invalid, it will return the current language from before the call. But if the language was successfully changed, it will return the new $language instead.

Should the change fail and $give_warning is set to a non-zero value, it will write a warning to your screen telling you why it failed.

So assuming one of the language modules are intalled, it asks it for the list of months in the requested language. And once that list is retrieved only months in that language are supported when parsing a date string.

Languages like 'Greek' that rely on Wide Chars require the $wide flag set to true. Otherwise that language is disabled. Using the use_ut8 option when creating the Advanced::Config object causes the $wide flag to be set to 1.

$date = parse_date ( $date_str, $order[, $allow_dl[, $enable_2_digit_years]] );

Passed a date in some unknown format, it does it's best to parse it and return the date in YYYY-MM-DD format if it's a valid date. It returns undef if it can't find a valid date within $date_str.

The date can be surrounded by other information in the string that will be ignored. So it will strip out just the date info in something like:

Tues January 3rd, 2017 at 6:00 PM.

There are too many valid date formats to list them all, especially when other languages are added to the mix. But if you have one it doesn't support, open a CPAN ticket and I'll see if I can quickly add it.

$order tells the order to use for interpreting dates that are all digits. It's forwarded to all internal calls to parse_6_digit_date and parse_8_digit_date. So see those methods POD for more info on its meaning.

$allow_dl is non-zero and Date::Language is installed use it's method str2time () to attempt the conversion only if nothing else worked.

If $enable_2_digit_years is set to zero, it will not recognize any 2-digit year date formats as valid. Set to a non-zero value to enable them.

adjust_future_cutoff ( $num_years );

Changes the cutoff future date from 30 years to $num_years.

Set to 0 to disable years in the future!

This affects all Advanced::Config objects, not just the current one.

$year = make_it_a_4_digit_year ( $two_digit_year );

Used whenever this module needs to convert a two-digit year into a four-digit year.

When it converts YY into YYYY, it will assume 20YY unless the resulting date is more that 30 years in the future. Then it's 19YY.

If you don't like this rule, use adjust_future_cutoff to change this limit!

($year, $month, $day) = parse_8_digit_date ( $date_str, $order[, $skip] );

Looks for a valid date in an 8 digit string. It checks each of the formats below in the order specified by $order until it hits something that looks like a valid date.

(1) YYYYMMDD - ISO
(2) MMDDYYYY - American
(3) DDMMYYYY - European

The $order argument helps deal with ambiguities in the date. Its a comma seperated list of numbers specifying to order to try out. Ex: 3,2,1 means try out the European date format 1st, then the American date format 2nd, and finally the ISO format 3rd. You could also just say $order is 3 and only accept European dates.

It assumes its using the correct format when the date looks valid. It does this by validating the MM is between 1 and 12 and that the DD is between 1 and 31. (Using the correct max for that month). And then assumes the year is always valid.

If $skip is a non-zero value it will skip over the ISO format if it's listed in $order.

Returns 3 undef's if nothing looks good.

($year, $month, $day) = parse_6_digit_date ( $date_str, $order );

Looks for a valid date in an 6 digit string. It checks each of the formats below in the order specified by $order until it hits something that looks like a valid date.

(1) YYMMDD - ISO
(2) MMDDYY - American
(3) DDMMYY - European

The $order argument helps deal with ambiguities in the date. Its a comma seperated list of numbers specifying to order to try out. Ex: 2,3,1 means try out the American date format 1st, then the European date format 2nd, and finally the ISO format 3rd. You could also just say $order is 2 and only accept European dates.

So if you use the wrong order, more than likely you'll get the wrong date!

Returns 3 undef's if nothing looks good.

It always returns the year as a 4-digit year!

(\@months, \@weekdays) = init_special_date_arrays ( $lang[, $mode[, $wok[, $wide]]] );

Prefers getting the date names from Date::Manip::Lang::${lang} for the Advanced::Config special date variables. But if the language isn't supported by that module it tries Date::Language::${lang} instead. This is because the 1st module is more consistant.

If the $lang doesn't exist, then it returns the arrays for the last valid language.

If $wok is set to a non-zero value, it will print warnings to your screen if there were issues in changing the language used.

$mode tells how to return the various arrays:

1 - Abreviated month/weekday names in the requested language.
2 - Full month/weekday names in the requested language.
Any other value and it will return the numeric values. (default)

For @months, indexes are 0..11, with 0 representing January.

For @weekdays, indexes are 0..6, with 0 representing Sunday.

Languages like 'Greek' that rely on Wide Chars require the $wide flag set to true. Otherwise that language is disabled.

SOME EXAMPLE DATES

Here are some sample date strings in English that this module can parse. All for Christmas 2017. This is not a complete list of available date formats supported. But should hopefully give you a starting point of what is possible. Remember that if a date string contains extra info arround the date part of it, that extra information is thrown away.

12/25/2017, Mon Dec 25th 2017 at 09:00, Mon 2017/12/25, 2017-12-25, Monday December 25th, 2017 at 09:00, 12.25.2017, 25-DEC-2017, 25-DECEMBER-2017, 20171225, 12252017, Mon dec. 25th 00:00:00 2017, 2017 12 25 mon.

Most of the above examples will also work with 2-digit years as well.

And just to remind you that other languages are supported if Date::Language is installed, here's a date in Spanish that would be legal after swap_language("Spanish") was called.

Lun Diciembre 25to 2017 18:05.

COPYRIGHT

This program is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)