fairtilizer-vpim 0.695

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,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
+

data/lib/vpim.rb

@@ -0,0 +1,13 @@
+=begin
+  Copyright (C) 2008 Sam Roberts
+
+  This library is free software; you can redistribute it and/or modify it
+  under the same terms as the ruby language itself, see the file COPYING for
+  details.
+=end
+
+# the existence of this file is a hack to support users or rubygems
+
+require 'vpim/icalendar'
+require 'vpim/vcard'
+

data/lib/vpim/address.rb

@@ -0,0 +1,219 @@
+=begin
+  Copyright (C) 2008 Sam Roberts
+
+  This library is free software; you can redistribute it and/or modify it
+  under the same terms as the ruby language itself, see the file COPYING for
+  details.
+=end
+
+=begin
+
+Notes on a CAL-ADDRESS
+
+When used with ATTENDEE, the parameters are:
+  CN
+  CUTYPE
+  DELEGATED-FROM
+  DELEGATED-TO
+  DIR
+  LANGUAGE
+  MEMBER
+  PARTSTAT
+  ROLE
+  RSVP
+  SENT-BY
+
+When used with ORGANIZER, the parameters are:
+  CN
+  DIR
+  LANGUAGE
+  SENT-BY
+
+
+What I've seen in Notes invitations, and iCal responses:
+  ROLE
+  PARTSTAT
+  RSVP
+  CN
+
+Support these last 4, for now.
+
+=end
+
+module Vpim
+  class Icalendar
+    # Used to represent calendar fields containing CAL-ADDRESS values.
+    # The organizer or the attendees of a calendar event are examples of such
+    # a field.
+    #
+    # Example:
+    #
+    #   ORGANIZER;CN="A. Person":mailto:a_person@example.com
+    #
+    #   ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION
+    #    ;CN="Sam Roberts";RSVP=TRUE:mailto:SRoberts@example.com
+    #
+    class Address
+
+      # Create a copy of Address. If the original Address was frozen, this one
+      # won't be.
+      def copy
+        #Marshal.load(Marshal.dump(self))
+        self.dup.dirty
+      end
+
+      def dirty #:nodoc:
+        @field = nil
+        self
+      end
+
+      # Addresses in a CAL-ADDRESS are represented as a URI, usually a mailto URI.
+      attr_accessor :uri
+      # The common or displayable name associated with the calendar address, or
+      # nil if there is none.
+      attr_accessor :cn
+      # The participation role for the calendar user specified by the address.
+      #
+      # The standard roles are:
+      # - CHAIR Indicates chair of the calendar entity
+      # - REQ-PARTICIPANT Indicates a participant whose participation is required
+      # - OPT-PARTICIPANT Indicates a participant whose participation is optional
+      # - NON-PARTICIPANT Indicates a participant who is copied for information purposes only
+      #
+      # The default role is REQ-PARTICIPANT, returned if no ROLE parameter was
+      # specified.
+      attr_accessor :role
+      # The participation status for the calendar user specified by the
+      # property PARTSTAT, a String.
+      #
+      # These are the participation statuses for an Event:
+      # - NEEDS-ACTION Event needs action
+      # - ACCEPTED Event accepted
+      # - DECLINED Event declined
+      # - TENTATIVE Event tentatively accepted
+      # - DELEGATED Event delegated
+      #
+      # Default is NEEDS-ACTION.
+      #
+      # FIXME - make the default depend on the component type.
+      attr_accessor :partstat
+      # The value of the RSVP field, either +true+ or +false+. It is used to
+      # specify whether there is an expectation of a reply from the calendar
+      # user specified by the property value.
+      attr_accessor :rsvp
+
+      def initialize(field=nil) #:nodoc:
+        @field = field
+        @uri = ''
+        @cn = ''
+        @role = "REQ-PARTICIPANT"
+        @partstat = "NEEDS-ACTION"
+        @rsvp = false
+      end
+
+      # Create a new Address. It will encode as a +name+ property.
+      def self.create(uri='')
+        adr = new
+        adr.uri = uri.to_str
+        adr
+      end
+
+      def self.decode(field)
+        adr = new(field)
+        adr.uri = field.value
+
+        cn = field.param('CN')
+
+        if cn
+          adr.cn = cn.first
+        end
+
+        role = field.param('ROLE')
+
+        if role
+          adr.role = role.first.strip.upcase
+        end
+
+        partstat = field.param('PARTSTAT')
+
+        if partstat
+          adr.partstat = partstat.first.strip.upcase
+        end
+        
+        rsvp = field.param('RSVP')
+
+        if rsvp
+          adr.rsvp = case rsvp.first
+                     when /TRUE/i then true
+                     when /FALSE/i then false
+                     else raise InvalidEncodingError, "RSVP param value not TRUE/FALSE: #{rsvp}"
+                     end
+        end
+
+        adr.freeze
+      end
+
+      # Return a representation of this Address as a DirectoryInfo::Field.
+      def encode(name) #:nodoc:
+        if @field
+          # FIXME - set the field name, it could be different from cached
+          return @field
+        end
+
+        value = uri.to_str.strip
+
+        if value.empty?
+          raise Uencodeable, "Address#uri is zero-length"
+        end
+
+        params = {}
+
+        if cn.length > 0
+          params['CN'] = Vpim::encode_paramvalue(cn)
+        end
+
+        # FIXME - default value is different for non-vEvent
+        if role.length > 0 && role != 'REQ-PARTICIPANT'
+          params['ROLE'] = Vpim::encode_paramtext(role)
+        end
+
+        # FIXME - default value is different for non-vEvent
+        if partstat.length > 0 && partstat != 'NEEDS-ACTION'
+          params['PARTSTAT'] = Vpim::encode_paramtext(partstat)
+        end
+
+        if rsvp
+          params['RSVP'] = 'true'
+        end
+
+        Vpim::DirectoryInfo::Field.create(name, value, params)
+      end
+
+      # Return true if the +uri+ is == to this address' URI. The comparison
+      # is case-insensitive (because email addresses and domain names are).
+      def ==(uri)
+        # TODO - could I use a URI library?
+        Vpim::Methods.casecmp?(self.uri.to_str, uri.to_str)
+      end
+
+      # A string representation of an address, using the common name, and the
+      # URI. The URI protocol is stripped if it's "mailto:".
+      def to_s
+        u = uri
+        u = u.gsub(/^mailto: */i, '')
+
+        if cn.length > 0
+          "#{cn.inspect} <#{uri}>"
+        else
+          uri
+        end
+      end
+
+      def inspect #:nodoc:
+        "#<Vpim::Icalendar::Address:cn=#{cn.inspect} status=#{partstat} rsvp=#{rsvp} #{uri.inspect}>"
+      end
+
+    end
+  end
+end
+