ical

package
v0.7.14-dev.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package ical reads an iCalendar (RFC 5545) feed, the ICS document a calendar service publishes at a subscription address, and expands its events into the occurrences that fall in a window: recurrences (RRULE, RDATE, EXDATE), the instances a feed overrides (RECURRENCE-ID), all-day events and the time zones events are written in.

It reads; it never writes a calendar. It is part of the runner image's embedded build context, so it is stdlib-only.

Index

Constants

View Source
const (
	// MaxLineBytes is the longest unfolded content line read.
	MaxLineBytes = 256 << 10
	// MaxEvents is the most VEVENTs one feed may hold.
	MaxEvents = 50000
)

Limits on what one feed may hold, so a hostile or broken feed cannot make the reader work without end.

View Source
const MaxWork = 1_000_000

MaxWork bounds what one expansion of a feed may do, counted in periods walked and candidate instances made across all its series, so a feed whose rules are hostile or enormous costs a bounded time and memory; what is past it is left out, with a note.

Variables

View Source
var ErrNotCalendar = errors.New("not an iCalendar feed: no BEGIN:VCALENDAR")

ErrNotCalendar is returned for a document that is not an iCalendar object: no BEGIN:VCALENDAR.

Functions

This section is empty.

Types

type Calendar

type Calendar struct {
	// Name is X-WR-CALNAME, when the feed gives one.
	Name string
	// TimeZone is X-WR-TIMEZONE, when the feed gives one: the zone its
	// floating times are meant in.
	TimeZone string
	// Events are the feed's VEVENTs: the series' masters and the
	// instances they override, in feed order.
	Events []Event
	// contains filtered or unexported fields
}

Calendar is one parsed feed.

func Parse

func Parse(r io.Reader, maxBytes int64) (*Calendar, error)

Parse reads an iCalendar document. It reads at most maxBytes (zero means unbounded; the caller bounds the fetch itself as well).

func (*Calendar) BusyOnly

func (c *Calendar) BusyOnly() bool

BusyOnly says the feed was published as free/busy only: VFREEBUSY blocks, or events none of which has a title of its own, a location or a description.

func (*Calendar) Expand

func (c *Calendar) Expand(from, to time.Time, loc *time.Location) Expansion

Expand returns every occurrence that overlaps [from, to), sorted by start. All-day events and floating times are read in loc, unless the feed names its own zone for floating times.

type Event

type Event struct {
	UID         string
	Summary     string
	Location    string
	Description string
	URL         string
	Organizer   string
	// Status is TENTATIVE, CONFIRMED or CANCELLED (upper case), or empty.
	Status string
	// Transparent is TRANSP:TRANSPARENT: the event does not block time.
	Transparent bool

	Start    dateTime
	End      *dateTime
	Duration time.Duration

	RRule   string
	RDates  []dateTime
	ExDates []dateTime
	// RecurrenceID, when set, makes this event an override of the
	// instance of UID's series that would have started then.
	RecurrenceID *dateTime
	// contains filtered or unexported fields
}

Event is one VEVENT.

type Expansion

type Expansion struct {
	Occurrences []Occurrence
	// Notes say what could not be read exactly: a time zone held at a
	// fixed offset or not recognised, a rule that could not be followed.
	Notes []string
}

Expansion is what Expand found.

type Occurrence

type Occurrence struct {
	UID         string
	Summary     string
	Location    string
	Description string
	URL         string
	Organizer   string
	// Status is TENTATIVE or CONFIRMED, or empty; a cancelled instance is
	// never an occurrence.
	Status string
	Start  time.Time
	End    time.Time
	// AllDay is an event of whole days: Start is midnight of its first
	// day and End midnight after its last, in the zone it was read in.
	AllDay bool
	// Busy says the instance blocks time: it is not TRANSP:TRANSPARENT.
	Busy bool
	// Recurring says the instance is one of a series.
	Recurring bool
}

Occurrence is one instance of an event that falls in a window.

type Slot

type Slot struct{ Start, End time.Time }

Slot is a span of time.

func FreeSlots

func FreeSlots(occs []Occurrence, windows []Slot, min time.Duration) []Slot

FreeSlots are the spans within windows, each at least min long, that no busy occurrence covers.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL