vpim 0.17 → 0.323

data/lib/vpim/maker/vcard.rb~

@@ -1,382 +0,0 @@
-=begin
-  $Id: vcard.rb,v 1.7 2005/02/04 21:09:34 sam Exp $
-
-  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/vcard'
-
-module Vpim
-  module Maker
-    # A helper class to assist in building a vCard.
-    #
-    # Examples:
-    # - link:ex_mkvcard.txt: an example of making a vCard
-    # - link:ex_cpvcard.txt: an example of copying and modifying a vCard
-    #
-    # Note - The Maker module is modelled after rss/maker, but if a Vcard was
-    # mutable these methods could be added to Vpim::Vcard. Hm.
-    class Vcard
-      # Make a vCard for +full_name+.
-      #
-      # Yields +card+, a Vpim::Maker::Vcard to which fields can be added, and returns a Vpim::Vcard.
-      #
-      # Note that calling #add_name is required, all other fields are optional.
-      def Vcard.make(full_name, &block) # :yields: +card+
-        new(full_name).make(&block)
-      end
-
-      def make # :nodoc:
-        yield self
-        unless @card['N']
-          raise Vpim::InvalidEncodingError, 'It is mandatory to have a name field, see #add_name.'
-        end
-        @card
-      end
-
-      private
-
-      def initialize(full_name) # :nodoc:
-        @card = Vpim::Vcard::create
-        @card << Vpim::DirectoryInfo::Field.create('FN', full_name )
-        # pp @card
-      end
-
-      public
-
-      # Add an arbitrary Field, +field+.
-      def add_field(field)
-        fieldname = field.name.upcase
-        case
-        when [ 'BEGIN', 'END', 'VERSION' ].include?(fieldname)
-          raise Vpim::InvalidEncodingError, "Not allowed to manually add #{field.name} to a vCard."
-
-        when [ 'N', 'FN' ].include?(fieldname)
-          if @card.field(fieldname)
-            raise Vpim::InvalidEncodingError, "Not allowed to add more than one #{fieldname} to a vCard."
-          end
-          @card << field
-
-        else
-          @card << field
-        end
-      end
-
-      # Copy the fields from +card+ into self using #add_field. If a block is
-      # provided, each Field from +card+ is yielded. The block should return a
-      # Field to add, or nil.  The Field doesn't have to be the one yielded,
-      # this allows modified fields to be copied in (use Field#copy), or fields
-      # to be filtered out (if the block yields nil).
-      #
-      # The vCard fields BEGIN, END, VERSION aren't copied, and N and FN aren't copied
-      # if the target already has them
-      def copy(card) # :yields: Field
-        card.each do |field|
-          fieldname = field.name.upcase
-          case
-          when [ 'BEGIN', 'END', 'VERSION' ].include?(fieldname)
-            # Never copy these
-
-          when [ 'N', 'FN' ].include?(fieldname) && @card.field(fieldname)
-            # Copy these only if they don't already exist.
-
-          else
-            if block_given?
-              field = yield field
-            end
-
-            if field
-              add_field(field)
-            end
-          end
-        end
-      end
-
-      # Add a name field, N.
-      #
-      # Warning: This is the only mandatory field, besides the full name, which
-      # is added from Vcard.make's +full_name+.
-      #
-      # Attributes of N are:
-      # - family: family name
-      # - given: given name
-      # - additional: additional names
-      # - prefix: such as "Ms." or "Dr."
-      # - suffix: such as "BFA", or "Sensei"
-      #
-      # All attributes are optional.
-      #
-      # 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.
-      def add_name # :yield: n
-        x = Struct.new(:family, :given, :additional, :prefix, :suffix).new
-        yield x
-        @card << Vpim::DirectoryInfo::Field.create(
-          'N',
-          x.map { |s| s ? s.to_str : '' }
-          )
-        self
-      end
-
-      # Add a address field, ADR.
-      #
-      # Attributes of ADR that describe the address are:
-      # - pobox: post office box
-      # - extended: seldom used, its not clear what it is for
-      # - street: street address, multiple components should be separated by a comma, ','
-      # - locality: usually the city
-      # - region: usually the province or state
-      # - postalcode: postal code
-      # - country: country name, no standard for country naming is specified
-      #
-      # Attributes that describe how the address is used, and customary values, are:
-      # - location: home, work - often used, can be set to other values
-      # - preferred: true - often used, set if this is the preferred address
-      # - delivery: postal, parcel, dom (domestic), intl (international) - rarely used
-      #
-      # All attributes are optional. #location and #home can be set to arrays of
-      # strings.
-      #
-      # TODO: Add #label to support LABEL.
-      #
-      # FIXME: Need to escape specials in the String.
-      def add_addr # :yield: adr
-        x = Struct.new(
-          :location, :preferred, :delivery,
-          :pobox, :extended, :street, :locality, :region, :postalcode, :country
-          ).new
-        yield x
-
-        values = x.to_a[3, 7].map { |s| s ? s.to_str : '' }
-
-        # All these attributes go into the TYPE parameter.
-        params = [ x[:location], x[:delivery] ]
-        params << 'pref' if x[:preferred]
-        params = params.flatten.uniq.compact.map { |s| s.to_str }
-
-        paramshash = {}
-
-        paramshash['type'] = params if params.first
-
-        @card << Vpim::DirectoryInfo::Field.create( 'ADR', values, paramshash)
-        self
-      end
-
-      # Add a telephone number field, TEL.
-      #
-      # +number+ is supposed to be a "X.500 Telephone Number" according to RFC 2426, if you happen
-      # to be familiar with that. Otherwise, anything that looks like a phone number should be OK.
-      # 
-      # Attributes of TEL are:
-      # - location: home, work, msg, cell, car, pager - often used, can be set to other values
-      # - preferred: true - often used, set if this is the preferred telephone number
-      # - capability: voice,fax,video,bbs,modem,isdn,pcs - fax is useful, the others are rarely used
-      #
-      # All attributes are optional, and so is the block.
-      def add_tel(number) # :yield: tel
-        params = {}
-        if block_given?
-          x = Struct.new( :location, :preferred, :capability ).new
-
-          yield x
-
-          x[:preferred] = 'pref' if x[:preferred]
-
-          types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
-
-          params['type'] = types if types.first
-        end
-
-        @card << Vpim::DirectoryInfo::Field.create( 'TEL', number, params)
-        self
-      end
-
-      # Add a email address field, EMAIL.
-      #
-      # Attributes of EMAIL are:
-      # - location: home, work - often used, can be set to other values
-      # - preferred: true - often used, set if this is the preferred email address
-      # - protocol: internet,x400 - internet is the default, set this for other kinds
-      #
-      # All attributes are optional, and so is the block.
-      def add_email(email) # :yield: email
-        params = {}
-        if block_given?
-          x = Struct.new( :location, :preferred, :protocol ).new
-
-          yield x
-
-          x[:preferred] = 'pref' if x[:preferred]
-
-          types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
-
-          params['type'] = types if types.first
-        end
-
-        @card << Vpim::DirectoryInfo::Field.create( 'EMAIL', email, params)
-        self
-      end
-
-      # Add a nickname field, NICKNAME.
-      def nickname=(nickname)
-        @card << Vpim::DirectoryInfo::Field.create( 'NICKNAME', nickname );
-      end
-
-      # Add a birthday field, BDAY.
-      #
-      # +birthday+ must be a time or date object.
-      #
-      # Warning: It may confuse both humans and software if you add multiple
-      # birthdays.
-      def birthday=(birthday)
-        if !birthday.respond_to? :month
-          raise Vpim::InvalidEncodingError, 'birthday doesn\'t have #month, so it is not a date or time object.'
-        end
-        @card << Vpim::DirectoryInfo::Field.create( 'BDAY', birthday );
-      end
-=begin
-TODO - need text=() implemented in Field
-
-      # Add a note field, NOTE. It can contain newlines, they will be escaped.
-      def note=(note)
-        @card << Vpim::DirectoryInfo::Field.create( 'NOTE', note );
-      end
-=end
-
-      # Add an instant-messaging/point of presence address field, IMPP. The address
-      # is a URL, with the syntax depending on the protocol.
-      #
-      # Attributes of IMPP are:
-      # - preferred: true - set if this is the preferred address
-      # - location: home, work, mobile - location of address
-      # - purpose: personal,business - purpose of communications
-      #
-      # All attributes are optional, and so is the block.
-      #
-      # The URL syntaxes for the messaging schemes is fairly complicated, so I
-      # don't try and build the URLs here, maybe in the future. This forces
-      # the user to know the URL for their own address, hopefully not too much
-      # of a burden.
-      #
-      # IMPP is defined in draft-jennings-impp-vcard-04.txt. It refers to the
-      # URI scheme of a number of messaging protocols, but doesn't give
-      # references to all of them:
-      # - "xmpp" indicates to use XMPP, draft-saintandre-xmpp-uri-06.txt
-      # - "irc" or "ircs" indicates to use IRC, draft-butcher-irc-url-04.txt
-      # - "sip" indicates to use SIP/SIMPLE, RFC 3261
-      # - "im" or "pres" indicates to use a CPIM or CPP gateway, RFC 3860 and RFC 3859
-      # - "ymsgr" indicates to use yahoo
-      # - "msn" might indicate to use Microsoft messenger
-      # - "aim" indicates to use AOL
-      #
-      def add_impp(url) # :yield: impp
-        params = {}
-
-        if block_given?
-          x = Struct.new( :location, :preferred, :purpose ).new
-
-          yield x
-
-          x[:preferred] = 'pref' if x[:preferred]
-
-          types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
-
-          params['type'] = types if types.first
-        end
-
-        @card << Vpim::DirectoryInfo::Field.create( 'IMPP', url, params)
-        self
-      end
-
-      # Add an Apple style AIM account name, +xaim+ is an AIM screen name.
-      #
-      # I don't know if this is conventional, or supported by anything other
-      # than AddressBook.app, but an example is:
-      #   X-AIM;type=HOME;type=pref:exampleaccount
-      #
-      # Attributes of X-AIM are:
-      # - preferred: true - set if this is the preferred address
-      # - location: home, work, mobile - location of address
-      #
-      # All attributes are optional, and so is the block.
-      def add_x_aim(xaim) # :yield: xaim
-        params = {}
-
-        if block_given?
-          x = Struct.new( :location, :preferred ).new
-
-          yield x
-
-          x[:preferred] = 'pref' if x[:preferred]
-
-          types = x.to_a.flatten.uniq.compact.map { |s| s.to_str }
-
-          params['type'] = types if types.first
-        end
-
-        @card << Vpim::DirectoryInfo::Field.create( 'X-AIM', xaim, params)
-        self
-      end
-
-
-      # Add a photo field, PHOTO.
-      #
-      # Attributes of PHOTO are:
-      # - image: set to image data to inclue inline
-      # - link: set to the URL of the image data
-      # - type: string identifying the image type, supposed to be an "IANA registered image format",
-      #     or a non-registered image format (usually these start with an x-)
-      #
-      # An error will be raised if neither image or link is set, or if both image
-      # and link is set.
-      #
-      # Setting type is optional for a link image, because either the URL, the
-      # image file extension, or a HTTP Content-Type may specify the type. If
-      # it's not a link, setting type is mandatory, though it can be set to an
-      # empty string, <code>''</code>, if the type is unknown.
-      #
-      # TODO - I'm not sure about this API. I'm thinking maybe it should be
-      # #add_photo(image, type), and that I should detect when the image is a
-      # URL, and make type mandatory if it wasn't a URL.
-      def add_photo # :yield: photo
-        x = Struct.new(:image, :link, :type).new
-        yield x
-        if x[:image] && x[:link]
-          raise Vpim::InvalidEncodingError, 'Image is not allowed to be both inline and a link.'
-        end
-
-        value = x[:image] || x[:link]
-
-        if !value
-          raise Vpim::InvalidEncodingError, 'A image link or inline data must be provided.'
-        end
-
-        params = {}
-
-        # Don't set type to the empty string.
-        params['type'] = x[:type] if( x[:type] && x[:type].length > 0 )
-
-        if x[:link]
-          params['value'] = 'uri'
-        else # it's inline, base-64 encode it
-          params['encoding'] = :b64
-          if !x[:type]
-            raise Vpim::InvalidEncodingError, 'Inline image data must have it\'s type set.'
-          end
-        end
-
-        @card << Vpim::DirectoryInfo::Field.create( 'PHOTO', value, params )
-        self
-      end
-
-    end
-  end
-end
-

data/lib/vpim/rfc2425.rb~

@@ -1,246 +0,0 @@
-=begin
-  $Id: rfc2425.rb,v 1.10 2005/01/01 17:17:01 sam Exp $
-
-  Copyright (C) 2005 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/vpim'
-
-module Vpim
-  # 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
-    NAME    = '[-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-numzome = sign time-hour [":"] time-minute
-    TIME = '(\d\d):?(\d\d):?(\d\d)(\.\d+)?(Z|[-+]\d\d:?\d\d)?'
-  end
-end
-
-module Vpim
-  # Split on \r\n or \n to get the lines, unfold continued lines (they
-  # start with ' ' or \t), and return the array of unfolded lines.
-  #
-  # This also supports the (invalid) encoding convention of allowing empty
-  # lines to be inserted for readability - it does this by dropping zero-length
-  # lines.
-  def Vpim.unfold(card) #:nodoc:
-      unfolded = []
-
-      card.each do |line|
-        line.chomp!
-        # If it's a continuation line, add it to the last.
-        # If it's an empty line, drop it from the input.
-        if( line =~ /^[ \t]/ )
-          unfolded[-1] << line[1, line.size-1]
-        elsif( line =~ /^$/ )
-        else
-          unfolded << line
-        end
-      end
-
-      unfolded
-  end
-
-  # Convert a +sep+-seperated list of values into an array of values.
-  def Vpim.decode_list(value, sep = ',') # :nodoc:
-    list = []
-    
-    value.each(sep) {
-      |item|
-      list << yield(item) unless item =~ %r{^\s*#{sep}?$}
-    }
-    list
-  end
-
-  # Convert a RFC 2425 date into an array of [year, month, day].
-  def Vpim.decode_date(v) # :nodoc:
-    unless v =~ %r{\s*#{Bnf::DATE}\s*}
-      raise Vpim::InvalidEncodingError, "date not valid (#{v})"
-    end
-    [$1.to_i, $2.to_i, $3.to_i]
-  end
-
-  # Note in the following the RFC2425 allows yyyy-mm-ddThh:mm:ss, but RFC2445
-  # does not. I choose to encode to the subset that is valid for both.
-
-  # Encode a Date object as "yyyymmdd".
-  def Vpim.encode_date(d) # :nodoc:
-     "%0.4d%0.2d%0.2d" % [ d.year, d.mon, d.day ]
-  end
-
-  # Encode a Date object as "yyyymmdd".
-  def Vpim.encode_time(d) # :nodoc:
-     "%0.4d%0.2d%0.2d" % [ d.year, d.mon, d.day ]
-  end
-
-  # Encode a Time or DateTime object as "yyyymmddThhmmss"
-  def Vpim.encode_date_time(d) # :nodoc:
-     "%0.4d%0.2d%0.2dT%0.2d%0.2d%0.2d" % [ d.year, d.mon, d.day, d.hour, d.min, d.sec ]
-  end
-
-  # Convert a RFC 2425 time into an array of [hour,min,sec,secfrac,timezone]
-  def Vpim.decode_time(v) # :nodoc:
-    unless match = %r{\s*#{Bnf::TIME}\s*}.match(v)
-      raise Vpim::InvalidEncodingError, "time not valid (#{v})"
-    end
-    hour, min, sec, secfrac, tz = match.to_a[1..5]
-
-    [hour.to_i, min.to_i, sec.to_i, secfrac ? secfrac.to_f : 0, tz]
-  end
-
-  # Convert a RFC 2425 date-time into an array of [hour,min,sec,secfrac,timezone]
-  def Vpim.decode_date_time(v) # :nodoc:
-    unless match = %r{\s*#{Bnf::DATE}T#{Bnf::TIME}\s*}.match(v)
-      raise Vpim::InvalidEncodingError, "date-time '#{v}' not valid"
-    end
-    year, month, day, hour, min, sec, secfrac, tz = match.to_a[1..8]
-
-    [
-      # date
-      year.to_i, month.to_i, day.to_i,
-      # time
-      hour.to_i, min.to_i, sec.to_i, secfrac ? secfrac.to_f : 0, tz
-    ]
-  end
-
-  # Vpim.decode_boolean
-  #
-  # float
-  #
-  # float_list
-  #
-  # integer
-  #
-  # integer_list
-  #
-  # text_list
-
-  # Convert a RFC 2425 date-list into an array of dates.
-  def Vpim.decode_date_list(v) # :nodoc:
-    dates = Vpim.decode_list(v) { |date| Vpim.decode_date(date) }
-  end
-
-  # Convert a RFC 2425 time-list into an array of times.
-  def Vpim.decode_time_list(v) # :nodoc:
-    times = Vpim.decode_list(v) { |time| Vpim.decode_time(time) }
-  end
-
-  # Convert a RFC 2425 date-time-list into an array of date-times.
-  def Vpim.decode_date_time_list(v) # :nodoc:
-    datetimes = Vpim.decode_list(v) { |datetime| Vpim.decode_date_time(datetime) }
-  end
-
-  # Convert RFC 2425 text into a String.
-  # \\ -> \
-  # \n -> NL
-  # \N -> NL
-  # \, -> ,
-  def Vpim.decode_text(v) # :nodoc:
-    v.gsub(/\\[nN]/, "\n").gsub(/\\,/, ",").gsub(/\\\\/) { |m| "\\" }
-  end
-
-
-  # Unfold the lines in +card+, then return an array of one Field object per
-  # line.
-  def Vpim.decode(card) #:nodoc:
-      content = Vpim.unfold(card).collect { |line| DirectoryInfo::Field.decode(line) }
-  end
-
-
-  # Expand an array of fields into its syntactic entities. Each entity is a sequence
-  # of fields where the sequences is delimited by a BEGIN/END field. Since
-  # BEGIN/END delimited entities can be nested, we build a tree. Each entry in
-  # the array is either a Field or an array of entries (where each entry is
-  # either a Field, or an array of entries...).
-  def Vpim.expand(src) #:nodoc:
-    # output array to expand the src to
-    dst = []
-    # stack used to track our nesting level, as we see begin/end we start a
-    # new/finish the current entity, and push/pop that entity from the stack
-    current = [ dst ]
-
-    for f in src
-      if f.name? 'begin'
-        e = [ f ]
-
-        current.last.push(e)
-        current.push(e)
-
-      elsif f.name? 'end'
-        current.last.push(f)
-
-        unless current.last.first.value? current.last.last.value
-          raise "BEGIN/END mismatch (#{current.last.first.value} != #{current.last.last.value})"
-        end
-
-        current.pop
-
-      else
-        current.last.push(f)
-      end
-    end
-
-    dst
-  end
-
-  # Split an array into an array of all the fields at the outer level, and
-  # an array of all the inner arrays of fields. Return the array [outer,
-  # inner].
-  def Vpim.outer_inner(fields) #:nodoc:
-    # seperate into the outer-level fields, and the arrays of component
-    # fields
-    outer = []
-    inner = []
-    fields.each do |line|
-      case line
-      when Array; inner << line
-      else;       outer << line
-      end
-    end
-    return outer, inner
-  end
-
-end
-