Add --include-overdue arg to include items before the specified due date (#98)

Closes #71 by adding an `--include-overdue` argument that includes
reminders due _before_ the date specified with `--due-date`

This makes it easy to recreate the "Today" view by running `reminders
show-all --due-date today --include-overdue`

I also added some examples of date-based usage to the README as none
currently existed.

Author: alexjsp

README.md

@@ -72,6 +72,21 @@ $ reminders show Soon
 3: Something really important (priority: high)
 ```
 
+#### Show reminders due on or by a date
+
+```
+$ reminders show-all --due-date today
+1: Contribute to open source (in 3 hours)
+$ reminders show-all --due-date today --include-overdue
+0: Ship reminders-cli (2 days ago)
+1: Contribute to open source (in 3 hours)
+$ reminders show-all --due-date 2025-02-16
+1: Contribute to open source (in 3 hours)
+$ reminders show Soon --due-date today --include-overdue
+0: Ship reminders-cli (2 days ago)
+1: Contribute to open source (in 3 hours)
+```
+
 #### See help for more examples
 
 ```

Sources/RemindersLibrary/CLI.swift

@@ -26,6 +26,9 @@ private struct ShowAll: ParsableCommand {
     @Flag(help: "Include completed items in output")
     var includeCompleted = false
 
+    @Flag(help: "When using --due-date, also include items due before the due date")
+    var includeOverdue = false
+
     @Option(
         name: .shortAndLong,
         help: "Show only reminders due on this date")
@@ -52,7 +55,8 @@ private struct ShowAll: ParsableCommand {
         }
 
         reminders.showAllReminders(
-            dueOn: self.dueDate, displayOptions: displayOptions, outputFormat: format)
+            dueOn: self.dueDate, includeOverdue: self.includeOverdue,
+            displayOptions: displayOptions, outputFormat: format)
     }
 }
 
@@ -71,6 +75,9 @@ private struct Show: ParsableCommand {
     @Flag(help: "Include completed items in output")
     var includeCompleted = false
 
+    @Flag(help: "When using --due-date, also include items due before the due date")
+    var includeOverdue = false
+
     @Option(
         name: .shortAndLong,
         help: "Show the reminders in a specific order, one of: \(Sort.commaSeparatedCases)")
@@ -107,8 +114,8 @@ private struct Show: ParsableCommand {
         }
 
         reminders.showListItems(
-            withName: self.listName, dueOn: self.dueDate, displayOptions: displayOptions,
-            outputFormat: format, sort: sort, sortOrder: sortOrder)
+            withName: self.listName, dueOn: self.dueDate, includeOverdue: self.includeOverdue,
+            displayOptions: displayOptions, outputFormat: format, sort: sort, sortOrder: sortOrder)
     }
 }
 

Sources/RemindersLibrary/Reminders.swift

@@ -100,8 +100,9 @@ public final class Reminders {
         }
     }
 
-    func showAllReminders(dueOn dueDate: DateComponents?,
-                          displayOptions: DisplayOptions, outputFormat: OutputFormat) {
+    func showAllReminders(dueOn dueDate: DateComponents?, includeOverdue: Bool,
+        displayOptions: DisplayOptions, outputFormat: OutputFormat
+    ) {
         let semaphore = DispatchSemaphore(value: 0)
         let calendar = Calendar.current
 
@@ -120,7 +121,10 @@ public final class Reminders {
 
                 let sameDay = calendar.compare(
                     reminderDueDate, to: dueDate, toGranularity: .day) == .orderedSame
-                if sameDay {
+                let earlierDay = calendar.compare(
+                    reminderDueDate, to: dueDate, toGranularity: .day) == .orderedAscending
+
+                if sameDay || (includeOverdue && earlierDay) {
                     matchingReminders.append((reminder, i, listName))
                 }
             }
@@ -140,8 +144,8 @@ public final class Reminders {
         semaphore.wait()
     }
 
-    func showListItems(withName name: String, dueOn dueDate: DateComponents?, displayOptions: DisplayOptions,
-                       outputFormat: OutputFormat, sort: Sort, sortOrder: CustomSortOrder)
+    func showListItems(withName name: String, dueOn dueDate: DateComponents?, includeOverdue: Bool,
+        displayOptions: DisplayOptions, outputFormat: OutputFormat, sort: Sort, sortOrder: CustomSortOrder)
     {
         let semaphore = DispatchSemaphore(value: 0)
         let calendar = Calendar.current
@@ -162,7 +166,10 @@ public final class Reminders {
 
                 let sameDay = calendar.compare(
                     reminderDueDate, to: dueDate, toGranularity: .day) == .orderedSame
-                if sameDay {
+                let earlierDay = calendar.compare(
+                    reminderDueDate, to: dueDate, toGranularity: .day) == .orderedAscending
+
+                if sameDay || (includeOverdue && earlierDay) {
                     matchingReminders.append((reminder, index))
                 }
             }