README.rdoc in csv_pirate-2.1.2 vs README.rdoc in csv_pirate-2.4.4

@@ -1,32 +1,36 @@
-== CsvPirate v2.0.1 (20091001)
+== CsvPirate
 
 Easily create CSVs of any data that can be derived from your models.
 
 CsvPirate is the easy way to create a CSV of essentially anything in Rails, in full pirate regalia.
 It works better if you are wearing a tricorne!
 
 CsvPirate only works for commissions of swag OR grub!
 
 Initialize method (a.k.a new()) takes a hash of params:
 
-  swag:         the ARrr collection of swag to work on (optional)
-  grub:         the ARrr class that the spyglasses will be used on (optional)
-  spyglasses:   named scopes in your model that will refine the rows in the CSV according to conditions of the spyglass,
-                  and order them according to the order of the spyglass (only used with grub, not swag)
-  booty:        booty on your model that you want printed in the CSV
-  chart:        name of directory where you want to hide your loot
-  waggoner:     name of document where you will give detailed descriptions of the loot
-  chronometer:  keeps track of when you hunt for treasure
-  gibbet:       filename spacer after the date, and before the iterative counter/timestamp.  MuST contain a '.'
-  swab:         can be :counter, :timestamp, or :none
-    :counter    - default, each successive run will create a new file using a counter
-    :timestamp  - each successive run will create a new file using a HHMMSS time stamp
-    :none       - no iterative file naming convention, just use waggoner and aft
-  mop:          can be :clean or :dirty (:overwrite or :append) (only has an effect if :swab is :none) since overwriting is irrelevant for a new file
-    :clear      - do not use :counter or :timestamp, and instead overwrite the file
-    :dirty      - do not use :counter, or :timestamp, or :overwrite.  Just keep adding on.
+  # CsvPirate only works for commissions of swag OR grub!
+  # :swag         the ARrr collection of swag to work on (optional)
+  # :grub         the ARrr class that the spyglasses will be used on (optional)
+  # :spyglasses   named scopes in your model that will refine the rows in the CSV according to conditions of the spyglasses,
+  #                 and order them according to the order of the spyglasses (optional)
+  # :booty        booty (columns/methods) on your model that you want printed in the CSV, also used to create the figurehead (CSV header)
+  # :chart        name of directory where you want to hide your loot
+  # :wagonner     name of document where you will give detailed descriptions of the loot
+  # :aft          filename extention ('.csv')
+  # :shrouds      CSV column separator, default is ','. For tsv, tab-delimited, "\t"
+  # :chronometer  keeps track of when you hunt for treasure
+  # :gibbet       filename spacer after the date, and before the iterative counter/timestamp.  MuST contain a '.'
+  # :swab         can be :counter, :timestamp, or :none
+  #   :counter - default, each successive run will create a new file using a counter
+  #   :timestamp - each successive run will create a new file using a HHMMSS time stamp
+  #   :none - no iterative file naming convention, just use waggoner and aft
+  # :mop          can be :clean or :dirty (:overwrite or :append) (only has an effect if :swab is :none) since overwriting is irrelevant for a new file
+  #   :clear - do not use :counter or :timestamp, and instead overwrite the file
+  #   :dirty - do not use :counter, or :timestamp, or :overwrite.  Just keep adding on.
+  # There are others too, check the source for a complete picture!
 
 The create method has the same parameters, and actually creates the CSV.
 
 Avast! Here be pirates! To brush up on pirate coding naming conventions:
 
@@ -87,11 +91,11 @@
 
     has_csv_pirate_ship :spyglasses => [:factory_in_germany],
                         :booty => [:id, :name]
   end
 
-To create a csv of the names and ids of makes with factories in germany:
+To create a csv of the names and ids of makes with factories in germany and return the text of the export:
 
   Make.walk_the_plank  # Get it? HA! If you can't believe I wrote this whole thing JUST to be able to make jokes like that... check ma sources :)
 
 The name of the csv that comes out will be (by defualt located in log directory):
 
@@ -102,47 +106,47 @@
 All of those filename parts are customizable to a degree.
 
 You can also customize the CSV, for example if you want to add a column to the csv:
 
   Make.walk_the_plank({:booty => [:id, :name, :sales]})
+
+Youw want a timestamp file counter instead of the integer default:
+
   Make.walk_the_plank({:booty => [:id, :name, :sales], :spyglasses => [:all], :swab => :timestamp})
+
+If you want to append each export to the end of the same file (on a per day basis):
+
   Make.walk_the_plank({:booty => [:id, :name, :sales], :spyglasses => [:all], :swab => :none, :mop => :dirty})
 
+If you want to restrict the csv to a particular set of named scopes:
+
+  Make.walk_the_plank({:booty => [:id, :name, :sales], :spyglasses => [:with_abs, :with_esc, :with_heated_seats]})
+
+If you want to create a tsv (tab-delimited) or psv (pipe-delimited) instead of a csv:
+
+  Make.walk_the_plank({:booty => [:id, :name, :sales], :shrouds => '\t'})
+  Make.walk_the_plank({:booty => [:id, :name, :sales], :shrouds => '|'})
+
 If you have a method in the Make class like this:
 
   def to_slug
     "#{self.name}_#{self.id}"
   end
 
 getting it in the CSV is easy peasy:
 
   Make.walk_the_plank({:booty => [:id, :name, :to_slug]})
 
-Add whatever methods you want to the :booty array.  Write new methods, and add them!  Make lots of glorious CSVs full of data to impress the pointy ones in the office.
+If you want to traverse Active Record Associations, or call a method on the return value of another method (unlimited nesting):
 
-You can also use the raw CsvPirate class itself directly wherever you want.  These are the available options to methods:
-new, create, or walk_the_plank
+  Make.walk_the_plank({:booty => [:id, :name, :to_slug, {:to_slug => :hash}]})  #will call .hash on the result of make.to_slug
+  Make.walk_the_plank({:booty => [:id, :name, :to_slug, {:to_slug => {:hash => :abs}}]})  #returns make.to_slug.hash.abs
 
-  # CsvPirate only works for commissions of swag OR grub!
-  # :swag         the ARrr collection of swag to work on (optional)
-  # :grub         the ARrr class that the spyglasses will be used on (optional)
-  # :spyglasses   named scopes in your model that will refine the rows in the CSV according to conditions of the spyglasses,
-  #                 and order them according to the order of the spyglasses (optional)
-  # :booty        booty (columns/methods) on your model that you want printed in the CSV, also used to create the figurehead (CSV header)
-  # :chart        name of directory where you want to hide your loot
-  # :wagonner     name of document where you will give detailed descriptions of the loot
-  # :aft          filename extention ('.csv')
-  # :chronometer  keeps track of when you hunt for treasure
-  # :gibbet       filename spacer after the date, and before the iterative counter/timestamp.  MuST contain a '.'
-  # :swab         can be :counter, :timestamp, or :none
-  #   :counter - default, each successive run will create a new file using a counter
-  #   :timestamp - each successive run will create a new file using a HHMMSS time stamp
-  #   :none - no iterative file naming convention, just use waggoner and aft
-  # :mop          can be :clean or :dirty (:overwrite or :append) (only has an effect if :swab is :none) since overwriting is irrelevant for a new file
-  #   :clear - do not use :counter or :timestamp, and instead overwrite the file
-  #   :dirty - do not use :counter, or :timestamp, or :overwrite.  Just keep adding on.
+Add whatever methods you want to the :booty array.  Write new methods, and add them!  Make lots of glorious CSVs full of data to impress the pointy ones in the office.
 
+You can also use the raw CsvPirate class itself directly wherever you want.
+
 The following two sets of code are identical:
 
   csv_pirate = CsvPirate.new({
     :grub => User,
     :spyglasses => [:active,:logged_in],
@@ -180,9 +184,38 @@
   csv_pirate = CsvPirate.new({:grub => User,:spyglasses => [:active,:logged_in],:waggoner => 'active_users_logged_in',:booty => ["id","number","login","created_at"],:chart => 'log/csv/'})
 
 OR
 
   csv_pirate = CsvPirate.new({:swag => users,:waggoner => 'inactive_users_not_logged_in',:booty => ["id","number","login","created_at"],:chart => 'log/csv/'})
+
+
+== Downloading the CSV
+
+You have the same Make class as above, and you have a MakeController:
+
+  class MakeController < ApplicationController
+
+    def download_csv
+      send_data Make.say_your_last_words  # "utf-8" is default, and uses options from has_csv_pirate_ship
+    end
+
+    # OR you can customize it just like walk_the_plank
+
+    def download_csv
+      send_data Make.say_your_last_words("iso-8859-1", {:booty => [:id, :name]})
+    end
+
+  end
+
+Too easy?  I wrote this for two reasons... pirate jokes and to make my life easier.  If you need more flexibility then:
+
+  def download_csv
+    csv_pirate = Make.blindfold
+    send_data csv_pirate.maroon,
+      :type => 'text/csv; charset=iso-8859-1; header=present',
+      :disposition => "attachment; filename=#{csv_pirate.nocturnal}"
+  end
+
 
 == Advanced Example with Nested Methods
 
 You have a VehicleModel class and the same Make class as up above: