Initial commit

Author: Koen Zwikstra

.gitignore

@@ -0,0 +1,10 @@
+# https://dart.dev/guides/libraries/private-files
+# Created by `dart pub`
+.dart_tool/
+.vscode/
+
+# Avoid committing pubspec.lock for library packages; see
+# https://dart.dev/guides/libraries/private-files#pubspeclock.
+pubspec.lock
+
+*.exe

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-01-15
+
+### Added
+- RFC 5545 compliant iCalendar parser
+- Support for VEVENT, VTODO, VJOURNAL, VTIMEZONE components
+- Full RRULE recurrence expansion
+- Streaming parser for large files
+- Custom property parser registration
+- Timezone-aware date/time handling
+- Two-layer architecture (document + semantic)
+
+[1.0.0]: https://github.com/firstfloorsoftware/firstfloor_calendar/releases/tag/v1.0.0

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 First Floor Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,147 @@
+# firstfloor_calendar
+
+[![Pub Package](https://img.shields.io/pub/v/firstfloor_calendar.svg)](https://pub.dev/packages/firstfloor_calendar)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Dart library for parsing iCalendar (.ics) files with RFC 5545 support.
+
+## Features
+
+- Parse iCalendar files into strongly typed models
+- Support for events, todos, journals, and timezones
+- Full RRULE recurrence expansion
+- Stream large files without loading into memory
+- Extensible with custom property parsers
+
+## Installation
+
+```yaml
+dependencies:
+  firstfloor_calendar: ^1.0.0
+```
+
+## Usage
+
+### Basic Parsing
+
+Parse iCalendar text into a strongly typed `Calendar` object. The parser handles all RFC 5545 components including events, todos, journals, and timezones.
+
+```dart
+import 'package:firstfloor_calendar/firstfloor_calendar.dart';
+
+final icsContent = '''
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Example//EN
+BEGIN:VEVENT
+UID:event-123@example.com
+DTSTART:20240315T100000Z
+DTEND:20240315T110000Z
+SUMMARY:Team Meeting
+END:VEVENT
+END:VCALENDAR''';
+
+final parser = CalendarParser();
+final calendar = parser.parseFromString(icsContent);
+
+for (final event in calendar.events) {
+  print('${event.summary}: ${event.dtstart}');
+}
+```
+
+### Working with Events
+
+Access event properties with full type safety. Required properties like `uid` and `dtstart` are non-nullable, while optional properties return nullable values.
+
+```dart
+final event = calendar.events.first;
+
+// Required properties
+print('UID: ${event.uid}');
+print('Start: ${event.dtstart}');
+
+// Optional properties
+print('Summary: ${event.summary ?? "Untitled"}');
+print('Location: ${event.location ?? "No location"}');
+print('Description: ${event.description ?? ""}');
+
+// Attendees
+for (final attendee in event.attendees) {
+  print('Attendee: ${attendee.address}');
+}
+```
+
+### Recurring Events
+
+Generate occurrences from recurrence rules (RRULE). The `occurrences()` method returns a lazy stream that handles both recurring and non-recurring events gracefully.
+
+```dart
+final event = calendar.events.first;
+
+// Get first 10 occurrences
+for (final occurrence in event.occurrences().take(10)) {
+  print('Occurrence: $occurrence');
+}
+```
+
+### Streaming Large Files
+
+Parse large iCalendar files efficiently using the streaming parser. Components are processed one at a time without loading the entire file into memory.
+
+```dart
+import 'dart:io';
+
+final file = File('large-calendar.ics');
+final streamParser = DocumentStreamParser();
+
+await for (final component in streamParser.streamComponents(file.openRead())) {
+  if (component.name == 'VEVENT') {
+    final summary = component.properties
+        .where((p) => p.name == 'SUMMARY')
+        .firstOrNull
+        ?.value;
+    print('Event: ${summary ?? "Untitled"}');
+  }
+}
+```
+
+### Custom Property Parsers
+
+Extend the parser with custom property handlers for vendor-specific or experimental properties. Register custom parsers before parsing your calendar data.
+
+```dart
+final parser = CalendarParser();
+
+parser.registerPropertyRule(
+  componentName: 'VEVENT',
+  propertyName: 'X-CUSTOM-PRIORITY',
+  rule: PropertyRule(
+    parser: (property) {
+      final value = int.tryParse(property.value);
+      if (value == null || value < 1 || value > 10) {
+        throw ParseException(
+          'X-CUSTOM-PRIORITY must be between 1-10',
+          lineNumber: property.lineNumber,
+        );
+      }
+      return value;
+    },
+  ),
+);
+
+final calendar = parser.parseFromString(icsContent);
+final priority = calendar.events.first.value<int>('X-CUSTOM-PRIORITY');
+```
+
+## Architecture
+
+The library uses a two-layer architecture:
+
+- **Document Layer** (`DocumentParser`): Parses raw .ics text into an untyped tree structure
+- **Semantic Layer** (`CalendarParser`): Converts the document tree into strongly typed models with validation
+
+Use `DocumentParser` for low-level access, and `CalendarParser` for most applications.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

analysis_options.yaml

@@ -0,0 +1,30 @@
+# This file configures the static analysis results for your project (errors,
+# warnings, and lints).
+#
+# This enables the 'recommended' set of lints from `package:lints`.
+# This set helps identify many issues that may lead to problems when running
+# or consuming Dart code, and enforces writing Dart using a single, idiomatic
+# style and format.
+#
+# If you want a smaller set of lints you can change this to specify
+# 'package:lints/core.yaml'. These are just the most critical lints
+# (the recommended set includes the core lints).
+# The core lints are also what is used by pub.dev for scoring packages.
+
+include: package:lints/recommended.yaml
+
+# Uncomment the following section to specify additional rules.
+
+# linter:
+#   rules:
+#     - camel_case_types
+
+# analyzer:
+#   exclude:
+#     - path/to/excluded/files/**
+
+# For more information about the core and recommended set of lints, see
+# https://dart.dev/go/core-lints
+
+# For additional information about configuring this file, see
+# https://dart.dev/guides/language/analysis-options

example/main.dart

@@ -0,0 +1,57 @@
+import 'package:firstfloor_calendar/firstfloor_calendar.dart';
+
+void main() {
+  // Sample iCalendar content
+  final icsContent = '''
+BEGIN:VCALENDAR
+VERSION:2.0
+PRODID:-//Example//EN
+BEGIN:VEVENT
+UID:daily-standup@example.com
+DTSTAMP:20240315T080000Z
+DTSTART:20240315T090000Z
+DTEND:20240315T091500Z
+SUMMARY:Daily Standup
+LOCATION:Conference Room A
+RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR;COUNT=10
+END:VEVENT
+BEGIN:VEVENT
+UID:team-lunch@example.com
+DTSTAMP:20240320T100000Z
+DTSTART:20240320T120000Z
+DTEND:20240320T130000Z
+SUMMARY:Team Lunch
+LOCATION:Downtown Bistro
+DESCRIPTION:Monthly team lunch to celebrate achievements
+END:VEVENT
+END:VCALENDAR''';
+
+  // Parse the calendar
+  final parser = CalendarParser();
+  final calendar = parser.parseFromString(icsContent);
+
+  print('Calendar: ${calendar.prodid}');
+  print('Events: ${calendar.events.length}\n');
+
+  // List all events
+  for (final event in calendar.events) {
+    print('📅 ${event.summary}');
+    print('   Start: ${event.dtstart}');
+    if (event.location != null) {
+      print('   Location: ${event.location}');
+    }
+    if (event.description != null) {
+      print('   Description: ${event.description}');
+    }
+
+    // Show recurring event occurrences
+    if (event.rrule != null) {
+      print('   Recurring: ${event.rrule!.freq}');
+      print('   First 5 occurrences:');
+      for (final occurrence in event.occurrences().take(5)) {
+        print('     • $occurrence');
+      }
+    }
+    print('');
+  }
+}

lib/firstfloor_calendar.dart

@@ -0,0 +1,4 @@
+library;
+
+export 'src/document/document.dart';
+export 'src/semantic/semantic.dart';

lib/src/document/calendar_document.dart

@@ -0,0 +1,96 @@
+import 'package:collection/collection.dart';
+
+/// Represents the raw structural representation of an iCalendar document
+/// without any type interpretation of property values.
+class CalendarDocument extends CalendarDocumentComponent {
+  /// Creates a new calendar document with the given properties and components.
+  const CalendarDocument({
+    super.properties = const [],
+    super.components = const [],
+    super.lineNumber = 0,
+  }) : super(name: 'VCALENDAR');
+}
+
+/// Represents a component in the calendar document structure.
+class CalendarDocumentComponent {
+  /// The name of the calendar component.
+  final String name;
+
+  /// The list of properties associated with this component.
+  final List<CalendarProperty> properties;
+
+  /// The list of sub-components within this component.
+  final List<CalendarDocumentComponent> components;
+
+  /// The line number where this component is defined.
+  final int lineNumber;
+
+  /// Creates a new  component with the given name, properties, and components.
+  const CalendarDocumentComponent({
+    required this.name,
+    this.properties = const [],
+    this.components = const [],
+    this.lineNumber = 0,
+  });
+
+  /// Returns the properties with the given name.
+  Iterable<CalendarProperty> propertiesNamed(String name) {
+    return properties.where((p) => p.name == name);
+  }
+
+  /// Returns the values for the properties with the given name.
+  Iterable<String> values(String name) {
+    return properties.where((p) => p.name == name).map((p) => p.value);
+  }
+
+  // Return the first value for the given property name, or null if not found.
+  String? value(String name) {
+    return properties.firstWhereOrNull((p) => p.name == name)?.value;
+  }
+
+  /// Returns the components with the given name.
+  Iterable<CalendarDocumentComponent> componentsNamed(String name) {
+    return components.where((c) => c.name == name);
+  }
+
+  /// Returns the first component with the given name, or null if not found.
+  CalendarDocumentComponent? component(String name) {
+    return components.firstWhereOrNull((c) => c.name == name);
+  }
+
+  @override
+  String toString() {
+    return name;
+  }
+}
+
+/// Represents a raw property in the document structure
+class CalendarProperty {
+  /// The name of the property.
+  final String name;
+
+  /// The parameters associated with the property, if any.
+  final Map<String, List<String>> parameters;
+
+  /// The raw value of the property.
+  final String value;
+
+  /// The line number where this property is defined.
+  final int lineNumber;
+
+  /// Creates a new calendar property with the given name, parameters, and value.
+  const CalendarProperty({
+    required this.name,
+    this.parameters = const {},
+    required this.value,
+    this.lineNumber = 0,
+  });
+
+  @override
+  String toString() {
+    final params = parameters.entries
+        .map((e) => '${e.key}=${e.value.join(',')}')
+        .join(';');
+    return '$name${params.isNotEmpty ? ';$params' : ''}:$value';
+  }
+}

lib/src/document/document.dart

@@ -0,0 +1,3 @@
+export 'calendar_document.dart';
+export 'document_parser.dart';
+export 'parser.dart' show ParseException;