parseICal function
Parses an iCalendar text into event inputs. Never throws on data: what is
wrong is in problems, and an event whose start cannot be read is left
out. Only VEVENTs are read. defaultZone: where floating times (no TZID,
no Z) are read when the file names no zone (X-WR-TIMEZONE).
Implementation
ParsedICal parseICal(String text, {String? defaultZone}) {
final problems = <Problem>[];
final events = <EventInput>[];
final cals = _components(text, problems);
// Several VCALENDARs in one text (concatenated feeds) are read as one; the first names it.
final all = cals.where((c) => c.name == 'VCALENDAR').toList();
final _Component cal;
if (all.isEmpty) {
cal = _Component('VCALENDAR')..children.addAll(cals);
} else if (all.length == 1) {
cal = all.first;
} else {
cal = _Component('VCALENDAR');
for (final c in all) {
cal.props.addAll(c.props);
cal.children.addAll(c.children);
}
}
final wrZone = cal.prop('X-WR-TIMEZONE')?.value.trim();
final calZone = wrZone == null || wrZone.isEmpty ? null : (isValidZone(wrZone) ? wrZone : ianaIn(wrZone));
// An empty default is none; one that is no zone makes the floating times unreadable (as on the web).
final floatingZone = calZone ?? (defaultZone == null || defaultZone.isEmpty ? null : defaultZone);
final name = cal.prop('X-WR-CALNAME');
final calendar = ICalCalendar(
name: name == null ? null : unescapeText(name.value),
zone: calZone,
prodId: cal.prop('PRODID')?.value,
);
final vevents = cal.children.where((c) => c.name == 'VEVENT').toList();
for (final kind in const ['VTODO', 'VJOURNAL']) {
if (cal.children.any((c) => c.name == kind)) {
problems.add(_issue(ProblemCode.icalUnsupported, Severity.warning, kind, 'skipped'));
}
}
final vtimezones = {
for (final c in cal.children.where((c) => c.name == 'VTIMEZONE')) c.prop('TZID')?.value.trim() ?? '': c,
};
// The years the file's events start in: what a VTIMEZONE is compared over.
final years = {
for (final v in vevents)
if (_year.firstMatch(v.prop('DTSTART')?.value ?? '') case final m?) int.parse(m[1]!),
}.toList()..sort();
final unsupported = <String>{};
void once(String what, String path) {
if (unsupported.add(what)) problems.add(_issue(ProblemCode.icalUnsupported, Severity.warning, path, what));
}
final zones = <String, _Zone?>{};
_Zone? zoneFor(String tzid, String path) {
if (zones.containsKey(tzid)) return zones[tzid];
final iana = ianaIn(tzid);
_Zone? zone = iana == null ? null : _Iana(iana);
final vtz = zone != null ? null : vtimezones[tzid];
if (vtz != null) {
final obs = _observances(vtz);
// Old events can fall under rules the VTIMEZONE no longer states (US 2005 vs its 2007+ rules):
// all the years first, then the latest alone.
final latest = years.isNotEmpty ? [years.last] : [2026];
final found =
matchObservances(obs, years.isNotEmpty ? years.sublist(years.length > 12 ? years.length - 12 : 0) : latest) ??
(years.length > 1 ? matchObservances(obs, latest) : null);
if (found != null) {
problems.add(_issue(ProblemCode.zoneGuessed, Severity.warning, path, '$tzid → $found'));
zone = _Iana(found);
} else if (obs.isNotEmpty) {
// Each wall time gets the offset the VTIMEZONE's rules give it, as a fixed-offset moment:
// right for every start, though a series repeats at that one offset.
zone = _Own(obs);
problems.add(_issue(ProblemCode.zoneFixedOffset, Severity.warning, path, tzid));
}
}
if (zone == null) problems.add(_issue(ProblemCode.unknownZone, Severity.warning, path, tzid));
zones[tzid] = zone;
return zone;
}
// UTC times stay UTC's on a recurring event: RFC 5545 repeats them in UTC.
var keepUtc = false;
/// One value of a date or date-time property, written as the core reads it.
_Moment? moment(String value, ContentLine p, String path) {
final v = value.trim();
final d = _date.firstMatch(v);
if (d != null) {
final date = _plainDate(int.parse(d[1]!), int.parse(d[2]!), int.parse(d[3]!));
if (date != null) return (kind: 'date', text: '$date');
} else if (_dateTime.firstMatch(v) case final t?) {
final wall = _wallOf(v);
if (wall != null) {
if (t[7]!.isNotEmpty) {
final at = Instant.fromEpochMilliseconds(wall.wallMs);
// A file that names its zone means its UTC times to be read there;
// otherwise they are UTC's, as RFC 5545 repeats them.
final inZone = floatingZone != null && !keepUtc;
if (!inZone) return (kind: 'zoned', text: '$wall[UTC]');
if (isValidZone(floatingZone)) return (kind: 'zoned', text: '${ZonedDateTime(at, floatingZone)}');
// A default zone that is none: the web cannot place it either (ical-syntax below).
} else {
final tzid = p.param('TZID');
final _Zone? zone = tzid != null ? zoneFor(tzid, path) : (floatingZone == null ? null : _Iana(floatingZone));
switch (zone) {
case _Own(:final observances):
final off = fixedZone(offsetIn(observances, wall));
return (kind: 'zoned', text: '$wall$off[$off]');
// A fixed-offset zone (`+05:30`) is written with its offset, as the own-rules reading is.
case _Iana(:final id):
return (kind: 'zoned', text: _offsetZone.hasMatch(id) ? '$wall$id[$id]' : '$wall[$id]');
case null:
return (kind: 'floating', text: '$wall');
}
}
}
}
problems.add(_issue(ProblemCode.icalSyntax, Severity.error, path, v));
return null;
}
List<String> list(_Component c, String name, String path) {
final out = <String>[];
final props = c.props.where((p) => p.name == name).toList();
for (var k = 0; k < props.length; k++) {
final p = props[k];
final period = p.param('VALUE')?.toUpperCase() == 'PERIOD';
if (period) once('RDATE;VALUE=PERIOD', '$path.$name');
for (final raw in p.value.split(',')) {
final m = moment(period ? raw.split('/').first : raw, p, '$path.$name[$k]');
if (m != null) out.add(m.text);
}
}
return out;
}
for (var i = 0; i < vevents.length; i++) {
final v = vevents[i];
final path = 'VEVENT[$i]';
final dtstart = v.prop('DTSTART');
keepUtc = v.props.any((p) => p.name == 'RRULE' || p.name == 'RDATE');
final start = dtstart == null ? null : moment(dtstart.value, dtstart, '$path.DTSTART');
if (start == null) {
if (dtstart == null) problems.add(_issue(ProblemCode.icalSyntax, Severity.error, '$path.DTSTART', 'missing'));
continue;
}
// An empty UID is none (the event gets an id of its own), as on the web.
final uidText = v.prop('UID')?.value.trim();
final uid = uidText == null || uidText.isEmpty ? null : uidText;
final rid = v.prop('RECURRENCE-ID');
final recurrence = rid == null ? null : moment(rid.value, rid, '$path.RECURRENCE-ID');
if (rid != null && rid.param('RANGE')?.toUpperCase() == 'THISANDFUTURE') {
once('RECURRENCE-ID;RANGE=THISANDFUTURE', '$path.RECURRENCE-ID');
}
final override = uid != null && recurrence != null;
final dtend = v.prop('DTEND');
final end = dtend == null ? null : moment(dtend.value, dtend, '$path.DTEND');
final duration = v.prop('DURATION')?.value.trim();
final summary = v.prop('SUMMARY');
final rrules = [for (final p in v.props.where((p) => p.name == 'RRULE')) p.value.trim()];
if (v.prop('EXRULE') != null) once('EXRULE', '$path.EXRULE');
final exdate = list(v, 'EXDATE', path);
final rdate = list(v, 'RDATE', path);
final status = v.prop('STATUS')?.value.trim().toLowerCase();
final url = v.prop('URL');
final props = <String, Object?>{};
final description = v.prop('DESCRIPTION');
if (description != null) props['description'] = unescapeText(description.value);
final location = v.prop('LOCATION');
if (location != null) props['location'] = unescapeText(location.value);
final categories = [for (final p in v.props.where((p) => p.name == 'CATEGORIES')) ...splitText(p.value)];
if (categories.isNotEmpty) props['categories'] = categories;
final organizer = v.prop('ORGANIZER');
if (organizer != null) {
final cn = organizer.param('CN');
final email = organizer.value.replaceFirst(RegExp('^mailto:', caseSensitive: false), '').trim();
props['organizer'] = {if (cn != null && cn.isNotEmpty) 'name': cn, if (email.isNotEmpty) 'email': email};
}
events.add(
EventInput(
id: override ? '$uid@${rid!.value.trim()}' : uid,
seriesId: override ? uid : null,
recurrenceId: override ? recurrence.text : null,
start: start.text,
allDay: start.kind == 'date' ? true : null,
end: end?.text,
// RFC 5545 §3.6.1: no end and no duration is one day for a date, an instant for a time.
duration: end != null
? null
: (duration != null && duration.isNotEmpty ? duration : (start.kind == 'date' ? 'P1D' : 'PT0S')),
title: summary == null ? null : unescapeText(summary.value),
rrule: rrules.isEmpty ? null : (rrules.length == 1 ? rrules.first : rrules),
exdate: exdate.isEmpty ? null : exdate,
rdate: rdate.isEmpty ? null : rdate,
status: status == null ? null : EventStatus.fromCode(status),
busy: v.prop('TRANSP')?.value.trim().toUpperCase() == 'TRANSPARENT' ? false : null,
url: url?.value.trim(),
extendedProps: props.isEmpty ? null : props,
),
);
}
return ParsedICal(events, problems, calendar);
}