pump 0.2.0 → 0.3.0

data/.yardopts

@@ -0,0 +1,5 @@
+--markup          markdown
+-
+README.md
+CHANGES.md
+MIT-LICENSE

data/{LICENSE.txt → MIT-LICENSE}

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Sebastian
+Copyright (c) 2013 Sebastian Munz
 
 MIT License
 

data/README.md

@@ -6,8 +6,8 @@ Fast but inflexible XML encoding for ruby objects.
 
 Serializing an array of 100 random entries 1.000 times.
 
-                                      user     system      total        real
-    Pump::Xml#encode                  1.560000   0.020000   1.580000 (  1.581375)
-    Pump::Xml#encode (optimized)      1.060000   0.010000   1.070000 (  1.067321)
-    Ox                                1.470000   0.000000   1.470000 (  1.467247)
-    ActiveModel#serialize            22.840000   0.040000  22.880000 ( 22.871247)
+                                   user     system      total        real
+Pump::Xml#encode               1.450000   0.010000   1.460000 (  1.466962)
+Pump::Xml#encode (optimized)   1.100000   0.010000   1.110000 (  1.110234)
+Ox                             1.490000   0.000000   1.490000 (  1.483275)
+ActiveModel#serialize         23.280000   0.060000  23.340000 ( 23.333999)

data/Rakefile

@@ -3,3 +3,29 @@ require "bundler/gem_tasks"
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 task :default => :spec
+
+begin
+  require "yard"
+  require "yard/rake/yardoc_task"
+
+  namespace :doc do
+    desc "Generate Yardoc documentation"
+    YARD::Rake::YardocTask.new do |yardoc|
+      yardoc.name = "yard"
+      yardoc.options = ["--verbose", "--markup", "markdown"]
+      yardoc.files = FileList[
+        "lib/**/*.rb",
+        "-", "README.md", "CHANGES.md", "MIT-LICENSE"
+      ]
+    end
+  end
+
+  task "clobber" => ["doc:clobber_yard"]
+
+  desc "Alias to doc:yard"
+  task "doc" => "doc:yard"
+rescue LoadError
+  # If yard isn't available, it's not the end of the world
+  desc "Alias to doc:rdoc"
+  task "doc" => "doc:rdoc"
+end

data/lib/pump/version.rb

@@ -1,3 +1,3 @@
 module Pump
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/pump/xml/dsl.rb

@@ -0,0 +1,51 @@
+module Pump
+  class Xml
+    class Dsl
+      def initialize(&blk)
+        raise ArgumentError unless block_given?
+        instance_eval(&blk)
+      end
+
+      def config
+        @config ||= []
+      end
+
+      private
+
+      def tag(name, options={}, &blk)
+        method = if block_given?
+          self.class.new(&blk).config
+        else
+          options.delete(:from) || (name.to_s =~ /-/ ? name.to_s.gsub('-', '_').to_sym : name)
+        end
+        config << ({ name => method }).merge(options)
+      end
+      alias_method :string, :tag
+
+      def integer(name, options={})
+        with_type('integer', name, options)
+      end
+
+      def date(name, options={})
+        with_type('date', name, options)
+      end
+
+      def datetime(name, options={})
+        options[:typecast] = :xmlschema unless options.has_key?(:typecast)
+        with_type('datetime', name, options)
+      end
+      alias_method :time, :datetime
+
+      def with_type(type, name, options)
+        (options[:attributes] ||= {}).merge!({:type => type})
+        options[:xmlsafe] = true unless options.has_key?(:xmlsafe)
+        tag(name, options)
+      end
+
+      def array(name, options={}, &blk)
+        options[:array] = self.class.new(&blk).config
+        tag(name, options)
+      end
+    end
+  end
+end

data/lib/pump/xml.rb

@@ -1,19 +1,60 @@
 require "pump/xml/tag"
 require "pump/xml/value"
 require "pump/xml/tag_array"
+require "pump/xml/dsl"
+require 'active_support/core_ext/string/inflections'
 
 module Pump
   class Xml
+
     attr_reader :root_tag_name, :tag_config, :options
 
-    def initialize(root_tag_name, tag_config, options={})
+    # Creates a new XML-encoder with a root tag named after +root_tag_name+.
+    #
+    # @example Create a simple encoder for a person with a name attribute:
+    #   Pump::Xml.new :person do
+    #     tag :name
+    #   end
+    #
+    # @example Create the same without usage of the DSL:
+    #   Pump::Xml.new :person, [{:name => :name}]
+    #
+    # @example Create the same but without the xml instruct
+    #   Pump::Xml.new :person, :instruct => false do
+    #     tag :name
+    #   end
+    #
+    # @example The same again without DSL:
+    #
+    #   Pump::Xml.new :person, [{:name => :name}], :instruct => false
+    #
+    # @param [String, Symbol] root_tag_name     the name of the used root tag
+    # @param [Array<Hash>] tag_config           optional config for all tags
+    # @param [Hash] options                     optional options for the whole encoder
+    # @yield an optional block to create the encoder with the Pump::Xml::Dsl
+    #
+    # @return [self]
+    def initialize(root_tag_name, tag_config=nil, options={}, &blk)
+      unless Array === tag_config
+        raise ArgumentError unless block_given?
+        @options = tag_config || {}
+        @tag_config = Dsl.new(&blk).config
+      else
+        @tag_config    = tag_config
+        @options       = options
+      end
       @root_tag_name = root_tag_name
-      @tag_config    = tag_config
-      @options       = options
 
       compile
     end
 
+    # Encode a object or an array of objects to an XML-string.
+    #
+    # @param [Object, Array<Object>] object object or an array of objects to
+    #    encode to XML. The only requirement: The given objects must respond
+    #    to all methods configured during initalization of the Pump::Xml instance.
+    #
+    # @return [String]
     def encode(object)
       Array === object ? encode_array(object) : encode_single(object)
     end
@@ -44,12 +85,14 @@ module Pump
 
     def build_tag(config)
       tag_name, method_name = config.keys.first, config.values.first
+      attrs = config[:attributes]
       if method_name.is_a?(Array)
-        Tag.new(tag_name, config[:attributes], method_name.map{|conf| build_tag(conf) }, config)
-      elsif config[:array].is_a?(Array)
-        TagArray.new(tag_name, config[:attributes], config[:array].map{|conf| build_tag(conf) }, config.merge({:array_method => method_name}))
+        Tag.new(tag_name, attrs, method_name.map{|conf| build_tag(conf) }, config)
+      elsif config[:array]
+        config.merge!(:array_method => method_name, :array_root => tag_name)
+        TagArray.new(config[:child_root] || tag_name.to_s.singularize, attrs, config[:array].map{|conf| build_tag(conf) }, config)
       else
-        Tag.new(tag_name, config[:attributes], Value.new(method_name), config)
+        Tag.new(tag_name, attrs, Value.new(method_name), config)
       end
     end
 

data/lib/pump.rb

@@ -1,5 +1,6 @@
 require "pump/version"
 require "pump/xml"
 
+# Fast but inflexible XML encoding for ruby objects.
 module Pump
 end

data/spec/pump/xml/dsl_spec.rb

@@ -0,0 +1,123 @@
+require 'spec_helper'
+
+describe Pump::Xml::Dsl do
+  subject { Pump::Xml::Dsl.new {} }
+
+  describe ".new" do
+    it "requires one block" do
+      lambda{ Pump::Xml::Dsl.new }.should raise_error(ArgumentError)
+      lambda{ subject }.should_not raise_error
+    end
+  end
+
+  describe "#config" do
+    its(:config) { should eql([]) }
+
+    context "with tag" do
+      subject { Pump::Xml::Dsl.new { tag :name } }
+      its(:config) { should eql([{:name => :name}]) }
+
+      context "with attributes and options" do
+        subject { Pump::Xml::Dsl.new { tag :name, :attributes => {:a => 'b'}, :options => false } }
+        its(:config) { should eql([{:name => :name, :attributes => {:a => 'b'}, :options => false}]) }
+      end
+
+      context "with :from option" do
+        subject { Pump::Xml::Dsl.new { tag :name, :from => :method_name } }
+        its(:config) { should eql([{:name => :method_name}]) }
+      end
+
+      context "with dashs in tag name" do
+        subject { Pump::Xml::Dsl.new { tag :"first-name" } }
+        its(:config) { should eql([{:"first-name" => :first_name}]) }
+      end
+    end
+
+    context "with string" do
+      subject { Pump::Xml::Dsl.new { string :name } }
+      its(:config) { should eql([{:name => :name}]) }
+
+      context "with attributes and options" do
+        subject { Pump::Xml::Dsl.new { string :name, :attributes => {:a => 'b'}, :options => false } }
+        its(:config) { should eql([{:name => :name, :attributes => {:a => 'b'}, :options => false}]) }
+      end
+    end
+
+    context "with integer" do
+      subject { Pump::Xml::Dsl.new { integer :name } }
+      its(:config) { should eql([{:name => :name, :attributes => {:type => 'integer'}, :xmlsafe => true}]) }
+
+      context "with attributes and options" do
+        subject { Pump::Xml::Dsl.new { integer :name, :attributes => {:a => 'b'}, :options => false } }
+        its(:config) { should eql([{:name => :name, :attributes => {:type => 'integer', :a => 'b'}, :options => false, :xmlsafe => true}]) }
+      end
+    end
+
+    context "with date" do
+      subject { Pump::Xml::Dsl.new { date :at } }
+      its(:config) { should eql([{:at => :at, :attributes => {:type => 'date'}, :xmlsafe => true}]) }
+
+      context "with attributes and options" do
+        subject { Pump::Xml::Dsl.new { date :at, :attributes => {:a => 'b'}, :options => false } }
+        its(:config) { should eql([{:at => :at, :attributes => {:type => 'date', :a => 'b'}, :options => false, :xmlsafe => true}]) }
+      end
+    end
+
+    context "with (date)time" do
+      subject { Pump::Xml::Dsl.new { time :at } }
+      its(:config) { should eql([{:at => :at, :typecast => :xmlschema, :attributes => {:type => 'datetime'}, :xmlsafe => true}]) }
+
+      context "with attributes and options" do
+        subject { Pump::Xml::Dsl.new { time :at, :attributes => {:a => 'b'}, :options => false } }
+        its(:config) { should eql([{:at => :at, :attributes => {:a => 'b', :type => 'datetime'}, :options => false, :typecast => :xmlschema, :xmlsafe => true}]) }
+      end
+    end
+
+    context "with nested tags" do
+      subject do
+        Pump::Xml::Dsl.new do
+          tag :person, :option => 'x' do
+            string :name
+            integer :age
+          end
+          string :parent_name
+        end
+      end
+      its(:config) { should eql([
+        {:person => [
+          {:name => :name},
+          {:age => :age, :attributes => {:type => 'integer'}, :xmlsafe => true}
+        ], :option => 'x'},
+        {:parent_name => :parent_name}
+      ]) }
+    end
+  end
+
+  context "with array tag" do
+    subject do
+      Pump::Xml::Dsl.new do
+        array(:children) do
+          tag :name
+        end
+      end
+    end
+
+    its(:config) { should eql(
+      [{:children => :children, :array => [{:name => :name}]}]
+    )}
+
+    context "with options" do
+      subject do
+        Pump::Xml::Dsl.new do
+          array(:children, :from => :kids, :child_root => :ugly_kid_joe) do
+            tag :name
+          end
+        end
+      end
+
+      its(:config) { should eql(
+        [{:children => :kids, :array => [{:name => :name}], :child_root => :ugly_kid_joe}]
+      )}
+    end
+  end
+end

data/spec/pump/xml_spec.rb

@@ -2,10 +2,21 @@ require 'spec_helper'
 
 describe Pump::Xml do
   describe ".new" do
-    it "requires two parameters" do
+    it "requires two parameters or one and a block" do
       lambda{ Pump::Xml.new }.should raise_error(ArgumentError)
       lambda{ Pump::Xml.new('record') }.should raise_error(ArgumentError)
       lambda{ Pump::Xml.new('record', []) }.should_not raise_error
+      lambda{ Pump::Xml.new('record') {} }.should_not raise_error
+    end
+
+    describe "with block given" do
+      subject do
+        Pump::Xml.new('human', :instruct => false) do
+          tag :name
+        end.encode(Struct.new(:name).new('Artur'))
+      end
+
+      its(:encode) { should eql("<human>\n  <name>Artur</name>\n</human>\n")}
     end
   end
 
@@ -201,15 +212,27 @@ describe Pump::Xml do
     end
 
     context "deep array-like nesting" do
-      let(:person) { Struct.new(:name, :children).new('Gustav', [Struct.new(:name).new('Lilly'), Struct.new(:name).new('Lena')]) }
-      let(:xml) { Pump::Xml.new('person', [{:name => :name}, {:child => :children, :array => [{:name => :name}]}], :instruct => false) }
+      let(:person) {
+        Struct.new(:name, :children).new('Gustav', [
+          Struct.new(:name).new('Lilly'),
+          Struct.new(:name).new('Lena')
+      ]) }
+
+      let(:xml) { Pump::Xml.new('person', [{:name => :name}, {:children => :children,
+                                            :array => [{:name => :name}]}], :instruct => false) }
 
       it "returns xml string" do
         xml.encode(person).should eql("<person>\n  <name>Gustav</name>\n  <children type=\"array\">\n    <child>\n      <name>Lilly</name>\n    </child>\n    <child>\n      <name>Lena</name>\n    </child>\n  </children>\n</person>\n")
       end
-    end
-
 
+      context "overwriting child name" do
+        let(:xml) { Pump::Xml.new('person', [{:name => :name}, {:children => :children,
+                                            :array => [{:name => :name}], :child_root => 'kid'}], :instruct => false) }
 
+        it "returns xml string" do
+          xml.encode(person).should eql("<person>\n  <name>Gustav</name>\n  <children type=\"array\">\n    <kid>\n      <name>Lilly</name>\n    </kid>\n    <kid>\n      <name>Lena</name>\n    </kid>\n  </children>\n</person>\n")
+        end
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pump
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-11 00:00:00.000000000 Z
+date: 2013-02-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -70,21 +70,24 @@ files:
 - .rbenv-gemsets
 - .rbenv-version
 - .rspec
+- .yardopts
 - CHANGES.md
 - Gemfile
 - Guardfile
-- LICENSE.txt
+- MIT-LICENSE
 - README.md
 - Rakefile
 - benchmarks/encode.rb
 - lib/pump.rb
 - lib/pump/version.rb
 - lib/pump/xml.rb
+- lib/pump/xml/dsl.rb
 - lib/pump/xml/node.rb
 - lib/pump/xml/tag.rb
 - lib/pump/xml/tag_array.rb
 - lib/pump/xml/value.rb
 - pump.gemspec
+- spec/pump/xml/dsl_spec.rb
 - spec/pump/xml/tag_array_spec.rb
 - spec/pump/xml/tag_spec.rb
 - spec/pump/xml/value_spec.rb
@@ -116,8 +119,10 @@ signing_key:
 specification_version: 3
 summary: Fast but inflexible XML encoding for ruby objects.
 test_files:
+- spec/pump/xml/dsl_spec.rb
 - spec/pump/xml/tag_array_spec.rb
 - spec/pump/xml/tag_spec.rb
 - spec/pump/xml/value_spec.rb
 - spec/pump/xml_spec.rb
 - spec/spec_helper.rb
+has_rdoc: