vcard 0.1.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,7 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg
+*.gem
+*.gemspec

data/LICENSE

@@ -0,0 +1,58 @@
+vPim is copyrighted free software by Sam Roberts <sroberts@uniserve.com>.
+
+You can redistribute it and/or modify it under either the terms of the GPL (see
+the file GPL), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise make them
+       Freely Available, such as by posting said modifications to Usenet or an
+       equivalent medium, or by allowing the author to include your
+       modifications in the software.
+
+       b) use the modified software only within your corporation or
+       organization.
+
+       c) give non-standard binaries non-standard names, with instructions on
+       where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or binary form,
+     provided that you do at least ONE of the following:
+
+       a) distribute the binaries and library files of the software, together
+       with instructions (in the manual page or equivalent) on where to get the
+       original distribution.
+
+       b) accompany the distribution with the machine-readable source of the
+       software.
+
+       c) give non-standard binaries non-standard names, with instructions on
+       where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under these terms.
+
+     For the list of those files and their copying conditions, see the
+     file LEGAL.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README.rdoc

@@ -0,0 +1,7 @@
+= vcard
+
+Description goes here.
+
+== Copyright
+
+Copyright (c) 2009 Jakub Kuźma. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,58 @@
+# encoding: UTF-8
+
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "vcard"
+    gem.summary = %Q{Vcard support extracted from Vpim (Ruby 1.9.1 compatible)}
+    gem.email = "qoobaa@gmail.com"
+    gem.homepage = "http://github.com/qoobaa/vcard"
+    gem.authors = ["Jakub Kuźma"]
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "vcard #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.1

data/lib/vcard.rb

@@ -0,0 +1,34 @@
+=begin
+  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
+
+#:main:README
+#:title:vPim - vCard and iCalendar support for Ruby
+module Vpim
+  # 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
+
+require "vcard/attachment"
+require "vcard/dirinfo"
+require "vcard/enumerator"
+require "vcard/field"
+require "vcard/rfc2425"
+require "vcard/vcard"

data/lib/vcard/attachment.rb

@@ -0,0 +1,100 @@
+=begin
+  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
+
+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/vcard/dirinfo.rb

@@ -0,0 +1,272 @@
+=begin
+  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
+
+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)
+  #
+  # 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
+
+    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 if f.value != ''}
+      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)
+      accum = []
+      each do |f|
+        if f.name? name
+          accum << f.to_text
+        end
+      end
+      accum
+    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.
+    #
+    # An Enumerator supports all the methods of Enumerable, so it allows iteration,
+    # collection, mapping, etc.
+    #
+    # Examples:
+    #
+    # Print all the nicknames in a card:
+    #
+    #   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? }
+    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
+
+    # Force card to be reencoded from the fields.
+    def dirty #:nodoc:
+      #string = nil
+    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)
+      dirty
+      @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
+
+    # Delete +field+.
+    #
+    # Warning: You can't delete BEGIN: or END: fields, but other
+    # 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 Vcard::Maker#copy, see
+    # the Vcard::Maker examples.
+    def delete(field)
+      case
+      when field.name?('BEGIN'), field.name?('END')
+        raise ArgumentError, 'Cannot delete BEGIN or END fields.'
+      else
+        @fields.delete field
+      end
+
+      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} != #{@fields.last.value}"
+      end
+      if profile
+        if ! @fields.first.value? profile
+          raise "Mismatched profile"
+        end
+      end
+      true
+    end
+  end
+end
+