rwdaddresses 1.01 → 1.02

data/extras/vpim/dirinfo.rb

@@ -0,0 +1,229 @@
+=begin
+  $Id: dirinfo.rb,v 1.19 2004/11/17 05:06:27 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 'extras/vpim/enumerator'
+require 'extras/vpim/field'
+require 'extras/vpim/rfc2425'
+require 'extras/vpim/vpim'
+
+module Vpim
+  # An RFC 2425 directory info object.
+  #
+  # A directory information object is a sequence of fields. The basic
+  # structure of the object, and the way in which it is broken into fields
+  # is common to all profiles of the directory info type.
+  #
+  # A vCard, for example, is a specialization of a directory info object.
+  #
+  #  [RFC2425] the directory information framework (ftp://ftp.ietf.org/rfc/rfc2425.txt)
+  class DirectoryInfo
+    include Enumerable
+
+    private_class_method :new
+
+    # Initialize a DirectoryInfo object from +fields+. If +profile+ is
+    # 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'
+      end
+
+      @string = nil # this is used as a flag to indicate that recoding will be necessary
+      @fields = fields
+
+      check_begin_end(profile) if profile
+    end
+
+    # 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
+    # #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.
+    #
+    # A DirectoryInfo is mutable, you can add new fields to it, see
+    # Vpim::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:
+      if card.respond_to? :to_str
+        string = card.to_str
+      elsif card.kind_of? Array
+        string = card.join("\n")
+      elsif card.kind_of? IO
+        string = card.read(nil)
+      else
+        raise ArgumentError, "DirectoryInfo cannot be created from a #{card.type}"
+      end
+
+      fields = Vpim.decode(string)
+
+      new(fields)
+    end
+
+    # Create a new DirectoryInfo object. The +fields+ are an optional array of
+    # DirectoryInfo::Field objects to add to the new object, between the
+    # BEGIN/END.  If the +profile+ string is not nil, then it is the name of
+    # the directory info profile, and the BEGIN:+profile+/END:+profile+ fields
+    # will be added.
+    #
+    # A DirectoryInfo is mutable, you can add new fields to it using #push(),
+    # and see Field#create().
+    def DirectoryInfo.create(fields = [], profile = nil)
+
+      if profile
+        p = profile.to_str
+        f = [ Field.create('BEGIN', p) ]
+        f.concat fields
+        f.push Field.create('END', p)
+        fields = f
+      end
+      
+      new(fields, profile)
+    end
+
+    # The first field named +name+, or nil if no
+    # match is found.
+    def field(name)
+      enum_by_name(name).each { |f| return f }
+      nil
+    end
+
+    # 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 }
+      nil
+    end
+
+    # An array of all the values of fields named +name+, converted to text
+    # (using Field#to_text()).
+    #
+    # TODO - call this #texts(), as in the plural?
+    def text(name)
+      enum_by_name(name).map { |f| f.to_text }
+    end
+
+    # Array of all the Field#group()s.
+    def groups
+      @fields.collect { |f| f.group } .compact.uniq
+    end
+
+    # All fields, frozen.
+    def fields #:nodoc:
+      @fields.dup.freeze
+    end
+
+    # Yields for each Field for which +cond+.call(field) is true. The
+    # (default) +cond+ of nil is considered true for all fields, so
+    # this acts like a normal #each() when called with no arguments.
+    def each(cond = nil) # :yields: Field
+      @fields.each do |field|
+         if(cond == nil || cond.call(field))
+           yield field
+         end
+      end
+      self
+    end
+
+    # Returns an Enumerator for each Field for which #name?(+name+) is true.
+    #
+    # For example, to get an Array of all the email addresses in the card, you
+    # could do:
+    #
+    #   card.enum_by_name('email').collect { |f| f.value }
+    def enum_by_name(name)
+      Enumerator.new(self, Proc.new { |field| field.name?(name) })
+    end
+
+    # Returns an Enumerator for each Field for which #group?(+group+) is true.
+    #
+    # For example, to print all the fields, sorted by group, you could do:
+    #
+    #  card.groups.sort.each do |group|
+    #    card.enum_by_group(group).each do |field|
+    #    puts "#{group} -> #{field.name}"
+    #    end
+    #  end
+    #
+    # or to get an array of all the fields in group 'agroup', you could do:
+    # 
+    #  card.enum_by_group('agroup').to_a
+    def enum_by_group(group)
+      Enumerator.new(self, Proc.new { |field| field.group?(group) })
+    end
+
+    # Returns an Enumerator for each Field for which +cond+.call(field) is true.
+    def enum_by_cond(cond)
+      Enumerator.new(self, cond )
+    end
+
+    # Append +field+ to the fields. Note that it won't be literally appended
+    # to the fields, it will be inserted before the closing END field.
+    def push(field)
+      @fields[-1,0] = field
+      self
+    end
+
+    alias << push
+
+    # Push +field+ onto the fields, unless there is already a field
+    # with this name.
+    def push_unique(field)
+      push(field) unless @fields.detect { |f| f.name? field.name }
+      self
+    end
+
+    # Append +field+ to the end of all the fields. This isn't usually what you
+    # want to do, usually a DirectoryInfo's first and last fields are a
+    # BEGIN/END pair, see #push().
+    def push_end(field)
+      @fields << field
+      self
+    end
+
+    # The string encoding of the DirectoryInfo. See Field#encode for information
+    # about the width parameter.
+    def encode(width=nil)
+      unless @string
+        @string = @fields.collect { |f| f.encode(width) } . join ""
+      end
+      @string
+    end
+
+    alias to_s encode
+
+    # Check that the DirectoryInfo object is correctly delimited by a BEGIN
+    # and END, that their profile values match, and if +profile+ is specified, that 
+    # they are the specified profile.
+    def check_begin_end(profile=nil) #:nodoc:
+      unless @fields.first
+        raise "No fields to check"
+      end
+      unless @fields.first.name? "begin"
+        raise "Needs BEGIN, found: #{@fields.first.encode nil}"
+      end
+      unless @fields.last.name? "end"
+        raise "Needs END, found: #{@fields.last.encode nil}"
+      end
+      unless @fields.last.value? @fields.first.value
+        raise "BEGIN/END mismatch: (#{@fields.first.value.downcase} != #{@fields.last.value.downcase}"
+      end
+      if profile
+        if ! @fields.first.value? profile
+          raise "Mismatched profile"
+        end
+      end
+      true
+    end
+  end
+end
+

data/extras/vpim/enumerator.rb

@@ -0,0 +1,29 @@
+=begin
+  $Id: enumerator.rb,v 1.2 2004/11/17 05:06:27 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
+
+module Vpim
+  # 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
+  # Enumerable#find_all() can be used on it.
+  class Enumerator
+    include Enumerable
+
+    def initialize(obj, *args)
+      @obj = obj
+      @args = args
+    end
+
+    def each(&block)
+      @obj.each(*@args, &block)
+    end
+  end
+end
+