rrule 0.1.1

  • Readme
  • Changelog
  • Installing
  • 78

๐Ÿ” Recurrence rule parsing & calculation as defined in the iCalendar RFC

Build, Test & Lint Coverage

How to use this package #

Note: This package uses time_machine for handling date and time. See its README for how to initialize it on Flutter or the web.

Create a RecurrenceRule:

// Every two weeks on Tuesday and Thursday, but only in December.
final rrule = RecurrenceRule(
  frequency: Frequency.weekly,
  interval: 2,
  byWeekDays: {
    ByWeekDayEntry(DayOfWeek.tuesday),
    ByWeekDayEntry(DayOfWeek.thursday),
  },
  byMonths: {12},
  weekStart: DayOfWeek.sunday,
);

And get its recurrences by evaluating it from a start date:

final Iterable<LocalDateTime> instances = rrule.getInstances(
  start: LocalDateTime.now(),
);

To limit returned instances (besides using RecurrenceRule.until or RecurrenceRule.count), you can use Dart's default Iterable functions:

final firstThreeInstances = instances.take(3);

final onlyThisYear = instances.takeWhile(
  (instance) => instance.year == LocalDate.today().year,
);

final startingNextYear = instances.where(
  (instance) => instance.year > LocalDate.today().year,
);

Note: Convenience methods or parameters will be added soon to make these limitations easier.

Machine-readable String conversion #

You can convert between RecurrenceRules and iCalendar/RFC 5545-compliant Strings by using RecurrenceRuleStringCodec or the following convenience methods:

final string = 'RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;BYMONTH=12;WKST=SU';
final rrule = RecurrenceRule.fromString(string);

assert(rrule.toString() == string); // true

(Same RRULE as the first one)

Human-readable Text conversion #

You can convert a RecurrenceRule to a human-readable Strings by using RecurrenceRule.toText():

// First, load the localizations (currently, only English is supported):
final l10n = await RruleL10nEn.create();

final rrule = RecurrenceRule.fromString(
    'RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH;BYMONTH=12;WKST=SU');

final text = 'Every other week in December on Tuesday & Thursday';
assert(rrule.toText(l10n: l10n) == string); // true

(Same RRULE as the first one)

A few more examples:

  • RRULE:INTERVAL=4;FREQ=HOURLY: Every 4 hours
  • RRULE:FREQ=DAILY;BYSETPOS=1,-2;BYMONTH=1,12;BYMONTHDAY=1,-1: Daily in January & December on the 1st & 2nd-to-last instance of the 1st & last day of the month
  • RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR: Weekly on weekdays
  • RRULE:INTERVAL=2;FREQ=WEEKLY: Every other week
  • RRULE:FREQ=MONTHLY;BYDAY=-3TU: Monthly on the 3rd-to-last Tuesday
  • RRULE:FREQ=YEARLY;BYDAY=+13FR: Annually on the 13th Friday of the year
  • RRULE:FREQ=YEARLY;BYSETPOS=1,-2;BYMONTH=1,12;BYWEEKNO=1,-1;BYYEARDAY=1,-1;BYMONTHDAY=1,-1;BYDAY=MO,WE: Annually on the 1st & 2nd-to-last instance of every Monday & Wednesday that are also the 1st or last day of the month, that are also the 1st or last day of the year, that are also in the 1st or last week of the year, and that are also in January or December

While this already supports really complex RRULEs, some of them are not (yet) supported. See RecurrenceRule.canFullyConvertToText for more information.

Limitations #

  • leap seconds are not supported (limitation of the time_machine package)
  • only years 0โ€“9999 in the Common Era are supported (limitation of the iCalendar RFC, but if you have a use case this should be easy to extend)

Thanks #

The recurrence calculation code of RecurrencRules is mostly a partial port of rrule.js, though with a lot of modifications to use time_machine and not having to do date/time calculations manually. You can find the license of rrule.js in the file LICENSE-rrule.js.txt.

Changelog #

All notable changes to this project will be documented in this file.

This project adheres to Semantic Versioning.

Unreleased #

0.1.1 ยท 2020-07-09 #

๐ŸŽ‰ New Features #

  • add RecurrenceRule.toText() for conversion to a human-readable string (#7), closes: #5

0.1.0 ยท 2020-05-26 #

Initial release ๐ŸŽ‰

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  rrule: ^0.1.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:rrule/rrule.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
60
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
78
Learn more about scoring.

We analyzed this package on Jul 14, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.15

Maintenance suggestions

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and rrule.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
basics ^0.4.0 0.4.0+1
collection ^1.14.12 1.14.13 1.15.0-nullsafety
meta ^1.1.8 1.2.2 1.3.0-nullsafety
pedantic ^1.8.0+1 1.9.2
time_machine ^0.9.12 0.9.12
Transitive dependencies
matcher 0.12.9
path 1.7.0
quiver 2.1.3
resource 2.1.7
stack_trace 1.9.5
typed_data 1.2.0 1.3.0-nullsafety
Dev dependencies
test ^1.14.3
test_coverage ^0.4.1