to-csv 1.0.2 → 1.0.3

data/CHANGELOG.rdoc

@@ -1,15 +1,21 @@
-== 1.0.2 2010-01-04
-
-* Changed use of OpenStruct in favor of Struct, which supports any attribute name. Now a block yields a Struct and the object itself
-* Support for Rails scopes
-* Improved documentation
-
-== 1.0.1 2009-12-24
-
-* Now compatible with Ruby 1.9.1
-* Updated documentation to reflect Ruby 1.9.1 support
-
-== 1.0.0 2009-12-23
-
-* First release
-
+== 1.0.3 2010-08-09
+* Supported (tested) Ruby versions: 1.8.7-p299, 1.9.1-p378, 1.9.2-rc1
+* Support for Ruby 1.8.6 has been dropped
+* New +include+ option
+* +csv_options+ has an +encoding+ option set with UTF-8
+
+== 1.0.2 2010-01-04
+
+* Changed use of OpenStruct in favor of Struct, which supports any attribute name. Now a block yields a Struct and the object itself
+* Support for Rails scopes
+* Improved documentation
+
+== 1.0.1 2009-12-24
+
+* Now compatible with Ruby 1.9.1
+* Updated documentation to reflect Ruby 1.9.1 support
+
+== 1.0.0 2009-12-23
+
+* First release
+

data/MIT-LICENSE

@@ -1,20 +1,20 @@
-Copyright (c) 2009 Ícaro Leopoldino da Motta
-
-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.
+Copyright (c) 2009 Ícaro Leopoldino da Motta
+
+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/README.rdoc

@@ -1,212 +1,237 @@
-= ToCSV
-
-
-ToCSV is a gem for converting arrays or scopes (Rails) to CSV by calling +to_csv+.
-These arrays can contain different data structures, as long as they are homogeneous, like the ones
-described below:
-
-* A simple array of anything that responds to <tt>to_s</tt>: <tt>['Date', Time.now].to_csv</tt>
-* An array of hashes: <tt>[ {'Name' => 'Icaro', 'Age' => 23}, {'Name' => 'Gabriel', 'Age' => 16} ].to_csv</tt>
-* A matrix: <tt>[['Name', 'Age'], ['Icaro', 23], ['Gabriel', 16]].to_csv</tt>
-* A hash like array: <tt>[ [['Name', 'Icaro'], ['Age', 23]], [['Name', 'Gabriel'], ['Age', 16]] ].to_csv</tt>
-* An array of ActiveRecord objects: <tt>@users.to_csv(:except => [:password, :phone], :timestamps => true)</tt>
-* Scopes in Rails
-
-
-=== Requirements
-
-ToCSV has been tested with Ruby 1.8.6/1.8.7/1.9.1.
-
-If you are using Ruby 1.9 the only dependency to use the basic features is +ActiveSupport+.
-Otherwise you will need +fastercsv+. You will receive a warning if you don't meet the requirements.
-
-  # If you don't have Rails installed...
-  $ sudo gem install activesupport
-
-  # And if your Ruby version is lower than 1.9
-  $ sudo gem install fastercsv
-
-
-=== Configuration
-
-  If you want to use this gem with Rails, put the following requirement in your environment.rb:
-
-  config.gem 'to-csv', :lib => 'to_csv', :source => 'http://gemcutter.org'
-
-After that, if you need to globally configure the gem, just create a <i>to_csv.rb</i> file in <i>initializers</i>.
-
-  ToCSV.byte_order_marker = true
-  ToCSV.timestamps        = true
-  ToCSV.locale            = 'en-US'
-  ToCSV.primary_key       = false
-  ToCSV.csv_options       = { :col_sep => ',', :row_sep => "\r\n" }
-
-
-== Examples
-
-Let's start with the most simple example.
-
-  ['Alfred Hitchcock', 'Robert Mitchum', 'Lucille Ball'].to_csv
-  #=> "Alfred Hitchcock;Robert Mitchum;Lucille Ball\n"
-
-
-Or, if we have an array of arrays (i.e. a matrix) we can create tabular data.
-  [
-    ['Name', 'Gender'],
-    ['Alfred',  'M'],
-    ['Robert',  'M'],
-    ['Lucille', 'F']
-  ].to_csv #=> "Name;Gender\nAlfred;M\nRobert;M\nLucille;F\n"
-
-
-Almost always, when we generate CSV files, we want it to have appropriate
-headers, so a better approach might be to use an array of hashes.
-
-  [
-    { 'Name' => 'Alfred',  'Gender' => 'M' },
-    { 'Name' => 'Robert',  'Gender' => 'M' },
-    { 'Name' => 'Lucille', 'Gender' => 'F' }
-  ].to_csv #=> "Gender;Name\nM;Alfred\nM;Robert\nF;Lucille\n"
-
-
-Look carefully to the above output. You can see that when we use hashes we can
-no longer be sure of the headers' order (true for Ruby versions older than 1.9).
-When we are working with tabular data the headers' order can be very important,
-thus we can use a somewhat similar data structure:
-
-  [
-    [ ['Name', 'Alfred'],  ['Gender', 'M'] ],
-    [ ['Name', 'Robert'],  ['Gender', 'M'] ],
-    [ ['Name', 'Lucille'], ['Gender', 'F'] ]
-  ].to_csv #=> "Name;Gender\nAlfred;M\nRobert;M\nLucille;F\n"
-
-That's a lot to type... The first example was much simpler...
-
-There is the <tt>headers</tt> option. You can use it in all the examples above
-to enable/disable headers from the output. Default is to show (true).
-
-  users = [{ 'Name' => 'Alfred',  'Gender' => 'M' }]
-  users.to_csv(:headers => false)
-
-
-==== Active Record Objects
-
-When we're building our data like the previous examples we have very few options
-compared to what can be passed when converting an array of AR objects. Again,
-the easiest way:
-
-  # Anywhere in your app.
-  # By default, all available model attributes (DB columns) are going to be used
-  # except timestamps and the primary key of the record
-  @users = User.all
-  File.open('path/to/file.csv', 'w') { |io| io.puts @users.to_csv }
-
-
-==== Headers
-
-You can control the order and the text of any header. You can accomplish that
-in various ways.
-
-By default all attribute/method names will be sorted in alphabetical order. So
-imagine a person model have +name+, +age+ and +email+ as attributes, and you
-want to get the following output:
-
-  Name | E-mail | Age
-  ...  | ...    | ..
-  ...  | ...    | ..
-
-You can tell <i>to-csv</i> to use a specific locale. If you don't, it uses
-your app current locale. It will try to translate attributes to a
-more friendly text by using the scope <tt>[:activerecord, :attributes, <model name>]</tt>.
-If the translation doesn't exist the header's text is going to be humanized.
-
-The order of columns can be changed with the option +headers+. The way this
-option works is very similar to the <tt>plugins</tt> method in your Rails
-<i>environment.rb</i> file.
-
-* If you pass +nil+ (default) then headers/columns will be in alphabetical order.
-* If you pass an empty array or +false+, no headers will be shown.
-* Instead, if you pass a non empty array, headers will be sorted in the order specified. <tt>:all</tt> can be used as a placeholder for all attributes not explicitly named.
-
-So, in our example above, we can say:
-
-  @users.to_csv(:headers => [:name, :email, :age])
-
-Or, using the placeholder +all+, which is not very useful here:
-
-  @users.to_csv(:headers => [:name, :email, :all])
-
-If you want a completely different result you could, for instance, map all
-users to a hash. Example:
-
-  # This makes use of a hash to completely change the CSV output.
-  @users.map do |user|
-    {
-      'Name' => user.name,
-      'Age'  => user.age,
-      'Total Comments' => user.comments.count
-    }
-  end.to_csv
-
-
-===== Passing a Block
-
-Sometimes you may want to change just one value out of six for example. The best
-way to go is to pass a block so that you don't have to repeat yourself writing
-five headers and it's obvious values and also loosing I18n header translations.
-
-  # The block yields a new Struct for each object in the list. By calling
-  # methods on this struct you can change their default values.
-  @users.to_csv do |row, user|
-    row.date_of_birth = user.date_of_birth.to_s(:long)
-  end
-
-
-===== A More Complete Example
-
-  # users/index.html.haml
-  = link_to 'export (CSV)', users_url(:csv)
-
-  # UsersController#index
-  class UsersController < ApplicationController
-    def index
-      @users = User.most_active
-      respond_to do |format|
-        format.html
-        format.csv do
-          send_data User.csv(@users), :filename => 'users_report.csv'
-        end
-      end
-    end
-  end
-  
-  # User model
-  class User < ActiveRecord::Base
-    def self.csv(users)
-      users.csv(:headers => [:id, :all], :primary_key => true, :except => :password) do |row, user|
-        row.id = "%04d" % user.id
-        row.created_at = I18n.l(user.created_at, :format => :default)
-      end
-    end
-  end
-  
-  # locales/en-US.yml
-  activerecord:
-    attributes:
-      user:
-        id: Code
-
-
-==== Full Customization
-
-You can always customize the output if you wish by building arrays of hashes,
-arrays of arrays of bidimensional arrays etc :). Or you can obviously mix
-anything you want and even use FasterCSV directly.
-
-  @user.to_csv { :only => [:name, :email] }, :col_sep => ','
-
-There are other options for you to customize the output. Take a look at the
-<tt>to_csv</tt> method documentation.
-
-Copyright (c) 2009 Ícaro Leopoldino da Motta, released under the MIT license.
-
+= ToCSV
+
+
+ToCSV is a gem for converting arrays or scopes (Rails) to CSV by calling +to_csv+.
+These arrays can contain different data structures, as long as they are homogeneous, like the ones
+described below:
+
+* A simple array of anything that responds to <tt>to_s</tt>: <tt>['Date', Time.now].to_csv</tt>
+* An array of hashes: <tt>[ {'Name' => 'Icaro', 'Age' => 23}, {'Name' => 'Gabriel', 'Age' => 16} ].to_csv</tt>
+* A matrix: <tt>[['Name', 'Age'], ['Icaro', 23], ['Gabriel', 16]].to_csv</tt>
+* A hash like array: <tt>[ [['Name', 'Icaro'], ['Age', 23]], [['Name', 'Gabriel'], ['Age', 16]] ].to_csv</tt>
+* An array of ActiveRecord objects: <tt>@users.to_csv(:except => [:password, :phone], :timestamps => true)</tt>
+* Scopes in Rails
+
+
+=== Requirements
+
+ToCSV has been tested with Ruby 1.8.7-p299/1.9.1-p378/1.9.2-rc1.
+
+If you are using Ruby 1.9 the only dependency to use the basic features is +ActiveSupport+.
+Otherwise you will need +fastercsv+. You will receive a warning if you don't meet the requirements.
+
+  # If you don't have Rails installed...
+  $ sudo gem install activesupport
+
+  # And if your Ruby version is lower than 1.9
+  $ sudo gem install fastercsv
+  
+Full compatibility with Rails 3 is on the way...as well as a new API, with new features.
+
+
+=== Configuration
+
+  If you want to use this gem with Rails, put the following requirement in your environment.rb:
+
+  config.gem 'to-csv', :lib => 'to_csv', :source => 'http://rubygems.org'
+
+After that, if you need to globally configure the gem, just create a <i>to_csv.rb</i> file in <i>initializers</i>.
+
+  ToCSV.byte_order_marker = true
+  ToCSV.timestamps        = true
+  ToCSV.locale            = 'en-US'
+  ToCSV.primary_key       = false
+  ToCSV.csv_options[:col_sep] = ','
+  ToCSV.csv_options[:row_sep] = "\r\n"
+
+
+== Examples
+
+Let's start with the most simple example.
+
+  ['Alfred Hitchcock', 'Robert Mitchum', 'Lucille Ball'].to_csv
+  #=> "Alfred Hitchcock;Robert Mitchum;Lucille Ball\n"
+
+
+Or, if we have an array of arrays (i.e. a matrix) we can create tabular data.
+  [
+    ['Name', 'Gender'],
+    ['Alfred',  'M'],
+    ['Robert',  'M'],
+    ['Lucille', 'F']
+  ].to_csv #=> "Name;Gender\nAlfred;M\nRobert;M\nLucille;F\n"
+
+
+Almost always, when we generate CSV files, we want it to have appropriate
+headers, so a better approach might be to use an array of hashes.
+
+  [
+    { 'Name' => 'Alfred',  'Gender' => 'M' },
+    { 'Name' => 'Robert',  'Gender' => 'M' },
+    { 'Name' => 'Lucille', 'Gender' => 'F' }
+  ].to_csv #=> "Gender;Name\nM;Alfred\nM;Robert\nF;Lucille\n"
+
+
+Look carefully to the above output. You can see that when we use hashes we can
+no longer be sure of the headers' order (true for Ruby versions older than 1.9).
+When we are working with tabular data the headers' order can be very important,
+thus we can use a somewhat similar data structure:
+
+  [
+    [ ['Name', 'Alfred'],  ['Gender', 'M'] ],
+    [ ['Name', 'Robert'],  ['Gender', 'M'] ],
+    [ ['Name', 'Lucille'], ['Gender', 'F'] ]
+  ].to_csv #=> "Name;Gender\nAlfred;M\nRobert;M\nLucille;F\n"
+
+That's a lot to type... The first example was much simpler...
+
+There is the <tt>headers</tt> option. You can use it in all the examples above
+to enable/disable headers from the output. Default is to show (true).
+
+  users = [{ 'Name' => 'Alfred',  'Gender' => 'M' }]
+  users.to_csv(:headers => false)
+
+
+==== Active Record Objects
+
+When we're building our data like the previous examples we have very few options
+compared to what can be passed when converting an array of AR objects. Again,
+the easiest way:
+
+  # Anywhere in your app.
+  # By default, all available model attributes (DB columns) are going to be used
+  # except timestamps and the primary key of the record
+  @users = User.all
+  File.open('path/to/file.csv', 'w') { |io| io.puts @users.to_csv }
+
+
+==== Headers
+
+You can control the order and the text of any header. You can accomplish that
+in various ways.
+
+By default all attribute/method names will be sorted in alphabetical order. So
+imagine a person model have +name+, +age+ and +email+ as attributes, and you
+want to get the following output:
+
+  Name | E-mail | Age
+  ...  | ...    | ..
+  ...  | ...    | ..
+
+You can tell <i>to-csv</i> to use a specific locale. If you don't, it uses
+your app current locale. It will try to translate attributes to a
+more friendly text by using the scope <tt>activerecord.attributes.<model name></tt>.
+If the translation doesn't exist the header's text is going to be humanized.
+
+The order of columns can be changed with the option +headers+. The way this
+option works is very similar to the <tt>plugins</tt> method in your Rails
+<i>environment.rb</i> file.
+
+* If you pass +nil+ (default) then headers/columns will be in alphabetical order.
+* If you pass an empty array or +false+, no headers will be shown.
+* Instead, if you pass a non empty array, headers will be sorted in the order specified. <tt>:all</tt> can be used as a placeholder for all attributes not explicitly named.
+
+So, in our example above, we can say:
+
+  @users.to_csv(:headers => [:name, :email, :age])
+
+Or, using the placeholder +all+, which is not very useful here:
+
+  @users.to_csv(:headers => [:name, :email, :all])
+
+If you want a completely different result you could, for instance, map all
+users to a hash. Example:
+
+  # This makes use of a hash to completely change the CSV output.
+  @users.map do |user|
+    {
+      'Name' => user.name,
+      'Age'  => user.age,
+      'Total Comments' => user.comments.count
+    }
+  end.to_csv
+
+
+==== Passing a Block
+
+Sometimes you may want to change just one value out of six for example. The best
+way to go is to pass a block so that you don't have to repeat yourself writing
+five headers and it's obvious values and also loosing I18n header translations.
+
+  # The block yields a new Struct for each object in the list. By calling
+  # methods on this struct you can change their default values.
+  @users.to_csv do |row, user|
+    row.date_of_birth = user.date_of_birth.to_s(:long)
+  end
+
+==== Include Relationships
+
+If you have an AR object with many relationships and you want to include these to
+CSV results, you can use :include option.
+
+Examples:
+
+  # If you want to include a <tt>has_many</tt> relationship, you can do the following:
+  User.all.to_csv(:include => :posts)
+
+  # If you want to include a <tt>belongs_to</tt> relationship:
+  User.all.to_csv(:include => :organization)
+
+  # Or you can use both in the same time.
+  User.all.to_csv(:include => [:organization, :posts])
+
+==== A More Complete Example
+
+  # users/index.html.haml
+  = link_to 'export (CSV)', users_url(:csv)
+
+  # UsersController#index
+  class UsersController < ApplicationController
+    def index
+      @users = User.most_active
+      respond_to do |format|
+        format.html
+        format.csv do
+          send_data User.csv(@users), :filename => 'users_report.csv'
+        end
+      end
+    end
+  end
+  
+  # User model
+  class User < ActiveRecord::Base
+    def self.csv(users)
+      users.csv(:headers => [:id, :all], :primary_key => true, :except => :password) do |row, user|
+        row.id = "%04d" % user.id
+        row.created_at = I18n.l(user.created_at, :format => :default)
+      end
+    end
+  end
+  
+  # locales/en-US.yml
+  activerecord:
+    attributes:
+      user:
+        id: Code
+
+==== Full Customization
+
+You can always customize the output if you wish by building arrays of hashes,
+arrays of arrays of bidimensional arrays etc :). Or you can obviously mix
+anything you want and even use FasterCSV directly.
+
+  @user.to_csv { :only => [:name, :email] }, :col_sep => ','
+
+There are other options for you to customize the output. Take a look at the
+<tt>to_csv</tt> method documentation.
+
+==== Credits
+
+Special thanks to these people for their contributions and/or ideas:
+
+* {Kyle J. Ginavan}[http://github.com/kylejginavan]
+* {Mauro Torres}[http://github.com/chebyte]
+* {petRUShka}[http://github.com/petRUShka]
+
+Copyright (c) 2010 Ícaro Leopoldino da Motta, released under the MIT license.
+