vcard 0.1.1 → 0.2.0

data/lib/vcard/attachment.rb

@@ -1,12 +1,10 @@
-=begin
-  Copyright (C) 2008 Sam Roberts
+# 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
+# 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
+# LICENSE-VPIM.txt for details.
 
-module Vpim
+module Vcard
 
   # 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
@@ -31,14 +29,14 @@ module Vpim
     # 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) || ''
+      format = field.pvalue(fmtparam) || ""
       kind = field.kind || defkind
       case kind
-      when 'text'
-        Inline.new(Vpim.decode_text(field.value), format)
-      when 'uri'
+      when "text"
+        Inline.new(::Vcard.decode_text(field.value), format)
+      when "uri"
         Uri.new(field.value_raw, format)
-      when 'binary'
+      when "binary"
         Inline.new(field.value, format)
       else
         raise InvalidEncodingError, "Attachment of type #{kind} is not allowed"

data/lib/vcard/bnf.rb

@@ -0,0 +1,66 @@
+# 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
+# LICENSE-VPIM.txt for details.
+
+module Vcard
+  # Contains regular expression strings for the EBNF of RFC 2425.
+  module Bnf #:nodoc:
+
+    # 1*(ALPHA / DIGIT / "-")
+    # Note: I think I can add A-Z here, and get rid of the "i" matches elsewhere.
+    # Note: added "_" to allowed because its produced by Notes  (X-LOTUS-CHILD_UID:)
+    # Note: added "/" to allowed because its produced by KAddressBook (X-messaging/xmpp-All:)
+    # Note: added " " to allowed because its produced by highrisehq.com (X-GOOGLE TALK:)
+    NAME    = "[-a-z0-9_/][-a-z0-9_/ ]*"
+
+    # <"> <Any character except CTLs, DQUOTE> <">
+    QSTR    = '"([^"]*)"'
+
+    # *<Any character except CTLs, DQUOTE, ";", ":", ",">
+    PTEXT   = '([^";:,]+)'
+
+    # param-value = ptext / quoted-string
+    PVALUE  = "(?:#{QSTR}|#{PTEXT})"
+
+    # param = name "=" param-value *("," param-value)
+    # Note: v2.1 allows a type or encoding param-value to appear without the type=
+    # or the encoding=. This is hideous, but we try and support it, if there
+    # is no "=", then $2 will be "", and we will treat it as a v2.1 param.
+    PARAM = ";(#{NAME})(=?)((?:#{PVALUE})?(?:,#{PVALUE})*)"
+
+    # V3.0: contentline  =   [group "."]  name *(";" param) ":" value
+    # V2.1: contentline  = *( group "." ) name *(";" param) ":" value
+    #
+    # We accept the V2.1 syntax for backwards compatibility.
+    #LINE = "((?:#{NAME}\\.)*)?(#{NAME})([^:]*)\:(.*)"
+    LINE = "^((?:#{NAME}\\.)*)?(#{NAME})((?:#{PARAM})*):(.*)$"
+
+    # date = date-fullyear ["-"] date-month ["-"] date-mday
+    # date-fullyear = 4 DIGIT
+    # date-month = 2 DIGIT
+    # date-mday = 2 DIGIT
+    DATE = "(\d\d\d\d)-?(\d\d)-?(\d\d)"
+
+    # time = time-hour [":"] time-minute [":"] time-second [time-secfrac] [time-zone]
+    # time-hour = 2 DIGIT
+    # time-minute = 2 DIGIT
+    # time-second = 2 DIGIT
+    # time-secfrac = "," 1*DIGIT
+    # time-zone = "Z" / time-numzone
+    # time-numzone = sign time-hour [":"] time-minute
+    TIME = "(\d\d):?(\d\d):?(\d\d)(\.\d+)?(Z|[-+]\d\d:?\d\d)?"
+
+    # integer = (["+"] / "-") 1*DIGIT
+    INTEGER = "[-+]?\d+"
+
+    # QSAFE-CHAR = WSP / %x21 / %x23-7E / NON-US-ASCII
+    #  ; Any character except CTLs and DQUOTE
+    QSAFECHAR = "[ \t\x21\x23-\x7e\x80-\xff]"
+
+    # SAFE-CHAR  = WSP / %x21 / %x23-2B / %x2D-39 / %x3C-7E / NON-US-ASCII
+    #   ; Any character except CTLs, DQUOTE, ";", ":", ","
+    SAFECHAR = "[ \t\x21\x23-\x2b\x2d-\x39\x3c-\x7e\x80-\xff]"
+  end
+end

data/lib/vcard/dirinfo.rb

@@ -1,12 +1,10 @@
-=begin
-  Copyright (C) 2008 Sam Roberts
+# 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
+# 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
+# LICENSE-VPIM.txt for details.
 
-module Vpim
+module Vcard
   # An RFC 2425 directory info object.
   #
   # A directory information object is a sequence of fields. The basic
@@ -19,13 +17,13 @@ module Vpim
   #
   # 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' )
+  #   card = Vcard::Vcard.create
+  #   card << Vcard::DirectoryInfo::Field.create("EMAIL", "user.name@example.com", "TYPE" => "INTERNET" )
+  #   card << Vcard::DirectoryInfo::Field.create("URL", "http://www.example.com/user" )
+  #   card << Vcard::DirectoryInfo::Field.create("FN", "User Name" )
   #   puts card.to_s
   #
-  # Don't do it like that, use Vpim::Vcard::Maker.
+  # Don't do it like that, use Vcard::Vcard::Maker.
   class DirectoryInfo
     include Enumerable
 
@@ -35,7 +33,7 @@ module Vpim
     # specified, check the BEGIN/END fields.
     def initialize(fields, profile = nil) #:nodoc:
       if fields.detect { |f| ! f.kind_of? DirectoryInfo::Field }
-        raise ArgumentError, 'fields must be an array of DirectoryInfo::Field objects'
+        raise ArgumentError, "fields must be an array of DirectoryInfo::Field objects"
       end
 
       @string = nil # this is used as a flag to indicate that recoding will be necessary
@@ -53,7 +51,7 @@ module Vpim
     # The lines in the string may be delimited using IETF (CRLF) or Unix (LF) conventions.
     #
     # A DirectoryInfo is mutable, you can add new fields to it, see
-    # Vpim::DirectoryInfo::Field#create() for how to create a new Field.
+    # Vcard::DirectoryInfo::Field#create() for how to create a new Field.
     #
     # TODO: I don't believe this is ever used, maybe I can remove it.
     def DirectoryInfo.decode(card) #:nodoc:
@@ -67,7 +65,7 @@ module Vpim
         raise ArgumentError, "DirectoryInfo cannot be created from a #{card.type}"
       end
 
-      fields = Vpim.decode(string)
+      fields = ::Vcard.decode(string)
 
       new(fields)
     end
@@ -84,9 +82,9 @@ module Vpim
 
       if profile
         p = profile.to_str
-        f = [ Field.create('BEGIN', p) ]
+        f = [ Field.create("BEGIN", p) ]
         f.concat fields
-        f.push Field.create('END', p)
+        f.push Field.create("END", p)
         fields = f
       end
 
@@ -103,7 +101,7 @@ module Vpim
     # The value of the first field named +name+, or nil if no
     # match is found.
     def [](name)
-      enum_by_name(name).each { |f| return f.value if f.value != ''}
+      enum_by_name(name).each { |f| return f.value if f.value != ""}
       enum_by_name(name).each { |f| return f.value }
       nil
     end
@@ -153,11 +151,11 @@ module Vpim
     #
     # Print all the nicknames in a card:
     #
-    #   card.enum_by_name('NICKNAME') { |f| puts f.value }
+    #   card.enum_by_name("NICKNAME") { |f| puts f.value }
     #
     # Print an Array of the preferred email addresses in the card:
     #
-    #   pref_emails = card.enum_by_name('EMAIL').select { |f| f.pref? }
+    #   pref_emails = card.enum_by_name("EMAIL").select { |f| f.pref? }
     def enum_by_name(name)
       Enumerator.new(self, Proc.new { |field| field.name?(name) })
     end
@@ -172,9 +170,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
@@ -224,8 +222,8 @@ module Vpim
     # the Vcard::Maker examples.
     def delete(field)
       case
-      when field.name?('BEGIN'), field.name?('END')
-        raise ArgumentError, 'Cannot delete BEGIN or END fields.'
+      when field.name?("BEGIN"), field.name?("END")
+        raise ArgumentError, "Cannot delete BEGIN or END fields."
       else
         @fields.delete field
       end
@@ -251,10 +249,10 @@ module Vpim
       unless @fields.first
         raise "No fields to check"
       end
-      unless @fields.first.name? 'BEGIN'
+      unless @fields.first.name? "BEGIN"
         raise "Needs BEGIN, found: #{@fields.first.encode nil}"
       end
-      unless @fields.last.name? 'END'
+      unless @fields.last.name? "END"
         raise "Needs END, found: #{@fields.last.encode nil}"
       end
       unless @fields.last.value? @fields.first.value

data/lib/vcard/enumerator.rb

@@ -1,12 +1,10 @@
-=begin
-  Copyright (C) 2008 Sam Roberts
+# 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
+# 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
+# LICENSE-VPIM.txt for details.
 
-module Vpim
+module Vcard
   # This is a way for an object to have multiple ways of being enumerated via
   # argument to it's #each() method. An Enumerator mixes in Enumerable, so the
   # standard APIs such as Enumerable#map(), Enumerable#to_a(), and

data/lib/vcard/errors.rb

@@ -0,0 +1,23 @@
+# 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
+# LICENSE-VPIM.txt for details.
+
+module Vcard
+  # 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

data/lib/vcard/field.rb

@@ -1,12 +1,10 @@
-=begin
-  Copyright (C) 2008 Sam Roberts
+# 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
+# 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.
 
-module Vpim
+module Vcard
 
   class DirectoryInfo
 
@@ -19,7 +17,7 @@ module Vpim
       #   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
+      # - 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.
@@ -37,14 +35,14 @@ module Vpim
       end
 
       # Encode a field.
-      def Field.encode0(group, name, params={}, value='') # :nodoc:
+      def Field.encode0(group, name, params={}, value="") # :nodoc:
         line = ""
 
         # A reminder of the line format:
         #   [<group>.]<name>;<pname>=<pvalue>,<pvalue>:<value>
 
         if group
-          line << group << '.'
+          line << group << "."
         end
 
         line << name
@@ -55,15 +53,15 @@ module Vpim
             pvalues = [ pvalues ]
           end
 
-          line << ';' << pname << '='
+          line << ";" << pname << "="
 
-          sep = "" # set to ',' after one pvalue has been appended
+          sep = "" # set to "," after one pvalue has been appended
 
           pvalues.each do |pvalue|
             # check if we need to do any encoding
-            if pname.casecmp('ENCODING') == 0 && pvalue == :b64
-              pvalue = 'B' # the RFC definition of the base64 param value
-              value = [ value.to_str ].pack('m').gsub("\n", '')
+            if pname.casecmp("ENCODING") == 0 && pvalue == :b64
+              pvalue = "B" # the RFC definition of the base64 param value
+              value = [ value.to_str ].pack("m").gsub("\n", "")
             end
 
             line << sep << pvalue
@@ -71,7 +69,7 @@ module Vpim
           end
         end
 
-        line << ':'
+        line << ":"
 
         line << Field.value_str(value)
 
@@ -79,16 +77,16 @@ module Vpim
       end
 
       def Field.value_str(value) # :nodoc:
-        line = ''
+        line = ""
         case value
         when Date
-          line << Vpim.encode_date(value)
+          line << ::Vcard.encode_date(value)
 
         when Time #, DateTime
-          line << Vpim.encode_date_time(value)
+          line << ::Vcard.encode_date_time(value)
 
         when Array
-          line << value.map { |v| Field.value_str(v) }.join(';')
+          line << value.map { |v| Field.value_str(v) }.join(";")
 
         when Symbol
           line << value
@@ -103,7 +101,7 @@ module Vpim
       # Decode a field.
       def Field.decode0(atline) # :nodoc:
         unless atline =~ %r{#{Bnf::LINE}}i
-          raise Vpim::InvalidEncodingError, atline
+          raise ::Vcard::InvalidEncodingError, atline
         end
 
         atgroup = $1.upcase
@@ -117,7 +115,7 @@ module Vpim
         atvalue.strip!
 
         if atgroup.length > 0
-          atgroup.chomp!('.')
+          atgroup.chomp!(".")
         else
           atgroup = nil
         end
@@ -134,21 +132,21 @@ module Vpim
             name = $1.upcase
             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'
+            # 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"
             # param).
 
             if $2 == ""
               params = $1
               case $1
               when /quoted-printable/i
-                name = 'ENCODING'
+                name = "ENCODING"
 
               when /base64/i
-                name = 'ENCODING'
+                name = "ENCODING"
 
               else
-                name = 'TYPE'
+                name = "TYPE"
               end
             end
 
@@ -188,16 +186,16 @@ 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:
       # - Time, encoded as a date-time value
       # - Date, encoded as a date value
       # - String, encoded directly
-      # - Array of String, concatentated with ';' between them.
+      # - Array of String, concatentated with ";" between them.
       #
       # TODO - need a way to encode String values as TEXT, at least optionally,
       # so as to escape special chars, etc.
@@ -206,7 +204,7 @@ module Vpim
 
         begin
           new(line)
-        rescue Vpim::InvalidEncodingError => e
+        rescue ::Vcard::InvalidEncodingError => e
           raise ArgumentError, e.to_s
         end
       end
@@ -236,7 +234,7 @@ module Vpim
           l = l.gsub(/.{#{width},#{width}}/) { |m| m + "\n " }
         end
         # Make sure it's terminated with no more than a single NL.
-        l.gsub(/\s*\z/, '') + "\n"
+        l.gsub(/\s*\z/, "") + "\n"
       end
 
       alias to_s encode
@@ -306,17 +304,17 @@ module Vpim
       #   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})"
+          raise ::Vcard::InvalidEncodingError, "unrecognized encoding (#{encoding})"
         end
       end
 
@@ -360,7 +358,7 @@ module Vpim
       def type?(type)
         type = type.to_str
 
-        types = param('TYPE')
+        types = param("TYPE")
 
         if types
           types = types.detect { |t| t.casecmp(type) == 0 }
@@ -368,18 +366,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
 
@@ -392,11 +390,11 @@ 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 ::Vcard::InvalidEncodingError, "multi-valued param 'ENCODING' (#{e})"
           end
           e = e.first.upcase
         end
@@ -406,7 +404,7 @@ 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})"
@@ -430,7 +428,7 @@ module Vpim
       # its ridiculous! I think I need my own DateTime variant.
       def to_time
         begin
-          Vpim.decode_date_time_list(value).collect do |d|
+          ::Vcard.decode_date_time_list(value).collect do |d|
             # We get [ year, month, day, hour, min, sec, usec, tz ]
             begin
               if(d.pop == "Z")
@@ -439,16 +437,16 @@ module Vpim
                 Time.local(*d)
               end
             rescue ArgumentError => e
-              raise Vpim::InvalidEncodingError, "Time.gm(#{d.join(', ')}) failed with #{e.message}"
+              raise ::Vcard::InvalidEncodingError, "Time.gm(#{d.join(', ')}) failed with #{e.message}"
             end
           end
-        rescue Vpim::InvalidEncodingError
-          Vpim.decode_date_list(value).collect do |d|
+        rescue ::Vcard::InvalidEncodingError
+          ::Vcard.decode_date_list(value).collect do |d|
             # We get [ year, month, day ]
             begin
               Time.gm(*d)
             rescue ArgumentError => e
-              raise Vpim::InvalidEncodingError, "Time.gm(#{d.join(', ')}) failed with #{e.message}"
+              raise ::Vcard::InvalidEncodingError, "Time.gm(#{d.join(', ')}) failed with #{e.message}"
             end
           end
         end
@@ -463,12 +461,12 @@ module Vpim
       # works an InvalidEncodingError will be raised.
       def to_date
         begin
-          Vpim.decode_date_time_list(value).collect do |d|
+          ::Vcard.decode_date_time_list(value).collect do |d|
             # We get [ year, month, day, hour, min, sec, usec, tz ]
             Date.new(d[0], d[1], d[2])
           end
-        rescue Vpim::InvalidEncodingError
-          Vpim.decode_date_list(value).collect do |d|
+        rescue ::Vcard::InvalidEncodingError
+          ::Vcard.decode_date_list(value).collect do |d|
             # We get [ year, month, day ]
             Date.new(*d)
           end
@@ -479,11 +477,11 @@ 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 'VALUE'
+      # 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
-        Vpim.decode_text(value)
+        ::Vcard.decode_text(value)
       end
 
       # The undecoded value, see +value+.
@@ -516,10 +514,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
@@ -597,7 +595,7 @@ module Vpim
         begin
           @group, @name, @params, @value = Field.decode0(line)
           @line = line
-        rescue Vpim::InvalidEncodingError => e
+        rescue ::Vcard::InvalidEncodingError => e
           raise ArgumentError, e.to_s
         end
         self