docs: mention string literals

zapier · Aug 13, 2020 · a08ecb4 · a08ecb4
1 parent e70fd87
commit a08ecb4
Showing 1 changed file with 55 additions and 42 deletions.
diff --git a/readme.md b/readme.md
@@ -22,9 +22,9 @@
 
 ## Features
 
-* ✌ **Small**: As it directly leverages `Intl.DateTimeFormat`, there is no need to bundle additional locales or a timezones database. It's already in your Browser!
-* 👌**Simple**: It supports a subset of ISO 8601 formats, discarding very rarely used date parts.
-* 🤟 **Extensible**: That said, if you want to customize things you can pass [custom formatters](#custom-formatters).
+- ✌ **Small**: As it directly leverages `Intl.DateTimeFormat`, there is no need to bundle additional locales or a timezones database. It's already in your Browser!
+- 👌**Simple**: It supports a subset of ISO 8601 formats, discarding very rarely used date parts.
+- 🤟 **Extensible**: That said, if you want to customize things you can pass [custom formatters](#custom-formatters).
 
 ## Installation
 
@@ -41,12 +41,14 @@ const date = new Date(Date.UTC(1984, 0, 17, 16, 13, 37, 0))
 
 formatDate(date, 'YYYY-MM-DD hh:mm:ss A')
 // → 1984-01-17 04:13:37 PM
-formatDate(date, 'YYYY, MMMM dddd DD')
-// → 1984, January Tuesday 17
 formatDate(date, 'YYYY-MM-DD hh:mm:ss A', { timezone: 'Asia/Singapore' })
 // → 1984-01-18 00:13:37 AM
+formatDate(date, 'YYYY, MMMM dddd DD')
+// → 1984, January Tuesday 17
+formatDate(date, '[It is] dddd [today!]')
+// → It is Tuesday today!
 formatDate(date, 'YYYY, MMMM dddd DD', { locale: 'fr' })
-// → 1984, Janvier Mercredi 18
+// → 1984, Janvier Mardi 17
 ```
 
 ## Usage
@@ -60,40 +62,51 @@ formatDate(date, 'YYYY-MM-DD hh:mm:ss A')
 // → 1984-01-17 04:13:37 PM
 ```
 
-| Argument  | Description               | Type                   
-| --------- | ------------------------- | -----------------------
-| `date`    | The date to format        | `Date`, `number`       
-| `format`  | The mask used to format   | See [Formats](#formats)
-| `options` | Custom locale or timezone | See [Options](#options)
-
-### Formats
-
-| Mask   | Description           | Example
-| ------ | --------------------- | -------
-| `YYYY` | 4-digits year         | `1984`
-| `YY`   | 2-digits year         | `84`
-| `MMMM` | Month name            | `January`
-| `MMM`  | Short month name      | `Jan`
-| `DD`   | 2-digits day          | `17`
-| `dddd` | Day of the week       | `Tuesday`
-| `ddd`  | Short day of the week | `Tue`
-| `A`    | Day period            | `AM`, `PM`
-| `a`    | Lowercased day period | `am`, `pm`
-| `HH`   | 24-hours hour         | `16`
-| `hh`   | 12-hours hour         | `04`
-| `mm`   | 2-digit minute        | `13`
-| `ss`   | 2-digit second        | `37`
+| Argument  | Description               | Type                    |
+| --------- | ------------------------- | ----------------------- |
+| `date`    | The date to format        | `Date`, `number`        |
+| `format`  | The format to use         | See [Format](#format)   |
+| `options` | Custom locale or timezone | See [Options](#options) |
+
+### Format
+
+The format is a combination of the following masks:
+
+| Mask   | Description           | Example    |
+| ------ | --------------------- | ---------- |
+| `YYYY` | 4-digits year         | `1984`     |
+| `YY`   | 2-digits year         | `84`       |
+| `MMMM` | Month name            | `January`  |
+| `MMM`  | Short month name      | `Jan`      |
+| `DD`   | 2-digits day          | `17`       |
+| `dddd` | Day of the week       | `Tuesday`  |
+| `ddd`  | Short day of the week | `Tue`      |
+| `A`    | Day period            | `AM`, `PM` |
+| `a`    | Lowercased day period | `am`, `pm` |
+| `HH`   | 24-hours hour         | `16`       |
+| `hh`   | 12-hours hour         | `04`       |
+| `mm`   | 2-digit minute        | `13`       |
+| `ss`   | 2-digit second        | `37`       |
+
+Masks will be replaced by their associated date part.
+
+You can also pass string literals in the format by surrouding them with a `[]`:
+
+```js
+formatDate(date, '[It is] dddd [today!]')
+// → It is Tuesday today!
+```
 
 ### Options
 
-* `locale` - A [BCP 47](https://tools.ietf.org/html/bcp47) tag to identify the output language
-  * Type: `string`
-  * Default: The system locale
-  * Example: `fr`, `fr-FR`
-* `timezone` - A [IANA timezone](https://www.iana.org/time-zones)
-  * Type: `string`
-  * Default: The system timezone
-  * Example: `Europe/Paris`, `America/Chicago`
+- `locale` - A [BCP 47](https://tools.ietf.org/html/bcp47) tag to identify the output language
+  - Type: `string`
+  - Default: The system locale
+  - Example: `fr`, `fr-FR`
+- `timezone` - A [IANA timezone](https://www.iana.org/time-zones)
+  - Type: `string`
+  - Default: The system timezone
+  - Example: `Europe/Paris`, `America/Chicago`
 
 ## Custom formatters
 
@@ -115,15 +128,15 @@ formatDate(date, 'YYYY-MM-DD h:mm:ss.SSS')
 // → 1984-01-17 4:13:37.505
 ```
 
-| Argument     | Description               | Type                   
-| ------------ | ------------------------- | -----------------------
-| `formatters` | Custom formatters         | See [Formatters](#formatters)
+| Argument     | Description       | Type                          |
+| ------------ | ----------------- | ----------------------------- |
+| `formatters` | Custom formatters | See [Formatters](#formatters) |
 
 ### Formatters
 
 Formatters are represented as a dictionary of functions, where the key represents the mask that is to be matched in the `format` and the value is the function that will format the date.
 
 The formatter function takes the following arguments:
 
-* `parts` - An object containing all the date parts provided by `Intl.DateTimeFormat`. You can inspect the [DatePartName](./src/types.ts) type for an exhaustive list of all the date parts
-* `date` - The original date passed to the `formatDate` function.
+- `parts` - An object containing all the date parts provided by `Intl.DateTimeFormat`. You can inspect the [DatePartName](./src/types.ts) type for an exhaustive list of all the date parts
+- `date` - The original date passed to the `formatDate` function.