b2b2dot0-fastercsv 1.4.1

data/INSTALL

@@ -0,0 +1,35 @@
+= Installing FasterCSV
+
+RubyGems is the preferred easy install method for FasterCSV.  However, you can
+install FasterCSV manually as described below.
+
+== Installing the Gem
+
+FasterCSV is intended to be installed via the
+RubyGems[http://rubyforge.org/projects/rubygems/] system.  To get the latest
+version, simply enter the following into your command prompt:
+
+	$ sudo gem install fastercsv
+
+You must have RubyGems[http://rubyforge.org/projects/rubygems/] installed for
+the above to work.
+
+== Installing Manually
+
+Download the latest version of FasterCSV from the
+{RubyForge project page}[http://rubyforge.org/frs/?group_id=1102].  Navigate to
+the root project directory and enter:
+
+	$ sudo ruby setup.rb
+
+== Running the Tests
+
+If you would like to run FasterCSV's test suite on your system before installing
+and you have Rake installed, just issue the following command from the root of
+the project directory:
+
+  $ rake
+
+If you do not have rake, use the following command instead:
+
+  $ ruby -I lib:test test/ts_all.rb

data/LICENSE

@@ -0,0 +1,7 @@
+= License Terms
+
+Distributed under the user's choice of the {GPL Version 2}[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html] (see COPYING for details) or the
+{Ruby software license}[http://www.ruby-lang.org/en/LICENSE.txt] by
+James Edward Gray II.
+
+Please email James[mailto:james@grayproductions.net] with any questions.

data/README.md

@@ -0,0 +1,73 @@
+[![Build Status](https://travis-ci.org/b2b2dot0/fastercsv.png)](https://travis-ci.org/b2b2dot0/fastercsv)
+
+# Read Me
+
+by James Edward Gray II
+
+## Description
+
+Welcome to FasterCSV.
+
+FasterCSV is intended as a replacement to Ruby's standard CSV library.  It was designed to address concerns users of that library had and it has three primary goals:
+
+1.  Be significantly faster than CSV while remaining a pure Ruby library.
+2.  Use a smaller and easier to maintain code base.  (FasterCSV is larger now, 
+    but considerably richer in features.  The parsing core remains quite small.)
+3.  Improve on the CSV interface.
+
+Obviously, the last one is subjective.  If you love CSV's interface, odds are
+good this one won't suit you.  I did try to defer to that interface whenever I
+didn't have a compelling reason to change it though, so hopefully this won't be
+too radically different.
+
+## What's Different From CSV?
+
+I'm sure I'll miss something, but I'll try to mention most of the major differences I am aware of, to help others quickly get up to speed:
+
+### CSV Parsing
+
+* FasterCSV has a stricter parser and will throw MalformedCSVErrors on
+  problematic data.
+* FasterCSV has a less liberal idea of a line ending than CSV.  What you set as
+  the <tt>:row_sep</tt> is law.
+* CSV returns empty lines as <tt>[nil]</tt>.  FasterCSV calls them <tt>[]</tt>.
+* FasterCSV has a much faster parser.
+
+### Interface
+
+* FasterCSV uses Hash-style parameters to set options.
+* FasterCSV does not have generate_row() or parse_row() from CSV.
+* FasterCSV does not have CSV's Reader and Writer classes.
+* FasterCSV::open() is more like Ruby's open() than CSV::open().
+* FasterCSV objects support most standard IO methods.
+* FasterCSV has a new() method used to wrap objects like String and IO for
+  reading and writing.
+* FasterCSV::generate() is different from CSV::generate().
+* FasterCSV does not support partial reads.  It works line-by-line.
+* FasterCSV does not allow the instance methods to override the separators for
+  performance reasons.  They must be set in the constructor.
+
+If you use this library and find yourself missing any functionality I have trimmed, please {let me know}[mailto:james@grayproductions.net].
+
+## Documentation
+
+See FasterCSV for documentation.
+
+## Installing
+
+See the INSTALL file for instructions.
+
+## What is CSV, really?
+
+FasterCSV maintains a pretty strict definition of CSV taken directly from {the RFC}[http://www.ietf.org/rfc/rfc4180.txt].  I relax the rules in only one place and that is to make using this library easier.  FasterCSV will parse all valid CSV.
+
+What you don't want to do is feed FasterCSV invalid CSV.  Because of the way the CSV format works, it's common for a parser to need to read until the end of the file to be sure a field is invalid.  This eats a lot of time and memory.
+
+Luckily, when working with invalid CSV, Ruby's built-in methods will almost always be superior in every way.  For example, parsing non-quoted fields is as easy as:
+
+  data.split(",")
+
+## Questions and/or Comments
+
+Feel free to email {James Edward Gray II}[mailto:james@grayproductions.net] with
+any questions.

data/Rakefile

@@ -0,0 +1,94 @@
+require "rdoc/task"
+require "rake/testtask"
+require "rubygems"
+require "rubygems/package_task"
+
+dir     = File.dirname(__FILE__)
+lib     = File.join(dir, "lib", "faster_csv.rb")
+version = File.read(lib)[/^\s*VERSION\s*=\s*(['"])(\d\.\d\.\d)\1/, 2]
+
+task :default => [:test]
+
+Rake::TestTask.new do |test|
+        test.libs       << "test"
+        test.test_files = [ "test/ts_all.rb" ]
+        test.verbose    = true
+end
+
+Rake::RDocTask.new do |rdoc|
+        rdoc.main     = "README.md"
+        rdoc.rdoc_dir = "doc/html"
+        rdoc.title    = "FasterCSV Documentation"
+        rdoc.rdoc_files.include( "README.md",  "INSTALL",
+                                 "TODO",    "CHANGELOG",
+                                 "AUTHORS", "COPYING",
+                                 "LICENSE", "lib/" )
+end
+
+desc "Upload current documentation to Rubyforge"
+task :upload_docs => [:rdoc] do
+        sh "scp -r doc/html/* " +
+           "bbazzarrakk@rubyforge.org:/var/www/gforge-projects/fastercsv/"
+end
+
+desc "Show library's code statistics"
+task :stats do
+        require 'code_statistics'
+        CodeStatistics.new( ["FasterCSV", "lib"],
+                            ["Units",     "test"] ).to_s
+end
+
+desc "Time FasterCSV and CSV"
+task :benchmark do
+  TESTS = 6
+  path = "test/test_data.csv"
+        sh %Q{time ruby -r csv -e } +
+           %Q{'#{TESTS}.times { CSV.foreach("#{path}") { |row| } }'}
+        sh %Q{time ruby -r lightcsv -e } +
+           %Q{'#{TESTS}.times { LightCsv.foreach("#{path}") { |row| } }'}
+        sh %Q{time ruby -r lib/faster_csv -e } +
+           %Q{'#{TESTS}.times { FasterCSV.foreach("#{path}") { |row| } }'}
+end
+
+spec = Gem::Specification.new do |spec|
+        spec.name    = "b2b2dot0-fastercsv"
+        spec.version = version
+
+        spec.platform = Gem::Platform::RUBY
+        spec.summary  = "FasterCSV is CSV, but faster, smaller, and cleaner."
+
+        spec.test_file = "test/ts_all.rb"
+        spec.files           = Dir.glob("{lib,test,examples}/**/*.rb").
+                                   reject { |item| item.include?(".svn") } +
+                               Dir.glob("{test,examples}/**/*.csv").
+                                   reject { |item| item.include?(".svn") } +
+                                   ["Rakefile", "setup.rb"]
+
+        spec.has_rdoc         = true
+        spec.extra_rdoc_files = %w[ AUTHORS COPYING README.md INSTALL TODO CHANGELOG
+                                    LICENSE ]
+        spec.rdoc_options     << "--title" << "FasterCSV Documentation" <<
+                                 "--main"  << "README.md"
+
+        spec.require_path = "lib"
+
+        spec.author            = "James Edward Gray II"
+        spec.email             = "james@grayproductions.net"
+        spec.rubyforge_project = "fastercsv"
+        spec.homepage          = "http://fastercsv.rubyforge.org"
+        spec.description       = <<END_DESC
+FasterCSV is intended as a complete replacement to the CSV standard library. It
+is significantly faster and smaller while still being pure Ruby code. It also
+strives for a better interface.
+END_DESC
+end
+
+Gem::PackageTask.new(spec) do |pkg|
+        pkg.need_zip = true
+        pkg.need_tar = true
+end
+
+desc "Add new files to Subversion"
+task :add_to_svn do
+  sh %Q{svn status | ruby -nae 'system "svn add \#{$F[1]}" if $F[0] == "?"' }
+end

data/TODO

@@ -0,0 +1,6 @@
+= To Do List
+
+The following is a list of planned expansions for FasterCSV, in no particular
+order.
+
+  * Rent this space...

data/examples/csv_converters.rb

@@ -0,0 +1,28 @@
+#!/usr/local/bin/ruby -w
+
+# csv_converters.rb
+#
+#  Created by James Edward Gray II on 2006-11-05.
+#  Copyright 2006 Gray Productions. All rights reserved.
+
+require "faster_csv"
+
+# convert a specific column
+options = {
+  :headers           => true,
+  :header_converters => :symbol,
+  :converters        => [
+    lambda { |f, info| info.index.zero?       ? f.to_i : f },
+    lambda { |f, info| info.header == :floats ? f.to_f : f }
+  ]
+}
+table = FCSV(DATA, options) { |csv| csv.read }
+
+table[:ints]    # => [1, 2, 3]
+table[:floats]  # => [1.0, 2.0, 3.0]
+
+__END__
+ints,floats
+1,1.000
+2,2
+3,3.0

data/examples/csv_filter.rb

@@ -0,0 +1,23 @@
+#!/usr/local/bin/ruby -w
+
+# = csv_filter.rb -- Faster CSV Reading and Writing
+#
+#  Created by James Edward Gray II on 2006-04-01.
+#  Copyright 2006 Gray Productions. All rights reserved.
+
+require "faster_csv"
+
+running_total = 0
+FasterCSV.filter( :headers           => true,
+                  :return_headers    => true,
+                  :header_converters => :symbol,
+                  :converters        => :numeric ) do |row|
+  if row.header_row?
+    row << "Running Total"
+  else
+    row << (running_total += row[:quantity] * row[:price])
+  end
+end
+# >> Quantity,Product Description,Price,Running Total
+# >> 1,Text Editor,25.0,25.0
+# >> 2,MacBook Pros,2499.0,5023.0

data/examples/csv_reading.rb

@@ -0,0 +1,57 @@
+#!/usr/local/bin/ruby -w
+
+# csv_reading.rb
+#
+#  Created by James Edward Gray II on 2006-11-05.
+#  Copyright 2006 Gray Productions. All rights reserved.
+
+require "faster_csv"
+
+CSV_FILE_PATH = File.join(File.dirname(__FILE__), "purchase.csv")
+CSV_STR       = <<END_CSV
+first,last
+James,Gray
+Dana,Gray
+END_CSV
+
+# read a file line by line
+FasterCSV.foreach(CSV_FILE_PATH) do |line|
+  puts line[1]
+end
+# >> Product Description
+# >> Text Editor
+# >> MacBook Pros
+
+# slurp file data
+data = FasterCSV.read(CSV_FILE_PATH)
+puts data.flatten.grep(/\A\d+\.\d+\Z/)
+# >> 25.00
+# >> 2499.00
+
+# read a string line by line
+FasterCSV.parse(CSV_STR) do |line|
+  puts line[0]
+end
+# >> first
+# >> James
+# >> Dana
+
+# slurp string data
+data = FasterCSV.parse(CSV_STR)
+puts data[1..-1].map { |line| "#{line[0][0, 1].downcase}.#{line[1].downcase}" }
+# >> j.gray
+# >> d.gray
+
+# adding options to make data manipulation easy
+total = 0
+FasterCSV.foreach( CSV_FILE_PATH, :headers           => true,
+                                  :header_converters => :symbol,
+                                  :converters        => :numeric ) do |line|
+  line_total = line[:quantity] * line[:price]
+  total += line_total
+  puts "%s: %.2f" % [line[:product_description], line_total]
+end
+puts "Total: %.2f" % total
+# >> Text Editor: 25.00
+# >> MacBook Pros: 4998.00
+# >> Total: 5023.00

data/examples/csv_table.rb

@@ -0,0 +1,56 @@
+#!/usr/local/bin/ruby -w
+
+# csv_table.rb
+#
+#  Created by James Edward Gray II on 2006-11-04.
+#  Copyright 2006 Gray Productions. All rights reserved.
+# 
+# Feature implementation and example code by Ara.T.Howard.
+
+require "faster_csv"
+
+table = FCSV.parse(DATA, :headers => true, :header_converters => :symbol)
+
+# row access
+table[0].class   # => FasterCSV::Row
+table[0].fields  # => ["zaphod", "beeblebrox", "42"]
+
+# column access
+table[:first_name]  # => ["zaphod", "ara"]
+
+# cell access
+table[1][0]            # => "ara"
+table[1][:first_name]  # => "ara"
+table[:first_name][1]  # => "ara"
+
+# manipulation
+table << %w[james gray 30]
+table[-1].fields  # => ["james", "gray", "30"]
+
+table[:type] = "name"
+table[:type]  # => ["name", "name", "name"]
+
+table[:ssn] = %w[123-456-7890 098-765-4321]
+table[:ssn]  # => ["123-456-7890", "098-765-4321", nil]
+
+# iteration
+table.each do |row|
+  # ...
+end
+
+table.by_col!
+table.each do |col_name, col_values|
+  # ...
+end
+
+# output
+puts table
+# >> first_name,last_name,age,type,ssn
+# >> zaphod,beeblebrox,42,name,123-456-7890
+# >> ara,howard,34,name,098-765-4321
+# >> james,gray,30,name,
+
+__END__
+first_name,last_name,age
+zaphod,beeblebrox,42
+ara,howard,34

data/examples/csv_writing.rb

@@ -0,0 +1,67 @@
+#!/usr/local/bin/ruby -w
+
+# csv_rails_import.rb
+#
+#  Created by James Edward Gray II on 2006-11-05.
+#  Copyright 2006 Gray Productions. All rights reserved.
+
+require "faster_csv"
+
+CSV_FILE_PATH = File.join(File.dirname(__FILE__), "output.csv")
+
+# writing to a file
+FasterCSV.open(CSV_FILE_PATH, "w") do |csv|
+  csv << %w[first last]
+  csv << %w[James Gray]
+  csv << %w[Dana Gray]
+end
+puts File.read(CSV_FILE_PATH)
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+
+# appending to an existing file
+FasterCSV.open(CSV_FILE_PATH, "a") do |csv|
+  csv << %w[Gypsy]
+  csv << %w[Storm]
+end
+puts File.read(CSV_FILE_PATH)
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+# >> Gypsy
+# >> Storm
+
+# writing to a string
+csv_str = FasterCSV.generate do |csv|
+  csv << %w[first last]
+  csv << %w[James Gray]
+  csv << %w[Dana Gray]
+end
+puts csv_str
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+
+# appending to an existing string
+FasterCSV.generate(csv_str) do |csv|
+  csv << %w[Gypsy]
+  csv << %w[Storm]
+end
+puts csv_str
+# >> first,last
+# >> James,Gray
+# >> Dana,Gray
+# >> Gypsy
+# >> Storm
+
+# changing the output format
+csv_str = FasterCSV.generate(:col_sep => "\t") do |csv|
+  csv << %w[first last]
+  csv << %w[James Gray]
+  csv << %w[Dana Gray]
+end
+puts csv_str
+# >> first	last
+# >> James	Gray
+# >> Dana	Gray