Display new features in README files

README.md

@@ -3,32 +3,34 @@
 ## Motivation
 
 This package aims to solve a set of needs present in applications where
-dates need to be represented in a relative fashion, like background periodic 
+dates need to be represented in a relative fashion, like background periodic
 tasks, datetime range pickers... in a compact and stringified format. This
 enables the programmer to persist these tokens during the lifetime of a
 process or even longer, since calculations are performed in the moment of
-re-evaluation
+evaluation. Theses tokens are also useful when caching URLs as replacement
+of timestamps, which would break caching given their mutability nature.
 
 Some common examples of relative tokens:
 
-|                    | From         | To           |
-|--------------------|--------------|--------------|
-| Today              | `now/d`      | `now`        |
-| Yesterday          | `now-d/d`    | `now-d@d`    |
-| Last 24 hours      | `now-24h`    | `now`        |
-| Last business week | `now-w/bw`   | `now-w@bw`   |
-| This business week | `now/bw`     | `now@bw`     |
-| Last month         | `now-1M/M`   | `now-1M@M`   |
-| Next week          | `now+w/w`    | `now+w@w`    |
-| Custom range       | `now+w-2d/h` | `now+2M-10h` |
+|                                | From           | To            |
+|--------------------------------|----------------|---------------|
+| Today                          | `now/d`        | `now`         |
+| Yesterday                      | `now-d/d`      | `now-d@d`     |
+| Last 24 hours                  | `now-24h`      | `now`         |
+| Last business week             | `now-w/bw`     | `now-w@bw`    |
+| This business week             | `now/bw`       | `now@bw`      |
+| Last month                     | `now-1M/M`     | `now-1M@M`    |
+| Next week                      | `now+w/w`      | `now+w@w`     |
+| Custom range                   | `now+w-2d/h`   | `now+2M-10h`  |
+| Last month first business week | `now-M/M+w/bw` | `now-M/+w@bw` |
 
 As you may have noticed, token follow a pattern:
 
 - The word `now`. It means the point in the future timeline when tokens are
   parsed to their datetime form.
-- Optionally, modifiers to add and/or subtract the future value of `now` can 
+- Optionally, modifiers to add and/or subtract the future value of `now` can
   be used. Unsurprisingly, additions are set via `+`, while `-` mean
-  subtractions. These modifiers can be chained as many times as needed. 
+  subtractions. These modifiers can be chained as many times as needed.
   E.g: `now-1M+3d+2h`. Along with the arithmetical sign and the amount, the
   unit of time the amount refers to must be specified. Currently, the supported
   units are:
@@ -68,26 +70,22 @@ or
 pip install datetoken
 ```
 
-## Ok, get me to the code
+## Examples
 
 Most probably you will be dealing with simple presets such as _yesterday_ or
 the _last 24 hours_.
 
 ```python
->>> from datetoken.utils import simple_token_to_date
+>>> from datetoken.utils import token_to_date
 >>> from datetime import datetime
 >>> print(datetime.utcnow())
 2018-10-18 14:08:47
->>> simple_token_to_date('now-d/d')  # Start of yesterday
+>>> token_to_date('now-d/d')  # Start of yesterday
 2018-10-17 00:00:00
->>> simple_token_to_date('now-d@d')  # End of yesterday
+>>> token_to_date('now-d@d')  # End of yesterday
 2018-10-17 23:59:59
 ```
 
-Simple tokens are defined as dates with zero or one modifiers. In case
-you disallow the usage of several modifiers, simple tokens will automatically
-read the first (if any) and discard the remaining ones.
-
 However, more complex configurations are also supported so as to
 provide the flexibility advanced users may need.
 

README.rst

@@ -2,11 +2,12 @@ Project description
 -------------------
 
 This package aims to solve a set of needs present in applications where
-dates need to be represented in a relative fashion, like background
-periodic tasks, datetime range pickers… in a compact and stringified
-format. This enables the programmer to persist these tokens during the
-lifetime of a process or even longer, since calculations are performed
-in the moment of re-evaluation
+dates need to be represented in a relative fashion, like background periodic
+tasks, datetime range pickers... in a compact and stringified format. This
+enables the programmer to persist these tokens during the lifetime of a
+process or even longer, since calculations are performed in the moment of
+evaluation. Theses tokens are also useful when caching URLs as replacement
+of timestamps, which would break caching given their mutability nature.
 
 Some common examples of relative tokens:
 
@@ -17,6 +18,7 @@ Some common examples of relative tokens:
 -  Last business week: ``now-w/bw``, ``now-w@bw``
 -  This business week: ``now/bw``, ``now@bw``
 -  Last month: ``now-1M/M``, ``now-1M@M``
+-  Last month first business week: ``now-M/M+w/bw``, ``now-M/M+w@bw``
 
 As you may have noticed, token follow a pattern:
 
@@ -76,7 +78,7 @@ Most probably you will be dealing with simple presets such as
 
 .. code:: python
 
-   >>> from datetoken.utils import simple_token_to_date
+   >>> from datetoken.utils import token_to_date
    >>> from datetime import datetime
    >>> print(datetime.utcnow())
    2018-10-18 14:08:47