Identifying a zman?

[Sternbach-Software]

I would like some input on the most ergonomic API surface for identifying a given zman.

I am developing KosherKotlin in tandem with BeautifulZmanim, and the need came up to indicate a user-readable description of each zman, and to filter/group together similar zmanim (e.g. all opinions for a given zman, all zmanim for a given opinion, etc.).

Right now, the function name and javadoc are the only info provided - which aren’t easily manipulated at runtime (not to mention the slight inconsistency in function naming which would make that even harder (e.g. alos60 vs. minchaGedola30Minutes)).

I assume that this is something that most user-facing apps had to do, which would imply that it is the responsibility of the library (instead of everyone making their own library on top of the library).

Ideally, the zman should also have some strongly-typed classification of how it was calculated (e.g. if(zman.opinion instanceof ZmanOpinion.FixedMinutes) print(zman.opinion.minutes)). This could be useful for translating the description into other languages (at the discretion of the library client), more in-depth user-facing explanations (ditto), grouping or filtering zmanim by their opinion/how they were calculated (not just what zman type they represent, such as latest shema), some simple data science/number-crunching, etc.

I have already wrapped all public APIs in a Zman object (defined below) with a ZmanType. I am wondering if this should be translated to Java and ported upstream?

Moshe Waisberg (author of Halachic Prayer Times Android) came up with 4 classifications for describing a zman to the user:

• “Day is $fixedMinutes minutes before sunrise / after sunset”
• “Day is $halachicMinutes minutes zmaniyos before sunrise / after sunset”
• “Day is $degrees˚ below sunrise / sunset”
• “According to $authority”
  It Seems like there is 1 more:
• Widely accepted or only opinion

So far, these use-cases lead me to the following abstraction:

• Every zman is one of two types:

• ValueBased: a zman that does not occur at a moment in time, but rather holds a duration/length of time (e.g. sha’ah zmanis)

• DateBased: a zman that has a momentOfOccurence.
  - I (re)discovered after I came up with the two types that there is already a Zman.java object with 4 properties:
  label: string
  duration: long
  zman: Date
  description: string,

• Every zman has a ZmanOpinion, one of (as in Moshe Waisberg’s model):

• FixedMinutes

• ZmaniyosMinutes

• Degrees

• Authority

• Unanimous

• Every zman has a ZmanType, (a user-friendly english and hebrew name is included here, but must be refactored into a localization mechanism). One of:

• SHAA_ZMANIS(“Halachic hour”, “שעה זמנית“),
  CHATZOS_HALAYLAH(“Halachic midnight”, “חצות הלילה“),
  MISHMAR(“Watch”, “משמר“), //synonymous with אשמורת
  ALOS(“Dawn”, “עלות השחר“),
  MISHEYAKIR(“Earliest Tallis and Teffillin (Misheyakir)“, ” (משיכיר) טלית ותפילין הכי מוקדם“), //pardon the modern Hebrew הכי vs. ביותר
  HANAITZ(“Sunrise”, “הנץ החמה“), //not NAITZ because the ה in Hanaitz is not a ה הידיעה (“the”), it is part of the participle (comparable to “הנצת“)
  CHATZOS_HAYOM(“Halachic midday”, “חצות היום“),
  MINCHA_GEDOLAH(“Greater Mincha”, “מנחה גדולה“), //any better translation? Just transliterate?
  MINCHA_KETANAH(“Lesser Mincha”, “מנחה קטנה“), //any better translation? Just transliterate?
  PLAG_HAMINCHA(“Plag Hamincha”, “פלג המנחה“), //should this be translated or transliterated?
  SHKIAH(“Sunset”, “שקיעה“),
  BAIN_HASHMASHOS(“Twilight”, “בין השמשות“),
  TZAIS(“Nightfall”, “צאת הכוכבים“),
  MOLAD(“New moon”, “מולד“), //accurate translation?

  //Related to rituals:
  SAMUCH_LEMINCHA_KETANA(“Close to Mincha Ketana”, “סמוך למנחה קטנה“), //see note on MINCHA_KETANAH
  SOF_ZMAN_KRIAS_SHEMA(“Latest time to say Shema”, “סוף זמן קריאת שמע“),
  SOF_ZMAN_TEFILLAH(“Latest time to daven Shacharis”, “סוף זמן תפילה“),
  SOF_ZMAN_ACHILAS_CHAMETZ(“Latest time to eat Chametz”, “סוף זמן אכילת חמץ“),
  SOF_ZMAN_BIUR_CHAMETZ(“Latest time to burn Chametz”, “סוף זמן ביעור חמץ“),
  EARLIEST_MINCHA(“Earliest Mincha”, “מנחה הכי מוקדם“),
  EARLIEST_KIDDUSH_LEVANA(“Earliest time to sanctify the moon”, “תחילת זמן קידוש לבנה“),
  SOF_ZMAN_KIDDUSH_LEVANA(“Latest time to sanctify the moon”, “סוף זמן קידוש לבנה“),
  CANDLE_LIGHTING(“Candle lighting”, “הדלקת נרות“)

The two edge-cases I saw in Moshe Waisberg’s classification and the possible solutions I see:

• what about when a zman has multiple originating authorities, or is known or held by several well-known authorities?
• Put the first author to formulate the calculation.
• Put all authors
• Put the most well known author(s)
• Put the most authoritative (e.g. I think R’ Moshe Feinstein is more authoritative for our generation than the Aruch Hashulchan)
• Put the first + most well known, in case it is known by an author other than the first one (e.g “Komarno” zmanim were sometimes from much older sources)
• or it is according to one authority’s understanding of another authority’s opinion? (e.g. , Rabeinu Tam as 72 minutes, Rabeinu Tam as 16.1 degrees, etc., or more complicated: R’Moshe’s understanding of the Magen Avraham as calculated using 18˚ to fixed local chatzos, 16.1˚, etc.)
• or it does not fit into the neat boxes defined by ZmanOpinion (e.g. sofZmanShmaAlos16Point1ToSunset)?
• A general description
• “Day starts at $startZman.description and ends at $endZman.description”
• A map of ZmanType to ZmanOpinion (possible split into start and end - or before or after?)
  - e.g. plagAlosToSunset:
  • day starts at alos16Point1Degrees
  • day ends at sunset,
  • sha’ah zmanis is calculated based on the opinion that the day is calculated from a alos16Point1Degrees of 16.1 degrees before sunrise to seaLevelSunset.
  • bainHashmashosRT13Point5MinutesBefore7Point083Degrees
    • Rabeinu tam
    • FixedMinutes(13.5)
    • Before: 7.083 degrees

What about when there is only one way to calculate a zman? What should the ZmanOpinion type be?
And should authority names be in Hebrew (e.g. sefer names), transliterated English (for languages that need ASCII), etc.? Should they be standardized across ports?
I am not sure which alternatives would be best, and would like input.