mwhuss-contact_csv 0.2.0

data/History.txt

@@ -0,0 +1,10 @@
+== 0.2.0 2008-02-07
+
+* 1 major enhancement
+  * Removed the Importer class because it wasn't needed. Added the functionality to the ContactManager class
+  * Beefed up the documentation
+
+== 0.1.0 2008-02-05
+
+* 1 major enhancement:
+  * Initial release

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Marshall Huss
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,33 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+config/hoe.rb
+config/requirements.rb
+lib/contact_csv.rb
+lib/contact_csv/contact.rb
+lib/contact_csv/contact_csv.rb
+lib/contact_csv/contact_manager.rb
+lib/contact_csv/lookup_tables/lookup_table.rb
+lib/contact_csv/lookup_tables/outlook_csv.rb
+lib/contact_csv/lookup_tables/outlook_doc_csv.rb
+lib/contact_csv/version.rb
+script/destroy
+script/generate
+script/txt2html
+setup.rb
+tasks/deployment.rake
+tasks/environment.rake
+tasks/website.rake
+test/outlook_contacts.csv
+test/outlook_contacts_dos.csv
+test/test_contact.rb
+test/test_contact_manager.rb
+test/test_helper.rb
+test/test_lookup_table.rb
+website/index.html
+website/index.txt
+website/javascripts/rounded_corners_lite.inc.js
+website/stylesheets/screen.css
+website/template.rhtml

data/README.txt

@@ -0,0 +1,63 @@
+# === ContactCsv
+#
+# ==== Supported CSV
+#   * Outlook 2003 CSV (Windows)
+# 
+# ==== Reading in CSV
+#
+#   To import contacts you use a ContactManager...
+#
+#
+#   contact_manager = ContactCsv::ContactManager.new
+#
+#   contact_manager.read('/path/to/file.csv')
+#   or
+#   contact_manager.parse('csv,data,string')
+#
+#
+# ==== Getting the contacts
+#
+#   contact_manager.contacts.each do |contact|
+#     puts contact.name
+#     puts contact.email
+#     puts contact.extras['Spouse']
+#   end
+#
+#   See the Contact class for a complete list of attributes.
+#
+#
+# ==== Lookup Tables
+#
+#   A lookup table is used to map the csv columns to Contact class attributes. You can create your own lookup tables
+#   by using the LookupTable class and passing it in inside an array to the ContactManager class.
+#
+#   # These are the column headers in the csv
+#   headers = ["First Name","Last Name","Email Address"]
+#
+#   # These map the column headers to the attribute of the Contact class
+#   legend = { 
+#     'First Name'    => :first_name,
+#     'Last Name '    => :last_name,
+#     'Email Address' => :email
+#   }
+#
+#   lookup_table = LookupTable.new(headers, legend)
+#
+#   # The lookup table is passed into the ContactManager
+#   contact_manager = ContactCsv::ContactManager.new([lookup_table])
+#   or
+#   contact_manager.lookup_tables << lookup_table
+#
+#
+#   If you think you have composed a good lookup table email it to me (mwhuss@gmail.com) and I will include it in the gem.
+#
+#
+# ==== To Do
+#  * Add lookup table for Outlook 2003 CSV (DOS)
+#  * Add lookup table for GMail CSV
+#
+#
+#
+
+
+

data/Rakefile

@@ -0,0 +1,4 @@
+require 'config/requirements'
+require 'config/hoe' # setup Hoe + all gem configuration
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/config/hoe.rb

@@ -0,0 +1,71 @@
+require 'contact_csv/version'
+
+AUTHOR = 'Marshall Huss'  # can also be an array of Authors
+EMAIL = "mwhuss@gmail.com"
+DESCRIPTION = "Simple gem for reading in contact csv files that you can export from email clients like Outlook or GMail"
+GEM_NAME = 'contact_csv' # what ppl will type to install your gem
+RUBYFORGE_PROJECT = 'contactcsv' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+RUBYFORGE_USERNAME = "mwhuss"
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  RUBYFORGE_USERNAME.replace @config["username"]
+end
+
+
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = ContactCsv::VERSION::STRING + (REV ? ".#{REV}" : "")
+RDOC_OPTS = ['--quiet', '--title', 'contact_csv documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject! { |x| Array(x).first == 'hoe' } 
+    @extra_deps
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.developer(AUTHOR, EMAIL)
+  p.description = DESCRIPTION
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = [ ['fastercsv'] ]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+  
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\\n\\n")
+#PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+PATH    = RUBYFORGE_PROJECT
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+hoe.rsync_args = '-av --delete --ignore-errors'

data/config/requirements.rb

@@ -0,0 +1,17 @@
+require 'fileutils'
+include FileUtils
+
+require 'rubygems'
+%w[rake hoe newgem rubigen].each do |req_gem|
+  begin
+    require req_gem
+  rescue LoadError
+    puts "This Rakefile requires the '#{req_gem}' RubyGem."
+    puts "Installation: gem install #{req_gem} -y"
+    exit
+  end
+end
+
+$:.unshift(File.join(File.dirname(__FILE__), %w[.. lib]))
+
+require 'contact_csv'

data/lib/contact_csv.rb

@@ -0,0 +1,9 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'rubygems'
+require 'fastercsv'
+require 'contact_csv/contact_csv.rb'
+require 'contact_csv/contact.rb'
+require 'contact_csv/contact_manager.rb'
+require 'contact_csv/lookup_tables/lookup_table.rb'
+require 'contact_csv/lookup_tables/outlook_csv.rb'

data/lib/contact_csv/contact.rb

@@ -0,0 +1,36 @@
+# === Contact
+#
+#   Object that represents a Contact from an address book. This class is meant to support the most common attributes.
+#
+class ContactCsv::Contact
+  
+  attr_accessor :first_name, :middle_name, :last_name, :email, :title, :extras
+  
+  # Initializes a Contact objest and will take a hash of the attributes with values
+  #
+  # Contact.new(:first_name => "Willy", :last_name => "Wonka") 
+  def initialize(attributes={})
+    @extras = {}
+    @first_name = attributes[:first_name]
+    @middle_name = attributes[:middle_name]
+    @last_name = attributes[:last_name]
+    @email = attributes[:email]
+    @title = attributes[:title]
+  end
+  
+  # Returns a hash of all attributes that could not be mapped to a Contact class attribute
+  def extras
+    @extras
+  end
+  
+  # Adds an unmappable attribute
+  def add_extra(extra)
+    @extras.merge!(extra)
+  end
+  
+  # First name and last name
+  def full_name
+    [@first_name, @last_name].join(' ')
+  end
+  
+end

data/lib/contact_csv/contact_csv.rb

@@ -0,0 +1,4 @@
+module ContactCsv
+  module LookupTables
+  end
+end

data/lib/contact_csv/contact_manager.rb

@@ -0,0 +1,61 @@
+# === ContctManager
+#
+#  The ContactManager handles finding the appropriate lookup table and creating the array of Contact objects
+#
+#
+class ContactCsv::ContactManager
+  include ContactCsv
+  include ContactCsv::LookupTables
+  
+  attr_accessor :contacts, :lookup_tables
+  
+  # Initializes a ContactManager, accepts an Array of LookupTables
+  def initialize(lookup_tables=[])
+    @lookup_tables = lookup_tables + [OutlookCsv.lookup_table]
+    @contacts = []
+  end
+  
+  # Reads a CSV file and creates a contact list
+  def read(file_path)
+    csv = FasterCSV.read(file_path, :headers => true)
+    create_contacts(csv)
+  end
+
+  # Reads a CSV string and creates a contact list
+  def parse(csv_string)
+    csv = FasterCSV.parse(csv_string, :headers => true)
+    create_contacts(csv)
+  end
+  
+  
+  private
+  
+  # Creates a contact list from a CSV object
+  def create_contacts(csv)
+    @contacts = []
+    lookup_table = find_lookup_table(csv, lookup_tables)
+    raise LookupTableNotFoundError if lookup_table.nil?
+    csv.each do |row|
+      c = Contact.new
+      row.each do |r|
+        col = lookup_table.lookup(r[0])
+        c.send("#{col.to_s}=", r[1]) if !col.nil? && c.respond_to?(col.to_sym)
+        c.add_extra({ r[0] => r[1] })
+      end
+      @contacts << c
+    end
+  end
+  
+  
+  # Determines the lookup table that matches the file
+  def find_lookup_table(csv, lookup_tables)
+    tables = lookup_tables + [OutlookCsv.lookup_table]
+    tables.each do |table|
+      return table if table.headers == csv.headers
+    end
+    return nil
+  end
+  
+  class LookupTableNotFoundError < StandardError; end
+
+end

data/lib/contact_csv/lookup_tables/lookup_table.rb

@@ -0,0 +1,27 @@
+# === LookupTable
+#
+#  This class is so users can define their own lookup tables if it isn't supported natively. The headers is an 
+#  Array of Strings that define the column names for the CSV file. Legend is a hash that maps the column strings 
+#  to a Contact class attribute. Look at the Contact class for a list of available attributes.  
+#
+#
+class ContactCsv::LookupTables::LookupTable
+  
+  attr_accessor :legend, :headers
+
+  # Initializes a LookupTable taking an Array of headers and a Hash that maps the column headers to the Contact object attributes
+  def initialize(headers, legend)
+    raise InvalidInputFormatError unless headers.is_a?(Array) && legend.is_a?(Hash)
+    @headers = headers
+    @legend = legend
+  end
+
+
+  # Returns the corresponding Contact attribute mapped to the specific Outlook CSV column name
+  def lookup(column)
+    @legend[column]
+  end
+  
+  class InvalidInputFormatError < StandardError; end
+  
+end

data/lib/contact_csv/lookup_tables/outlook_csv.rb

@@ -0,0 +1,116 @@
+# === OutlookCsv
+#
+#  Basic class to define the headers and legend for reading Outlook 2003 CSV (Windows) files
+#
+#
+class ContactCsv::LookupTables::OutlookCsv
+   include ContactCsv::LookupTables
+   
+   # Returns a Hash of how the columns map to the Contact attributes
+   def self.legend
+     {
+       'Title'               => :title,
+       'First Name'          => :first_name,
+       'Middle Name'         => :middle_name,
+       'Last Name'           => :last_name,
+       'E-mail Address'      => :email
+     }
+   end 
+  
+  # Returns an Array of all the headers for a Outlook CSV file
+  def self.headers
+    [ "Title",
+      "First Name",
+      "Middle Name",
+      "Last Name",
+      "Suffix",
+      "Company",
+      "Department",
+      "Job Title",
+      "Business Street",
+      "Business Street 2",
+      "Business Street 3",
+      "Business City",
+      "Business State",
+      "Business Postal Code",
+      "Business Country",
+      "Home Street",
+      "Home Street 2",
+      "Home Street 3",
+      "Home City",
+      "Home State",
+      "Home Postal Code",
+      "Home Country",
+      "Other Street",
+      "Other Street 2",
+      "Other Street 3",
+      "Other City",
+      "Other State",
+      "Other Postal Code",
+      "Other Country",
+      "Assistant's Phone",
+      "Business Fax",
+      "Business Phone",
+      "Business Phone 2",
+      "Callback",
+      "Car Phone",
+      "Company Main Phone",
+      "Home Fax","Home Phone",
+      "Home Phone 2",
+      "ISDN",
+      "Mobile Phone",
+      "Other Fax",
+      "Other Phone",
+      "Pager",
+      "Primary Phone",
+      "Radio Phone",
+      "TTY/TDD Phone",
+      "Telex","Account",
+      "Anniversary",
+      "Assistant's Name",
+      "Billing Information",
+      "Birthday",
+      "Business Address PO Box",
+      "Categories","Children",
+      "Directory Server",
+      "E-mail Address",
+      "E-mail Type",
+      "E-mail Display Name",
+      "E-mail 2 Address",
+      "E-mail 2 Type",
+      "E-mail 2 Display Name",
+      "E-mail 3 Address",
+      "E-mail 3 Type",
+      "E-mail 3 Display Name",
+      "Gender",
+      "Government ID Number",
+      "Hobby",
+      "Home Address PO Box",
+      "Initials",
+      "Internet Free Busy",
+      "Keywords","Language",
+      "Location",
+      "Manager's Name",
+      "Mileage",
+      "Notes",
+      "Office Location",
+      "Organizational ID Number",
+      "Other Address PO Box",
+      "Priority","Private",
+      "Profession",
+      "Referred By",
+      "Sensitivity",
+      "Spouse",
+      "User 1",
+      "User 2",
+      "User 3",
+      "User 4",
+      "Web Page"]
+  end
+
+  # Returns a LookupTable object
+  def self.lookup_table
+    LookupTable.new(self.headers, self.legend)
+  end
+
+end