Content deleted Content added
Pathoschild (talk | contribs) m fix |
Pathoschild (talk | contribs) add code documentation, tweaked docs on regex method |
||
Line 7:
var ohc = ohc || {};
/**
* Provides internal utilities for manipulating dates in wikitext.
*/
ohc.dateutil = {
/**
* Get the raw pattern from a regular expression object. For example, this
* function will convert /x+/ig into "x+".
* @param {object} s The regular expression to convert.
*/
regex_to_string: function(s) {
return s.toString()
Line 17 ⟶ 23:
},
/**
* Show an alert containing an error message.
* @param {string} s The message to display.
* @param {object} reg The regular expression that caused the error.
*/
alert_error: function(s, reg) { //reg can be undefined
var message = "DATES SCRIPT:\n" + s;
Line 26 ⟶ 37:
/**
* Replace regular expression patterns in the given text. The given regex
* and substitution strings can contain tokens that specify the date format
* trailing slashes are not needed for the regex.
*
* The tokens can be either capturing or non-capturing. The capturing
* tokens make their output available for later processing. Most of the
* capturing magic strings can be used in the output with equivalent
* meaning.
*
* Internally, the routine maintains information about several dates, so
* the regex can contain more than one token specifying day, month or year.
* The first date will be assigned the first occurrences of tokens from
* each group, the second date will be assigned the second occurrences and
* so on. For example, if the regex is '@MM @DD @YYYY, @Month @ZM @Day',
* days. The third date will be assigned @ZM as months.
*
* If used in the replacement string, all tokens in the format @XX will
* output the data of the first date. To access the subsequent dates,
* tokens in the format @XX2, @XX3, and so on must be used. @XX1 is
* provided as alias to @XX for convenience.
*
* AVAILABLE REGEX MAGIC STRINGS
* =============================
* Note: The capturing tokens start with an uppercase letter whereas the
* equivalent non-capturing tokens start with a lowercase letter.
*
* Days:
* • @SD : Matches a day in numeric format without leading zero (1..31).
* • @ZD : Matches a day in numeric format with leading zero (01..31).
* • @DD : Matches a day in numeric format with optional leading zero (@SD or @ZD).
* • @Day : Matches a day in numeric format with optional leading zero, with optional st, nd or th suffix. Equivalent to @DD@th?
* • @sd, @zd, ... : noncapturing equivalents.
* • @th : Matches st, nd, rd or th.
*
* Months:
* • @SM : Matches a month in numeric format without leading zero (1,2..12).
* • @MM : Matches a month in numeric format with optional leading zero (@SM or @ZM).
* • @FullMonth : Matches a full month name (January, February).
* • @Mon : Matches a short month name (Jan, Feb, ..). Also optionally matches dot (Jan., Feb., ..) and 'Sept', 'Sept.'.
* • @Month : Matches a full or short month name (@FullMonth or @Mon).
*
* Years:
* • @YYYY : Matches a 4-digit year.
* • @YY : Matches a 2-digit year. 50-99 are interpreted as 1950..1999, 0-49 are interpreted as 2000-2049.
* • @YYNN : Matches a 4 or 2-digit year (@YYYY or @YY).
* • @Year : Matches a 1 to 4 digit year.
* • @yyyy, @yy, ... : noncapturing equivalents.
*
* Special tokens:
* • @@ : Matches a literal @.
*
* AVAILABLE REPLACEMENT STRING MAGIC STRINGS
* ==========================================
* Days:
* • @SD : Outputs a day in numeric format without leading zero (1-31).
* • @ZD : Outputs a day in numeric format with leading zero (01-31).
* • @DD : Equivalent to @ZD.
* • @Day : Equivalent to @SD.
* • @LDay : Outputs the matched day string without any transformations.
* • @SDn, @ZDn, ... : Where n is integer, outputs the day of the nth date in the specified format.
*
* Months:
* • @SM : Outputs a month in numeric format without leading zero (1-12).
* • @ZM : Outputs a month in numeric format with leading zero (01-12).
* • @MM : Equivalent to @ZM.
* • @FullMonth : Outputs a full name of a month (January, February).
* • @Mon : Outputs a short name of a month (Jan, Feb).
* • @Month : Equivalent to @FullMonth.
* • @LMonth : Outputs the matched month string without any transformations.
* • @SMn, @ZMn, ... : Where n is integer, outputs the month of the nth date in the specified format.
*
* Years:
* • @YYYY Outputs 4-digit year. Valid only if the year was not captured by @Year.
* • @YY Outputs 2-digit year. Outputs the last two digits of a year. Valid only if the year was not captured by @Year.
* • @YYNN Equivalent to @YYYY
* • @Year Outputs 1 to 4 digit number identifying a year. Equivalent to @YYYY if the year is between 1000 and 9999.
* • @LYear Outputs the matched year string without any transformations.
* • @YYYYn, @YYn, ... : Where n is integer, outputs the year of the nth date in the specified format.
*
* Special tokens:
* • @@ : Outputs a literal @.
*
* All tokens in the replacement string which refer to data which isn't
* defined will be replaced with '@ERROR@'.
*
* An optional function defining whether to make the replacement in particular
* cases can be provided. The function is supplied a number of parameters, each
* of which is an object defining the nth date as parsed by the routine. Each
* object contains numeric values of days, months and years as 'd', 'm' and 'y'
* properties respectively. Each value can be -1 if a magic string for that
* date value was not specified in the regex, or an error occurs. The function
* should return true if the replacement should be done, false otherwise.
*
* @param {string} text The text to change.
* @param {object|string} rg The regular expression to search in the text.
* @param {string} sub The pattern to replace matches with.
* @param {function} func A callback passed the matching date information
* which returns whether to continue with the replacement.
*/
regex: function(text, rg, sub, func) {
var reg = ohc.dateutil.regex_to_string(rg);
Line 647 ⟶ 620:
};
/**
* Extends string objects with a chainable method to replace patterns containing
* special date tokens.
* @see ohc.dateutils.regex
*/
String.prototype.ohc_regex = function(rg, sub, func) {
return ohc.dateutil.regex(this.toString(), rg, sub, func);
| |||