justinwongcn/moon-ical/ical/model does not have a README file

    Component

    pub struct Component {
    kind : String
    properties : Array[
    ContentLine
    ]
    children : Array[Component]
    } derive(Eq,
    Debug
    )

    One iCalendar component: its kind, its own properties in wire order, and any nested components. Nesting is real (VALARM lives inside VEVENT, VEVENT inside VCALENDAR), so the model keeps a tree instead of a flat list, and properties stay in the order the feed sent them.

    Component::equal

    fn Component::equal(Component, Component) -> Bool

    Component::event

    fn Component::event(self : Component, zones~ : ZoneTable) -> Event? raise

    Map this component when it is a VEVENT; other component kinds return None. Only properties of this event are interpreted, so unrelated unsupported time zones or event properties do not prevent a selective query.

    Component::events

    fn Component::events(self : Component, zones~ : ZoneTable) -> Array[Event] raise

    The VEVENT children of this component as typed events, in wire order.

    zones resolves TZID= parameters. Pass the table the way [parse_events] builds it — [ZoneTable::with_builtin] over [build_zone_table] applied to the same feed — so unsupported feed declarations shadow UTC defaults.

    Only direct children are considered: a VEVENT nests directly inside a VCALENDAR, never deeper.

    Component::not_equal

    fn Component::not_equal(x : Component, y : Component) -> Bool

    Component::properties_named

    Every property with this name — EXDATE and RDATE may be repeated, and a single one may hold a comma-separated list.

    Component::property

    The first property with this name, if the component carries one.

    Event

    pub struct Event {
    uid : String?
    summary : String?
    location : String?
    description : String?
    dtstart : IcalDateTime?
    dtend : IcalDateTime?
    rrule : String?
    recurrence_id : IcalDateTime?
    recurrence_range : String?
    status : String?
    exdates : Array[IcalDateTime]
    rdates : Array[IcalDateTime]
    } derive(
    Debug
    )

    One calendar event, mapped from a VEVENT component (RFC 5545 §3.6.1).

    This is a typed view over the component tree, not a replacement for it: unknown properties stay in the Component and nothing is dropped. Every field is optional because RFC 5545 makes every VEVENT property optional; a property that is present but malformed raises [@text.ParseError] instead of being silently skipped, so a broken feed is loud rather than subtly wrong. A property that is simply absent is None — absence is not breakage. An event that states no DTEND ends where its DURATION says it does (RFC 5545 §3.8.5.3 offers DURATION as the alternative end); carrying both is the spec violation it names and raises.

    Recurrence dates and overrides are retained for the rrule package's series union, exclusions, and override merge.
    impl Show for Event

    Event::all_day

    fn Event::all_day(self : Event) -> Bool

    An all-day event is one whose DTSTART is a DATE value.

    Event::output

    fn Event::output(self : Event, logger : &Logger) -> Unit

    Event::to_repr

    Event::to_string

    fn Event::to_string(self : Event) -> String

    IcalDateTime

    pub struct IcalDateTime {
    wall :
    PlainDateTime

    utc_offset : Int?
    zone_id : String
    all_day : Bool
    } derive(Eq,
    Debug
    )

    A parsed iCalendar date-time value (DTSTART, DTEND, DUE, UNTIL, EXDATE, ...).

    iCalendar writes wall-clock readings rather than instants, so the wall time is kept next to the offset that says where it should be read:

    • DTSTART:20260908T013000Z → utc_offset = Some(0)
    • DTSTART;TZID=Asia/Shanghai:20260908T093000 → utc_offset = Some(28800)
    • DTSTART:20260908T093000 → utc_offset = None (floating: the feed declared no zone, so it means 09:30 wherever it is read)
    • DTSTART;VALUE=DATE:20260908 → all_day = true, wall time at midnight

    moonbitlang/x/time supplies the calendar arithmetic; the offset stays a plain Int instead of a Zone because named zones are resolved through a fixed-offset table (see [ZoneTable] and seam S2 in docs/upstream-seams.md).

    IcalDateTime::compare

    fn IcalDateTime::compare(self : IcalDateTime, other : IcalDateTime) -> Int

    Negative when self happens before other, zero for the same instant, positive afterwards. All-day values compare by their calendar day.

    IcalDateTime::equal

    IcalDateTime::instant_seconds

    fn IcalDateTime::instant_seconds(self : IcalDateTime) -> Int64

    Seconds since the Unix epoch for this value.

    A floating value is treated as UTC so that floating and explicitly-zoned times can still be sorted in one pass; the feed gave nothing better to go on.

    IcalDateTime::is_floating

    fn IcalDateTime::is_floating(self : IcalDateTime) -> Bool

    Whether this value floats: the feed declared no zone, so the wall reading means that time wherever it is read. Floating values sort as if UTC (see [IcalDateTime::instant_seconds]) but are not UTC.

    IcalDateTime::is_utc

    fn IcalDateTime::is_utc(self : IcalDateTime) -> Bool

    Whether this value is pinned to UTC — a Z designator rather than a TZID, an absolute offset, or nothing at all.

    IcalDateTime::not_equal

    fn IcalDateTime::not_equal(x : IcalDateTime, y : IcalDateTime) -> Bool

    IcalDateTime::on_date

    The same clock reading as self, on another calendar day: the clock time, UTC offset, zone spelling, and all-day flag all carry over unchanged.

    Recurrence arithmetic preserves the explicitly fixed binding. Dynamic TZIDs are rejected during parsing rather than approximated here. Raises if date is not a valid calendar day.

    IcalDateTime::output

    fn IcalDateTime::output(self : IcalDateTime, logger : &Logger) -> Unit

    IcalDateTime::shift_seconds

    fn IcalDateTime::shift_seconds(self : IcalDateTime, seconds : Int64) -> IcalDateTime raise

    Shift this wall-clock value by an exact number of seconds while preserving its zone spelling, fixed offset, and all-day marker.

    IcalDateTime::to_string

    fn IcalDateTime::to_string(self : IcalDateTime) -> String

    ZoneTable

    pub struct ZoneTable {
    entries : Map[String, Int]
    rejected : Map[String, String]
    } derive(
    Debug
    )

    A zone-name to UTC-offset table used to resolve TZID= parameters.

    Offsets are seconds east of UTC. iCalendar defines TZID case-sensitively, but real feeds are sloppy (Google emits Asia/Shanghai, some Outlook exports ASIA/SHANGHAI), so keys are normalised before comparison.

    Only explicit fixed bindings are usable: UTC aliases, caller inserts, or a provably fixed VTIMEZONE. Regional names are not guessed. Unsupported feed declarations are retained as rejections and shadow default bindings.

    ZoneTable::builtin_common

    fn ZoneTable::builtin_common() -> ZoneTable

    Intrinsically fixed UTC aliases only. Regional names need an explicit caller binding or a provably fixed feed declaration.

    ZoneTable::empty

    fn ZoneTable::empty() -> ZoneTable

    An empty table: every TZID fails to resolve until zones are added.

    ZoneTable::insert

    fn ZoneTable::insert(self : ZoneTable, tzid : String, seconds : Int) -> Unit

    Explicitly bind a fixed offset. Later caller inserts win and remove a prior rejection. This is an assertion by the caller, not IANA resolution.

    ZoneTable::lookup

    fn ZoneTable::lookup(self : ZoneTable, tzid : String) -> Int?

    Look a zone up, case-insensitively; the most recently inserted match wins.

    ZoneTable::rejection_reason

    fn ZoneTable::rejection_reason(self : ZoneTable, tzid : String) -> String?

    Why a feed declaration cannot be used as a fixed binding, if present.

    ZoneTable::with_builtin

    fn ZoneTable::with_builtin(feed : ZoneTable) -> ZoneTable

    UTC defaults overridden by feed declarations, including rejections. A malformed same-name declaration must not fall back to a default.

    build_zone_table

    fn build_zone_table(roots : Array[Component]) -> ZoneTable

    Collect provably fixed feed declarations without interpreting dynamic transitions. Invalid or unsupported declarations shadow defaults and fail only when a date property references their TZID. A fixed STANDARD has a local DTSTART and equal FROM/TO offsets, with no transition rules.

    Example

    fn test_example() raise {
    let roots = @model.parse_components([
    "BEGIN:VCALENDAR", "BEGIN:VTIMEZONE", "TZID:MY-ZONE", "BEGIN:STANDARD", "DTSTART:19700101T000000",
    "TZOFFSETFROM:+0930", "TZOFFSETTO:+0930", "END:STANDARD", "END:VTIMEZONE", "END:VCALENDAR",
    ])
    let table = @model.build_zone_table(roots)
    assert_eq(table.lookup("my-zone"), Some(9 * 3600 + 30 * 60))
    }

    parse_calendar

    fn parse_calendar(input : String) -> Array[Component] raise

    Parse a complete iCalendar document into its lossless component trees. Unknown components and properties remain available for inspection and serialization.

    parse_components

    fn parse_components(lines : Array[String]) -> Array[Component] raise

    Build a component tree from already-unfolded logical lines.

    Unknown components are preserved rather than dropped, so an unusual feed loses no data. Unbalanced BEGIN/END, a mismatched END name, a property outside any component, and nesting deeper than [MAX_COMPONENT_DEPTH] all raise [@text.ParseError] carrying the offending line number.

    Example

    fn test_example() raise {
    let roots = @model.parse_components([
    "BEGIN:VCALENDAR", "BEGIN:VEVENT", "SUMMARY:Sync", "END:VEVENT", "END:VCALENDAR",
    ])
    assert_eq(roots.length(), 1)
    assert_eq(roots[0].children[0].properties[0].value, "Sync")
    }

    parse_date_time

    fn parse_date_time(line :
    ContentLine
    , zones : ZoneTable, line_no? : Int) -> IcalDateTime raise

    Parse a DTSTART / DTEND / DUE property into an [IcalDateTime].

    zones resolves a TZID= parameter; pass [ZoneTable::with_builtin] over [build_zone_table] when reading a feed that ships its own VTIMEZONE. An unresolvable TZID is an error rather than a silent fallback to UTC, because guessing would move every event in that calendar by hours.

    Example

    fn test_example() raise {
    let line = @text.parse_content_line(
    "DTSTART;TZID=Asia/Shanghai:20260908T093000", 1,
    )
    let dt = @model.parse_date_time(line, @model.ZoneTable::builtin_common())
    assert_eq(dt.utc_offset, Some(8 * 3600))
    assert_eq(dt.to_string(), "2026-09-08T09:30:00+08:00")
    }

    parse_date_time_value

    fn parse_date_time_value(raw : String, zones : ZoneTable, tzid? : String?, value_is_date? : Bool, line_no? : Int) -> IcalDateTime raise

    Parse one date-time value together with the context its property line carried. EXDATE and RDATE pack several comma-separated values into one line, and the line's TZID= / VALUE=DATE parameters apply to every one of them — split the values, pass each through here with the same context.

    parse_duration

    fn parse_duration(text : String, line_no~ : Int, raw~ : String) -> Int64 raise

    Parse an iCalendar DURATION value (RFC 5545 §3.3.6) into its total seconds. The grammar: an optional sign, P, then either nW alone, or nD optionally followed by T and a run of nH/nM/nS in that exact order — each component at most once, each with at least one digit. Raises [@text.ParseError] with the offending text on anything else.

    Day and week components count as their exact 86400 / 604800 seconds. Nominal durations would drift across DST changes, but this project's fixed-offset ZoneTable has no DST history (see [ZoneTable] and seam S2 in docs/upstream-seams.md), so nominal and exact coincide by the same boundary that freezes every other wall-clock computation.

    Example

    fn test_example() raise {
    assert_eq(@model.parse_duration("PT1H30M", line_no=1, raw="PT1H30M"), 5400)
    assert_eq(@model.parse_duration("-P1D", line_no=1, raw="-P1D"), -86400)
    }

    parse_events

    fn parse_events(input : String) -> Array[Event] raise

    Parse a whole iCalendar feed into typed events: unfold the text, build the component tree, register fixed zones and unsupported declarations, then map every VEVENT. Referenced unsupported zones raise.

    Example

    fn test_example() raise {
    let events = @model.parse_events(
    "BEGIN:VCALENDAR\r\nBEGIN:VEVENT\r\nSUMMARY:Sync\r\nEND:VEVENT\r\nEND:VCALENDAR",
    )
    assert_eq(events.length(), 1)
    assert_eq(events[0].summary, Some("Sync"))
    }

    parse_single_date_time

    fn parse_single_date_time(text : String, zones : ZoneTable, line_no? : Int) -> IcalDateTime raise

    Parse a bare date-time text, as found in RRULE's UNTIL= and in an EXDATE list, where no property carries a TZID.

    RFC 5545 requires UNTIL to be UTC when DTSTART is UTC, so a trailing Z is read here; anything else is floating, exactly like a DTSTART written without a designator.

    parse_utc_offset

    fn parse_utc_offset(text : String, line_no~ : Int, raw~ : String) -> Int raise

    Parse an iCalendar UTC-offset value (RFC 5545 §3.3.14): +0800, -0500, +0530, +053030, or a bare +08 (a deliberate lenience — the RFC grammar requires the minutes). Raises [ParseError] on anything else: an offset whose shape or components are not read whole would silently shift every event in a calendar, which is how the pre-S12 half-read of +05:30 lost half an hour.

    Example

    fn test_example() raise {
    assert_eq(
    @model.parse_utc_offset("+0530", line_no=1, raw="+0530"),
    5 * 3600 + 30 * 60,
    )
    assert_eq(
    @model.parse_utc_offset("-0800", line_no=1, raw="-0800"),
    -(8 * 3600),
    )
    }