vpim 0.323 → 0.357

data/lib/vpim.rb

@@ -6,9 +6,8 @@
   details.
 =end
 
-# I think a file like this may be required by ruby-gems.
+# the existence of this file is a hack to support users or rubygems
 
 require 'vpim/icalendar'
 require 'vpim/vcard'
-require 'vpim/maker/vcard'
 

data/lib/vpim/address.rb

@@ -0,0 +1,181 @@
+=begin
+  Copyright (C) 2006 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 an Address from a DirectoryInfo::Field, +field+.
+      #
+      # TODO - make private, and split into the encode/decode/create trinity.
+      def initialize(field)
+        unless field.value
+          raise ArgumentError
+        end
+
+        @field = field
+      end
+
+      # Return a representation of this Address as a DirectoryInfo::Field.
+      def field
+        @field.copy
+      end
+
+      # Create a copy of Address. If the original Address was frozen, this one
+      # won't be.
+      def copy
+        Marshal.load(Marshal.dump(self))
+      end
+
+      # Addresses in a CAL-ADDRESS are represented as a URI, usually a mailto URI.
+      def uri
+        @field.value
+      end
+
+      # Return true if the +uri+ is == to this address' URI. The comparison
+      # is case-insensitive.
+      #
+      # FIXME - why case insensitive? Email addresses. Should use a URI library
+      # if I can find one and it knows how to do URI comparisons.
+      def ==(uri)
+        Vpim::Methods.casecmp?(self.uri.to_str, uri.to_str)
+      end
+
+      # The common or displayable name associated with the calendar address,
+      # or nil if there is none.
+      def cn
+        return nil unless n = @field.param('CN')
+
+        # FIXME = the CN param may have no value, which is an error, but don't try
+        # to decode it, return either nil, or InvalidEncoding
+        Vpim.decode_text(n.first)
+      end
+
+      # A string representation of an address, using the common name, and the
+      # URI. The URI protocol is stripped if it's "mailto:".
+      # 
+      # TODO - this needs to properly escape the cn string!
+      def to_s
+        u = uri
+        u.gsub!(/^mailto: */i, '')
+
+        if cn
+          "\"#{cn}\" <#{uri}>"
+        else
+          uri
+        end
+      end
+
+      def inspect
+        "#<Vpim::Icalendar::Address:cn=#{cn.inspect} status=#{partstat} rsvp?=#{rsvp} #{uri.inspect}>"
+      end
+
+      # 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.
+      def role
+        return 'REQ-PARTICIPANT' unless r = @field.param('ROLE')
+        r.first.upcase
+      end
+
+      # 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.
+      #
+      # TODO - make the default depend on the component type.
+      def partstat
+        return 'NEEDS-ACTION' unless r = @field.param('PARTSTAT')
+        r.first.upcase
+      end
+
+      # Set or change the participation status of the address, the PARTSTAT,
+      # to +status+.
+      #
+      # See #partstat.
+      def partstat=(status)
+        @field['PARTSTAT'] = status.to_str
+        status
+      end
+
+      # The value of the RSVP field, either +true+ or +false+. It is used to
+      # specify whether there is an expectation of a favor of a reply from the
+      # calendar user specified by the property value.
+      #
+      # TODO - should be #rsvp?
+      def rsvp
+        return false unless r = @field.param('RSVP')
+        r = r.first
+        return false unless r
+        case r
+          when /TRUE/i then true
+          when /FALSE/i then false
+          else raise InvalidEncodingError, "RSVP param value not TRUE/FALSE: #{r}"
+        end
+      end
+    end
+  end
+end
+

data/lib/vpim/attachment.rb

@@ -0,0 +1,102 @@
+=begin
+  Copyright (C) 2006 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/icalendar'
+
+module Vpim
+
+  # Attachments are used by both iCalendar and vCard. They are either a URI or
+  # inline data, and their decoded value will be either a Uri or a Inline, as
+  # appropriate.
+  #
+  # Besides the methods specific to their class, both kinds of object implement
+  # a set of common methods, allowing them to be treated uniformly:
+  # - Uri#to_io, Inline#to_io: return an IO from which the value can be read.
+  # - Uri#to_s, Inline#to_s: return the value as a String.
+  # - Uri#format, Inline#format: the format of the value. This is supposed to
+  #   be an "iana defined" identifier (like "image/jpeg"), but could be almost
+  #   anything (or nothing) in practice.  Since the parameter is optional, it may
+  #   be "".
+  #
+  # The objects can also be distinguished by their class, if necessary.
+  module Attachment
+
+    # TODO - It might be possible to autodetect the format from the first few
+    # bytes of the value, and return the appropriate MIME type when format
+    # isn't defined.
+    #
+    # iCalendar and vCard put the format in different parameters, and the
+    # default kind of value is different.
+    def Attachment.decode(field, defkind, fmtparam) #:nodoc:
+      format = field.pvalue(fmtparam) || ''
+      kind = field.kind || defkind
+      case kind
+      when 'text'
+        Inline.new(Vpim.decode_text(field.value), format)
+      when 'uri'
+        Uri.new(field.value_raw, format)
+      when 'binary'
+        Inline.new(field.value, format)
+      else
+        raise InvalidEncodingError, "Attachment of type #{kind} is not allowed"
+      end
+    end
+
+    # Extends a String to support some of the same methods as Uri.
+    class Inline < String
+      def initialize(s, format) #:nodoc:
+        @format = format
+        super(s)
+      end
+
+      # Return an IO object for the inline data. See +stringio+ for more
+      # information.
+      def to_io
+        StringIO.new(self)
+      end
+
+      # The format of the inline data.
+      # See Attachment.
+      attr_reader :format
+    end
+
+    # Encapsulates a URI and implements some methods of String.
+    class Uri
+      def initialize(uri, format) #:nodoc:
+        @uri = uri
+        @format = format
+      end
+
+      # The URI value.
+      attr_reader :uri
+
+      # The format of the data referred to by the URI.
+      # See Attachment.
+      attr_reader :format
+
+      # Return an IO object from opening the URI.  See +open-uri+ for more
+      # information.
+      def to_io
+        open(@uri)
+      end
+
+      # Return the String from reading the IO object to end-of-data.
+      def to_s
+        to_io.read(nil)
+      end
+
+      def inspect #:nodoc:
+        s = "<#{self.class.to_s}: #{uri.inspect}>"
+        s << ", #{@format.inspect}" if @format
+        s
+      end
+    end
+
+  end
+end
+

data/lib/vpim/dirinfo.rb

@@ -21,6 +21,16 @@ module Vpim
   # A vCard, for example, is a specialization of a directory info object.
   #
   # - [RFC2425] the directory information framework (ftp://ftp.ietf.org/rfc/rfc2425.txt)
+  #
+  # Here's an example of encoding a simple vCard using the low-level APIs:
+  #
+  #   card = Vpim::Vcard.create
+  #   card << Vpim::DirectoryInfo::Field.create('EMAIL', 'user.name@example.com', 'TYPE' => 'INTERNET' )
+  #   card << Vpim::DirectoryInfo::Field.create('URL', 'http://www.example.com/user' )
+  #   card << Vpim::DirectoryInfo::Field.create('FN', 'User Name' )
+  #   puts card.to_s
+  #
+  # Don't do it like that, use Vpim::Vcard::Maker.
   class DirectoryInfo
     include Enumerable
 
@@ -215,8 +225,8 @@ module Vpim
     # profile-specific fields can be deleted, including mandatory ones. For
     # vCards in particular, in order to avoid destroying them, I suggest
     # creating a new Vcard, and copying over all the fields that you still
-    # want, rather than using #delete. This is easy with Maker::Vcard#copy, see
-    # the Maker::Vcard examples.
+    # want, rather than using #delete. This is easy with Vcard::Maker#copy, see
+    # the Vcard::Maker examples.
     def delete(field)
       case
       when field.name?('BEGIN'), field.name?('END')

data/lib/vpim/field.rb

@@ -15,19 +15,18 @@ module Vpim
   class DirectoryInfo
 
     # A field in a directory info object.
-    #
-    # TODO
-    # - Field should know which param values and field vales are
-    # case-insensitive, configurably, so it can down case them
-    # - perhaps should have pvalue_set/del/add, perhaps case-insensitive, or
-    # pvalue_iset/idel/iadd, where set sets them all, add adds if not present,
-    # and del deletes any that are present
-    # - I really, really, need a case-insensitive string...
-    # - should allow nil as a field value, its not the same as '', if there is
-    # more than one pvalue, the empty string will show up. This isn't strictly
-    # disallowed, but its odd. Should also strip empty strings on decoding, if
-    # I don't already.
     class Field
+      # TODO
+      # - Field should know which param values and field values are
+      #   case-insensitive, configurably, so it can down case them
+      # - perhaps should have pvalue_set/del/add, perhaps case-insensitive, or
+      #   pvalue_iset/idel/iadd, where set sets them all, add adds if not present,
+      #   and del deletes any that are present
+      # - I really, really, need a case-insensitive string...
+      # - should allow nil as a field value, its not the same as '', if there is
+      #   more than one pvalue, the empty string will show up. This isn't strictly
+      #   disallowed, but its odd. Should also strip empty strings on decoding, if
+      #   I don't already.
       private_class_method :new
 
       def Field.create_array(fields)
@@ -263,6 +262,19 @@ module Vpim
       # FIXME - remove my own uses of #params
       alias params pnames # :nodoc:
 
+      # The first value of the param +name+,  nil if there is no such param,
+      # the param has no value, or the first param value is zero-length.
+      def pvalue(name)
+        v = pvalues( name )
+        if v
+          v = v.first
+        end
+        if v
+          v = nil unless v.length > 0
+        end
+        v
+      end
+
       # The Array of all values of the param +name+,  nil if there is no such
       # param, [] if the param has no values. If the Field isn't frozen, the
       # Array is mutable.
@@ -402,9 +414,9 @@ module Vpim
           if v.size > 1
             raise InvalidEncodingError, "multi-valued param 'VALUE' (#{values})"
           end
-          v = v.first
+          v = v.first.downcase
         end
-        v.downcase
+        v
       end
 
       # The value as an array of Time objects (all times and dates in

data/lib/vpim/icalendar.rb

@@ -10,6 +10,8 @@ require 'vpim/rfc2425'
 require 'vpim/dirinfo'
 require 'vpim/rrule'
 require 'vpim/vevent'
+require 'vpim/vtodo'
+require 'vpim/vjournal'
 require 'vpim/vpim'
 
 module Vpim
@@ -64,26 +66,24 @@ module Vpim
       @properties = DirectoryInfo.create(outer)
       @properties.check_begin_end('VCALENDAR')
 
-      # Categorize the components
-      @vevents = []
-      @vtodos  = []
-      @vjournals  = []
-      @others = []
+      @components = []
+
+      factory = {
+        'VEVENT' => Vevent,
+        'VTODO' => Vtodo,
+        'VJOURNAL' => Vjournal,
+      }
 
       inner.each do |component|
-        # First field in every component should be a "BEGIN:".
         name = component.first
-        if ! name.name? 'BEGIN'
+        unless name.name? 'BEGIN'
           raise InvalidEncodingError, "calendar component begins with #{name.name}, instead of BEGIN!"
         end
 
-        name = name.value.upcase
+        name = name.value
 
-        case name
-          when 'VEVENT'    then @vevents << Vevent.new(component)
-          when 'VTODO'     then @vtodos  << Vtodo.new(component)
-          when 'VJOURNAL'  then @vjournals  << Vjournal.new(component)
-          else @others << component
+        if klass = factory[name]
+          @components << klass.new(component)
         end
       end
     end
@@ -141,9 +141,7 @@ module Vpim
 
       last = fields.pop
 
-      @vevents.each { |c| fields << c.fields }
-      @vtodos.each  { |c| fields << c.fields }
-      @others.each  { |c| fields << c.fields }
+      @components.each { |c| fields << c.fields }
 
       fields << last
     end
@@ -153,14 +151,10 @@ module Vpim
     # Push a calendar component onto the calendar.
     def push(component)
       case component
-        when Vevent
-          @vevents << component
-        when Vtodo
-          @vtodos << component
-        when Vjournal
-          @vjournals << component
+        when Vevent, Vtodo, Vjournal
+          @components << component
         else
-          raise ArgumentError, "can't add component type #{component.type} to a calendar"
+          raise ArgumentError, "can't add a #{component.type} to a calendar"
       end
     end
 
@@ -270,196 +264,56 @@ module Vpim
       m ? m.upcase : m
     end
 
-    # The array of all calendar event components (each is a Vevent).
+    # The value of the CALSCALE: property, or "GREGORIAN" if CALSCALE: is not
+    # present.
     #
-    # TODO - should this take an interval: t0,t1?
-    def events
-      @vevents
-    end
-
-    # The array of all calendar todo components (each is a Vtodo).
-    def todos
-      @vtodos
+    # This is of academic interest, really because there aren't any other
+    # calendar scales defined, and given that its hard enough just dealing with
+    # Gregorian calendars, there probably won't be.
+    def calscale
+      proptext('CALSCALE') || 'GREGORIAN'
     end
 
-    # The array of all calendar journal components (each is a Vjournal).
-    def journals
-      @vjournals
-    end
-  end
-
-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.
+    # The array of all supported calendar components. If a class is provided,
+    # return only the components of that class.
     #
-    # 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
+    # If a block is provided, yield the components instead of returning them.
     #
-    class Address
-
-      # Create an Address from a DirectoryInfo::Field, +field+.
-      #
-      # TODO - make private, and split into the encode/decode/create trinity.
-      def initialize(field)
-        unless field.value
-          raise ArgumentError
-        end
-
-        @field = field
-      end
-
-      # Return a representation of this Address as a DirectoryInfo::Field.
-      def field
-        @field.copy
-      end
-
-      # Create a copy of Address. If the original Address was frozen, this one
-      # won't be.
-      def copy
-        Marshal.load(Marshal.dump(self))
-      end
-
-      # Addresses in a CAL-ADDRESS are represented as a URI, usually a mailto URI.
-      def uri
-        @field.value
-      end
-
-      # Return true if the +uri+ is == to this address' URI. The comparison
-      # is case-insensitive.
-      #
-      # FIXME - why case insensitive? Email addresses. Should use a URI library
-      # if I can find one and it knows how to do URI comparisons.
-      def ==(uri)
-        Vpim::Methods.casecmp?(self.uri.to_str, uri.to_str)
-      end
-
-      # The common or displayable name associated with the calendar address,
-      # or nil if there is none.
-      def cn
-        return nil unless n = @field.param('CN')
+    # Examples:
+    #   calendar.components(Vpim::Icalendar::Vevent)
+    #   => array of all calendar components
+    #
+    #   calendar.components(Vpim::Icalendar::Vtodo) {|c| c... }
+    #   => yield all todo components
+    #
+    #   calendar.components {|c| c... }
+    #   => yield all components
+    def components(klass=Object) #:yields:component
+      # TODO - should this take an interval: t0,t1?
 
-        # FIXME = the CN param may have no value, which is an error, but don't try
-        # to decode it, return either nil, or InvalidEncoding
-        Vpim.decode_text(n.first)
+      unless block_given?
+        return @components.select{|c| klass === c}.freeze
       end
 
-      # A string representation of an address, using the common name, and the
-      # URI. The URI protocol is stripped if it's "mailto:".
-      # 
-      # TODO - this needs to properly escape the cn string!
-      def to_s
-        u = uri
-        u.gsub!(/^mailto: */i, '')
-
-        if cn
-          "\"#{cn}\" <#{uri}>"
-        else
-          uri
+      @components.each do |c|
+        if klass === c
+          yield c
         end
       end
+      self
+    end
 
-      def inspect
-        "#<Vpim::Icalendar::Address:cn=#{cn.inspect} status=#{partstat} rsvp?=#{rsvp} #{uri.inspect}>"
-      end
-
-      # 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.
-      def role
-        return 'REQ-PARTICIPANT' unless r = @field.param('ROLE')
-        r.first.upcase
-      end
-
-      # 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.
-      #
-      # TODO - make the default depend on the component type.
-      def partstat
-        return 'NEEDS-ACTION' unless r = @field.param('PARTSTAT')
-        r.first.upcase
-      end
-
-      # Set or change the participation status of the address, the PARTSTAT,
-      # to +status+.
-      #
-      # See #partstat.
-      def partstat=(status)
-        @field['PARTSTAT'] = status.to_str
-        status
-      end
+    # For backwards compatibility. Use #components.
+    def events #:nodoc:
+      components Icalendar::Vevent
+    end
 
-      # The value of the RSVP field, either +true+ or +false+. It is used to
-      # specify whether there is an expectation of a favor of a reply from the
-      # calendar user specified by the property value.
-      #
-      # TODO - should be #rsvp?
-      def rsvp
-        return false unless r = @field.param('RSVP')
-        r = r.first
-        return false unless r
-        case r
-          when /TRUE/i then true
-          when /FALSE/i then false
-          else raise InvalidEncodingError, "RSVP param value not TRUE/FALSE: #{r}"
-        end
-      end
+    # For backwards compatibility. Use #components.
+    def todos #:nodoc:
+      components Icalendar::Vtodo
     end
+
   end
+
 end