Rename list-holidays and add some docs

Author: luciolucio

CHANGELOG.md

@@ -3,14 +3,15 @@
 * UNRELEASED
   * API now throws if holi does not recognize a calendar name
   * Fixed a bug in the calendar showcase
-  * Added an API function to list the names of holidays in a particular date
+  * Added the `holidays-in-date` API fn to list the names of holidays in a particular date
+  * The `list-holidays` API fn is now called `holidays-in-year`
 
 * 0.16.0 - 3Mar2023
   * API now throws when holi has no record of holidays for given year
   * Improved performance of API fns even more, up to 100x faster!
 
 * 0.15.0 - 2Mar2023
-  * Improved performance of main api functions to be 5 to 10 times faster
+  * Improved performance of main API functions to be 5 to 10 times faster
 
 * 0.14.0 - 6Feb2023
   * Date lists are now about 55% smaller - great for js bundles. They also link dates and holiday names now

doc/02-TIPS.md

@@ -25,3 +25,12 @@ example: an invoice due date is every 10th of the month. If it's a weekend, then
     (holi/add 1 :months)         ; 2022-07-06, Sat
     (holi/add 0 :business-days)) ; 2022-07-08, Mon
 ```
+
+## An example use case for holidays-in-date
+
+Imagine you want to keep a list of people and their birthdays, so your program can
+run daily and congratulate whoever celebrates their birthday that day. You could:
+
+1. Create a [custom calendar](04-CUSTOM.md) named, say, `BIRTHDAYS`, where each line represents one person, with their birthday in the `DDMMM` format
+2. Call `(holi/holidays-in-date current-date "BIRTHDAYS")` to get everyone that celebrates their birthday each day
+3. Use that info to congratulate them

resources/holi-template/resources/calendars.cljc

@@ -16,5 +16,8 @@
 (defn business-day? [date & calendars]
   (apply holi/business-day? date calendars))
 
-(defn list-holidays [year calendar]
-  (holi/list-holidays year calendar))
+(defn holidays-in-year [year calendar]
+  (holi/holidays-in-year year calendar))
+
+(defn holidays-in-date [date calendar]
+  (holi/holidays-in-date date calendar))

src/luciolucio/holi.cljc

@@ -108,7 +108,7 @@
   [date & calendars]
   (not (apply non-business-day? date calendars)))
 
-(defn list-holidays
+(defn holidays-in-year
   "Returns a collection of maps of the form `{:name \"Name\" :date LocalDate}`
   where every item of the collection represents a holiday in the given year according
   to the given holiday calendar
@@ -117,7 +117,7 @@
   [year calendar]
   (core/read-calendar (safe-calendar calendar) year))
 
-(defn holidays
+(defn holidays-in-date
   "Returns a collection containing names of holidays in the given date, for example: `[\"New Year's Day\" \"Independence Day\"]`
 
   If there are none, it will return an empty collection.
@@ -131,7 +131,7 @@
   [date calendar]
   (if (holiday? date calendar)
     (->> calendar
-         (list-holidays (-> date t/date t/year))
+         (holidays-in-year (-> date t/date t/year))
          (filter #(= (t/date date) (:date %)))
          (map :name))
     []))

test/luciolucio/holi/holidays_test.cljc …ciolucio/holi/holidays_in_date_test.cljctest/luciolucio/holi/holidays_test.cljc renamed to test/luciolucio/holi/holidays_in_date_test.cljc test/luciolucio/holi/holidays_test.cljc renamed to test/luciolucio/holi/holidays_in_date_test.cljc

@@ -1,4 +1,4 @@
-(ns luciolucio.holi.holidays-test
+(ns luciolucio.holi.holidays-in-date-test
   (:require [clojure.test :as ct]
             [luciolucio.holi :as holi]
             [luciolucio.holi.test-setup :as setup]
@@ -8,17 +8,17 @@
 
 (ct/use-fixtures :each setup/test-datelist-fixture)
 
-(ct/deftest should-return-holidays-when-holidays-with-date
+(ct/deftest should-return-holidays-when-holidays-in-date-with-date
   (ct/are [date calendar expected]
-          (= expected (holi/holidays (t/date date) calendar))
+          (= expected (holi/holidays-in-date (t/date date) calendar))
     "2020-08-01" "DAY-TWENTY-NINE" []
     "2020-07-29" "DAY-TWENTY-NINE" ["Twenty Ninth Day"]
     "2020-07-30" "DAY-THREE" []
     "2020-08-03" "DAY-THREE" ["Third Day"]))
 
-(ct/deftest should-return-holidays-when-holidays-with-date-time
+(ct/deftest should-return-holidays-when-holidays-in-date-with-date-time
   (ct/are [date calendar expected]
-          (= expected (holi/holidays (t/date-time date) calendar))
+          (= expected (holi/holidays-in-date (t/date-time date) calendar))
     "2020-08-01T00:00:00" "DAY-TWENTY-NINE" []
     "2020-07-29T11:11:22" "DAY-TWENTY-NINE" ["Twenty Ninth Day"]
     "2020-07-30T22:22:22" "DAY-THREE" []
@@ -27,21 +27,21 @@
 (ct/deftest
   ^{:doc "This test relies on TEST-WEEKEND and DAY-THREE, which only list dates in 2020.
           Any argument outside 2020 should raise an exception"}
-  should-throw-when-holidays-with-date-beyond-limit-year
+  should-throw-when-holidays-in-date-with-date-beyond-limit-year
   (ct/are [date calendar]
-          (thrown-with-msg? ExceptionInfo #"Date is out of bounds" (holi/holidays (t/date date) calendar))
+          (thrown-with-msg? ExceptionInfo #"Date is out of bounds" (holi/holidays-in-date (t/date date) calendar))
     "2021-08-03" "DAY-THREE"
     "2019-08-03" "DAY-THREE"))
 
 (ct/deftest
   ^{:doc "This test relies on TEST-WEEKEND and DAY-THREE, which only list dates in 2020.
           Any argument outside 2020 should raise an exception"}
-  should-throw-when-holidays-with-date-time-beyond-limit-year
+  should-throw-when-holidays-in-date-with-date-time-beyond-limit-year
   (ct/are [date calendar]
-          (thrown-with-msg? ExceptionInfo #"Date is out of bounds" (holi/holidays (t/date-time date) calendar))
+          (thrown-with-msg? ExceptionInfo #"Date is out of bounds" (holi/holidays-in-date (t/date-time date) calendar))
     "2021-08-03T10:10:10" "DAY-THREE"
     "2019-08-03T23:59:59" "DAY-THREE"))
 
-(ct/deftest should-throw-when-holidays-with-inexistent-calendar-or-WEEKEND
-  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendars: HOL" (holi/holidays (t/date "2020-10-10") "HOL")))
-  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendar: WEEKEND" (holi/holidays (t/date "2020-10-10") "WEEKEND"))))
+(ct/deftest should-throw-when-holidays-in-date-with-inexistent-calendar-or-WEEKEND
+  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendars: HOL" (holi/holidays-in-date (t/date "2020-10-10") "HOL")))
+  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendar: WEEKEND" (holi/holidays-in-date (t/date "2020-10-10") "WEEKEND"))))

test/luciolucio/holi/list_test.cljc …ciolucio/holi/holidays_in_year_test.cljctest/luciolucio/holi/list_test.cljc renamed to test/luciolucio/holi/holidays_in_year_test.cljc test/luciolucio/holi/list_test.cljc renamed to test/luciolucio/holi/holidays_in_year_test.cljc

@@ -1,4 +1,4 @@
-(ns luciolucio.holi.list-test
+(ns luciolucio.holi.holidays-in-year-test
   (:require [clojure.test :as ct]
             [luciolucio.holi :as holi]
             [luciolucio.holi.test-setup :as setup]
@@ -8,9 +8,9 @@
 
 (ct/use-fixtures :each setup/test-datelist-fixture)
 
-(ct/deftest should-list-the-correct-holidays-for-calendar-and-year-when-list-holidays
+(ct/deftest should-list-the-correct-holidays-for-calendar-and-year-when-holidays-in-year
   (ct/are [year expected]
-          (= expected (holi/list-holidays year "TEST-US"))
+          (= expected (holi/holidays-in-year year "TEST-US"))
     2021 [{:date (t/date "2021-01-01") :name "New Year's Day"}
           {:date (t/date "2021-01-18") :name "Martin Luther King Jr. Day"}
           {:date (t/date "2021-02-15") :name "President's Day"}
@@ -59,14 +59,14 @@
           {:date (t/date "2024-11-28") :name "Thanksgiving"}
           {:date (t/date "2024-12-25") :name "Christmas"}]))
 
-(ct/deftest should-throw-when-list-holidays-with-year-beyond-limits
-  (ct/is (thrown-with-msg? ExceptionInfo #"Year is out of bounds" (holi/list-holidays 1942 "TEST-US")))
-  (ct/is (thrown-with-msg? ExceptionInfo #"Year is out of bounds" (holi/list-holidays 2104 "TEST-US"))))
+(ct/deftest should-throw-when-holidays-in-year-with-year-beyond-limits
+  (ct/is (thrown-with-msg? ExceptionInfo #"Year is out of bounds" (holi/holidays-in-year 1942 "TEST-US")))
+  (ct/is (thrown-with-msg? ExceptionInfo #"Year is out of bounds" (holi/holidays-in-year 2104 "TEST-US"))))
 
 (ct/deftest
   ^{:doc "These should say 'No such calendars' before
           checking that the year is out of bounds"}
-  should-throw-when-list-holidays-with-inexistent-calendar-or-WEEKEND
-  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendars: OMG" (holi/list-holidays 1930 "OMG")))
-  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendars: WATIZIT" (holi/list-holidays 2200 "WATIZIT")))
-  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendar: WEEKEND" (holi/list-holidays 2200 "WEEKEND"))))
+  should-throw-when-holidays-in-year-with-inexistent-calendar-or-WEEKEND
+  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendars: OMG" (holi/holidays-in-year 1930 "OMG")))
+  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendars: WATIZIT" (holi/holidays-in-year 2200 "WATIZIT")))
+  (ct/is (thrown-with-msg? ExceptionInfo #"No such calendar: WEEKEND" (holi/holidays-in-year 2200 "WEEKEND"))))