vpim 0.597 → 0.602

data/CHANGES

@@ -0,0 +1,420 @@
+0.602 - 2008-03-12
+
+- Updated reminder utility to work with iCal 3.
+- Reworked gem to include tests, samples, and binaries.
+
+
+0.597 - 2008-03-01
+
+- Support for BYSETPOS in recurrence rules (development supported by ZipDX.com)
+
+- Support for FREQ=weekly in recurrence rules (development supported by ZipDX.com)
+
+- Fixed an encode_text() bug (patch supplied by Jan Becvar)
+
+- Fixed problem with interaction between BYMONTH and BYDAY (patch supplied by
+  Sam Stephenson of 32signals.com)
+
+- Vevent::Maker - Started adding high-level iCalendar encoding APIs
+
+- Vpim::Vcard::Maker - the vCard maker is moved here
+
+- Vpim::Maker - deprecated
+
+- Vcard::make, Maker::Vcard#delete_if - new
+
+- Vcard::Maker#add_name - deprecate, see Vcard::Maker#name
+
+- Vcard::Maker#fullname= - deprecate, see Vcard::Maker#name
+
+- Added high-level vCard decoding API.
+
+- Beginning to depend on ruby1.8. I'm willing to try for backwards compat if I
+  get feedback that this causes difficulties.
+
+- Icalendar#components - new
+
+- Icalendar#vevents - deprecated, see Icalendar#components
+
+- split Vtodo and Vjournal into own files
+
+- Added Recurrence module to Vtodo and Vjournal
+
+- Property::Common#sequence - new
+
+- Property::Common#attachments - new
+
+- Icalendar::Attachment - new
+
+- Maker::Vcard#add_url - new
+
+- ex_mkyourown.rb - new example
+
+- Modularized the component property accessor methods, and added lots of
+  Icalendar property support for Vevent, Vtodo, and Vjournal.
+
+- Fixed support for TEXT decoding.
+
+- Use Subversion revision as release sub-version.
+
+- It appears that a top-level vpim.rb that requires everything else is needed
+  for ruby-gems, gemspec seems to work now.
+
+- Don't package backup files (.../*.rb~).
+
+- Icalendar decoding optimizations. Icalendar.decode is about twice as fast
+  now, and more optimizations are scheduled.
+
+- Continue the move to using uppercase for all syntactic elements that can be
+  mixed case. The API might eventually allow only uppercase, it appears
+  case-insensitive comparisons still have a noticeable effect on performance.
+
+
+0.17 - 2006-03-08
+
+- DirectoryInfo#delete - new
+
+- Maker::Vcard#fullname - new
+
+- Provide an example of how to create, copy, and modify version 2.1 vCards.
+
+- Maker::Vcard.make2 - new
+
+- Maker::Vcard.make - deprecated
+
+- Profiled decoding of a huge iCalendar file. Performance appears to be
+  dominated by overhead of String#downcase (20% of time spent in Field#name?).
+  Keeping the field group, field name, and field's parameter's names internally
+  in uppercase and using ruby 1.8's String#casecmp? is a first attempt at
+  optimization. This is a change in the default case returned, but it aligns
+  with the RFC and common usage.
+
+- Maker::Vcard.make -  full_name is now optional, it will be derived from name/N:
+
+- Maker::Vcard#add_field -  better argument checking
+
+- Maker::Vcard#copy - new
+
+- Vcard#[] -  now limits return to fields with values
+
+- Vcard#name - new 
+
+- Vcard::Name - new 
+
+- Vcard#nicknames - new 
+
+- Field#params and Field#param - deprecated and undocumented, I could never
+  remember the difference
+
+- Field#pnames - new
+
+- Field#pvalues - new
+
+- Methods.casecmp? - new
+
+- Field#pref= - new
+
+- Field#pvalue_idel - new
+
+- Field#pvalue_iadd - new
+
+
+0.16 - 2006-02-19
+
+- Packaged in gem format, experimental.
+
+- Read vCards in UTF-8 or UTF-16, big or little endian, with or without a byte
+  order mark (BOM).
+
+- Fixed bug with rrule occurences containing the end of the interval. Reported
+  with patch by Brad Ediger.
+
+0.15 - 2005-07-29
+
+- Fixed bug with param values with quoted strings, particularly a quoted string
+  containing a : character, like
+    name;param="file:///":value
+
+  Thanks to Tamiji Homma for reporting this and sending me an example calendar.
+
+- Vtodo.create - new
+- Icalendar#push - allow Vtodos to be added
+
+  Thanks to Maximillian Dornseif for contributing the above two Vtodo patches.
+
+- Vevent.duration - bug fixes so duration can be calculated from begin/end, and
+  end can be calculated from begin/duration
+
+- Vcard#nickname that strips whitespace to see if there really is a nickname
+
+- Vcard#birthday - returns birthday as a date
+
+- Vevent#create_yearly - easy, cheesy way to create yearly recurring events
+
+- vcf-to-ics.rb: example of how to create calendars of bdays from vcards
+
+- Icalendar.create()  like Vevent.create(), it will take arrays of Fields, or
+  Hashes of String => value.
+
+- maker/vcard.rb: Added support for X-AIM, an Apple extension.
+
+0.14 - 2005-02-01
+
+- Fix: if an RRULE didn't ever yield an event (a bug in the rule) dountil was never tested.
+
+- Change: don't throw an ArgumentError with infinite events, just stop when the
+  Time is no longer representable
+
+0.13 - 2005-01-20
+
+- Was calling to_time with an arg, fixed.
+
+0.12 - 2005-01-17
+
+- Removed require of pp from the library and utilities where it wasn't needed,
+  it was causing problems because it doesn't exist on ruby 1.6 systems.
+
+- Added Field#to_date, returns field value as an array of Date objects
+  
+- Changed Field#to_time - it now auto-detects format of values
+  (DATE/DATE-TIME),  and doesn't take/require a default_kind argument.
+
+- Added IMPP support to Vpim::Maker::Vcard.
+
+- Makefile wasn't copying the Maker classes into the release.
+
+- Duration value not returned unless it was negative, fixed.
+
+- An RRULE's UNTIL was always being assumed to be a DATE-TIME, but it can be a
+  DATE. I fixed this, but is something of a hack, see comments and TODO.
+
+- Use String#scan instead of String#gsub, when appropriate (I didn't know it
+  existed when I stated the project).
+
+- Run tests on 3 ruby versions.
+
+- Don't include docs in release package, it makes it way too large.
+
+- Change: use String.unpack instead of iconv to convert UCS-2 to UTF-8,
+  removing dependency on iconv (it wasn't standard in ruby 1.6).
+
+- Change: simplified mutt_ab_query.rb, and renamed to vcf-to-mutt.
+
+- Change: reminder.rb sorts todo items by priority.
+
+- New: Vtodo#priority - the priority of the vTodo component.
+
+0.11 - 2004-11-17
+
+- Added a Vpim::Maker::Vcard class to simplify the creation of vCards, modelled
+  after the RSS maker from ruby's RSS library.
+
+0.10 - 2004-11-07
+
+- If events don't have a recurrence rule, they occur once, but they
+  were being returned even if they occurred after "dountil". Fixed.
+
+- New sample of converting tab-delimited files to a vcard file, from
+  Dane G. Avilla. Thanks!
+
+0.9a - 2004-10-31
+
+- Made sure all events occur once in rrules.
+
+- New sample of encoding: mutt-aliases-vcard.rb
+
+- Added ToDo support to reminder.rb.
+
+0.9 - 2004-06-17
+
+- Field now is mutable, you can change the group, value, params, etc.
+
+- Using the Enumerator object for DirectoryInfo now, instead of all the
+each_by_X, and field_by_X() APIs.
+
+- Moved homepage and docs to Ruby Forge.
+
+- DirectoryInfo.create: added a profile argument
+
+- DirectoryInfo#push: now pushes to 1 before the end
+
+- DirectoryInfo#push_end: pushes onto end, in case you really want to
+
+- Field.create: a Date or Time object value will now be encoded as date or time
+
+- Vpim.encode_date(): encodes an RFC2425 date
+
+- Vpim.encode_time(): encodes an RFC2425 time
+
+- Vpim.encode_date_time(): encodes an RFC2425 date-time
+
+- Icalendar#encode(): encodes an Icalendar
+
+- Icalendar#push(): pushes a calendar component onto a calendar
+
+- Vevent#accept(): accepts an event invitation
+
+- Vevent#create(): creates a new event
+
+- Address#copy(): create a copy of Address. If the original Address was frozen,
+this one won't be.
+
+- Address#partstat=(): set or change the PARTSTAT.
+
+- Field#copy(): create a copy of Field. If the original Field was frozen, this
+one won't be.
+
+0.8 - 2004-04-01
+
+- Moved DirectoryInfo::Field into it's own file, vpim/field.rb.
+
+- New: Vpim::Duration - crude way of getting days/hours/mins/secs from a
+duration in seconds.
+
+- New: Icalendar#create() and Icalendar#create_reply()
+
+- New: Icalendar#encode(), #to_s is an alias to #encode.
+
+- New: Icalendar#protocol?()
+
+- Change: Icalendar#version() raises an error if there is no VERSION
+
+- Change: made all the DirectoryInfo, Vcard, and Field .new() class methods
+private, and replaced with the 2 class methods:
+
+ - decode() decodes a string, returning a ruby object
+ - create() creates a new object
+
+and all objects now get encoded using:
+
+ - encode() takes a ruby object, and encodes it as a string
+
+They become more symetrical, and the overloaded meanings of .new() dissappear -
+with .new() are you decoding, encoding, creating...?
+
+- Change: Icalendar::Vevent#attendees() can return only attendees
+with a particular URI.
+
+- New: Icalendar::Address#==()
+
+- New: Icalendar::Vevent#attendee?()
+
+- Fixed bug: Field#encode() was adding an unexpecte NL to the line.
+
+- Change: Field#name?() can accept a symbol.
+
+- New: DirectoryInfo has an #each(), so I included Enumerable. Because of this
+#to_a() now returns all the Fields in a DirectoryInfo.
+
+- New: DirectoryInfo#push() and DirectoryInfo@push_uniq().
+
+- Change: DirectoryInfo#<<() is now an alias for  DirectoryInfo#push()
+
+- Change: DirectoryInfo#each() and DirectoryInfo#each_by() now return self
+instead of nil, I think this is more rubyish.
+
+- New: Date#to_time() - converts a Date, and maybe a DateTime, to a Time
+
+- New: Icalendar#protocol()
+
+- New: Icalendar::Address
+
+- New: Icalendar::Vevent#organizer()/attendees(), which return an
+Icalendar::Address
+
+- New: An array of all the values of fields named name, converted to text,
+using Field.to_text().
+
+
+0.7 - 2004-03-21
+
+- Bug fixes, not all files were requiring vpim.rb, which had the definition of
+the invalid encoding error.
+
+- Implemented much requested feature: ignore empty lines in input. This is an
+invalid encoding, but I'm tired of fighting it.
+
+
+0.6 - 2004-03-20
+
+WARNING: major API renamings!
+
+- Replaced the Vpim::Errors::*Error exception classes with a single exception
+class: Vpim::InvalidEncodingError. That, and a message, is all I really need.
+I don't think people need different classes for different types of encoding
+errors, either the library can decode it for them, or it can't.
+
+- Renamed project to "vpim" (to reflect vCard and vCalendar/iCalendar support),
+renamed top-level Rfc2425 module to Vpim, split vard.rb into multiple files.
+
+- Add support for iCalendar (RFC2445), see vpim/icalendar.rb. Currently only
+supports VEVENT, no VTODO or VALARM yet, but is useable to print my upcoming
+iCal events.
+
+- Implemented the iCalendar recurrence rules mini-language, which is possibly
+of more general use than just for iCalendar.
+
+- Fixed bug in time decoding where usec would be nil instead of zero when no
+usec were present in the time value.
+
+- Field#to_time now assumes that time is in local time, unless the timezone is
+"Z", meaning UTC.
+
+- Field#to_text - new method, unescapes newlines, commas, and escape
+characters.
+
+- Field#field(name) - new method, returns the first field named +name+.
+
+
+0.5 - 3003-11-23
+
+- ab-query.rb - short option for --me was mistyped as -v, instead of -m.
+
+- mutt_ab_query.rb - added a --pipe option, so that the output of an other
+script can be directly queried.
+
+- New method: Rfc2425.version
+
+- Decode vCard 2.1 abbreviated parameters (ones where the name of the parameter
+is missing, only the value is present, which only works for type and encoding).
+
+- Vcard.decode() now support UCS-2 encoded vCards, by translating anything that
+looks like UCS-2 to UTF-8 before decoding.
+
+0.4 - 2003-04-14
+
+- More support for decoding date, time, and date-time values.
+
+- New method Field#to_time().
+
+- Can pass an IO object to decode APIs, its entire contents is read as a
+string.
+
+- Field#group?() now considers nil as equivalent to no group, so you can use
+each_group(nil) to iterate through all fields without a group.
+
+0.3 -
+
+- Added description of how to use mutt_ab_query.rb
+
+- Added support for querying the kind of a value, and began support for
+decoding date and time values.
+
+0.2 -
+
+- Supports encoding.
+
+- Supports accessing values using [].
+
+- No longer have methods return an Array, or nil if the array is zero length, I
+just return an Array.
+
+- mutt_ab_query.rb - an example of using vcard.rb to do lookups in the OS X
+Address Book from Mutt
+
+0.1 -
+
+- First release.
+---
+
+vim:expandtab:tabstop=8:softtabstop=2:shiftwidth=2

data/COPYING

@@ -0,0 +1,58 @@
+vPim is copyrighted free software by Sam Roberts <sroberts@uniserve.com>.
+
+You can redistribute it and/or modify it under either the terms of the GPL (see
+the file GPL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise make them
+       Freely Available, such as by posting said modifications to Usenet or an
+       equivalent medium, or by allowing the author to include your
+       modifications in the software.
+
+       b) use the modified software only within your corporation or
+       organization.
+
+       c) give non-standard binaries non-standard names, with instructions on
+       where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software, together
+       with instructions (in the manual page or equivalent) on where to get the
+       original distribution.
+
+       b) accompany the distribution with the machine-readable source of the
+       software.
+
+       c) give non-standard binaries non-standard names, with instructions on
+       where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README

@@ -0,0 +1,175 @@
+Author::     Sam Roberts <sroberts@uniserve.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
+
+This is a pure-ruby library for decoding and encoding vCard and iCalendar data
+("personal information") called vPim.
+
+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.
+
+= Project Information
+
+The latest release can be downloaded from the Ruby Forge project page:
+
+- http://rubyforge.org/projects/vpim
+
+For notifications about new releases, or asking questions about vPim, please
+subscribe to "vpim-talk":
+
+- http://rubyforge.org/mailman/listinfo/vpim-talk
+
+= Thanks
+
+- Ruby Forge: for their generous hosting of this project.
+- ZipDX.com: for sponsoring support for FREQ=weekly and BYSETPOS in recurrence
+  rules.
+
+= 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
+module Vpim
+end
+
+= Installation
+
+There is a vPim package installable using ruby-gems.
+
+It is also installable in the standard way. Untar the package, and see:
+
+  ruby setup.rb --help
+
+or do:
+
+  $ ruby setup.rb config
+  $ ruby setup.rb setup
+  # ruby setup.rb install (may require root privilege)
+