Author

Sam Roberts <[email protected]>

Copyright

Copyright © 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:[email protected]"
  end

  attendee = Vpim::Icalendar::Address.create("mailto:[email protected]")
  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:[email protected]
ATTENDEE;RSVP=true:mailto:[email protected]
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:

• ex_mkvcard.txt: example of creating a vCard

• ex_cpvcard.txt: example of copying and them modifying a vCard

• ex_mkv21vcard.txt: example of creating version 2.1 vCard

• mutt-aliases-to-vcf.txt: convert a mutt aliases file to vCards

• ex_get_vcard_photo.txt: pull photo data from a vCard

• ab-query.txt: query the OS X Address Book to find vCards

• vcf-to-mutt.txt: query vCards for matches, output in formats useful with Mutt (see README.mutt for details)

• tabbed-file-to-vcf.txt: convert a tab-delimited file to vCards, a (small but) complete application contributed by Dane G. Avilla, thanks!

• vcf-to-ics.txt: example of how to create calendars of birthdays from vCards

• vcf-dump.txt: utility for dumping contents of .vcf files

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:

• rubyforge.org/projects/vpim

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”:

• rubyforge.org/mailman/listinfo/vpim-talk