Author:: Sam Roberts <vieuxtech@gmail.com> Copyright:: Copyright (C) 2008 Sam Roberts License:: May be distributed under the same terms as Ruby Homepage:: http://vpim.rubyforge.org Download:: http://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 - http://ZipDX.com: for sponsoring development of FREQ=weekly and BYSETPOS in recurrence rules. - http://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: - 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, from http://pragprog.com/pragdave/Tech/Blog/ToDos.rdoc. - 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: - http://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": - http://rubyforge.org/mailman/listinfo/vpim-talk