README

Path: README
Last Update: Mon Apr 14 21:23:04 -0700 2008
Author:Sam Roberts <vieuxtech@gmail.com>
Copyright:Copyright (C) 2008 Sam Roberts
License:May be distributed under the same terms as Ruby
Homepage:vpim.rubyforge.org
Download:rubyforge.org/projects/vpim
Install:sudo gem install vpim

vPim provides calendaring, scheduling, and contact support for Ruby through the standard iCalendar and vCard data formats for "personal information" exchange.

Thanks

  • ZipDX.com: for sponsoring development of FREQ=weekly and BYSETPOS in recurrence rules.
  • RubyForge.org: for their generous hosting of this project.

Installation

There is a vPim package installable using ruby-gems:

  # sudo gem install vpim (may require root privilege)

It is also installable in the standard way. Untar the package, and do:

  $ ruby setup.rb --help

or do:

  $ ruby setup.rb config
  $ ruby setup.rb setup
  # ruby setup.rb install (may require root privilege)

Overview

vCard (RFC 2426) is a format for personal information, see Vpim::Vcard and Vpim::Maker::Vcard.

iCalendar (RFC 2445) is a format for calendar related information, see Vpim::Icalendar.

vCard and iCalendar support is built on top of an implementation of the MIME Content-Type for Directory Information (RFC 2425). The basic RFC 2425 format is implemented by Vpim::DirectoryInfo and Vpim::DirectoryInfo::Field.

The libary is quite useful, but improvements are ongoing. If you find something missing or have suggestions, please contact me. I can‘t promise instantaneous turnaround, but I might be able to suggest another approach, and features requested by users of vPim go to the top of the todo list. If you need a feature for a commercial project, consider sponsoring development.

Examples

Here‘s an example to give a sense for how iCalendars are encoded and decoded:

  require 'vpim/icalendar'

  cal = Vpim::Icalendar.create2

  cal.add_event do |e|
    e.dtstart       Date.new(2005, 04, 28)
    e.dtend         Date.new(2005, 04, 29)
    e.summary       "Monthly meet-the-CEO day"
    e.description <<'---'
  Unlike last one, this meeting will change your life because
  we are going to discuss your likely demotion if your work isn't
  done soon.
  ---
    e.categories    [ 'APPOINTMENT' ]
    e.categories do |c| c.push 'EDUCATION' end
    e.url           'http://www.example.com'
    e.sequence      0
    e.access_class  "PRIVATE"
    e.transparency  'OPAQUE'

    now = Time.now
    e.created       now
    e.lastmod       now

    e.organizer do |o|
      o.cn = "Example Organizer, Mr."
      o.uri = "mailto:organizer@example.com"
    end

    attendee = Vpim::Icalendar::Address.create("mailto:attendee@example.com")
    attendee.rsvp = true
    e.add_attendee attendee
  end

  icsfile = cal.encode

  puts '--- Encode:'

  puts icsfile

  puts '--- Decode:'

  cal = Vpim::Icalendar.decode(icsfile).first

  cal.components do |e|
    puts e.summary
    puts e.description
    puts e.dtstart.to_s
    puts e.dtend.to_s
  end

This produces:

  --- Encode:
  BEGIN:VCALENDAR
  VERSION:2.0
  PRODID:-//Ensemble Independent//vPim 0.357//EN
  CALSCALE:Gregorian
  BEGIN:VEVENT
  DTSTART;VALUE=DATE:20050428
  DTEND;VALUE=DATE:20050429
  SUMMARY:Monthly meet-the-CEO day
  DESCRIPTION:Unlike last one, this meeting will change your life because\nwe
    are going to discuss your likely demotion if your work isn't\ndone soon.\n
  CATEGORIES:APPOINTMENT,EDUCATION
  URL:http://www.example.com
  SEQUENCE:0
  CLASS:PRIVATE
  CREATED:20060402T231755
  LAST-MODIFIED:20060402T231755
  ORGANIZER;CN="Example Organizer, Mr.":mailto:organizer@example.com
  ATTENDEE;RSVP=true:mailto:attendee@example.com
  END:VEVENT
  END:VCALENDAR
  --- Decode:
  Monthly meet-the-CEO day
  Unlike last one, this meeting will change your life because
  we are going to discuss your likely demotion if your work isn't
  done soon.
  Thu Apr 28 00:00:00 UTC 2005
  Fri Apr 29 00:00:00 UTC 2005

More examples of using vPim are provided in samples/.

vCard examples are:

iCalendar examples are:

  • ics-to-rss.txt: prints todos as RSS, or starts a WEBrick servlet that publishes todos as a RSS feed. Thanks to Dave Thomas for this idea, from pragprog.com/pragdave/Tech/Blog/ToDos.rdoc.
  • cmd-itip.txt: prints emailed iCalendar invitations in human-readable form, and see README.mutt for instruction on mutt integration. I get a lot of meeting invitations from Lotus Notes/Domino users at work, and this is pretty useful in figuring out where and when I am supposed to be.
  • reminder.txt: prints upcoming events and todos, by default from Apple‘s iCal calendars
  • rrule.txt: utility for printing recurrence rules
  • ics-dump.txt: utility for dumping contents of .ics files

Project Information

vPim can be downloaded from the Ruby Forge project page:

or installed as a gem:

  • sudo gem install vpim

For notifications about new releases, or to ask questions about vPim, please subscribe to "vpim-talk":

[Validate]