Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 183 lines (138 sloc) 5.893 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182
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

Something went wrong with that request. Please try again.