vpim 0.17 → 0.323

data/lib/vpim/dirinfo.rb

@@ -20,7 +20,7 @@ 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)
+  # - [RFC2425] the directory information framework (ftp://ftp.ietf.org/rfc/rfc2425.txt)
   class DirectoryInfo
     include Enumerable
 
@@ -42,7 +42,7 @@ module Vpim
     # Decode +card+ into a DirectoryInfo object.
     #
     # +card+ may either be a something that is convertible to a string using
-    # #to_str or an array of objects that can be joined into a string using
+    # #to_str or an Array of objects that can be joined into a string using
     # #join("\n"), or an IO object (which will be read to end-of-file).
     #
     # The lines in the string may be delimited using IETF (CRLF) or Unix (LF) conventions.
@@ -108,7 +108,13 @@ module Vpim
     #
     # TODO - call this #texts(), as in the plural?
     def text(name)
-      enum_by_name(name).map { |f| f.to_text }
+      accum = []
+      each do |f|
+        if f.name? name
+          accum << f.to_text
+        end
+      end
+      accum
     end
 
     # Array of all the Field#group()s.
@@ -161,9 +167,9 @@ module Vpim
     #     end
     #   end
     #
-    # or to get an array of all the fields in group 'agroup', you could do:
+    # or to get an array of all the fields in group 'AGROUP', you could do:
     # 
-    #   card.enum_by_group('agroup').to_a
+    #   card.enum_by_group('AGROUP').to_a
     def enum_by_group(group)
       Enumerator.new(self, Proc.new { |field| field.group?(group) })
     end

data/lib/vpim/field.rb

@@ -67,7 +67,7 @@ module Vpim
           pvalues.each do |pvalue|
             # check if we need to do any encoding
             if Vpim::Methods.casecmp?(pname, 'ENCODING') && pvalue == :b64
-              pvalue = 'b' # the RFC definition of the base64 param value
+              pvalue = 'B' # the RFC definition of the base64 param value
               value = [ value.to_str ].pack('m').gsub("\n", '')
             end
 
@@ -139,7 +139,7 @@ module Vpim
             params = $3
 
             # v2.1 params have no '=' sign, figure out what kind of param it
-            # is (either its a known encoding, or we treat it as a 'type'
+            # is (either its a known encoding, or we treat it as a 'TYPE'
             # param).
            
             if $2 == ""
@@ -192,9 +192,9 @@ module Vpim
       # name (a String) to either a single string or symbol, or an array of
       # strings and symbols (parameters can be multi-valued).
       #
-      # If 'encoding' => :b64 is specified as a parameter, the value will be
+      # If 'ENCODING' => :b64 is specified as a parameter, the value will be
       # base-64 encoded. If it's already base-64 encoded, then use String
-      # values ('encoding' => 'b'), and no further encoding will be done by
+      # values ('ENCODING' => 'B'), and no further encoding will be done by
       # this routine.
       #
       # Currently handled value types are:
@@ -290,16 +290,21 @@ module Vpim
       # Note: Both the RFC 2425 encoding param ("b", meaning base-64) and the
       # vCard 2.1 encoding params ("base64", "quoted-printable", "8bit", and
       # "7bit") are supported.
+      #
+      # FIXME:
+      # - should use the VALUE parameter
+      # - should also take a default value type, so it can be converted
+      #   if VALUE parameter is not present.
       def value
         case encoding
-          when nil, '8bit', '7bit' then @value
+          when nil, '8BIT', '7BIT' then @value
 
           # Hack - if the base64 lines started with 2 SPC chars, which is invalid,
           # there will be extra spaces in @value. Since no SPC chars show up in
           # b64 encodings, they can be safely stripped out before unpacking.
-          when 'b', 'base64'       then @value.gsub(' ', '').unpack('m*').first
+          when 'B', 'BASE64'       then @value.gsub(' ', '').unpack('m*').first
 
-          when 'quoted-printable'  then @value.unpack('M*').first
+          when 'QUOTED-PRINTABLE'  then @value.unpack('M*').first
 
           else
             raise Vpim::InvalidEncodingError, "unrecognized encoding (#{encoding})"
@@ -346,7 +351,7 @@ module Vpim
       def type?(type)
         type = type.to_str
 
-        types = param('type')
+        types = param('TYPE')
 
         if types
           types = types.detect { |t| Vpim::Methods.casecmp?(t, type) }
@@ -354,18 +359,18 @@ module Vpim
       end
 
       # Is this field marked as preferred? A vCard field is preferred if
-      # #type?('pref'). This method is not necessarily meaningful for
+      # #type?('PREF'). This method is not necessarily meaningful for
       # non-vCard profiles.
       def pref?
-        type? 'pref'
+        type? 'PREF'
       end
 
       # Set whether a field is marked as preferred. See #pref?
       def pref=(ispref)
         if ispref
-          pvalue_iadd('type', 'pref')
+          pvalue_iadd('TYPE', 'PREF')
         else
-          pvalue_idel('type', 'pref')
+          pvalue_idel('TYPE', 'PREF')
         end
       end
 
@@ -378,13 +383,13 @@ module Vpim
       # The value of the ENCODING parameter, if present, or nil if not
       # present.
       def encoding
-        e = param("encoding")
+        e = param('ENCODING')
 
         if e
           if e.length > 1
-            raise Vpim::InvalidEncodingError, "multi-valued param 'encoding' (#{e})"
+            raise Vpim::InvalidEncodingError, "multi-valued param 'ENCODING' (#{e})"
           end
-          e = e.first.downcase
+          e = e.first.upcase
         end
         e
       end
@@ -392,10 +397,10 @@ module Vpim
       # The type of the value, as specified by the VALUE parameter, nil if
       # unspecified.
       def kind
-        v = param('value')
+        v = param('VALUE')
         if v
           if v.size > 1
-            raise InvalidEncodingError, "multi-valued param 'value' (#{values})"
+            raise InvalidEncodingError, "multi-valued param 'VALUE' (#{values})"
           end
           v = v.first
         end
@@ -465,7 +470,7 @@ module Vpim
       # characters, this method will strip them, if present.
       #
       # In theory, #value could also do this, but it would need to know that
-      # the value is of type 'text', and often for text values the 'type'
+      # the value is of type 'TEXT', and often for text values the 'VALUE'
       # parameter is not present, so knowledge of the expected type of the
       # field is required from the decoder.
       def to_text
@@ -502,10 +507,10 @@ module Vpim
       # currently has. See Field.create() for a description of +pvalue+.
       #
       # Example:
-      #  if field['type']
-      #    field['type'] << 'home'
+      #  if field['TYPE']
+      #    field['TYPE'] << 'HOME'
       #  else
-      #    field['type'] = [ 'home'
+      #    field['TYPE'] = [ 'HOME' ]
       #  end
       #
       # TODO - this could be an alias to #pvalue_set

data/lib/vpim/icalendar.rb

@@ -12,106 +12,6 @@ require 'vpim/rrule'
 require 'vpim/vevent'
 require 'vpim/vpim'
 
-=begin
-
-  ...            ; y/n    (whether I've seen it in Apple's calendars)
-                   name
-                   section
-                   type/comments
-
-
-  icalbody = icalprops component
-
-  icalprops =
-     prodid /    ; y  PRODID    4.7.3  required, TEXT
-     version /   ; y            4.7.4  required, TEXT, "2.0"
-     calscal /   ; y            4.7.1  only defined value is GREGORIAN
-     method /    ; n  METHOD    4.7.2  used with transport protocols
-
-  component =
-     eventc /    ; y  VEVENT    4.6.1
-     todoc /     ; y  VTODO     4.6.2
-     journalc /  ; n
-     freebusyc / ; n
-     timezonec / ; n
-     
-   alarmc        ; y  VALARM  4.6.6  occurs inside a VEVENT or a VTODO
-
-   class         ; y  CLASS     4.8.1.3   private/public/confidentical/... (default=public)
-
-   comment       ; n            4.8.1.4   TEXT
-   description   ; y            4.8.1.5   TEXT
-   summary       ; y            4.8.1.12  TEXT
-   location      ; y            4.8.1.7   TEXT  intended venue
- 
-   priority      ; n why?       4.8.1.9   INTEGER, why isn't this seen for my TODO items?
-
-   status        ; y            4.8.1.11  TEXT, different values defined for event, todo, journal
-
-      Event: TENTATIVE, CONFIRMED, CANCELLED
-
-      Todo: NEEDS-ACTION, COMPLETED, IN-PROCESS, CANCELLED
-
-      Journal: DRAFT, FINAL, CANCELLED
-
-   dtstart       ; y  DTSTART   4.8.2.4   DATE-TIME is default, value=date can be set
-   dtend         ; y  DTEND     4.8.2.2   Unless it has Z (UTC), or a tzid, then it is local-time.
-
-   dtstamp       ; y  DTSTAMP   4.8.7.2   DATE-TIME, creation time, inclusion is mandatory, but what does
-     it mean? It seems to be when the icalendar was actually created (as opposed to when the user entered
-     the information into the calendar database, for example), but in that case my Apple icalendars should
-     have all components having the same DTSTAMP, but they don't!
-
-   duration      ; y  DURATION  4.8.2.5   dur-value
-
-     dur-value  = (["+"] / "-") "P" (dur-date / dur-time / dur-week)
-
-     dur-date   = dur-day [dur-time]
-                = 1*DIGIT "D" [ dur-time ]
-                
-     dur-time   = "T" (dur-hour / dur-minute / dur-second)
-                = "T" (
-                    1*DIGIT "H" [ 1*DIGIT "M" [ 1*DIGIT "S" ] ] /
-                                  1*DIGIT "M" [ 1*DIGIT "S" ]   /
-                                                1*DIGIT "S"
-                    )
-
-     dur-week   = 1*DIGIT "W"
-     dur-day    = 1*DIGIT "D"
-     dur-hour   = 1*DIGIT "H" [dur-minute]
-     dur-minute = 1*DIGIT "M" [dur-second]
-     dur-second = 1*DIGIT "S"
-
-     The EBNF is complicated, because they want to say that /some/ component
-     must be present, and that if you have a "T", you need a time after it,
-     and that you can't have an hour followed by seconds with no intervening
-     minutes... but we don't care about that during decoding, so we rewrite
-     the EBNF as:
-
-     dur-value = ["+" / "-"] "P" [ 1*DIGIT "W" ] [ 1*DIGIT "D" ] [ "T" [ 1*DIGIT "H" ]  [ 1*DIGIT "M" ] [ 1*DIGIT "S" ] ]
-
-   dtdue         ; n  DTDUE     4.8.2.3
-
-   uid           ; y  UID       4.8.4.7   TEXT, recommended to generate them in RFC822 form
-
-   rrule         ; y  RRULE     4.8.5.4   RECUR, can occur multiple times!
-
-   
-
-VEVENT Ifx:
-
-  TEXT: summary, description, comment, location, uid
-
-  think about:  uid
-
-  Vevent#status -> The status, upper-case.
-  Vevent#status= -> set a new status, only allow the defined statuses!
-  Vevent#status?(s) -> check if the status is s
-
-  can contain alarms... should it include an alarms module?
-
-=end
-
 module Vpim
   # An iCalendar.
   #
@@ -167,12 +67,13 @@ module Vpim
       # Categorize the components
       @vevents = []
       @vtodos  = []
+      @vjournals  = []
       @others = []
 
       inner.each do |component|
         # First field in every component should be a "BEGIN:".
         name = component.first
-        if ! name.name? 'begin'
+        if ! name.name? 'BEGIN'
           raise InvalidEncodingError, "calendar component begins with #{name.name}, instead of BEGIN!"
         end
 
@@ -181,6 +82,7 @@ module Vpim
         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
         end
       end
@@ -255,6 +157,8 @@ module Vpim
           @vevents << component
         when Vtodo
           @vtodos << component
+        when Vjournal
+          @vjournals << component
         else
           raise ArgumentError, "can't add component type #{component.type} to a calendar"
       end
@@ -359,23 +263,29 @@ module Vpim
     # transport a snapshot of some calendar information; without the intention
     # of conveying a scheduling semantic.
     #
-    # Note that this can't be called 'method', that name is reserved.
+    # Note that this method can't be called +method+, thats already a method of
+    # Object.
     def protocol
       m = @properties['METHOD']
       m ? m.upcase : m
     end
 
-    # The array of all calendar events (each is a Vevent).
+    # The array of all calendar event components (each is a Vevent).
     #
     # TODO - should this take an interval: t0,t1?
     def events
       @vevents
     end
 
-    # The array of all calendar todos (each is a Vtodo).
+    # The array of all calendar todo components (each is a Vtodo).
     def todos
       @vtodos
     end
+
+    # The array of all calendar journal components (each is a Vjournal).
+    def journals
+      @vjournals
+    end
   end
 
 end
@@ -488,6 +398,10 @@ module Vpim
         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:
@@ -526,13 +440,15 @@ module Vpim
       #
       # See #partstat.
       def partstat=(status)
-        @field['partstat'] = status.to_str
+        @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

data/lib/vpim/maker/vcard.rb

@@ -16,6 +16,7 @@ module Vpim
     # - 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:ex_mkyourown.txt: example of adding support for new fields to Maker::Vcard
     class Vcard
       # Make a vCard.
       #
@@ -80,16 +81,13 @@ module Vpim
       #
       # All attributes are optional.
       #
-      # Warning: This is the only mandatory field besides the full name, FN,
-      # but FN: can be set in #make, and if not set will be constucted as the
-      # string "#{prefix} #{given} #{additional} #{family}, #{suffix}".
-      #
-      # FIXME: is it possible to deduce given/family from the full_name?
-      # 
-      # FIXME: Each attribute can currently only have a single String value.
-      #
-      # FIXME: Need to escape specials in the String.
+      # Warning: This is the only mandatory field besides the full name, FN.
+      # FN: can be set in #make, or by #fullname=, and if not set will be
+      # constucted as the string "#{prefix} #{given} #{additional} #{family},
+      # #{suffix}".
       def add_name # :yield: n
+        # FIXME: Each attribute can currently only have a single String value.
+        # FIXME: Need to escape specials in the String.
         x = Struct.new(:family, :given, :additional, :prefix, :suffix).new
         yield x
         @card << Vpim::DirectoryInfo::Field.create(
@@ -101,8 +99,8 @@ module Vpim
 
       # Add a full name field, FN.
       #
-      # Normally the FN field value is derived from the N: field value, but
-      # it can be explicitly set.
+      # Normally the FN field value is derived from the N: field value, see
+      # #add_name, but it can be explicitly set.
       def fullname=(fullname)
         if @card.field('FN')
           raise Vpim::InvalidEncodingError, "Not allowed to add more than one FN field to a vCard."
@@ -130,9 +128,8 @@ module Vpim
       # strings.
       #
       # TODO - Add #label to support LABEL.
-      #
-      # FIXME - Need to escape specials in the String.
       def add_addr # :yield: adr
+        # FIXME - Need to escape specials in the String.
         x = Struct.new(
           :location, :preferred, :delivery,
           :pobox, :extended, :street, :locality, :region, :postalcode, :country
@@ -143,12 +140,12 @@ module Vpim
 
         # All these attributes go into the TYPE parameter.
         params = [ x[:location], x[:delivery] ]
-        params << 'pref' if x[:preferred]
+        params << 'PREF' if x[:preferred]
         params = params.flatten.uniq.compact.map { |s| s.to_str }
 
         paramshash = {}
 
-        paramshash['type'] = params if params.first
+        paramshash['TYPE'] = params if params.first
 
         @card << Vpim::DirectoryInfo::Field.create( 'ADR', values, paramshash)
         self
@@ -172,11 +169,11 @@ module Vpim
 
           yield x
 
-          x[:preferred] = 'pref' if x[:preferred]
+          x[:preferred] = 'PREF' if x[:preferred]
 
           types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
 
-          params['type'] = types if types.first
+          params['TYPE'] = types if types.first
         end
 
         @card << Vpim::DirectoryInfo::Field.create( 'TEL', number, params)
@@ -198,11 +195,11 @@ module Vpim
 
           yield x
 
-          x[:preferred] = 'pref' if x[:preferred]
+          x[:preferred] = 'PREF' if x[:preferred]
 
           types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
 
-          params['type'] = types if types.first
+          params['TYPE'] = types if types.first
         end
 
         @card << Vpim::DirectoryInfo::Field.create( 'EMAIL', email, params)
@@ -226,6 +223,7 @@ module Vpim
         end
         @card << Vpim::DirectoryInfo::Field.create( 'BDAY', birthday );
       end
+
 =begin
 TODO - need text=() implemented in Field
 
@@ -269,11 +267,11 @@ TODO - need text=() implemented in Field
 
           yield x
 
-          x[:preferred] = 'pref' if x[:preferred]
+          x[:preferred] = 'PREF' if x[:preferred]
 
-          types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
+          types = x.to_a.flatten.uniq.compact.map { |s| s.upcase }
 
-          params['type'] = types if types.first
+          params['TYPE'] = types if types.first
         end
 
         @card << Vpim::DirectoryInfo::Field.create( 'IMPP', url, params)
@@ -299,11 +297,11 @@ TODO - need text=() implemented in Field
 
           yield x
 
-          x[:preferred] = 'pref' if x[:preferred]
+          x[:preferred] = 'PREF' if x[:preferred]
 
-          types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
+          types = x.to_a.flatten.uniq.compact.map { |s| s.upcase }
 
-          params['type'] = types if types.first
+          params['TYPE'] = types if types.first
         end
 
         @card << Vpim::DirectoryInfo::Field.create( 'X-AIM', xaim, params)
@@ -346,12 +344,12 @@ TODO - need text=() implemented in Field
         params = {}
 
         # Don't set type to the empty string.
-        params['type'] = x[:type] if( x[:type] && x[:type].length > 0 )
+        params['TYPE'] = x[:type] if( x[:type] && x[:type].length > 0 )
 
         if x[:link]
-          params['value'] = 'uri'
+          params['VALUE'] = 'URI'
         else # it's inline, base-64 encode it
-          params['encoding'] = :b64
+          params['ENCODING'] = :b64
           if !x[:type]
             raise Vpim::InvalidEncodingError, 'Inline image data must have it\'s type set.'
           end
@@ -361,6 +359,11 @@ TODO - need text=() implemented in Field
         self
       end
 
+      # Add a URL field, URL:.
+      def add_url(url)
+        @card << Vpim::DirectoryInfo::Field.create( 'URL', url.to_str );
+      end
+
       # Add a Field, +field+.
       def add_field(field)
         fieldname = field.name.upcase

data/lib/vpim/property/base.rb

@@ -0,0 +1,63 @@
+module Vpim
+  class Icalendar
+    module Property #:nodoc:
+
+      # FIXME - these should be part of Dirinfo
+      module Base
+        # Value of first property with name +name+
+        def propvalue(name) #:nodoc:
+          prop = @properties.detect { |f| f.name? name }
+          if prop
+            prop = prop.value
+          end
+          prop
+        end
+
+        def proptoken(name, allowed, default_token = nil) #:nodoc:
+          prop = propvalue name
+
+          if prop
+            prop = prop.to_str.upcase
+            unless allowed.include?(prop)
+              raise Vpim::InvalidEncodingError, "Invalid #{name} value '#{prop}'"
+            end
+          else
+            prop = default_token
+          end
+
+          prop
+        end
+
+        # Value as DATE-TIME or DATE of object of first property with name +name+
+        def proptime(name) #:nodoc:
+          prop = @properties.detect { |f| f.name? name }
+          if prop
+            prop = prop.to_time.first
+          end
+          prop
+        end
+
+        # Value as TEXT of first property with name +name+
+        def proptext(name) #:nodoc:
+          prop = @properties.detect { |f| f.name? name }
+          if prop
+            prop = prop.to_text
+          end
+          prop
+        end
+
+        # Array of values as TEXT of all properties with name +name+
+        def proptextarray(name) #:nodoc:
+          @properties.select{ |f| f.name? name }.map{ |p| p.to_text }
+        end
+
+        # Array of values as TEXT list of all properties with name +name+
+        def proptextlistarray(name) #:nodoc:
+          @properties.select{ |f| f.name? name }.map{ |p| Vpim.decode_text_list(p.value_raw) }.flatten
+        end
+
+      end
+    end
+  end
+end
+