mumboe-vpim 0.7

data/README

@@ -0,0 +1,185 @@
+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.
+
+= Mumboe
+This code has been modified by Mumboe, Inc. for purposes of Ruby 1.9 compatibility and adding some useful methods for vCard 3.0 specs
+
+= 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/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
+

data/lib/vpim/agent/atomize.rb

@@ -0,0 +1,104 @@
+=begin
+  Copyright (C) 2009 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
+
+require "atom"
+
+module Vpim
+  module Agent
+
+    module Atomize
+      MIME = "application/atom+xml"
+
+      # +ical+, an icalendar, or at least a Repo calendar's subset of an Icalendar
+      # +feeduri+, the atom xml should know the URI of where the feed is available from.
+      # +caluri+, optionally, the URI of the calendar its converted from.
+      #
+      # TODO - and the URI of an alternative/html representation of this feed?
+      def self.calendar(ical, feeduri, caluri = nil, calname = nil)
+        mime = MIME
+
+        feeduri = feeduri.to_str
+        caluri = caluri
+        calname = (calname or caluri or "Unknown").to_str
+
+        f = Atom::Feed.new
+        # Mandatory attributes:
+        # For ID, we should use http://.../ics/atom?....., or just the URL of the ics?
+        #   I think it can be a full URI... or maybe a sha-1 of our full URI?
+        # or like gmail, no id for feed,
+        #   <id>tag:gmail.google.com,2004:1295062805013769502</id>
+        #
+        f.id = feeduri
+        f.title = calname
+        f.updated = Time.now
+        f.authors << Atom::Person.new(:name => (caluri or calname))
+        f.generator = Atom::Generator.new do |g|
+          g.name = Vpim::PRODID
+          g.uri = "http://vpim.rubyforge.org"
+          g.version = Vpim::VERSION
+        end
+
+        f.links << Atom::Link.new do |l|
+          l.href = feeduri
+          l.type = mime
+          l.rel  = :self
+        end
+
+        if caluri
+          # This is maybe better described as :via, but with :alternate being
+          # an html view of this feed.
+          #
+          # TODO should I change the scheme to be webcal?
+          # TODO should I extend URI to support webcal?
+          f.links << Atom::Link.new do |l|
+            l.href = caluri
+            l.type = "text/calendar"
+            l.rel  = :alternate
+          end
+        end
+
+        # .icon = uri to the vAgent icon
+        entry_id = 0
+        ical.events do |ve|
+          # TODO - infinite?
+          ve.occurrences do |t|
+            f.entries << Atom::Entry.new do |e|
+              # iCalendar -> atom
+              # -----------------
+              # summary -> title
+              # description -> text/content
+              # uid -> id
+              # created -> published?
+              # organizer -> author?
+              # contact -> author?
+              # last-mod -> semantically, this is updated, but atom doesn't
+              #   have the notion that an entry has a relationship to a time,
+              #   other than the time the entry itself was published, and when
+              #   the entry gets updated. We'll abuse updated for the event's time.
+              # categories -> where do "tags" go in atom, if anywhere?
+              # attachment -> into a link?
+              e.title = ve.summary if ve.summary
+              e.content = Atom::Content::Text.new(ve.description) if ve.description
+              e.updated = t
+
+              # Use "tag:", as defined by RFC4151, and use event UID if possible. Otherwise,
+              # construct something. Maybe I should mix something in to make it unique for
+              # each time a feed is generated for the calendar?
+              entry_id += 1
+              tag = ve.uid || "#{entry_id}@#{feeduri}"
+              e.id = "tag:vpim.rubyforge.org,2009:#{tag}"
+            end
+          end
+        end
+        return f
+      end
+    end # Atomize
+
+  end # Agent
+end # Vpim
+

data/lib/vpim/agent/base.rb

@@ -0,0 +1,73 @@
+=begin
+  Copyright (C) 2009 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
+
+require 'cgi'
+
+require 'sinatra/base'
+
+# TODO Pasting of webcal links, conversion to webcal links?
+
+module Vpim
+  module Agent
+
+    class Base < Sinatra::Base
+      # Ensure that this happens...
+      set :haml, :format=>:html4 # Appears to do nothing, but maybe it will some day...
+
+      def css(template)
+        render :css, template, {}
+      end
+
+      def render_css(template, data, options) # :nodoc:
+        data
+      end
+
+      # Complete path, as requested by the client. Take care about CGI path rewriting.
+      def request_path
+        # Using .to_s because rack/request.rb does, though I think the Rack
+        # spec requires these to be strings already.
+        begin
+          URI.parse(env["SCRIPT_URI"].to_s).path
+        rescue
+          env["SCRIPT_NAME"].to_s + env["PATH_INFO"].to_s
+        end
+      end
+
+      # Complete path, as requested by the client, without the env's PATH_INFO.
+      # This is the path to whatever is "handling" the request.
+      #
+      # Recent discussions on how PATH_INFO must be decoded leads me to think
+      # this might not work if the path had any URL encoded characters in it.
+      def script_path
+        request_path.sub(/#{env["PATH_INFO"]}$/, "")
+      end
+
+      # URL-ready form of the host and port, where the port isn't specified if
+      # it is the default for the URL scheme.
+      def host_port
+        r = request
+        host_port = r.host
+
+        if r.scheme == "https" && r.port != 443 ||
+          r.scheme == "http" && r.port != 80
+          host_port << ":#{r.port}"
+        end
+
+        host_port
+      end
+
+      # URL to the script
+      def script_url
+        request.scheme + "://" + host_port + script_path
+      end
+
+    end # Base
+
+  end # Agent
+end # Vpim
+