csv_pirate 3.1.1 → 3.3.0

data/CHANGELOG

@@ -1,3 +1,16 @@
+Version 3.3.0 2009-10-05
+- Fixed ArgumentError bugs in Initializer and has_csv_pirate_ship
+- Fixed typo in piratey_args
+- Major enhancements to documentation
+- Now complete control over filename is possible
+
+Version 3.2.1 2009-10-04
+- Fixed bug in parlay by creating method parlance
+
+Version 3.2.0 2009-10-01
+- Fixed typo in documentation
+- Added land_ho method!
+
 Version 3.1.1 2009-10-01
 - Readme Cleanup
 - Removing broken say_your_last_words method

data/README.rdoc

@@ -28,7 +28,7 @@ Initialize method (a.k.a new()) takes a hash of params:
   #   :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
+  #   :clean - do not use :counter or :timestamp, and instead overwrite the file
   #   :dirty - do not use :counter, or :timestamp, or :overwrite.  Just keep adding on.
   # :bury_treasure  should we store the csv data as it is collected in an array in Ruby form for later use (true), or just write the CSV (false)?
   # check the source to see if there anything else hiding in there!
@@ -52,6 +52,10 @@ Release Announcement:
 
 == Installation
 
+Gem from Gemcutter (after setting up your machine to use the gemcutter repo, see http://gemcutter.org):
+
+  sudo gem install csv_pirate
+
 Gem Using Git building from source:
 
   mkdir -p ~/src
@@ -59,7 +63,7 @@ Gem Using Git building from source:
   git clone git://github.com/pboling/csv_pirate.git
   cd csv_pirate
   gem build csv_pirate.gemspec
-  sudo gem install csv_pirate-2.0.1.gem # (Or whatever version gets built)
+  sudo gem install csv_pirate-3.3.0.gem # (Or whatever version gets built)
 
 Then cd to your rails app to optionally freeze the gem into your app:
 
@@ -73,6 +77,7 @@ Plugin using Git:
 
   ruby script/plugin install git://github.com/pboling/csv_pirate.git
 
+If installed as a gem load it with config.gem 'csv_pirate' # or 'pboling-csv_pirate' if from github
 
 == Upgrading
 
@@ -81,7 +86,73 @@ Plugin using Git:
   ['log','csv','pirates','model_name']
   CsvPirate ensures that whatever you choose as your chart exists in the filesystem, and creates the directories if need be.
 
-== Example & Usage
+== Usage with ActiveRecord
+
+What's the simplest thing that'll work?
+
+  class MyClass < ActiveRecord::Base
+    has_csv_pirate_ship   # defaults to csv of all columns of all records
+  end
+
+  MyClass.blindfold       # creates the csv, and returns the CsvPirate instance
+  MyClass.walk_the_plank  # creates the csv, and returns contents of the exported data (that was written into the csv) (as a string)
+  MyClass.land_ho         # Does Not create the csv, sets up the CsvPirate instance.  You can manipulate it and then call .hoist_mainstay on it to create the csv
+
+== Usage without ActiveRecord
+
+Since the defaults assume an active record class you need to override some of them:
+
+  class Star
+    extend NinthBit::PirateShip::ActMethods
+    has_csv_pirate_ship :booty => [:name, :distance, :spectral_type, {:name => :hash}, {:name => :next}, {:name => :upcase}, :star_vowels],
+                        :spyglasses => [:get_stars]
+
+    attr_accessor :name, :distance, :spectral_type
+
+    def initialize(*args)
+      @name = args.first[:name]
+      @distance = args.first[:distance]
+      @spectral_type = args.first[:spectral_type]
+    end
+    
+    def star_vowels
+      self.name.tr('aeiou', '*')
+    end
+
+    def self.get_stars
+      [
+        Star.new(:name => "Proxima Centauri", :distance => "4.2 LY", :spectral_type => "M5.5Vc"),
+        Star.new(:name => "Rigil Kentaurus", :distance => "4.3 LY", :spectral_type => "G2V"),
+        Star.new(:name => "Barnard's Star", :distance => "5.9 LY", :spectral_type => "M3.8V"),
+        Star.new(:name => "Wolf 359", :distance => "7.7 LY", :spectral_type => "M5.8Vc"),
+        Star.new(:name => "Lalande 21185", :distance => "8.26 LY", :spectral_type => "M2V"),
+        Star.new(:name => "Luyten 726-8A and B", :distance => "8.73 LY", :spectral_type => "M5.5 de & M6 Ve"),
+        Star.new(:name => "Sirius A and B", :distance => "8.6 LY", :spectral_type => "A1Vm"),
+        Star.new(:name => "Ross 154", :distance => "9.693 LY", :spectral_type => "M3.5"),
+        Star.new(:name => "Ross 248", :distance => "10.32 LY", :spectral_type => "M5.5V"),
+        Star.new(:name => "Epsilon Eridani", :distance => "10.5 LY", :spectral_type => "K2V")
+      ]
+    end
+  end
+
+
+  rails development  >a = Star.blindfold
+    => #<CsvPirate:0x2209098 @buried_treasure=[], @mop=:clean, @spyglasses=[:get_stars], @swabbie=".3", @booty=[:name, :distance, :spectral_type, {:name=>:hash}, {:name=>:next}, {:name=>:upcase}, :star_vowels], @bury_treasure=false, @swab=:counter, @chronometer=Sun, 04 Oct 2009, @maroon="name,distance,spectral_type,namehash,namenext,nameupcase,star_vowels\nProxima Centauri,4.2 LY,M5.5Vc,971295636,Proxima Centaurj,PROXIMA CENTAURI,Pr*x*m* C*nt**r*\nRigil Kentaurus,4.3 LY,G2V,-231389024,Rigil Kentaurut,RIGIL KENTAURUS,R*g*l K*nt**r*s\nBarnard's Star,5.9 LY,M3.8V,1003964756,Barnard's Stas,BARNARD'S STAR,B*rn*rd's St*r\nWolf 359,7.7 LY,M5.8Vc,429493790,Wolf 360,WOLF 359,W*lf 359\nLalande 21185,8.26 LY,M2V,466625069,Lalande 21186,LALANDE 21185,L*l*nd* 21185\nLuyten 726-8A and B,8.73 LY,M5.5 de & M6 Ve,-886693495,Luyten 726-8A and C,LUYTEN 726-8A AND B,L*yt*n 726-8A *nd B\nSirius A and B,8.6 LY,A1Vm,-969980943,Sirius A and C,SIRIUS A AND B,S*r**s A *nd B\nRoss 154,9.693 LY,M3.5,-26506942,Ross 155,ROSS 154,R*ss 154\nRoss 248,10.32 LY,M5.5V,-18054910,Ross 249,ROSS 248,R*ss 248\nEpsilon Eridani,10.5 LY,K2V,931307088,Epsilon Eridanj,EPSILON ERIDANI,Eps*l*n Er*d*n*\n", @waggoner="Star", @astrolabe=false, @grub=Star, @rhumb_lines=#<File:/Users/pboling/RubymineProjects/empty_csv_pirate_app/log/csv/Star.20091004.export.3.csv (closed)>, @nocturnal="Star.20091004.export.3.csv", @aft=".csv", @gibbet=".export", @shrouds=",", @swag=[#<Star:0x2202db0 @spectral_type="M5.5Vc", @distance="4.2 LY", @name="Proxima Centauri">, #<Star:0x2202d10 @spectral_type="G2V", @distance="4.3 LY", @name="Rigil Kentaurus">, #<Star:0x2202c98 @spectral_type="M3.8V", @distance="5.9 LY", @name="Barnard's Star">, #<Star:0x2202c20 @spectral_type="M5.8Vc", @distance="7.7 LY", @name="Wolf 359">, #<Star:0x2202ba8 @spectral_type="M2V", @distance="8.26 LY", @name="Lalande 21185">, #<Star:0x2202b30 @spectral_type="M5.5 de & M6 Ve", @distance="8.73 LY", @name="Luyten 726-8A and B">, #<Star:0x2202ab8 @spectral_type="A1Vm", @distance="8.6 LY", @name="Sirius A and B">, #<Star:0x2202a40 @spectral_type="M3.5", @distance="9.693 LY", @name="Ross 154">, #<Star:0x22029c8 @spectral_type="M5.5V", @distance="10.32 LY", @name="Ross 248">, #<Star:0x2202950 @spectral_type="K2V", @distance="10.5 LY", @name="Epsilon Eridani">], @chart=["log", "csv"]>
+  rails development  >a.weigh_anchor
+    name,distance,spectral_type,namehash,namenext,nameupcase,star_vowels
+    Proxima Centauri,4.2 LY,M5.5Vc,971295636,Proxima Centaurj,PROXIMA CENTAURI,Pr*x*m* C*nt**r*
+    Rigil Kentaurus,4.3 LY,G2V,-231389024,Rigil Kentaurut,RIGIL KENTAURUS,R*g*l K*nt**r*s
+    Barnard's Star,5.9 LY,M3.8V,1003964756,Barnard's Stas,BARNARD'S STAR,B*rn*rd's St*r
+    Wolf 359,7.7 LY,M5.8Vc,429493790,Wolf 360,WOLF 359,W*lf 359
+    Lalande 21185,8.26 LY,M2V,466625069,Lalande 21186,LALANDE 21185,L*l*nd* 21185
+    Luyten 726-8A and B,8.73 LY,M5.5 de & M6 Ve,-886693495,Luyten 726-8A and C,LUYTEN 726-8A AND B,L*yt*n 726-8A *nd B
+    Sirius A and B,8.6 LY,A1Vm,-969980943,Sirius A and C,SIRIUS A AND B,S*r**s A *nd B
+    Ross 154,9.693 LY,M3.5,-26506942,Ross 155,ROSS 154,R*ss 154
+    Ross 248,10.32 LY,M5.5V,-18054910,Ross 249,ROSS 248,R*ss 248
+    Epsilon Eridani,10.5 LY,K2V,931307088,Epsilon Eridanj,EPSILON ERIDANI,Eps*l*n Er*d*n*
+    => #<File:/Users/pboling/RubymineProjects/empty_csv_pirate_app/log/csv/Star.20091004.export.3.csv (closed)>
+
+== Advanced Usage & Examples
 
 Assuming a Make (as in manufacturers of automobiles) model like this:
 
@@ -99,8 +170,29 @@ Assuming a Make (as in manufacturers of automobiles) model like this:
     has_many :vehicle_models
     named_scope :factory_in_germany, :conditions => ["factory = ?", "Germany"]
 
-    has_csv_pirate_ship :spyglasses => [:factory_in_germany],
-                        :booty => [:id, :name]
+    # Showing all available options with their default values
+    has_csv_pirate_ship :chart          => ['log','csv']        # Array of Strings: directory where csv will be created (Yes, it creates all of them if they do not already exist)
+                        :aft            => '.csv'               # String: filename extension, usually this would be '.csv', but can be whatever you want.
+                        :gibbet         => '.export'            # String: Middle part of the filename {the '.' is required for iterative filenames, set :swab => :none to turn off iterative filenames}
+                                                                # Comes after waggoner and chronometer, before swabbie and aft
+                        :waggoner       => "#{Make}"            # String: First part of filename
+
+                        # Must provide :swag or :grub (not both)
+                        :swag           => nil                  # Array of objects: to use to create the CSV (i.e. you've already done the query and have the results you want a CSV of)
+                        :grub           => Make                 # Class:  on which to call the method chain in :spyglasses that will return the array of objects to be placed in :swag by CsvPirate (See description of swag above).
+                        :spyglasses     => [:all]               # Array of symbols/strings: Methods that will be chained together and called on :grub in order to get the :swag records which will become the rows of the CSV.
+                        :booty          => Make.column_names    # Array of symbols/strings or nested hashes of symbols/strings: Methods to call on each object in :swag.  These become the columns of the CSV.  The method names become the CSV column headings.  Methods can be chained to dig deep (e.g. traverse several ActiveRecord associations) to get at a value for the CSV.
+
+                        :swab           => :counter             # Symbol: What kind of file counter to use to avoid overwtiting the CSV file, :counter is Integer, :timestamp is HHMMSS, :none is no file counter, increasing the liklihood of duplicate filenames on successive csv exports.
+                        :mop            => :clean               # Symbol: If we DO end up writing to a preexisting file (by design or accident) should we overwrite (:clean) or append (:dirty)?
+                        :shrouds        => ','                  # String: Delimiter for CSV.  '\t' will create a tab delimited file (tsv), '|' will create a pipe delimited file.
+                        :bury_treasure  => true                 # Boolean: Should the array of objects in :swag be stored in the CsvPirate object for later inspection?
+
+    # A customized version to create a tab delimited file for this class might look like this:
+    # has_csv_pirate_ship   :spyglasses => [:factory_in_germany],
+    #                       :booty      => [:id, :name],
+    #                       :shrouds    => '\t'
+    #                       # kepping the rest of the options at the default values, so they don't need to be defined.
   end
 
 To create a csv of the names and ids of makes with factories in germany and return the text of the export:
@@ -113,15 +205,28 @@ The name of the csv that comes out will be (by defualt located in log directory)
 
 Where Make is the class, 20090930 is today's date, .export is the gibbet, and 13 is the iterative file counter, meaning I've run this export 13 times today.
 
-All of those filename parts are customizable to a degree.
+All of those filename parts are customizable to a degree.  For example if you want to have the date NOT be today's date you can supply your own date:
+
+  Make.walk_the_plank({:chronometer => Date.parse("December 21, 2012") })
+  # Filename would be: Make.20121221.export.13.csv
+
+  Make.walk_the_plank({:chronometer => false })
+  # Filename would be: Make.export.13.csv
+
+What if you want the file name to be always the same and to always append to the end of it?
+  #Example: I want the file to be named "data", with no extension, both of the following accomplish that:
+  Make.walk_the_plank({:chronometer => false, :gibbet => "", :aft => "", :swab => :none, :waggoner => 'data'})
+  Make.blindfold(:chronometer => false, :gibbet => "", :aft => "", :swab => :none, :waggoner => 'data')
+
+All of the options to has_csv_pirate_ship are available to walk_the_plank, land_ho, and blindfold, as well as to the raw class methods CsvPirate.new and CsvPirate.create, but not neccessarily the other way around.
 
-You can also customize the CSV, for example if you want to add a column to the csv:
+You can also customize the CSV, for example if you want to customize which columns are in the csv:
 
   Make.walk_the_plank({:booty => [:id, :name, :sales]})
 
-Youw want a timestamp file counter instead of the integer default:
+You want a timestamp file counter instead of the integer default:
 
-  Make.walk_the_plank({:booty => [:id, :name, :sales], :spyglasses => [:all], :swab => :timestamp})
+  Make.walk_the_plank({:booty => [:id, :name, :sales], :swab => :timestamp})
 
 If you want to append each export to the end of the same file (on a per day basis):
 
@@ -270,6 +375,23 @@ Then check the output from the console:
 
 Joy to recursive code everywhere!
 
+If you wanted to create the CsvPirate object and then modify it before creating the csv you can do that too.
+Does not actually create the csv, so you need to do this in your code:
+
+  csv_pirate = VehicleModel.land_ho({:booty => [:id, :name, :year, :horsepower, :price]})
+
+This allows you to modify the csv_pirate object before creating the csv like this:
+
+  csv_pirate.booty -= [:id, :name]
+  csv_pirate.hoist_mainstay()
+
+== Thanks
+
+Thanks go to
+9thBit LLC (http://www.9thBit.net)
+Sagebit LLC (http://www.sagebit.com) - Sagebit has been very supportive of my open source efforts, thanks Ben!
+TimePerks LLC (http://www.timeperks.com) - Many useful enhancements were requested and paid for by TimePerks
+
 ----------------------------------------------------------------------------------
   Author: Peter Boling, peter.boling at gmail dot com
   Copyright (c) 2009 Peter H. Boling of 9thBit LLC, released under the MIT license.  See LICENSE for details.

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:patch: 1
+:patch: 0
 :major: 3
-:minor: 1
+:minor: 3

data/csv_pirate.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{csv_pirate}
-  s.version = "3.1.1"
+  s.version = "3.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Peter Boling"]
-  s.date = %q{2009-10-01}
+  s.date = %q{2009-10-05}
   s.description = %q{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!}
   s.email = %q{peter.boling@gmail.com}

data/lib/csv_pirate.rb

@@ -14,15 +14,15 @@ class CsvPirate
   BOOKIE = [:counter, :timestamp, :none]
   MOP_HEADS = [:clean, :dirty]
 
-  attr_accessor :waggoner         #filename
-  attr_accessor :chart            #directory, default is (['log','csv'])
-  attr_accessor :aft              #extension, default is ('.csv')
-  attr_accessor :gibbet           #part of the filename after waggoner and date, before swabbie and aft
-  attr_accessor :chronometer
+  attr_accessor :waggoner         # First part of filename
+  attr_accessor :chart            # directory, default is (['log','csv'])
+  attr_accessor :aft              # extension, default is ('.csv')
+  attr_accessor :gibbet           # part of the filename after waggoner and date, before swabbie and aft
+  attr_accessor :chronometer      # Date object or false
 
   # Must provide swag or grub (not both)
-  attr_accessor :swag             # ARrr array of objects
-  attr_accessor :grub             # ARrr class
+  attr_accessor :swag             # Array of objects
+  attr_accessor :grub             # Class
   # spyglasses is only used with grub, not swag
   attr_accessor :spyglasses       # named_scopes
   
@@ -60,14 +60,14 @@ class CsvPirate
   # :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
+  # :chronometer    keeps track of when you hunt for treasure, can be false if you don't want to keep track.
   # :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
+  #   :none - no iterative file naming convention, just use waggoner, aft and gibbet 
   # :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
+  #   :clean - do not use :counter or :timestamp, and instead overwrite the file
   #   :dirty - do not use :counter, or :timestamp, or :overwrite.  Just keep adding on.
   # :bury_treasure  should we store the csv data as it is collected in an array in Ruby form for later use (true), or just write the CSV (false)?
   # See README for examples
@@ -79,33 +79,34 @@ class CsvPirate
     @grub = args.first[:grub]
 
     # if they provide both
-    raise ArgumentError, "must provide either :swag or :grub" if !args.first[:swag].blank? && !args.first[:grub].blank?
+    raise ArgumentError, "must provide either :swag or :grub, not both" if !self.swag.blank? && !self.grub.blank?
     # if they provide neither
-    raise ArgumentError, "must provide either :swag or :grub, not both" if args.first[:swag].blank? && args.first[:grub].blank?
+    raise ArgumentError, "must provide either :swag or :grub" if self.swag.blank? && self.grub.blank?
 
     @swab = args.first[:swab] || :counter
-    raise ArgumentError, ":swab is #{args.first[:swab].inspect}, but must be one of #{CsvPirate::BOOKIE.inspect}" unless CsvPirate::BOOKIE.include?(args.first[:swab])
+    raise ArgumentError, ":swab is #{self.swab.inspect}, but must be one of #{CsvPirate::BOOKIE.inspect}" unless CsvPirate::BOOKIE.include?(self.swab)
 
     @mop = args.first[:mop] || :clean
-    raise ArgumentError, ":mop is #{args.first[:mop].inspect}, but must be one of #{CsvPirate::MOP_HEADS.inspect}" unless CsvPirate::MOP_HEADS.include?(args.first[:mop])
+    raise ArgumentError, ":mop is #{self.mop.inspect}, but must be one of #{CsvPirate::MOP_HEADS.inspect}" unless CsvPirate::MOP_HEADS.include?(self.mop)
 
     @gibbet = args.first[:gibbet] || '.export'
-    raise ArgumentError, ":gibbet is #{args.first[:gibbet].inspect}, and does not contain a '.' character, which is required for iterative filenames" if args.first[:gibbet].nil? || !args.first[:gibbet].include?('.')
+    raise ArgumentError, ":gibbet is #{self.gibbet.inspect}, and does not contain a '.' character, which is required when using iterative filenames (set :swab => :none to turn off iterative filenames)" if self.swab != :none && (self.gibbet.nil? || !self.gibbet.include?('.'))
 
     @waggoner = args.first[:waggoner] || "#{self.grub || self.swag}"
-    raise ArgumentError, ":waggoner is #{args.first[:waggoner].inspect}, and must be a string at least one character long" if args.first[:waggoner].nil? || args.first[:waggoner].length < 1
+    raise ArgumentError, ":waggoner is #{self.waggoner.inspect}, and must be a string at least one character long" if self.waggoner.nil? || self.waggoner.length < 1
 
     @booty = args.first[:booty] || []
-    raise ArgumentError, ":booty is #{args.first[:booty].inspect}, and must be an array of methods to call on a class for CSV data" if args.first[:booty].nil? || !args.first[:booty].is_a?(Array) || args.first[:booty].empty?
+    raise ArgumentError, ":booty is #{self.booty.inspect}, and must be an array of methods to call on a class for CSV data" if self.booty.nil? || !self.booty.is_a?(Array) || self.booty.empty?
 
     @chart = args.first[:chart] || ['log','csv']
-    raise ArgumentError, ":chart is #{args.first[:chart].inspect}, and must be an array of directory names, which will become the filepath for the csv file" if args.first[:chart].nil? || !args.first[:chart].is_a?(Array) || args.first[:booty].empty?
+    raise ArgumentError, ":chart is #{self.chart.inspect}, and must be an array of directory names, which will become the filepath for the csv file" if self.chart.nil? || !self.chart.is_a?(Array) || self.chart.empty?
 
     @aft = args.first[:aft] || '.csv'
-    @chronometer = args.first[:chronometer] || Date.today
+    @chronometer = args.first[:chronometer] == false ? false : args.first[:chronometer] || Date.today
 
     @spyglasses = (args.first[:spyglasses] || [:all]) if self.grub
     @shrouds = args.first[:shrouds] || ','  # for tsv, tab-delimited, "\t"
+    raise ArgumentError, ":shrouds is #{self.shrouds.inspect}, and must be a string (e.g. ',' or '\t'), which will be used as the delimeter for the csv file" if self.shrouds.nil? || !self.shrouds.is_a?(String)
 
     @astrolabe = args.first[:astrolabe] || false
 
@@ -198,7 +199,7 @@ class CsvPirate
 
     self.rhumb_lines.close
 
-    self.jolly_roger if CsvPirate.parlay > 1
+    self.jolly_roger if CsvPirate.parlay && CsvPirate.parlance(1)
 
     # returns the text of this CSV export
     return self.maroon
@@ -215,10 +216,10 @@ class CsvPirate
   def jolly_roger
     if self.bury_treasure
       if self.buried_treasure.is_a?(Array)
-        puts "Found #{self.buried_treasure.length} deniers buried here: '#{self.poop_deck}'" if CsvPirate.parlay > 1
-        puts "You must weigh_anchor to review your plunder!" if CsvPirate.parlay > 1
+        puts "Found #{self.buried_treasure.length} deniers buried here: '#{self.poop_deck}'" if CsvPirate.parlay && CsvPirate.parlance(1)
+        puts "You must weigh_anchor to review your plunder!" if CsvPirate.parlay && CsvPirate.parlance(1)
       else
-        puts "Failed to locate treasure" if CsvPirate.parlay > 1
+        puts "Failed to locate treasure" if CsvPirate.parlay && CsvPirate.parlance(1)
       end
     end
   end
@@ -371,7 +372,7 @@ class CsvPirate
     return false unless block_given?
     count = 1 if report_kills
     FasterCSV.foreach(galley, {:headers => :first_row, :return_headers => false}) do |gun|
-      puts "Galleys sunk: #{count+=1}" if CsvPirate.parlay > 1
+      puts "Galleys sunk: #{count+=1}" if CsvPirate.parlance(1)
       yield gun
     end
   end
@@ -421,13 +422,13 @@ class CsvPirate
     cutthroat.figurehead
 
     carrack.scuttle do |cutlass|
-      puts "CUTLASS: #{cutlass.inspect}" if CsvPirate.parlay > 2
-      puts "CARRACK.SWAG: #{carrack.swag.inspect}" if CsvPirate.parlay > 2
+      puts "CUTLASS: #{cutlass.inspect}" if CsvPirate.parlance(2)
+      puts "CARRACK.SWAG: #{carrack.swag.inspect}" if CsvPirate.parlance(2)
       backstaff = cutlass[carrack.swag] || cutlass["#{carrack.spyglasses}"]
-      puts "BACKSTAFF: #{backstaff}" if CsvPirate.parlay > 2
-      puts "CARRACK.SPYGLASSES: #{carrack.spyglasses.inspect}" if CsvPirate.parlay > 2
+      puts "BACKSTAFF: #{backstaff}" if CsvPirate.parlance(2)
+      puts "CARRACK.SPYGLASSES: #{carrack.spyglasses.inspect}" if CsvPirate.parlance(2)
       gully = carrack.grub.send("find_by_#{carrack.spyglasses}".to_sym, backstaff)
-      puts "GULLY: #{gully.inspect}" if CsvPirate.parlay > 2
+      puts "GULLY: #{gully.inspect}" if CsvPirate.parlance(2)
       if gully
         flotsam = cutthroat.grub.is_a?(String) ? 
           gully.send(cutthroat.grub.to_sym) : 
@@ -438,16 +439,16 @@ class CsvPirate
               cutthroat.grub.class == Class ? 
                 cutthroat.grub.send("find_by_#{cutthroat.swag}", gully.send(cutthroat.spyglasses)) : 
                 nil
-        puts "FLOTSAM: #{flotsam.inspect}" if CsvPirate.parlay > 2
+        puts "FLOTSAM: #{flotsam.inspect}" if CsvPirate.parlance(2)
         if flotsam
           plunder = cutthroat.prize(flotsam)
           cutthroat.buried_treasure << plunder
           cutthroat.scrivener(plunder.map {|bulkhead| "#{bulkhead}"}.join(','))
         else
-          puts "Unable to locate: #{cutthroat.grub} related to #{carrack.grub}.#{carrack.spyglasses} '#{gully.send(carrack.spyglasses)}'" if CsvPirate.parlay > 1
+          puts "Unable to locate: #{cutthroat.grub} related to #{carrack.grub}.#{carrack.spyglasses} '#{gully.send(carrack.spyglasses)}'" if CsvPirate.parlance(1)
         end
       else
-        puts "Unable to locate: #{carrack.grub}.#{carrack.spyglasses} '#{gully.send(carrack.spyglasses)}'" if CsvPirate.parlay > 1
+        puts "Unable to locate: #{carrack.grub}.#{carrack.spyglasses} '#{gully.send(carrack.spyglasses)}'" if CsvPirate.parlance(1)
       end
     end
     
@@ -460,4 +461,9 @@ class CsvPirate
     return cutthroat
   end
 
+  # verbosity on a scale of 0 - 3 (0=:none, 1=:error, 2=:info, 3=:debug, 0 being no screen output, 1 is default
+  def self.parlance(level = 1)
+    self.parlay.is_a?(Numeric) && self.parlay >= level
+  end
+
 end

data/lib/ninth_bit/pirate_ship.rb

@@ -23,15 +23,16 @@ module NinthBit
         options[:parlay]        ||= 1
 
         # if they provide both
-        raise ArgumentError, "must provide either :swag or :grub" if !options[:swag].blank? && !options[:grub].blank?
+        raise ArgumentError, "must provide either :swag or :grub, not both" if !options[:swag].blank? && !options[:grub].blank?
         # if they provide neither
-        raise ArgumentError, "must provide either :swag or :grub, not both" if options[:swag].blank? && options[:grub].blank?
+        raise ArgumentError, "must provide either :swag or :grub" if options[:swag].blank? && options[:grub].blank?
         raise ArgumentError, ":swab is #{options[:swab].inspect}, but must be one of #{CsvPirate::BOOKIE.inspect}" unless CsvPirate::BOOKIE.include?(options[:swab])
         raise ArgumentError, ":mop is #{options[:mop].inspect}, but must be one of #{CsvPirate::MOP_HEADS.inspect}" unless CsvPirate::MOP_HEADS.include?(options[:mop])
-        raise ArgumentError, ":gibbet is #{options[:gibbet].inspect}, and does not contain a '.' character, which is required for iterative filenames" if options[:gibbet].nil? || !options[:gibbet].include?('.')
+        raise ArgumentError, ":gibbet is #{options[:gibbet].inspect}, and does not contain a '.' character, which is required when using iterative filenames (set :swab => :none to turn off iterative filenames)" if options[:swab] != :none && (options[:gibbet].nil? || !options[:gibbet].include?('.'))
         raise ArgumentError, ":waggoner is #{options[:waggoner].inspect}, and must be a string at least one character long" if options[:waggoner].nil? || options[:waggoner].length < 1
         raise ArgumentError, ":booty is #{options[:booty].inspect}, and must be an array of methods to call on a class for CSV data" if options[:booty].nil? || !options[:booty].is_a?(Array) || options[:booty].empty?
         raise ArgumentError, ":chart is #{options[:chart].inspect}, and must be an array of directory names, which will become the filepath for the csv file" if options[:chart].nil? || !options[:chart].is_a?(Array) || options[:chart].empty?
+        raise ArgumentError, ":shrouds is #{options[:shrouds].inspect}, and must be a string (e.g. ',' or '\t'), which will be used as the delimeter for the csv file" if options[:shrouds].nil? || !options[:shrouds].is_a?(String)
 
         extend ClassMethods unless (class << self; included_modules; end).include?(ClassMethods)
 
@@ -48,48 +49,58 @@ module NinthBit
 
       # intended for use with send_data for downloading the text of the csv:
       # send_data Make.say_your_last_words
-      # TODO: Fix say_yourr_last_words so it works! Use send_data args
+      # TODO: Fix say_yourr_last_words so it works! Use send_data args for real
       #def say_your_last_words(charset = 'utf-8', args = {})
       #  csv_pirate = self.blindfold(args)
       #  return [ csv_pirate.maroon,
       #    {:type => "text/csv; charset=#{charset}; header=present"},
       #    {:disposition => "attachment; filename=#{csv_pirate.nocturnal}"} ]
       #end
-      
-      #returns the text of the csv export (not the file - this is important if you are appending)
+
+      # returns the text of the csv export (not the file - this is important if you are appending)
       # warning if using from console: if you are exporting a large csv this will all print in your console.
       # intended for use with send_data for downloading the text of the csv:
       # send_data Make.walk_the_plank,
       #          :type => 'text/csv; charset=iso-8859-1; header=present',
       #          :disposition => "attachment; filename=Data.csv"
       def walk_the_plank(args = {})
-        csv_pirate = CsvPirate.new(self.piratey_args(args))
-        csv_pirate.hoist_mainstay()
+        self.land_ho(args).hoist_mainstay()
       end
 
-      #returns the csv_pirate object so you have access to everything
+      # returns the csv_pirate object so you have access to everything
+      # warning if using from console: if you are exporting a large csv this will all print in your console.
       # If using in a download action it might look like this:
       # csv_pirate = Make.blindfold
       # send_data csv_pirate.maroon,
       #          :type => 'text/csv; charset=iso-8859-1; header=present',
       #          :disposition => "attachment; filename=#{csv_pirate.nocturnal}"
       def blindfold(args = {})
-        CsvPirate.parlay = args[:parlay] || self.piratey_options[:parlay]
         CsvPirate.create(self.piratey_args(args))
       end
 
+      # returns the csv_pirate object so you have access to everything
+      # Does not actually create the csv, so you need to do this in your code:
+      #   csv_pirate = Klass.land_ho({:booty => [:id, :name, :dragons, :created_at]})
+      # This allows you to modify the csv_pirate object before creating the csv like this:
+      #   csv_pirate.booty -= [:id, :name]
+      #   csv_pirate.hoist_mainstay()
+      def land_ho(args = {})
+        CsvPirate.new(self.piratey_args(args))
+      end
+
       protected
 
       def piratey_args(args = {})
-        { :chart => args[:chart] || self.piratey_options[:chart],
+        CsvPirate.parlay = args[:parlay] || self.piratey_options[:parlay]
+        return { :chart => args[:chart] || self.piratey_options[:chart],
           :aft => args[:aft] || self.piratey_options[:aft],
           :gibbet => args[:gibbet] || self.piratey_options[:gibbet],
-          :chronometer => args[:chronometer] || Date.today,
+          :chronometer => args[:chronometer] == false ? false : args[:chronometer] || Date.today,
           :waggoner => args[:waggoner] || self.piratey_options[:waggoner] || "#{self}",
           :swag => args[:swag] || self.piratey_options[:swag],
           :swab => args[:swab] || self.piratey_options[:swab],
           :mop => args[:mop] || self.piratey_options[:mop],
-          :shrouds => args[:swab] || self.piratey_options[:shrouds],
+          :shrouds => args[:shrouds] || self.piratey_options[:shrouds],
           :grub => args[:grub] || self.piratey_options[:grub],
           :spyglasses => args[:spyglasses] || self.piratey_options[:spyglasses],
           :booty => args[:booty] || self.piratey_options[:booty],

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: csv_pirate
 version: !ruby/object:Gem::Version 
-  version: 3.1.1
+  version: 3.3.0
 platform: ruby
 authors: 
 - Peter Boling
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-01 00:00:00 -04:00
+date: 2009-10-05 00:00:00 -04:00
 default_executable: 
 dependencies: []