; ============================================================================
; An EXAMPLE overlay calendar for `colitur --overlay`.
;
; This file is shipped as documentation you can run, not as calendar data.
; Every celebration in it is INVENTED, with slugs prefixed `example-` so they
; cannot collide with anything real. Copy it, gut it, and put your own diocese
; or parish in its place.
;
;     colitur day 2026 --overlay <prefix>/share/colitur/examples/diocesan-example.sexp
;
; WHAT AN OVERLAY IS
;
; A list of directives applied ON TOP of the shipped 1962 universal calendar,
; never instead of it. colitur applies its own data/ef/adjustments.sexp first,
; then each --overlay in the order given. Later writers win, so a local
; calendar can deliberately override a universal entry by naming its slug.
;
; AN OVERLAY IS APPLIED, NOT VALIDATED. colitur's five test layers assert
; things about the SHIPPED calendar; none of them can vouch for this file or
; yours. A directive naming a slug that does not exist prints a warning on
; stderr and the run continues, so a typo is visible rather than silent; a
; file that fails to parse is fatal.
;
; THE FOUR DIRECTIVES
;
;   (Add     <entry>)          a celebration the universal calendar lacks
;   (Suppress <slug>)          remove one it has
;   (Replace <slug> <entry>)   swap one out wholesale
;   (Edit    <slug> (<edits>)) change named fields only
;
; DATES
;
;   (Fixed (month 7) (day 11))                      a civil date, every year
;   (Easter_offset -9)                              signed days from Easter
;   (Nth_weekday (month 10) (nth 1) (weekday Sun))  nth weekday of a month;
;                                                   negative nth counts back,
;                                                   so (nth -1) is the last
;
; RANKS are Class1..Class4; STATUS is Feast or Commemoration_only; COLOUR is
; White Red Green Violet Rose Black; SUBJECT is Lord Bvm Saint Temporal.
; NAMES are keyed by language code and any set of languages is allowed.
; CITATIONS are reading references, never scripture text; omit them and the
; day falls through to whatever the resolution chain finds.
; ============================================================================
((id diocesan-example)
  (directives
    (

     ; ---- 1. A fixed-date local patron, with its own proper readings -------
     ; The commonest thing a local calendar adds. III class is the usual rank
     ; for a diocesan patron who is not the cathedral's titular.
     (Add
       ((date (Fixed (month 7) (day 11)))
         (cel
           ((slug example-local-patron)
             (names ((la "Sancti Exempli Patroni") (en "St Example, Patron")
                     (pl "\197\154w. Przyk\197\130adu, Patrona")))
             (rank Class3) (status Feast) (colour White) (subject Saint)
             (citations (((part First) (reference "Ecclus 45:1-6"))
                         ((part Gospel) (reference "Matt 25:14-23"))))
             (layer diocesan-example)))))

     ; ---- 2. A MOVABLE feast: the first Sunday of October ------------------
     ; The anniversary of a church's own dedication is I class IN THAT CHURCH,
     ; which is why this one outranks and displaces the Sunday it lands on --
     ; at III class it would lose to a II-class Sunday every year.
     (Add
       ((date (Nth_weekday (month 10) (nth 1) (weekday Sun)))
         (cel
           ((slug example-dedication)
             (names ((la "Dedicatio Ecclesiae Exempli")
                     (en "Dedication of the Example Church")))
             (rank Class1) (status Feast) (colour White) (subject Saint)
             (citations (((part First) (reference "Apoc 21:2-5"))
                         ((part Gospel) (reference "Luke 19:1-10"))))
             (layer diocesan-example)))))

     ; ---- 3. An EASTER-RELATIVE local commemoration ------------------------
     ; Easter+61 is the Friday after Corpus Christi. A commemoration never
     ; wins the day; it is added to whatever office the day already has,
     ; subject to the admission limits of RG 111.
     (Add
       ((date (Easter_offset 61))
         (cel
           ((slug example-local-commemoration)
             (names ((la "Commemoratio Exempli") (en "A Local Commemoration")))
             (rank Class4) (status Commemoration_only) (colour White)
             (subject Saint) (citations ()) (layer diocesan-example)))))

     ; ---- 4. RAISING a universal feast for local use -----------------------
     ; A saint the whole Church keeps at III class may be the patron of your
     ; diocese and kept higher. Edit changes only the fields named; everything
     ; else, including the date and the readings, stays as shipped.
     (Edit stanislaus ((Set_rank Class1) (Set_colour Red)))

     ; ---- 5. SUPPRESSING one -----------------------------------------------
     ; Shown for completeness and commented out, because suppressing a
     ; universal feast is a real liturgical act and should be a deliberate
     ; one. Uncomment only if your own calendar genuinely omits it.
     ;
     ; (Suppress example-not-kept-here)
     )))