mumboe-vpim 0.7

data/lib/vpim/version.rb

@@ -0,0 +1,18 @@
+=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
+
+module Vpim
+  PRODID = '-//Octet Cloud//vPim 9.3.15//EN'
+
+  VERSION = '9.3.15'
+
+  # Return the API version as a string.
+  def Vpim.version
+    VERSION
+  end
+end

data/lib/vpim/vevent.rb

@@ -0,0 +1,187 @@
+=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
+
+require 'vpim/dirinfo'
+require 'vpim/field'
+require 'vpim/rfc2425'
+require 'vpim/rrule'
+require 'vpim/vpim'
+require 'vpim/property/base'
+require 'vpim/property/common'
+require 'vpim/property/priority'
+require 'vpim/property/location'
+require 'vpim/property/resources'
+require 'vpim/property/recurrence'
+
+module Vpim
+  class Icalendar
+    class Vevent
+
+      include Vpim::Icalendar::Property::Base
+      include Vpim::Icalendar::Property::Common
+      include Vpim::Icalendar::Property::Priority
+      include Vpim::Icalendar::Property::Location
+      include Vpim::Icalendar::Property::Resources
+      include Vpim::Icalendar::Property::Recurrence
+
+      def initialize(fields) #:nodoc:
+        outer, inner = Vpim.outer_inner(fields)
+
+        @properties = Vpim::DirectoryInfo.create(outer)
+
+        @elements = inner
+
+        # See "TODO - fields" in dirinfo.rb
+      end
+
+      # TODO - derive everything from Icalendar::Component to get rid of this kind of stuff?
+      def fields #:nodoc:
+        f = @properties.to_a
+        last = f.pop
+        f.push @elements
+        f.push last
+      end
+
+      def properties #:nodoc:
+        @properties
+      end
+
+      # Create a new Vevent object. All events must have a DTSTART field,
+      # specify it as either a Time or a Date in +start+, it defaults to "now"
+      #
+      # If specified, +fields+ must be either an array of Field objects to
+      # add, or a Hash of String names to values that will be used to build
+      # Field objects. The latter is a convenient short-cut allowing the Field
+      # objects to be created for you when called like:
+      #
+      #   Vevent.create(Date.today, 'SUMMARY' => "today's event")
+      #
+      def Vevent.create(start = Time.now, fields=[])
+        # TODO
+        # - maybe events are usually created in a particular way? With a
+        # start/duration or a start/end? Maybe I can make it easier. Ideally, I
+        # would like to make it hard to encode an invalid Event.
+        # - I don't think its useful to have a default dtstart for events
+        # - also, I don't think dstart is mandatory
+        dtstart = DirectoryInfo::Field.create('DTSTART', start)
+        di = DirectoryInfo.create([ dtstart ], 'VEVENT')
+
+        Vpim::DirectoryInfo::Field.create_array(fields).each { |f| di.push_unique f }
+
+        new(di.to_a)
+      end
+
+      # Creates a yearly repeating event, such as for a birthday.
+      def Vevent.create_yearly(date, summary)
+        create(
+          date,
+          'SUMMARY' => summary.to_str,
+          'RRULE' => 'FREQ=YEARLY'
+          )
+      end
+
+      # Accept an event invitation. The +invitee+ is the Address that wishes
+      # to accept the event invitation as confirmed.
+      #
+      # The event created is identical to this one, but
+      # - without the attendees
+      # - with the invitee added with a PARTSTAT of ACCEPTED
+      def accept(invitee)
+        # FIXME - move to Vpim::Itip.
+        invitee = invitee.copy
+        invitee.partstat = 'ACCEPTED'
+
+        fields = []
+
+        @properties.each_with_index do
+          |f,i|
+
+          # put invitee in as field[1]
+          fields << invitee.encode('ATTENDEE') if i == 1
+          
+          fields << f unless f.name? 'ATTENDEE'
+        end
+
+        Vevent.new(fields)
+      end
+
+      # In iTIP, whether this event is OPAQUE or TRANSPARENT to scheduling. If
+      # transparency is not explicitly set, it defaults to OPAQUE.
+      def transparency
+        proptoken 'TRANSP', ["OPAQUE", "TRANSPARENT"], "OPAQUE"
+      end
+
+      # The duration in seconds of an Event, or nil if unspecified. If the
+      # DURATION field is not present, but the DTEND field is, the duration is
+      # calculated from DTSTART and DTEND.  Durations of zero seconds are
+      # possible.
+      def duration
+        propduration 'DTEND'
+      end
+
+      # The end time for this Event. If the DTEND field is not present, but the
+      # DURATION field is, the end will be calculated from DTSTART and
+      # DURATION.
+      def dtend
+        propend 'DTEND'
+      end
+
+      # Make a new Vevent, or make changes to an existing Vevent.
+      class Maker
+        include Vpim::Icalendar::Set::Util #:nodoc:
+        include Vpim::Icalendar::Set::Common
+
+        # The event that changes are being made to.
+        attr_reader :event
+
+        def initialize(event) #:nodoc:
+          @event = event
+          @comp = event
+        end
+
+        # Make changes to +event+. If +event+ is not specified, creates a new
+        # event. Yields a Vevent::Maker, and returns +event+.
+        def self.make(event = Vpim::Icalendar::Vevent.create) #:yield:maker
+          m = self.new(event)
+          yield m
+          m.event
+        end
+
+        # Set transparency to "OPAQUE" or "TRANSPARENT", see Vpim::Vevent#transparency.
+        def transparency(token)
+          set_token 'TRANSP', ["OPAQUE", "TRANSPARENT"], "OPAQUE", token
+        end
+
+        # Set end for events with fixed durations. +end+ can be a Date or Time
+        def dtend(dtend)
+          set_date_or_datetime 'DTEND', 'DATE-TIME', dtend
+        end
+
+        # Add a RRULE to this event. The rule can be provided as a pre-build
+        # RRULE value, or the RRULE maker can be used.
+        def add_rrule(rule = nil, &block) #:yield: Rrule::Maker
+          # TODO - should be in Property::Reccurrence::Set
+          unless rule
+            rule = Rrule::Maker.new(&block).encode
+          end
+          @comp.properties.push(Vpim::DirectoryInfo::Field.create("RRULE", rule))
+          self
+        end
+
+        # Set the RRULE for this event. See #add_rrule
+        def set_rrule(rule = nil, &block) #:yield: Rrule::Maker
+          rm_all("RRULE")
+          add_rrule(rule, &block)
+        end
+
+      end
+
+    end
+  end
+end
+

data/lib/vpim/view.rb

@@ -0,0 +1,90 @@
+=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
+
+require "enumerator"
+
+module Vpim
+  module View
+    
+    SECSPERDAY = 24 * 60 * 60
+
+    # View only events occuring in the next week.
+    module Week
+      def each(klass = nil) #:nodoc:
+        unless block_given?
+          return Enumerable::Enumerator.new(self, :each, klass)
+        end
+
+        t0 = Time.new.to_a
+        t0[0] = t0[1] = t0[2] = 0 # sec,min,hour = 0
+        t0 = Time.local(*t0)
+        t1 = t0 + 7 * SECSPERDAY
+
+        # Need to filter occurrences, too. Create modules for this on the fly.
+        occurrences = Module.new
+        # I'm passing state into the module's instance methods by doing string
+        # evaluation... which sucks, but I don't think I can get this closure in
+        # there.
+        occurrences.module_eval(<<"__", __FILE__, __LINE__+1)
+          def occurrences(dountil=nil)
+            unless block_given?
+              return Enumerable::Enumerator.new(self, :occurrences, dountil)
+            end
+            super(dountil) do |t|
+              t0 = Time.at(#{t0.to_i})
+              t1 = Time.at(#{t1.to_i})
+              break if t >= t1
+              tend = t
+              if respond_to? :duration
+                tend += duration || 0
+              end
+              if tend >= t0
+                yield t
+              end
+            end
+          end
+__
+=begin
+        block = lambda do |dountil| 
+            unless block_given?
+              return Enumerable::Enumerator.new(self, :occurrences, dountil)
+            end
+            super(dountil) do |t|
+              break if t >= t1
+              yield t
+            end
+        end
+        occurrences.send(:define_method, :occurrences, block)
+=end
+        super do |ve|
+          if ve.occurs_in?(t0, t1)
+            if ve.respond_to? :occurrences
+              ve.extend occurrences
+            end
+            yield ve
+          end
+        end
+      end
+    end
+
+    # Return a calendar view for the next week.
+    def self.week(cal)
+      cal.clone.extend Week.dup
+    end
+
+    module Todo
+    end
+
+    # Return a calendar view of only todos (optionally, include todos that
+    # are done).
+    def self.todos(cal, withdone=false)
+    end
+
+  end
+end
+

data/lib/vpim/vjournal.rb

@@ -0,0 +1,58 @@
+=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
+
+require 'vpim/dirinfo'
+require 'vpim/field'
+require 'vpim/rfc2425'
+require 'vpim/vpim'
+require 'vpim/property/base'
+require 'vpim/property/common'
+require 'vpim/property/recurrence'
+
+module Vpim
+  class Icalendar
+
+    class Vjournal
+      include Vpim::Icalendar::Property::Base
+      include Vpim::Icalendar::Property::Common
+      include Vpim::Icalendar::Property::Recurrence
+
+      def initialize(fields) #:nodoc:
+        outer, inner = Vpim.outer_inner(fields)
+
+        @properties = Vpim::DirectoryInfo.create(outer)
+
+        @elements = inner
+      end
+
+      # TODO - derive everything from Icalendar::Component to get rid of this kind of stuff?
+      def fields #:nodoc:
+        f = properties.to_a
+        last = f.pop
+        f.push @elements
+        f.push last
+      end
+
+      def properties #:nodoc:
+        @properties
+      end
+
+      # Create a Vjournal component.
+      def self.create(fields=[])
+        di = DirectoryInfo.create([], 'VJOURNAL')
+
+        Vpim::DirectoryInfo::Field.create_array(fields).each { |f| di.push_unique f }
+
+        new(di.to_a)
+      end
+
+    end
+
+  end
+end
+

data/lib/vpim/vpim.rb

@@ -0,0 +1,65 @@
+=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
+
+require 'vpim/version'
+
+#:main:README
+#:title:vPim - vCard and iCalendar support for Ruby
+module Vpim
+  # Exception used to indicate that data being decoded is invalid, the message
+  # should describe what is invalid.
+  class InvalidEncodingError < StandardError; end
+
+  # Exception used to indicate that data being decoded is unsupported, the message
+  # should describe what is unsupported.
+  #
+  # If its unsupported, its likely because I didn't anticipate it being useful
+  # to support this, and it likely it could be supported on request.
+  class UnsupportedError < StandardError; end
+  
+  # Exception used to indicate that encoding failed, probably because the
+  # object would not result in validly encoded data. The message should
+  # describe what is unsupported.
+  class Unencodeable < StandardError; end
+end
+
+module Vpim::Methods #:nodoc:
+  module_function
+
+  # Case-insensitive comparison of +str0+ to +str1+, returns true or false.
+  # Either argument can be nil, where nil compares not equal to anything other
+  # than nil.
+  #
+  # This is available both as a module function:
+  #   Vpim::Methods.casecmp?("yes", "YES")
+  # and an instance method:
+  #   include Vpim::Methods
+  #   casecmp?("yes", "YES")
+  #
+  # Will work with ruby1.6 and ruby 1.8.
+  #
+  # TODO - could make this be more efficient, but I'm supporting 1.6, not
+  # optimizing for it.
+  def casecmp?(str0, str1)
+    if str0 == nil
+      if str1 == nil
+        return true
+      else
+        return false
+      end
+    end
+
+    begin
+      str0.casecmp(str1) == 0
+    rescue NoMethodError
+      str0.downcase == str1.downcase
+    end
+  end
+
+end
+

data/lib/vpim/vtodo.rb

@@ -0,0 +1,103 @@
+=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
+
+require 'vpim/dirinfo'
+require 'vpim/field'
+require 'vpim/rfc2425'
+require 'vpim/vpim'
+require 'vpim/property/base'
+require 'vpim/property/common'
+require 'vpim/property/priority'
+require 'vpim/property/location'
+require 'vpim/property/resources'
+require 'vpim/property/recurrence'
+
+module Vpim
+  class Icalendar
+
+    class Vtodo
+      include Vpim::Icalendar::Property::Base
+      include Vpim::Icalendar::Property::Common
+      include Vpim::Icalendar::Property::Priority
+      include Vpim::Icalendar::Property::Location
+      include Vpim::Icalendar::Property::Resources
+      include Vpim::Icalendar::Property::Recurrence
+
+      def initialize(fields) #:nodoc:
+        outer, inner = Vpim.outer_inner(fields)
+
+        @properties = Vpim::DirectoryInfo.create(outer)
+
+        @elements = inner
+      end
+
+      # TODO - derive everything from Icalendar::Component to get this kind of stuff?
+      def fields #:nodoc:
+        f = @properties.to_a
+        last = f.pop
+        f.push @elements
+        f.push last
+      end
+
+      def properties #:nodoc:
+        @properties
+      end
+
+      # Create a new Vtodo object.
+      #
+      # If specified, +fields+ must be either an array of Field objects to
+      # add, or a Hash of String names to values that will be used to build
+      # Field objects. The latter is a convenient short-cut allowing the Field
+      # objects to be created for you when called like:
+      #
+      #   Vtodo.create('SUMMARY' => "buy mangos")
+      #
+      # TODO - maybe todos are usually created in a particular way? I can
+      # make it easier. Ideally, I would like to make it hard to encode an invalid
+      # Event.
+      def Vtodo.create(fields=[])
+        di = DirectoryInfo.create([], 'VTODO')
+
+        Vpim::DirectoryInfo::Field.create_array(fields).each { |f| di.push_unique f }
+
+        new(di.to_a)
+      end
+
+      # The duration in seconds of a Todo, or nil if unspecified. If the
+      # DURATION field is not present, but the DUE field is, the duration is
+      # calculated from DTSTART and DUE. Durations of zero seconds are
+      # possible.
+      def duration
+        propduration 'DUE'
+      end
+
+      # The time at which this Todo is due to be completed. If the DUE field is not present,
+      # but the DURATION field is, due will be calculated from DTSTART and DURATION.
+      def due
+        propend 'DUE'
+      end
+
+      # The date and time that a to-do was actually completed, a Time.
+      def completed
+        proptime 'COMPLETED'
+      end
+
+      # The percentage completetion of the to-do, between 0 and 100. 0 means it hasn't
+      # started, 100 that it has been completed.
+      #
+      # TODO - the handling of this property isn't tied to either COMPLETED: or
+      # STATUS:, but perhaps it should be?
+      def percent_complete
+        propinteger 'PERCENT-COMPLETE'
+      end
+
+    end
+
+  end
+end
+

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/samples/README.mutt

@@ -0,0 +1,93 @@
+
+** cmd-itip.rb
+
+This script pretty-prints iTIP calendar invitations, often sent by email using iMIP
+as text/calendar objects.
+
+Download the latest vPim from:
+
+  http://rubyforge.org/projects/vpim/
+
+It requires Ruby to be installed.
+
+Install vpim:
+
+  tar -xzf vpim-XX.tgz
+  cd vpim-XX
+  ruby install.rb config
+  ruby install.rb setup
+  sudo ruby install.rb install
+
+Install cmd-itip.rb into your path, perhaps without the extension.
+
+  cp samples/cmd-itip.rb ~/bin/cmd-itip
+  chmod +x ~/bin/cmd-itip
+
+Modify your ~/.mailcap or /etc/mailcap files to call cmd-itip, add a line like:
+
+  text/calendar; cmd-itip --myaddr "sroberts@" %s; copiousoutput
+
+If you give a REGEX to --myaddr to tell cmd-itip your email addresses, cmd-itip
+will avoid printing some information on the attendees to an invitation.
+
+Modify muttrc to autoview calendars with a command like:
+
+  auto_view text/calendar
+
+Notes on Notes;
+
+Because Domino sends a close-to-unreadable text/plain attachment along with the
+text/calendar in a multipart/alternative, and the text/plain is first in the
+alternatives, the garbage will be at the top, and the nicely printed calendar
+at the bottom. Because of this, I reorder the view preference so the calendar
+invitation is clearly printed at the top of the message with a muttrc command
+like:
+
+ alternative_order text/calendar text/plain
+
+Domino also includes the calendar twice in the mail message, so you'll see it
+twice, I don't know what to do about that.
+
+Notes on application/octet-stream:
+
+Some calendar programs, such as Apple's Mail.app, wrongly send iCalendar attachments
+with a content-type of application/octet-stream. In order to be processed correctly, use
+the mutt 1.5 or later capability to lookup the correct MIME content-type based on the
+file extension. Put this in your muttrc file:
+
+ mime_lookup application/octet-stream
+
+and ensure /etc/mime.types or ~/.mime.types contains:
+
+  text/calendar       ics
+
+
+
+** vcf-to-mutt.rb
+
+This script searches a set of vCards can output the results as a Mutt query response,
+or a Mutt aliases file.
+
+It used to support querying the OS X Address Book, but that is better done with lbdb, see
+http://www.spinnaker.de/lbdb/.
+
+To install, you must:
+
+1 - install vPim (see README)
+
+3 - copy vcf-to-mutt into a directory in your path, such
+    as ~/bin, and chmod +x vcf-to-mutt.rb to make it executable.
+
+4 - Put in your muttrc file (either ~/.muttrc or ~/.mutt/muttrc) a line such as:
+
+set query_command = "vcf-to-mutt.rb '%s'"
+
+5 - The query command ("Q") will query the address book, control-t will give you auto-completion
+    of email addresses, see the Mutt manual page.
+
+
+** mutt-aliases-to-vcf.rb
+
+This script converts a mutt aliases file into a vCard file.
+
+

data/samples/ab-query.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+
+$-w = true
+$:.unshift File.dirname($0) + '/../lib'
+
+require 'osx-wrappers'
+
+require 'getoptlong'
+require 'vpim/vcard'
+require 'osx-wrappers'
+
+HELP =<<EOF
+Usage: ab-query.rb [--me] [--all]
+
+Queries the OS X Address Book for vCards.
+
+ -h, --help print this helpful message
+ -m, --me   list my vCard
+ -a, --all  list all vCards
+EOF
+
+opts = GetoptLong.new(
+  [ "--help",    "-h",              GetoptLong::NO_ARGUMENT ],
+  [ "--me",      "-m",              GetoptLong::NO_ARGUMENT ],
+  [ "--all",     "-a",              GetoptLong::NO_ARGUMENT ]
+)
+
+abook = nil
+
+opts.each do |opt, arg|
+  case opt
+    when "--help" then
+      puts HELP
+      exit 0
+
+    when "--all" then
+      abook = OSX::ABAddressBook.sharedAddressBook unless abook
+
+      abook.people.to_a.each {
+        |person|
+
+        puts person.vCard
+      }
+
+    when "--me" then
+     abook = OSX::ABAddressBook.sharedAddressBook unless abook
+
+     puts abook.me.vCard
+  end
+end
+
+
+unless abook
+  puts HELP
+  exit 1
+end
+

data/samples/agent.ru

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# Run as "rackup agent.ru", default rackup arguments follow:
+#\ -p 4567
+
+require "vpim/agent/ics"
+
+use Rack::Reloader, 0
+
+run Vpim::Agent::Ics
+