Skip to content

Files

Latest commit

0557edf · Oct 3, 2021

History

History
107 lines (79 loc) · 2.55 KB

EXTEND.md

File metadata and controls

107 lines (79 loc) · 2.55 KB

Extension

The easiest way to extend the default formatter and parser is to use plugins, but if the existing plugins do not meet your requirements, you can extend them yourself.

Token

Tokens in this library have the following rules:

  • All of the characters must be the same alphabet (A-Z, a-z).
'E'           // Good
'EE'          // Good
'EEEEEEEEEE'  // Good, but why so long!?
'EES'         // Not good
'???'         // Not good
  • It is case sensitive.
'eee'         // Good
'Eee'         // Not good
  • Only tokens consisting of the following alphabets can be added to the parser.
'Y'           // Year
'M'           // Month
'D'           // Day
'H'           // 24-hour
'A'           // AM PM
'h'           // 12-hour
's'           // Second
'S'           // Millisecond
'Z'           // Timezone offset
  • Existing tokens cannot be overwritten.
'YYY'         // This is OK because the same token does not exists.
'SSS'         // This cannot be added because the exact same token exists.
'EEE'         // This is OK for the formatter, but cannot be added to the parser.

Examples

Example 1

Add E token to the formatter. This new token will output "decade" like this:

const d1 =  new Date(2020, 0, 1);
const d2 =  new Date(2019, 0, 1);

date.format(d1, '[The year] YYYY [is] E[s].');  // => "The year 2020 is 2020s."
date.format(d2, '[The year] YYYY [is] E[s].');  // => "The year 2019 is 2010s."

Source code example is here:

const date = require('date-and-time');

date.extend({
  formatter: {
    E: function (d) {
      return (d.getFullYear() / 10 | 0) * 10;
    }
  }
});

Example 2

Add MMMMM token to the parser. This token ignores case:

date.parse('Dec 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
date.parse('dec 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019
date.parse('DEC 25 2019', 'MMMMM DD YYYY'); // => December 25, 2019

Source code example is here:

const date = require('date-and-time');

date.extend({
  parser: {
    MMMMM: function (str) {
      const mmm = this.res.MMM.map(m => m.toLowerCase());
      const result = this.find(mmm, str.toLowerCase());
      result.value++;
      return result;
    }
  }
});

Extending the parser may be a bit difficult. Refer to the library source code to grasp the default behavior.

Caveats

Note that switching locales or applying plugins after extending the library will be cleared all extensions. In such cases, you need to extend the library again.