Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
183 lines (138 sloc) 5.75 KB
Author:: Sam Roberts <>
Copyright:: Copyright (C) 2008 Sam Roberts
License:: May be distributed under the same terms as Ruby
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
- for sponsoring development of FREQ=weekly and BYSETPOS in
recurrence rules.
- 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
iCalendar (RFC 2445) is a format for calendar related information, see
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, 04, 28)
e.dtend, 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 ''
e.sequence 0
e.access_class "PRIVATE"
e.transparency 'OPAQUE'
now =
e.created now
e.lastmod now
e.organizer do |o| = "Example Organizer, Mr."
o.uri = ""
attendee = Vpim::Icalendar::Address.create("") = true
e.add_attendee attendee
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
This produces:
--- Encode:
PRODID:-//Ensemble Independent//vPim 0.357//EN
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
ORGANIZER;CN="Example Organizer, Mr."
--- 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:
- link:ex_mkvcard.txt: example of creating a vCard
- link:ex_cpvcard.txt: example of copying and them modifying a vCard
- link:ex_mkv21vcard.txt: example of creating version 2.1 vCard
- link:mutt-aliases-to-vcf.txt: convert a mutt aliases file to vCards
- link:ex_get_vcard_photo.txt: pull photo data from a vCard
- link:ab-query.txt: query the OS X Address Book to find vCards
- link:vcf-to-mutt.txt: query vCards for matches, output in formats useful
with Mutt (see link:README.mutt for details)
- link:tabbed-file-to-vcf.txt: convert a tab-delimited file to vCards, a
(small but) complete application contributed by Dane G. Avilla, thanks!
- link:vcf-to-ics.txt: example of how to create calendars of birthdays from vCards
- link:vcf-dump.txt: utility for dumping contents of .vcf files
iCalendar examples are:
- link: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,
- link:cmd-itip.txt: prints emailed iCalendar invitations in human-readable
form, and see link: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.
- link:reminder.txt: prints upcoming events and todos, by default from
Apple's iCal calendars
- link:rrule.txt: utility for printing recurrence rules
- link: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":