From 6c0cb6489a34eb7b37fff6dc277bdf4a5b67395f Mon Sep 17 00:00:00 2001
From: Joscha <joscha@plugh.de>
Date: Sun, 7 Nov 2021 12:09:38 +0000
Subject: [PATCH] Flesh out commands a bit more

---
 README.md       | 62 ++++++++++++++++++++++++++++++++++++++++++++++++-
 src/commands.rs | 42 ++++++++++++++++++++++++++++++++-
 2 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f5eb038..279fd14 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,39 @@
 # today
 
-## `DATE` annotations
+## Commands
+
+### The `TASK` command
+
+```
+TASK title
+(DATE annotation)*
+[FROM annotation]
+[UNTIL annotation]
+(DONE annotation)*
+    long description
+```
+
+### The `NOTE` command
+
+```
+NOTE title
+(DATE annotation)+
+[FROM annotation]
+[UNTIL annotation]
+(DONE annotation)*
+    long description
+```
+
+### The `BIRTHDAY` command
+
+```
+BIRTHDAY name
+BDATE annotation
+```
+
+## Annotations
+
+### The `DATE` annotation
 
 Most commands allow or require `DATE` annotations. They are roughly structured
 like `DATE start [-- end]`. The `end` part can only contain time-related
@@ -26,6 +59,27 @@ a semicolon.
 If multiple `DATE` annotations from a single command start on the same date, all
 except the first are ignored.
 
+### The `FROM` and `UNTIL` annotations
+
+Commands that allow `DATE` annotations also allow the `FROM` and `UNTIL`
+annotations. These can be used to restrict occurrences of entries.
+
+The `FROM` annotation has the form `FROM date` and only keeps occurences that
+end at or after the specified date. These occurences may begin before the
+specified date.
+
+The `UNTIL` annotation has the form `UNTIL date` and only keeps occurrences that
+start at or before the specified date. These occurrences may extend past the
+specified date.
+
+### The `BDATE` annotations
+
+This is a very simple date annotation for birthdays. It has the form
+`BDATE date` where the year may optionally be replaced by a `?`.
+
+If the year is specified, the person's current age is displayed in the birthday
+occurrence title.
+
 ## Examples
 ```
 NOTE Spielerunde
@@ -52,4 +106,10 @@ DATE (wd = sat) -- +d
 
 NOTE last of each month
 DATE (m = 1) -d
+
+BIRTHDAY Max
+BDATE 1987-05-14
+
+BIRTHDAY Martha
+BDATE ?-09-21
 ```
diff --git a/src/commands.rs b/src/commands.rs
index 51d6174..7a8cc12 100644
--- a/src/commands.rs
+++ b/src/commands.rs
@@ -13,12 +13,23 @@ enum Weekday {
 
 #[derive(Debug)]
 enum DeltaStep {
+    /// `y`, move by a year, keeping the same month and day
     Year(i32),
+    /// `m`, move by a month, keeping the same day `d`
     Month(i32),
+    /// `M`, move by a month, keeping the same day `D`
+    MonthReverse(i32),
+    /// `d`
     Day(i32),
+    /// `w`, move by 7 days
     Week(i32),
+    /// `h`
     Hour(i32),
+    /// `m`
     Minute(i32),
+    /// `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`
+    ///
+    /// Move to the next occurrence of the specified weekday
     Weekday(i32, Weekday),
 }
 
@@ -69,15 +80,41 @@ enum IntVar {
     /// `y`
     Year,
     /// `yl`, length of the current year in days
+    ///
+    /// Equal to `isLeapYear ? 366 : 365`
     YearLength,
     /// `yd`, day of the year
     YearDay,
+    /// `yD`, day of the year starting from the end
+    ///
+    /// Equal to `yl - yd + 1`
+    YearDayReverse,
+    /// `yw`, 1 during the first 7 days of the year, 2 during the next etc.
+    ///
+    /// Equal to `((yd - 1) / 7) + 1`
+    YearWeek,
+    /// `yw`, 1 during the last 7 days of the year, 2 during the previous etc.
+    ///
+    /// Equal to `((yD - 1) / 7) + 1`
+    YearWeekReverse,
     /// `m`
     Month,
     /// `ml`, length of the current month in days
     MonthLength,
-    /// `d`, day of the month
+    /// `d` or `md`, day of the month
     MonthDay,
+    /// `D` or `mD`, day of the month starting from the end
+    ///
+    /// Equal to `ml - md + 1`
+    MonthDayReverse,
+    /// `mw`, 1 during the first 7 days of the month, 2 during the next etc.
+    ///
+    /// Equal to `((md - 1) / 7) + 1`
+    MonthWeek,
+    /// `mW`, 1 during the last 7 days of the month, 2 during the previous etc.
+    ///
+    /// Equal to `((mD - 1) / 7) + 1`
+    MonthWeekReverse,
     /// `iy`, ISO 8601 year
     IsoYear,
     /// `iyl`, length of current ISO 8601 year **in weeks**
@@ -120,8 +157,11 @@ enum IntExpr {
 
 #[derive(Debug)]
 enum BoolVar {
+    /// `isWeekday`, whether the current day is one of mon-fri
     IsWeekday,
+    /// `isWeekend`, whether the current day is one of sat-sun
     IsWeekend,
+    /// `isLeapYear`, whether the current year is a leap year
     IsLeapYear,
 }