wsdsl 0.2.0 → 0.2.1

data/README.md

@@ -1,6 +1,6 @@
 # Web Service DSL
 
-WSDSL is a simple DSL allowind developers to simply describe and
+WSDSL is a simple DSL allowing developers to simply describe and
 document their web APIS. For instance:
 
 
@@ -87,6 +87,57 @@ Or a more complex example:
     end
 
 
+## JSON APIs
+
+This library was designed with XML responses in mind and JSON support
+was added later on which explains why some response methods are aliases.
+Consider the following JSON response:
+
+    { people: [ 
+      { 
+        id : 1, 
+        online : false,
+        created_at : 123123123123, 
+        team : {
+          id : 1231,
+          score : 123.32
+        }
+      }, 
+      { 
+        id : 2, 
+        online : true,
+        created_at : 123123123123, 
+        team: {
+          id : 1233,
+          score : 1.32
+        }
+      }, 
+    ] }
+
+It would be described as follows:
+
+    describe_service "json_list" do |service|
+      service.formats  :json
+      service.response do |response|
+        response.array :people do |node|
+          node.integer :id
+          node.boolean :online
+          node.datetime :created_at
+          node.object :team do |team|
+            team.integer :id
+            team.float :score
+          end
+        end
+      end
+    end
+
+Nodes/elements can also use some meta attributes. Currently the
+following meta attributes are available:
+
+* key (refers to an attribute name that is key to this object)
+* type (refers to the type of object described, valuable when using JSON
+  cross OO based apps.
+
 ## Test suite
 
 This library comes with a test suite requiring Ruby 1.9.2

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/lib/response.rb

@@ -13,6 +13,20 @@ class WSDSL
       @elements = []
     end
 
+    alias :nodes :elements
+
+    # Shortcut to automatically create a typed node.
+    # Very useful when describing a JSON response.
+    #
+    # @param [String, Symbol] name the name of the element.
+    # @param [Hash] opts the element options.
+    # @see Element#array
+    def array(name, opts={})
+      el = element(opts.merge(:name => name))
+      yield el if block_given?
+      el
+    end
+
     # Defines a new element and yields the content of an optional block
     # Each new element is then stored in the elements array.
     #
@@ -32,6 +46,7 @@ class WSDSL
       el = Element.new(opts[:name], opts[:type])
       yield(el) if block_given?
       @elements << el
+      el
     end
 
     # Returns a response element object based on its name
@@ -57,10 +72,17 @@ class WSDSL
       # @api public
       attr_reader :type
 
+      # The optional lookup key of an object
+      attr_reader :key
+
       # @return [Array<WSDSL::Response::Element::Attribute>] An array of attributes
       # @api public
       attr_reader :attributes
 
+      # @return [Array<WSDSL::Response::Element::MetaAttribute>] An array of meta attributes
+      # @api public
+      attr_reader :meta_attributes
+
       # @return [Array] An array of vectors/arrays
       # @api public
       attr_reader :vectors
@@ -72,6 +94,12 @@ class WSDSL
       # @return [NilClass, Array<WSDSL::Response::Element>] The optional nested elements
       attr_reader :elements
 
+      # Alias to use a JSON/JS jargon instead of XML.
+      alias :properties :attributes
+
+      # Alias to use a JSON/JS jargon instead of XML.
+      alias :objects :elements
+
       # param [String, Symbol] name The name of the element
       # param [String, Symbol] type The optional type of the element
       # @api public
@@ -82,7 +110,9 @@ class WSDSL
         @name       = name
         @type       = type
         @attributes = []
+        @meta_attributes = []
         @vectors    = []
+        @key        = nil
         # we don't need to initialize the nested elements, by default they should be nil
       end
 
@@ -115,6 +145,29 @@ class WSDSL
         @attributes
       end
 
+      # sets a new meta attribute and returns the entire list of meta attributes
+      #
+      # @param [Hash] opts An element's attribute options
+      # @option opts [String, Symbol] attribute_name The name of the attribute, the value being the type
+      # @option opts [String, Symbol] :mock An optional mock value used by service related tools
+      # 
+      # @example Creation of a response attribute called 'best_lap_time'
+      #   service.response do |response|
+      #    response.element(:name => "my_stats", :type => 'Leaderboard') do |e|
+      #      e.meta_attribute "id"       => :key
+      #    end
+      #   end
+      #
+      # @return [Array<WSDSL::Response::MetaAttribute>]
+      # @api public
+      def meta_attribute(opts)
+        raise ArgumentError unless opts.is_a?(Hash)
+        # extract the documentation part and add it where it belongs
+        new_attribute = MetaAttribute.new(opts)
+        @meta_attributes << new_attribute
+        @meta_attributes
+      end
+
       # Defines an array aka vector of elements.
       #
       # @param [Hash] opts A hash representing the array information, usually a name and a type.
@@ -167,11 +220,88 @@ class WSDSL
       #
       # @return [Array<WSDSL::Response::Element>]
       # @api public
-      def element(opts={})
+      def element(opts={}, &block)
         el = Element.new(opts[:name], opts[:type])
-        yield(el) if block_given?
+        block.call(el) if block_given?
         @elements ||= []
         @elements << el
+        el
+      end
+
+      # Shortcut to create a new element.
+      #
+      # @param [Symbol, String] name the name of the element.
+      # @param [Hash] opts the options for the newly created element.
+      def object(name, opts={}, &block)
+        element(opts.merge(:name => name), &block)
+      end
+
+      # Getter/setter for the key meta attribute.
+      # A key name can be used to lookup an object by a primary key for instance.
+      #
+      # @param [Symbol, String] name the name of the key attribute.
+      # @param [Hash] opts the options attached with the key.
+      def key(name=nil, opts={})
+        meta_attribute_getter_setter(:key, name, opts)
+      end
+
+      # Getter/setter for the type meta attribute.
+      #
+      # @param [Symbol, String] name the name of the type attribute.
+      # @param [Hash] opts the options attached with the key.
+      def type(name=nil, opts={})
+        meta_attribute_getter_setter(:type, name, opts)
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def string(name=nil, opts={})
+        attribute(opts.merge(:name => name, :type => :string))
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def integer(name=nil, opts={})
+        attribute({name => :integer}.merge(opts))
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def float(name=nil, opts={})
+        attribute({name => :float}.merge(opts))
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def boolean(name=nil, opts={})
+        attribute({name => :boolean}.merge(opts))
+      end
+
+      # Shortcut to create a string attribute
+      #
+      # @param [Symbol, String] name the name of the attribute.
+      # @param [Hash] opts the attribute options.
+      def datetime(name=nil, opts={})
+        attribute({name => :datetime}.merge(opts))
+      end
+
+      private
+
+      # Create a meta element attribute
+      def meta_attribute_getter_setter(type, name, opts)
+        if name
+          meta_attribute({name => type}.merge(opts))
+        else
+          meta_attributes.find{|att| att.type == type}
+        end
       end
 
       # Response element's attribute class
@@ -181,6 +311,7 @@ class WSDSL
         # @return [String, #to_s] The attribute's name.
         # @api public
         attr_reader :name
+        alias :value :name
 
         # @return [Symbol, String, #to_s] The attribute's type such as boolean, string etc..
         # @api public
@@ -223,6 +354,11 @@ class WSDSL
         end
       end
 
+      # Response's meta attribute meant to set some extra
+      # attributes which are not part of the response per se.
+      class MetaAttribute < Attribute
+      end
+
       # Array of objects inside an element
       # @api public
       class Vector

data/lib/wsdsl.rb

@@ -354,6 +354,7 @@ module Kernel
     service = WSDSL.new(url)
     yield service
     WSList.add(service)
+    service
   end
   
 end

data/spec/json_response_description_spec.rb

@@ -0,0 +1,92 @@
+require File.expand_path("spec_helper", File.dirname(__FILE__))
+
+describe "WSDSL JSON response description" do
+
+# JSON response example
+=begin
+  { vouchers: [ 
+  { 
+    id : 1, 
+    redeemed : false,
+    created_at : 123123123123, 
+    option: {
+      id : 1231,
+      price: 123.32
+    }
+  }, 
+  { 
+    id : 2, 
+    redeemed : true,
+    created_at : 123123123123, 
+    option: {
+      id : 1233,
+      price: 1.32
+    }
+  }, 
+] }
+=end
+
+  before :all do
+    @service =  describe_service "json_list" do |service|
+      service.formats  :json
+      service.response do |response|
+        response.array :vouchers do |node|
+          node.key :id
+          node.type :Voucher
+          node.integer :id, :doc => "Identifier"
+          node.boolean :redeemed
+          node.datetime :created_at
+          node.object :option do |option|
+            option.integer :id
+            option.integer :deal_id, :mock => 1
+            option.float :price
+          end
+        end
+      end
+    end
+    @response  = @service.response
+    @root_node = @response.nodes.find{|n| n.name == :vouchers}
+
+  end
+
+  it "should handle the json root node" do
+    @root_node.should_not be_nil
+  end
+
+  it "should handle a node property list" do
+    props = @root_node.properties
+    props.should_not be_empty
+    {:id => :integer, :redeemed => :boolean, :created_at => :datetime}.each do |key, type|
+      prop = props.find{|prop| prop.name == key}
+      prop.should_not be_nil
+      prop.type.should == type
+    end
+  end
+
+  it "should handle a nested object with properties" do
+    @root_node.objects.should_not be_nil
+    option = @root_node.objects.find{|o| o.name == :option}
+    option.should_not be_nil
+    {:id => :integer, :deal_id => :integer, :price => :float}.each do |key, type|
+      prop = option.properties.find{|prop| prop.name == key}
+      if prop.nil?
+        puts option.properties.inspect
+        puts [key, type].inspect
+      end
+      prop.should_not be_nil
+      prop.type.should == type
+    end
+  end
+
+  it "should allow some meta attributes" do
+    atts = @root_node.meta_attributes
+    atts.should_not be_nil
+    {:key => :id, :type => :Voucher}.each do |type, value|
+      meta = atts.find{|att| att.type == type}
+      puts [type, atts].inspect if meta.nil?
+      meta.should_not be_nil
+      meta.value.should == value
+    end
+  end
+  
+end

data/spec/wsdsl_spec.rb

@@ -60,8 +60,8 @@ describe WSDSL do
   end
 
   it "should have a default action" do
-   service = WSDSL.new('spec_test.xml')
-   service.action.should == 'list'
+    service = WSDSL.new('spec_test.xml')
+    service.action.should == 'list'
   end
 
   it "should route to show when an id is the last passed param" do

data/wsdsl.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{wsdsl}
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Matt Aimonetti"]
-  s.date = %q{2011-05-19}
+  s.authors = [%q{Matt Aimonetti}]
+  s.date = %q{2011-09-02}
   s.description = %q{A Ruby DSL describing Web Services without implementation details.}
   s.email = %q{mattaimonetti@gmail.com}
   s.extra_rdoc_files = [
@@ -32,6 +32,7 @@ Gem::Specification.new do |s|
     "lib/wsdsl.rb",
     "spec/hello_world_controller.rb",
     "spec/hello_world_service.rb",
+    "spec/json_response_description_spec.rb",
     "spec/params_verification_spec.rb",
     "spec/preferences_service.rb",
     "spec/spec_helper.rb",
@@ -41,20 +42,10 @@ Gem::Specification.new do |s|
     "wsdsl.gemspec"
   ]
   s.homepage = %q{http://github.com/mattetti/wsdsl}
-  s.licenses = ["MIT"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.7.2}
+  s.licenses = [%q{MIT}]
+  s.require_paths = [%q{lib}]
+  s.rubygems_version = %q{1.8.6}
   s.summary = %q{Web Service DSL}
-  s.test_files = [
-    "spec/hello_world_controller.rb",
-    "spec/hello_world_service.rb",
-    "spec/params_verification_spec.rb",
-    "spec/preferences_service.rb",
-    "spec/spec_helper.rb",
-    "spec/test_services.rb",
-    "spec/wsdsl_sinatra_ext_spec.rb",
-    "spec/wsdsl_spec.rb"
-  ]
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

metadata

@@ -1,28 +1,24 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: wsdsl
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.2.1
   prerelease: 
-  version: 0.2.0
 platform: ruby
-authors: 
+authors:
 - Matt Aimonetti
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-05-19 00:00:00 Z
+date: 2011-09-02 00:00:00.000000000Z
 dependencies: []
-
 description: A Ruby DSL describing Web Services without implementation details.
 email: mattaimonetti@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - LICENSE
 - README.md
-files: 
+files:
 - LICENSE
 - README.md
 - Rakefile
@@ -38,6 +34,7 @@ files:
 - lib/wsdsl.rb
 - spec/hello_world_controller.rb
 - spec/hello_world_service.rb
+- spec/json_response_description_spec.rb
 - spec/params_verification_spec.rb
 - spec/preferences_service.rb
 - spec/spec_helper.rb
@@ -46,38 +43,28 @@ files:
 - spec/wsdsl_spec.rb
 - wsdsl.gemspec
 homepage: http://github.com/mattetti/wsdsl
-licenses: 
+licenses:
 - MIT
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.7.2
+rubygems_version: 1.8.6
 signing_key: 
 specification_version: 3
 summary: Web Service DSL
-test_files: 
-- spec/hello_world_controller.rb
-- spec/hello_world_service.rb
-- spec/params_verification_spec.rb
-- spec/preferences_service.rb
-- spec/spec_helper.rb
-- spec/test_services.rb
-- spec/wsdsl_sinatra_ext_spec.rb
-- spec/wsdsl_spec.rb
+test_files: []