From: James Gray <james@...>
Date: 2008-01-02T23:55:14+09:00
Subject: Re: replace csv.rb with fastercsv.rb

On Dec 24, 2007, at 5:27 PM, Dave Thomas wrote:

>
> On Dec 24, 2007, at 4:31 PM, NAKAMURA, Hiroshi wrote:
>
>> We can download plain old CSV from
>> http://dev.ctor.org/csv/browser/trunk/lib/csv.rb?format=txt
>> As far as I know "the core team" does not use csv.rb.  You and I  
>> are the
>> person who well knows 'how users use csv.rb in ruby' in comitters.   
>> You
>> can help users who will posts compatibility questions to ruby-talk,
>> right?  Go ahead.
>
> James:
>
> Are there any points you'd like me to make about it when I update  
> the CSV page in PickAxe 3?

Things you may want to point out in the prose:

* It's the FasterCSV code base, renamed to CSV.  Many people are  
familiar with it.
* The API is almost the same as the old CSV, if you stick to the class  
methods of CSV itself.
* The main exception is CSV.open() which now behaves like File.open()  
instead of File.foreach().  Use CSV.foreach() if you want foreach()  
behavior.
* Options are now passed in the Hash argument style, instead of as  
positional parameters.  So the old CSV.foreach(path, "\r\n") changes  
to CSV.foreach(path, :row_sep => "\r\n").
* The new library has a lot more features, especially regarding CSV  
files with a header row.
* The code is fully documented, so users can read up on the changes.

Notes about your existing examples:

* Change open() to foreach() and drop the "r" mode indicator and your  
first example runs the same.
* Your second example is where the new library really shines and  
you'll probably want to rework it to show readers that.  I think you  
should show the library reading the headers and referring to the  
columns by name:

   total_cost = 0
   CSV.foreach("csvfile_hdr", :headers => true) do |line_item|
     total_cost += line_item["Count"] * line_item["Price"]
   end

* Your third example can be super short using the new code:

   CSV do |csv|
     # �
   end

That's really a shortcut and if you prefer to show the longhand  
version it is:

   CSV.instance($stdout) do |csv|
     # �
   end

New stuff:

The new code has a table feature that might fun to show in an  
example.  There's an example file in the FasterCSV source that should  
give you the feel of how it works:

   http://fastercsv.rubyforge.org/svn/trunk/examples/csv_table.rb

I understand if there just isn't room though.

I hope that helps you make the update.  I'm happy to answer any  
questions for you as needed, of course.

James Edward Gray II