gocal

README

gocal

Fast (and opinionated) ICAL parser in Golang.

Gocal takes an io.Reader and produces an array of Events from it.

Event are parsed between two given dates (Gocal.Start and Gocal.End, 3 months by default). Any event outside this range will be ignored. This behavior can be disabled by setting SkipBounds to true in the Gocal struct. Please note that the behavior will still be enacted for recurring event, to prevent infinite parsing.

Usage

package main

import (
  "github.com/apognu/gocal"
)

func main() {
  f, _ := os.Open("/tmp/mycalendar.ics")
  defer f.Close()

  start, end := time.Now(), time.Now().Add(12*30*24*time.Hour)

  c := gocal.NewParser(f)
  c.Start, c.End = &start, &end
  c.Parse()

  for _, e := range c.Events {
    fmt.Printf("%s on %s by %s", e.Summary, e.Start, e.Organizer.Cn)
  }
}

Timezones

Timezones specified in TZID attributes are parsed and expected to be parsable by Go's time.LoadLocation() method. If you have an ICS file using some other form of representing timezones, you can specify the mapping to be used with a callback function:

var tzMapping = map[string]string{
  "My Super Zone": "Asia/Tokyo",
  "My Ultra Zone": "America/Los_Angeles",
}

gocal.SetTZMapper(func(s string) (*time.Location, error) {
  if tzid, ok := tzMapping[s]; ok {
    return time.LoadLocation(tzid)
  }
  return nil, fmt.Errorf("")
})

If this callback returns an error, the usual method of parsing the timezone will be tried. If both those methods fail, the date and time will be considered UTC.

Custom X-* properties

Any property starting with X- is considered a custom property and is unmarshalled in the event.CustomAttributes map of string to string. For instance, a X-LABEL would be accessible through event.CustomAttributes["X-LABEL"].

Recurring rules

Recurring rule are automatically parsed and expanded during the period set by Gocal.Start and Gocal.End.

That being said, I try to handle the most common situations for RRULEs, as well as overrides (EXDATEs and RECURRENCE-ID overrides).

This was tested only lightly, I might not cover all the cases.

Strict mode

By default, any error in parsing an event will result in the whole feed being aborted altogether (this includes missing or invalid attributes). You can change strict mode's behavior by changing the Strict.Mode attribute of the Gocal struct, with the following behavior:

• StrictModeFailFeed - default, abort parsing of the whole feed
• StrictModeFailEvent - skip the current event
• StrictModeFailAttribute - skip parsing of the failing attribute, set the Valid attribute of the event to false

Duplicate attribute behavior

The behavior when an attribute is duplicated can be customized with the Duplicate.Mode field. The default is to follow the configured strict mode behavior, but you can relax those rule by instructing Gocal to keep either the first or last value.

• DuplicateModeFailStrict
• DuplicateModeKeepFirst
• DuplicateModeKeepLast

Limitations

I do not pretend this abides by RFC 5545, this only covers parts I needed to be parsed for my own personal use. Among other, most property parameters are not handled by the library, and, for now, only the following properties are parsed:

• UID
• SUMMARY / DESCRIPTION
• DTSTART / DTEND / DURATION (day-long, local, UTC and TZIDd)
• DTSTAMP / CREATED / LAST-MODIFIED
• LOCATION
• STATUS
• ORGANIZER (CN; DIR and value)
• ATTENDEEs (CN, DIR, PARTSTAT and value)
• ATTACH (FILENAME, ENCODING, VALUE, FMTTYPE and value)
• CATEGORIES
• GEO
• RRULE
• X-*

Also, we ignore whatever's not a VEVENT.

Documentation

Index

• Constants
• func SetTZMapper(cb func(s string) (*time.Location, error))
• type Attachment
• type Attendee
• type Context
  • func (ctx *Context) Nest(value int) *Context
• type DuplicateAttributeError
  • func NewDuplicateAttribute(k, v string) DuplicateAttributeError
  • func (err DuplicateAttributeError) Error() string
• type DuplicateParams
• type Event
• type Geo
• type Gocal
  • func NewParser(r io.Reader) *Gocal
  • func (gc *Gocal) ExpandRecurringEvent(buf *Event) []Event
  • func (gc *Gocal) IsInRange(d Event) bool
  • func (gc *Gocal) IsRecurringInstanceOverriden(instance *Event) bool
  • func (gc *Gocal) Parse() error
• type Line
  • func (l *Line) Is(key, value string) bool
  • func (l *Line) IsKey(key string) bool
  • func (l *Line) IsValue(value string) bool
• type Organizer
• type RawDate
• type StrictParams

Constants

const (
	StrictModeFailFeed = iota
	StrictModeFailAttribute
	StrictModeFailEvent
)

const (
	DuplicateModeFailStrict = iota
	DuplicateModeKeepFirst
	DuplicateModeKeepLast
)

const (
	ContextRoot = iota
	ContextEvent
	ContextUnknown
)

const YmdHis = "2006-01-02 15:04:05"

Functions

func SetTZMapper

func SetTZMapper(cb func(s string) (*time.Location, error))

Types

type Attachment

type Attachment struct {
	Encoding string
	Type     string
	Mime     string
	Filename string
	Value    string
}

type Attendee

type Attendee struct {
	Cn               string
	DirectoryDn      string
	Status           string
	Value            string
	CustomAttributes map[string]string
}

type Context

type Context struct {
	Value    int
	Previous *Context
}

func (*Context) Nest

func (ctx *Context) Nest(value int) *Context

type DuplicateAttributeError

type DuplicateAttributeError struct {
	Key, Value string
}

func NewDuplicateAttribute

func NewDuplicateAttribute(k, v string) DuplicateAttributeError

func (DuplicateAttributeError) Error

func (err DuplicateAttributeError) Error() string

type DuplicateParams

type DuplicateParams struct {
	Mode int
}

type Event

type Event struct {
	Uid              string
	Summary          string
	Description      string
	Categories       []string
	Start            *time.Time
	RawStart         RawDate
	End              *time.Time
	RawEnd           RawDate
	Duration         *time.Duration
	Stamp            *time.Time
	Created          *time.Time
	LastModified     *time.Time
	Location         string
	Geo              *Geo
	URL              string
	Status           string
	Organizer        *Organizer
	Attendees        []Attendee
	Attachments      []Attachment
	IsRecurring      bool
	RecurrenceID     string
	RecurrenceRule   map[string]string
	ExcludeDates     []time.Time
	Sequence         int
	CustomAttributes map[string]string
	Valid            bool
	Comment          string
	Class            string
	// contains filtered or unexported fields
}

type Geo

type Geo struct {
	Lat  float64
	Long float64
}

type Gocal

type Gocal struct {
	Events     []Event
	SkipBounds bool
	Strict     StrictParams
	Duplicate  DuplicateParams

	Start          *time.Time
	End            *time.Time
	Method         string
	AllDayEventsTZ *time.Location
	// contains filtered or unexported fields
}

func NewParser

func NewParser(r io.Reader) *Gocal

func (*Gocal) ExpandRecurringEvent

func (gc *Gocal) ExpandRecurringEvent(buf *Event) []Event

func (*Gocal) IsInRange

func (gc *Gocal) IsInRange(d Event) bool

func (*Gocal) IsRecurringInstanceOverriden

func (gc *Gocal) IsRecurringInstanceOverriden(instance *Event) bool

func (*Gocal) Parse

func (gc *Gocal) Parse() error

type Line

type Line struct {
	Key    string
	Params map[string]string
	Value  string
}

func (*Line) Is

func (l *Line) Is(key, value string) bool

func (*Line) IsKey

func (l *Line) IsKey(key string) bool

func (*Line) IsValue

func (l *Line) IsValue(value string) bool

type Organizer

type Organizer struct {
	Cn          string
	DirectoryDn string
	Value       string
}

type RawDate

type RawDate struct {
	Params map[string]string
	Value  string
}

type StrictParams

type StrictParams struct {
	Mode int
}