csv_shaper 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in csv_shaper.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Paul Springett
+
+MIT License
+
+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.md

@@ -0,0 +1,145 @@
+# CSV Shaper
+
+Beautiful DSL for creating CSV output in Ruby & Rails.
+
+Creating CSV files in Ruby is painful! CSV Shaper makes life easier! It's ideal for converting database backed models with attrbiutes into CSV output. It can be used without Rails, but works great with ActiveRecord models and even comes with support for it's own template handling.
+
+### Example Usage
+
+```ruby
+csv_string = CsvShaper::Shaper.encode do |csv|
+  csv.header :name, :age, :gender, :pet_names
+  
+  csv.rows @users do |csv, user|
+    csv.cells :name, :age, :gender
+    
+    if user.pets.any?
+      csv.cell :pet_names
+    end
+  end
+end
+```
+
+### Install
+
+Install using Rubygems
+
+```bash
+$ gem install csv_shaper
+```
+
+Or if you want to use it in your Rails app, add the following line to your Gemfile
+
+```ruby
+gem 'csv_shaper'
+```
+
+and then run
+
+```bash
+$ bundle install
+```
+
+### Usage
+
+Everything goes inside the `encode` block, like so
+
+```ruby
+csv_string = CsvShaper::Shaper.encode do |csv|
+  ...
+end
+```
+
+If you're using it in Rails 3.0+ you are already inside the block so you can just call the `csv` object.
+
+Create a Rails view, set the content-type to `csv` and the handler to `shaper`, like so
+
+    index.csv.shaper
+
+### Headers
+
+You must define the headers for your CSV output. This can be done in one of 3 ways.
+
+#### Standard attribute list
+
+```ruby
+csv.headers :name, :age, :location
+```
+
+This would create headers like so:
+
+```csv
+Name,Age,Location
+```
+
+#### Using the attribute names of a Class
+
+Say you have a User ActiveRecord class with attributes of `:name, :age, :location`. Simply pass the class to the headers method
+
+```ruby
+csv.headers User
+```
+
+#### Using a block to define headers and custom mappings
+
+```ruby
+csv.headers do |csv|
+  csv.columns :name, :age, :location
+  csv.mappings name: 'Full name', location: 'Region'
+end
+```
+
+This would create headers like so:
+
+```csv
+Full name,Age,Region
+```
+
+### Rows & Cells
+
+CSV Shaper allows you to define rows and cells in a variety of ways.
+
+#### Basic row without a model
+
+```ruby
+csv.row do |csv|
+  csv.cell :name, "Joe"
+  csv.cell :age, 24
+end
+```
+
+#### Passing a model and attributes
+
+```ruby
+csv.row @user, :name, :age, :location
+```
+
+This will call the column names (name, age...) on @user and assign them to the correct cells.
+
+#### Passing a model to a block
+
+```ruby
+csv.row @user, do |csv, user|
+  csv.cells :name, :age
+  if user.show_gender?
+    csv.cell :gender
+  end
+
+  csv.cell :exported_at, Time.now
+end
+```
+
+Any calls here to `cell` or `cells` without a value are called on the model (`user`), otherwise the second parameter is assigned.
+
+### Multiple Rows
+
+You can pass an Enumerable and a block to `csv.rows` like so
+
+```ruby
+csv.rows @users do |csv, user|
+  csv.cells :name, :age, :location, :gender
+  csv.cell :exported_at, Time.now
+end
+```
+
+Copyright (c) Paul Springett 2012

data/Rakefile

@@ -0,0 +1,5 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')

data/csv_shaper.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/csv_shaper/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Paul Springett"]
+  gem.email         = ["paul@springett.me"]
+
+  gem.summary       = %q{Beautiful DSL for creating CSV output in Ruby & Rails}
+  gem.description   = %q{
+    Creating CSV files in Ruby is painful! CSV Shaper makes life easier! It's
+    ideal for converting database backed models with attrbiutes into CSV output.
+    It can be used without Rails, but works great with ActiveRecord models and even
+    comes with support for it's own template handling.
+  }
+
+  gem.homepage      = "http://github.com/paulspringett/csv_shaper"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "csv_shaper"
+  gem.require_paths = ["lib"]
+  gem.version       = CsvShaper::VERSION
+
+  gem.add_dependency 'activesupport', '>= 3.0.0'
+  gem.add_dependency 'blankslate', '>= 2.1.2.4'
+  
+  gem.add_development_dependency 'rspec'
+end

data/lib/csv_shaper/encoder.rb

@@ -0,0 +1,42 @@
+require 'csv'
+
+module CsvShaper
+  class Encoder < BlankSlate
+    def initialize(header, rows = [])
+      if header.nil?
+        raise MissingHeadersError, 'you must define some headers using csv.headers ...'
+      end
+      
+      @header = header
+      @rows = rows
+    end
+    
+    # Public: converts the Shaper mapped headers and rows into
+    # a CSV String
+    #
+    # Returns a String
+    def to_csv
+      rows = padded_rows.map do |data|
+        CSV::Row.new(@header.mapped_columns, data, false)
+      end
+
+      table = CSV::Table.new(rows)
+      table.to_csv
+    end
+    
+    private
+    
+    # Internal: make use of CSV#values_at to pad out the
+    # cells into the correct columns for the headers
+    #
+    # Returns an Array of Arrays
+    def padded_rows
+      rows = @rows.map do |row|
+        CSV::Row.new(row.cells.keys, row.cells.values)
+      end
+      
+      table = CSV::Table.new(rows)
+      table.values_at(*@header.columns)
+    end
+  end
+end

data/lib/csv_shaper/header.rb

@@ -0,0 +1,76 @@
+module CsvShaper
+  
+  # Header
+  # Handles creating and mapping of the headers
+  # Examples:
+  #   # assign the headers from the attributes of a class
+  #   csv.headers User
+  # 
+  #   # assigns headers normally
+  #   csv.headers :name, :age, :location
+  # 
+  #   # pass a block
+  #   csv.headers do |csv|
+  #     csv.columns :name, :age, :location
+  #     csv.mappings name: 'Full name, location: 'Region'
+  #   end
+  #
+  class Header < BlankSlate
+    attr_reader :klass, :mappings, :mapped_columns
+
+    def initialize(*args)
+      @mappings = {}
+      @columns = []
+
+      # csv.headers do |head|
+      if block_given?
+        yield self
+      elsif args.any?
+        # csv.headers User
+        if (@klass = args.first.respond_to?(:attribute_names) && args.first)
+          columns(*@klass.attribute_names)
+        # csv.headers :name, :age, :location
+        else
+          columns(*args)
+        end
+      end
+    end
+    
+    # Public: serves as the getter and setter for the Array
+    # of Symbol column names. Union join the existing column
+    # names with those passed
+    # Example:
+    #   header.columns :name, :age, :location
+    #
+    #   args - Array of Symbol arguments passed
+    #
+    # Returns as Array of Symbols
+    def columns(*args)
+      @columns = @columns | args.map(&:to_sym)
+    end
+    
+    # Public: Define mappings of the Symbol column names
+    # to nicer, human names
+    # Example:
+    #   header.mappings name: 'Full name', age: 'Age of person'
+    #
+    #   hash - Hash of mappings where the key is the column name to map
+    #          and the value is the human readable value
+    #
+    # Returns a Hash of mappings
+    def mappings(hash = {}) 
+      @mappings.merge!(hash)
+    end
+    
+    # Public: converts columns and mappings into mapped columns
+    # ready for encoding. If a mapped value is found that is used,
+    # else the Symbol column name is humanized
+    #
+    # Returns an Array of Strings
+    def mapped_columns
+      @columns.map do |column|
+        @mappings[column] || column.to_s.humanize
+      end
+    end
+  end
+end

data/lib/csv_shaper/row.rb

@@ -0,0 +1,77 @@
+module CsvShaper
+  
+  # Row
+  # Handles creating of cells within a row and
+  # assigning of the model's values to cells
+  # Examples:
+  #   # pass a model to the row
+  #   csv.row @model do |csv, model|
+  #     ...
+  #   end
+  # 
+  #   # create an empty row instance
+  #   csv.row do |csv|
+  #     ...
+  #   end
+  # 
+  #   # create a row with prefilled cells from a model
+  #   # note no block is passed
+  #   csv.row @model, :name, :age, :location
+  # 
+  class Row < BlankSlate
+    attr_reader :model, :cells
+    
+    def initialize(*args)
+      @cells = ActiveSupport::OrderedHash.new
+
+      # csv.row @user do |csv, user|
+      if args.one? && block_given?
+        @model = args.first
+        yield self, @model
+      
+      # csv.row do |csv|
+      elsif args.empty? && block_given?
+        yield self
+      
+      # csv.row @user, :name, :age, :location
+      elsif args.length > 1
+        @model = args.shift
+        args.each { |col| cell(col) }
+      else
+        raise ArgumentError, 'invalid args passed to csv.row'
+      end        
+    end
+    
+    # Public: assign the given Array of args to cells in this Row
+    #
+    #   args - Array of the arguments passed (expected to be Symbols)
+    #
+    # Returns an Array of the Cells in this row
+    def cells(*args)
+      args.each { |col| cell(col) }
+      @cells
+    end
+    
+    # Public: add a cell to this Row
+    # If the Row has a @model defined passing just a Symbol will
+    # call that method on the @model and assign it to a column of
+    # the same name. Otherwise a value will need to be passed also
+    #
+    #   column - Symbol of the column to add to value to
+    #   value - data to assign to the cell (default: nil)
+    #
+    # Returns an Array of the Row's cells
+    def cell(column, value = nil)
+      column = column.to_sym
+      
+      if @model && value.nil?
+        @cells[column] = @model.send(column)
+      else
+        @cells[column] = value
+      end
+      
+      @cells
+    end
+    
+  end
+end

data/lib/csv_shaper/shaper.rb

@@ -0,0 +1,72 @@
+module CsvShaper
+  class Shaper < BlankSlate
+    attr_reader :header, :rows
+    
+    def initialize
+      @rows = []
+      yield self if block_given?
+    end
+    
+    # Public: creates a new instance of Shaper taps it with
+    # with the given block and encodes it to a String of CSV data
+    # Example:
+    #   data = CsvShaper::Shaper.encode do |csv|
+    #     csv.rows @users do |csv, user|
+    #       csv.cells :name, :age, :gender
+    #     end
+    #   end
+    #
+    #  puts data
+    #  => "Name,Age,Gender\n'Joe Bloggs',25,'M'\n'John Smith',34,'M'" 
+    #
+    # Returns a String
+    def self.encode
+      new.tap { |shaper| yield shaper }.to_csv
+    end
+    
+    # Public: creates a header row for the CSV
+    # This is delegated to the Header class
+    # see header.rb for usage examples
+    #
+    # Returns a Header instance
+    def headers(*args, &block)
+      @header = Header.new(*args, &block)
+    end
+    
+    # Public: adds a row to the CSV
+    # This is delegated to the Row class
+    # See row.rb for usage examples
+    #
+    # Returns an updated Array of Row objects
+    def row(*args, &block)
+      @rows.push Row.new(*args, &block)
+    end
+    
+    # Public: adds several rows to the CSV
+    #
+    #   collection - an Enumerable of objects to be passed to #row
+    #
+    # Returns an updated Array of Row objects
+    def rows(collection = nil, &block)
+      return @rows if collection.nil?
+      
+      unless collection.respond_to?(:each)
+        raise ArgumentError, 'csv.rows only accepts Enumerable object (that respond to #each). Use csv.row for a single object.'
+      end
+
+      collection.each do |element|
+        row(element, &block)
+      end
+
+      @rows
+    end
+
+    # Public: converts the Header and Row objects into a string
+    # of valid CSV data. Delegated to the Encoder class
+    #
+    # Returns a String
+    def to_csv
+      Encoder.new(@header, @rows).to_csv
+    end
+  end
+end

data/lib/csv_shaper/version.rb

@@ -0,0 +1,3 @@
+module CsvShaper
+  VERSION = "0.0.1"
+end

data/lib/csv_shaper.rb

@@ -0,0 +1,15 @@
+require 'blankslate'
+require 'active_support/ordered_hash'
+require 'active_support/inflector'
+
+require 'csv_shaper/version'
+require 'csv_shaper/header'
+require 'csv_shaper/row'
+require 'csv_shaper/encoder'
+require 'csv_shaper/shaper'
+
+module CsvShaper
+  class MissingHeadersError < StandardError; end
+end
+
+require "csv_shaper_template" if defined?(ActionView::Template)

data/lib/csv_shaper_template.rb

@@ -0,0 +1,25 @@
+class CsvShaperTemplate < CsvShaper::Shaper
+  def self.encode(context)
+    new(context).tap { |shaper| yield shaper }.to_csv
+  end
+  
+  def initialize(context)
+    @context = context
+    super()
+  end
+end
+
+class CsvShaperHandler
+  cattr_accessor :default_format
+  self.default_format = Mime::CSV
+
+  def self.call(template)
+    %{
+      CsvShaperTemplate.encode(self) do |csv|
+        #{template.source}
+      end
+    }
+  end
+end
+
+ActionView::Template.register_template_handler :shaper, CsvShaperHandler

data/spec/csv_shaper_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe CsvShaper::Shaper do
+  it "should return a version" do
+    CsvShaper::VERSION.should be_kind_of(String)
+  end
+  
+  it "should raise an exception when passing a non-enumarble to rows" do
+    csv = CsvShaper::Shaper.new
+    expect {
+      csv.rows :name
+    }.to raise_exception(ArgumentError, 'csv.rows only accepts Enumerable object (that respond to #each). Use csv.row for a single object.')
+  end
+  
+  it "should respond to to_csv" do
+    csv = CsvShaper::Shaper.new
+    csv.should respond_to(:to_csv)
+  end
+end

data/spec/encoder_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+require 'fixtures/user'
+
+describe CsvShaper::Encoder do
+  let(:user) { User.new(name: 'Paul', age: 27, gender: 'Male') }
+  
+  it "should raise an exception if the headers are missing" do
+    expect {
+      CsvShaper::Encoder.new(nil)
+    }.to raise_exception(CsvShaper::MissingHeadersError, 'you must define some headers using csv.headers ...')
+  end
+  
+  let(:users) { [User.new(name: 'Paul', age: 27, gender: 'Male'), User.new(name: 'Bob', age: 31, gender: 'Male'), User.new(name: 'Jane', age: 23, gender: 'Female')] }
+  let(:csv) {
+    CsvShaper::Shaper.new do |csv|
+      csv.headers do |csv|
+        csv.columns :name, :gender, :age
+        csv.mappings name: "Full name", gender: "Sex"
+      end
+
+      csv.rows users do |csv, user|
+        csv.cells :name, :age
+        csv.cell :gender
+      end
+
+      csv.row do |csv|
+      	csv.cell :age, users.map(&:age).reduce(:+)
+      end
+    end
+  }
+  
+  it "should encode a Shaper instance to a CSV string" do
+    encoder = CsvShaper::Encoder.new(csv.header, csv.rows)
+    encoder.to_csv.should eq("Full name,Sex,Age\nPaul,Male,27\nBob,Male,31\nJane,Female,23\n,,81\n")
+  end
+end

data/spec/fixtures/user.rb

@@ -0,0 +1,13 @@
+class User
+  attr_accessor :name, :age, :gender
+  
+  def initialize(attributes = {})
+    attributes.each do |name, value|
+      send("#{name}=", value)
+    end
+  end
+  
+  def self.attribute_names
+    [:name, :age, :gender]
+  end
+end

data/spec/header_spec.rb

@@ -0,0 +1,43 @@
+require 'spec_helper'
+require 'fixtures/user'
+
+describe CsvShaper::Header do
+  it "should accept and store a list of symbols" do
+    header = CsvShaper::Header.new(:name, :age, :location)
+    
+    header.columns.should eq [:name, :age, :location]
+  end
+  
+  it "should accept a Model and store it's attributes" do
+    header = CsvShaper::Header.new(User)
+    
+    header.columns.should eq [:name, :age, :gender]
+  end
+  
+  it "should accept a block with columns and mappings" do
+    header = CsvShaper::Header.new do |csv|
+      csv.columns :name, :age, :foo
+      csv.mappings name: 'User name'
+    end
+    
+    header.columns.should eq [:name, :age, :foo]
+    header.mapped_columns.should eq ['User name', 'Age', 'Foo']
+  end
+  
+  it "should merge columns with a union join" do
+    header = CsvShaper::Header.new(:name, :age, :location)
+    header.columns :age, :gender
+    
+    header.columns.should eq [:name, :age, :location, :gender]
+  end
+  
+  it "should merge mappings" do
+    header = CsvShaper::Header.new do |csv|
+      csv.columns :name, :age, :foo
+      csv.mappings name: 'User name'
+      csv.mappings foo: 'Bar'
+    end
+
+    header.mapped_columns.should eq ['User name', 'Age', 'Bar']
+  end
+end

data/spec/row_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+require 'fixtures/user'
+
+describe CsvShaper::Row do
+  let(:user) { User.new(name: 'Paul', age: 27, gender: 'Male') }
+  
+  it "should assign a model" do
+    row = CsvShaper::Row.new user do |csv, user|
+      # ...
+    end
+
+    row.model.should eq user
+  end
+  
+  it "should assign a model's attributes" do
+    row = CsvShaper::Row.new(user, :name, :age)
+    row.cells.should eq({ name: 'Paul', age: 27 })
+  end
+  
+  it "should yield to a block" do
+    CsvShaper::Row.new { |csv|
+      csv.should be_kind_of(CsvShaper::Row)
+    }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'rspec'
+require 'csv_shaper'
+
+RSpec.configure do |config|
+  config.color_enabled = true
+  config.formatter = 'documentation'
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: csv_shaper
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Paul Springett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70336817645940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70336817645940
+- !ruby/object:Gem::Dependency
+  name: blankslate
+  requirement: &70336817644820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 2.1.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: *70336817644820
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70336817643920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70336817643920
+description: ! "\n    Creating CSV files in Ruby is painful! CSV Shaper makes life
+  easier! It's\n    ideal for converting database backed models with attrbiutes into
+  CSV output.\n    It can be used without Rails, but works great with ActiveRecord
+  models and even\n    comes with support for it's own template handling.\n  "
+email:
+- paul@springett.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- csv_shaper.gemspec
+- lib/csv_shaper.rb
+- lib/csv_shaper/encoder.rb
+- lib/csv_shaper/header.rb
+- lib/csv_shaper/row.rb
+- lib/csv_shaper/shaper.rb
+- lib/csv_shaper/version.rb
+- lib/csv_shaper_template.rb
+- spec/csv_shaper_spec.rb
+- spec/encoder_spec.rb
+- spec/fixtures/user.rb
+- spec/header_spec.rb
+- spec/row_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/paulspringett/csv_shaper
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.16
+signing_key: 
+specification_version: 3
+summary: Beautiful DSL for creating CSV output in Ruby & Rails
+test_files:
+- spec/csv_shaper_spec.rb
+- spec/encoder_spec.rb
+- spec/fixtures/user.rb
+- spec/header_spec.rb
+- spec/row_spec.rb
+- spec/spec_helper.rb