crafterm-comma 0.1.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Marcus Crafter
+
+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.markdown

@@ -0,0 +1,76 @@
+= COMMA
+
+[http://github.com/crafterm/comma](http://github.com/crafterm/comma)
+
+== DESCRIPTION:
+
+Comma is a CSV (ie. comma separated values) generation extension for Ruby objects, that lets you seamlessly define a CSV output format via a small DSL. Comma works well on pure Ruby objects with attributes, as well as complex ones such as ActiveRecord objects with associations, extensions, etc. It doesnt distinguish between attributes, methods, associations, extensions, etc - they all are considered equal and invoked identically via the Comma DSL description.
+
+When multiple objects in an Array are converted to CSV, the output includes generation of a header row reflected from names of the properties requested, or specified via the DSL.
+
+CSV can be a bit of a boring format - the motivation behind Comma was to have a CSV extension that was simple, flexible, and would treat attributes, methods, associations, etc, all the same without the need for any complex configuration, and also work on Ruby objects, not just ActiveRecord or other base class derivatives.
+
+An example Comma CSV enabled ActiveRecord class:
+
+    class Book < ActiveRecord::Base
+  
+      # ================
+      # = Associations =
+      # ================
+      has_many   :pages
+      has_one    :isbn
+      belongs_to :publisher
+  
+      # ===============
+      # = CSV support =
+      # ===============
+      comma do
+
+        name
+        description
+    
+        pages :size => 'Pages'
+        publisher :name
+        isbn :number_10 => 'ISBN-10', :number_13 => 'ISBN-13'
+      
+      end
+
+    end
+
+Annotated, the comma description is as follows:
+
+    # starts a Comma description block, generating 2 methods #to_comma and #to_comma_headers for this class.
+    comma do
+
+      # name, description are attributes of Book with the header being reflected as 'Name', 'Description'
+      name
+      description
+  
+      # pages is an association returning an array, :size is called on the association results, with the header name specifed as 'Pages'
+      pages :size => 'Pages'
+    
+      # publisher is an association returning an object, :name is called on the associated object, with the reflected header 'Name'
+      publisher :name
+    
+      # isbn is an association returning an object, :number_10 and :number_13 are called on the object with the specified headers 'ISBN-10' and 'ISBN-13'
+      isbn :number_10 => 'ISBN-10', :number_13 => 'ISBN-13'
+    
+    end
+  
+In the above example, any of the declarations (name, description, pages, publisher, isbn, etc), could be methods, attributes, associations, etc - no distinction during configuration is required, as everything is invoked via Ruby's #send method.
+
+Object values are automatically converted to strings via to_s allowing you to reuse any existing to_s methods on your objects (instead of having to call particular properties or define CSV specific output methods). Header names are also automatically humanized when reflected (eg. replacing _ characters with whitespace). The 'isbn' example above shows how multiple values can be added to the CSV output.
+
+When used with Rails (ie. add 'comma' as a gem dependency), Comma automatically adds support for rendering CSV output in your controllers:
+
+    class BooksController < ApplicationController
+
+      def index
+        respond_to do |format|
+          format.csv { render :csv => Book.limited(50) }
+        end
+      end
+
+    end
+
+If you have any questions or suggestions for Comma, please feel free to contact me at crafterm@redartisan.com, all feedback welcome!

data/lib/comma/extractors.rb

@@ -0,0 +1,56 @@
+module Comma
+  
+  class Extractor
+
+    def initialize(instance, &block)
+      @instance = instance
+      @block = block
+      @results = []
+    end
+    
+    def results
+      instance_eval &@block
+      @results
+    end
+  end
+  
+  class HeaderExtractor < Extractor
+    
+    def method_missing(sym, *args, &block)
+      @results << sym.to_s.humanize if args.blank?
+      
+      args.each do |arg|
+        case arg
+        when Hash
+          arg.each do |k, v|
+            @results << v.to_s.humanize
+          end
+        when Symbol, String
+          @results << arg.to_s.humanize
+        else
+          raise "Unknown header symbol #{arg.inspect}"
+        end
+      end
+    end
+  end
+  
+  class DataExtractor < Extractor
+    
+    def method_missing(sym, *args, &block)
+      @results << @instance.send(sym).to_s if args.blank?
+      
+      args.each do |arg|
+        case arg
+        when Hash
+          arg.each do |k, v|
+            @results << @instance.send(sym).send(k).to_s
+          end
+        when Symbol, String
+          @results << @instance.send(sym).send(arg).to_s
+        else
+          raise "Unknown data symbol #{arg.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/comma.rb

@@ -0,0 +1,46 @@
+require 'activesupport'
+require 'fastercsv'
+require 'comma/extractors'
+
+class Array
+  def to_comma
+    FasterCSV.generate do |csv|
+      csv << first.to_comma_headers
+      each do |object| 
+        csv << object.to_comma
+      end
+    end
+  end
+end
+
+class Object
+  def self.comma(&block)
+    define_method :to_comma do
+      Comma::DataExtractor.new(self, &block).results
+    end
+
+    define_method :to_comma_headers do
+      Comma::HeaderExtractor.new(self, &block).results
+    end
+  end
+end
+
+if defined?(ActionController)
+  module RenderAsCSV
+
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.alias_method_chain :render, :csv
+    end
+
+    module InstanceMethods
+      def render_with_csv(options = nil, extra_options = {}, &block)
+        return render_without_csv(options, extra_options, &block) unless options and options[:csv]
+        send_data Array(options[:csv]).to_comma
+      end
+    end
+
+  end
+
+  ActionController::Base.send :include, RenderAsCSV
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: crafterm-comma
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Marcus Crafter
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-02-13 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: fastercsv
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.4.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.2.2
+    version: 
+description: 
+email: crafterm@redartisan.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.markdown
+- MIT-LICENSE
+- lib/comma.rb
+- lib/comma/extractors.rb
+has_rdoc: false
+homepage: http://github.com/crafterm/comma
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Ruby Comma Seperated Values generation library
+test_files: []
+