apipie-params 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+Gemfile.lock
+coverage

data/Gemfile

@@ -0,0 +1,8 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'pry'
+  gem 'simplecov'
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Pavel Pokorný
+
+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,23 @@
+Apipie Params
+=============
+
+DSL for Hash/JSON descriptions. Describe format of hashes using Ruby
+code, generate a json-schema for it and validate values against it.
+
+It's based on the DSL of apipie-rails. See
+[its documentation](https://github.com/Pajk/apipie-rails#parameter-description)
+for more details. It basically lets you use the param descriptions
+outside of Rails controllers.
+
+In this phase, the validation itself is an experimental feature. You
+need to install `json-schema` gem explicitly.
+
+License
+-------
+
+MIT
+
+Author
+------
+
+Ivan Nečas

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib' << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end

data/apipie-params.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "apipie/params/version"
+
+Gem::Specification.new do |s|
+  s.name        = "apipie-params"
+  s.version     = Apipie::Params::VERSION
+  s.authors     = ["Ivan Necas"]
+  s.email       = ["inecas@redhat.com"]
+  s.homepage    = "http://github.com/iNecas/apipie-params"
+  s.summary     = "DSL for describing data structures"
+  s.description = "Allows defining structure of data and " +
+                  "perform validation against it using json-schema"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_dependency "activesupport"
+  s.add_dependency "rake"
+  s.add_development_dependency "json-schema"
+  s.add_development_dependency "minitest"
+end

data/lib/apipie-params.rb

@@ -0,0 +1,6 @@
+require 'json-schema'
+require 'apipie/params.rb'
+require 'apipie/params/errors.rb'
+require 'apipie/params/dsl.rb'
+require 'apipie/params/description.rb'
+require 'apipie/params/descriptor.rb'

data/lib/apipie/params.rb

@@ -0,0 +1,7 @@
+module Apipie
+  module Params
+    def self.define(&block)
+      Params::Description.define(&block)
+    end
+  end
+end

data/lib/apipie/params/description.rb

@@ -0,0 +1,56 @@
+require 'forwardable'
+
+module Apipie
+  module Params
+    class Description
+
+      attr_accessor :name, :desc, :allow_nil, :required, :descriptor, :options
+
+      def self.define(&block)
+        param_description = Description.new(nil, nil, {})
+        param_description.descriptor = Descriptor::Hash.new(block, {})
+        return param_description
+      end
+
+      def initialize(name, descriptor_arg, options = {}, &block)
+        @options = options
+        @name = name
+        @desc = @options[:desc]
+        # if required is specified, set to boolean of the value, nil
+        # otherwise: nil allows us specify the default value later.
+        @required = @options.has_key?(:required) ? !!@options[:required] : nil
+        @allow_nil = @options.has_key?(:allow_nil) ? !!@options[:allow_nil] : nil
+
+        unless descriptor_arg.nil?
+          @descriptor = Params::Descriptor::Base.find(descriptor_arg,
+                                                      options,
+                                                      block)
+        else
+          @descriptor = nil
+        end
+
+      end
+
+      def validate!(value)
+        descriptor.validate!(self, value)
+      end
+
+      def respond_to?(method)
+        case method.to_s
+        when 'params', 'param'
+          @descriptor.respond_to?(method)
+        else
+          super
+        end
+      end
+
+      def method_missing(method, *args, &block)
+        if respond_to?(method)
+          @descriptor.send(method, *args, &block)
+        else
+          super
+        end
+      end
+    end
+  end
+end

data/lib/apipie/params/descriptor.rb

@@ -0,0 +1,343 @@
+require 'active_support/core_ext/hash/indifferent_access'
+require 'forwardable'
+
+module Apipie
+  module Params
+    module Descriptor
+
+      class Base
+        def initialize(options)
+          if options.is_a? ::Hash
+            @options = options
+          else
+            @options = {}
+          end
+        end
+
+        def self.inherited(subclass)
+          @descriptor_classes ||= []
+          @descriptor_classes.insert 0, subclass
+        end
+
+        # find the right descriptor for given options
+        def self.find(argument, options, block)
+          if argument.is_a? Descriptor::Base
+            return argument
+          end
+
+          # in case param description (or something else quacking the
+          # same) is passed
+          if argument.respond_to?(:descriptor) &&
+                argument.descriptor.is_a?(Descriptor::Base)
+            return argument.descriptor
+          end
+
+          @descriptor_classes.each do |descriptor_class|
+            descriptor = descriptor_class.build(argument, options, block)
+            return descriptor if descriptor
+          end
+
+          return nil
+        end
+
+        # to be used in the error description and json representation
+        def description
+          ""
+        end
+
+        def invalid_param_error(param_description, error_value, errors = [])
+          Params::Errors::Invalid.new(param_description, error_value, description)
+        end
+
+        def to_json
+          self.json_schema
+        end
+
+      end
+
+      class JsonSchema < Base
+        def self.inherited(subclass)
+          Base.inherited(subclass)
+        end
+
+        def self.build(*args)
+          # this is an abstract class
+          nil
+        end
+
+        def json_schema
+          {'description' => description}
+        end
+
+
+        def validate!(param_description, value)
+          encapsulated_value = {'root' => value}
+          encapsulated_schema = {
+            'type' => 'object',
+            'properties' => {'root' => json_schema}
+          }
+          errors = JSON::Validator.fully_validate(encapsulated_schema,
+                                                  encapsulated_value.with_indifferent_access,
+                                                  :errors_as_objects => true)
+
+          if errors.any?
+            raise invalid_param_error(param_description, value, errors)
+          else
+            return true
+          end
+        end
+
+      end
+
+      # validate arguments type
+      class String < JsonSchema
+
+        def self.build(type, options, block)
+          self.new(options) if type == ::String
+        end
+
+        def description
+          "Must be a string"
+        end
+
+        def json_schema
+          super.merge('type' => 'string')
+        end
+
+      end
+
+      # validate arguments type
+      class Integer < JsonSchema
+
+        def self.build(type, options, block)
+          self.new(options) if type == ::Integer
+        end
+
+        def description
+          "Must be an integer"
+        end
+
+        def json_schema
+          super.merge('type' => 'integer')
+        end
+
+      end
+
+      # validate arguments value with regular expression
+      class Regexp < JsonSchema
+
+        def self.build(regexp, options, block)
+          self.new(regexp, options) if regexp.is_a? ::Regexp
+        end
+
+        def initialize(regexp, options)
+          super(options)
+          @regexp = regexp
+        end
+
+        def description
+          "Must match regular expression /#{@regexp.source}/."
+        end
+
+        def json_schema
+          super.merge('type' => 'string', 'pattern' => @regexp.source)
+        end
+
+      end
+
+      # arguments value must be one of given in array
+      class Enum < JsonSchema
+
+        def self.build(enum, options, block)
+          if enum.is_a?(::Array) && block.nil?
+            self.new(enum, options)
+          end
+        end
+
+        def initialize(enum, options)
+          super(options)
+          @enum = enum
+        end
+
+        def description
+          "Must be one of: #{@enum.join(', ')}."
+        end
+
+        def json_schema
+          super.merge('type' => 'any', 'enum' => @enum)
+        end
+
+      end
+
+      class Hash < JsonSchema
+
+        class DSL
+          include Params::DSL
+
+          def initialize(&block)
+            instance_eval(&block)
+          end
+        end
+
+        def self.build(argument, options, block)
+          if block.is_a?(::Proc) && block.arity <= 0 && argument == ::Hash
+            self.new(block, options)
+          end
+        end
+
+        def initialize(block, options)
+          super(options)
+          @dsl_data = DSL.new(&block)._apipie_params_dsl_data
+        end
+
+        def params
+          @params ||= @dsl_data.map do |name, arg, options, block|
+            Description.new(name, arg, options, &block)
+          end
+          return @params
+        end
+
+        def param(param_name)
+          params.find { |param| param.name.to_s == param_name.to_s }
+        end
+
+        def description
+          "Must be a Hash"
+        end
+
+        def json_schema
+          properties = params.reduce({}) do |hash, description|
+            hash.update(description.name.to_s => description.descriptor.json_schema)
+          end
+          super.merge('type' => 'object',
+                      'properties' => properties)
+        end
+
+        def invalid_param_error(param_description, error_value, errors)
+          descriptions = errors.map do |error|
+            fragment_descriptor(param_description, error[:fragment])
+          end
+          # TODO: handle multiple errors at the same time
+          invalid_param = descriptions.first
+          description = invalid_param.descriptor.description
+          Params::Errors::Invalid.new(invalid_param, error_value, description)
+        end
+
+        def fragment_descriptor(param_description, fragment)
+          keys_path = fragment.sub(/\A#\/root\//,'').split('/')
+          keys_path.delete_if { |a| a =~ /\A\d+\Z/ }
+          keys_path.reduce(param_description) do |description, key|
+            description.param(key)
+          end
+        end
+
+      end
+
+      class Array < JsonSchema
+
+        extend Forwardable
+
+        def_delegators :@descriptor, :invalid_param_error
+
+        def self.build(argument, options, block)
+          if argument == ::Array && block.is_a?(::Proc)
+            self.new(block, options)
+          end
+        end
+
+        def initialize(descriptor_or_block, options)
+          super(options)
+          case descriptor_or_block
+          when ::Proc
+            @descriptor = Hash.new(descriptor_or_block, options)
+          when Descriptor::Base
+            @descriptor = descriptor_or_block
+          else
+            raise ArgumentError, "Proc or Descriptor::Base expected, got #{descriptor_or_block.class.name}"
+          end
+        end
+
+        def description
+          "Must be an Array"
+        end
+
+        def json_schema
+          super.merge(
+            'type' => 'array',
+            'items' => @descriptor.json_schema
+          )
+        end
+
+        # delegate to params and param only if @descriptor supports those
+        def respond_to?(method)
+          case method.to_s
+          when 'params', 'param'
+            @descriptor.respond_to?(method)
+          else
+            super
+          end
+        end
+
+        def method_missing(method, *args, &block)
+          if respond_to?(method)
+            @descriptor.send(method, *args, &block)
+          else
+            super
+          end
+        end
+
+      end
+
+      # special type of descriptor: we say that it's not specified
+      class Undef < JsonSchema
+
+        def self.build(argument, options, block)
+          if argument == :undef
+            self.new(options)
+          end
+        end
+
+        def json_schema
+          super.merge('type' => 'any')
+        end
+      end
+
+      class Number < Regexp
+
+        def self.build(argument, options, block)
+          if argument == :number
+            self.new(self.pattern, options)
+          end
+        end
+
+        def description
+          "Must be a number."
+        end
+
+        def self.pattern
+          /\A(0|[1-9]\d*)\Z$/
+        end
+
+      end
+
+      class Boolean < Enum
+
+        def self.build(argument, options, block)
+          if argument == :bool
+            self.new(valid_values, options)
+          end
+        end
+
+        def self.valid_values
+          %w[true false]
+        end
+
+        def description
+          "Must be 'true' or 'false'"
+        end
+
+      end
+
+    end
+  end
+end

data/lib/apipie/params/dsl.rb

@@ -0,0 +1,39 @@
+module Apipie
+  module Params
+    module DSL
+      def _apipie_params_dsl_data
+        @_apipie_params_dsl_data ||= _apipie_params_dsl_data_init
+      end
+
+      def _apipie_params_dsl_data_init
+        @_apipie_params_dsl_data = []
+      end
+
+      # Describe method's parameter
+      #
+      # Example:
+      #   param :greeting, String, :desc => "arbitrary text", :required => true
+      #
+      def param(param_name, descriptor_arg, desc_or_options = nil, options = {}, &block) #:doc:
+        if desc_or_options.is_a? String
+          options = options.merge(:desc => desc_or_options)
+        end
+        _apipie_params_dsl_data << [param_name,
+                                    descriptor_arg,
+                                    options,
+                                    block]
+      end
+
+      # +descriptor+ might be instance of Descriptor::Base or
+      # something that has it in :descriptor method
+      def array_of(descriptor)
+        descriptor = if descriptor.is_a? Descriptor::Base
+                     elsif descriptor.respond_to?(:descriptor)
+                       descriptor.descriptor
+                     end
+        Descriptor::Array.new(descriptor, {})
+      end
+    end
+
+  end
+end

data/lib/apipie/params/errors.rb

@@ -0,0 +1,35 @@
+module Apipie
+  module Params
+    module Errors
+
+      class ParamError < StandardError
+        attr_accessor :description
+
+        def initialize(description)
+          @description = description
+        end
+      end
+
+      class Missing < ParamError
+        def to_s
+          "Missing parameter #{@description.name}"
+        end
+      end
+
+      class Invalid < ParamError
+        attr_accessor :value, :error
+
+        def initialize(description, value, error)
+          super(description)
+          @value = value
+          @error = error
+        end
+
+        def to_s
+          "Invalid parameter '#{description.name}' value #{@value.inspect}: #{@error}"
+        end
+      end
+
+    end
+  end
+end

data/lib/apipie/params/version.rb

@@ -0,0 +1,5 @@
+module Apipie
+  module Params
+    VERSION = '0.0.1' unless defined? Apipie::Params::VERSION
+  end
+end

data/test/description_test.rb

@@ -0,0 +1,58 @@
+require 'test_helper'
+
+module Apipie
+  module Params
+    class DescriptionTest < Test::Unit::TestCase
+
+      def test_define
+        person_description = Params.define do
+          param :name,    String
+          param :age,     :number, 'in years'
+          param :address, Hash do
+            param :street, String
+            param :zip,    String
+          end
+        end
+
+        assert_equal [:name, :age, :address], person_description.params.map(&:name)
+        assert_equal [:street, :zip], person_description.param(:address).params.map(&:name)
+
+        classroom_description = Params.define do
+          param :name, String
+          param :teacher, person_description
+          param :students, array_of(person_description)
+        end
+
+        teacher_description = classroom_description.param(:teacher)
+        assert_equal [:name, :age, :address], teacher_description.params.map(&:name)
+        students_description = classroom_description.param(:students)
+        assert_instance_of Descriptor::Array, students_description.descriptor
+        assert_equal [:name, :age, :address], students_description.params.map(&:name)
+      end
+
+      def test_params
+        description = Description.new('test', nil, {})
+        descriptor_with_params =
+          Descriptor::Hash.new(Proc.new { param(:test, String) }, {})
+        descriptor_without_params = Descriptor::String.new({})
+
+        description.descriptor = descriptor_with_params
+        assert description.respond_to?(:params)
+        assert description.respond_to?(:param)
+
+        description.descriptor = descriptor_without_params
+        assert !description.respond_to?(:params)
+        assert !description.respond_to?(:param)
+      end
+
+      def test_validate
+        description = Description.new('test', String, {})
+        description.validate!('123')
+        assert_raise Errors::Invalid do
+          description.validate!(123)
+        end
+      end
+
+    end
+  end
+end

data/test/descriptor_test.rb

@@ -0,0 +1,120 @@
+require 'test_helper'
+
+module Apipie
+  module Params
+    describe Descriptor do
+
+      def self.describe_validator(valid_value, invalid_value, exception_matcher)
+        describe 'valid value' do
+          let(:value) { valid_value }
+
+          it 'succeeds' do
+            subject.validate!(value)
+          end
+        end
+
+        describe 'invalid value' do
+          let(:value) { invalid_value }
+
+          it 'fails' do
+            exception = lambda do
+              subject.validate!(value)
+            end.must_raise Params::Errors::Invalid
+            exception.message.must_match(exception_matcher)
+          end
+        end
+      end
+
+      describe 'custom descriptor' do
+        subject { Description.new('test', :custom, {}) }
+        #describe_validator('valid', 'invalid', /value has to be "value"/)
+        it 'allows to extend the default json schema'
+      end
+
+      describe 'string descriptor' do
+        subject { Description.new('test', String, {}) }
+        describe_validator('valid', :invalid, /Must be a string/)
+      end
+
+      describe 'integer descriptor' do
+        subject { Description.new('test', Integer, {}) }
+        describe_validator(123, '123', /Must be an integer/)
+      end
+
+      describe 'regexp descriptor' do
+        subject { Description.new('test', /\Avalid/, {}) }
+        describe_validator('valid', 'invalid', /Must match/)
+      end
+
+      describe 'enum descriptor' do
+        subject { Description.new('test', ['valid', 'valider'], {}) }
+        describe_validator('valid', 'invalid', /Must be one of/)
+      end
+
+      describe 'hash descriptor' do
+        subject do
+          Description.new('test', Hash, {}) do
+            param :name, String
+            param :address, Hash do
+              param :street, String
+              param :zip, String
+            end
+          end
+        end
+        # TODO: test require and allow_nil
+        describe_validator({:name => "valid"}, {:name => 123}, /Must be a string/)
+
+        describe '#params' do
+          it 'returns param descriptions of all keys' do
+            name_description, address_description = subject.params
+            name_description.name.must_equal :name
+            address_description.name.must_equal :address
+            address_description.params.map(&:name).must_equal([:street, :zip])
+          end
+        end
+
+        describe '#param' do
+          it 'returns param description for a key' do
+            street_description = subject.param(:address).param(:street)
+            street_description.name.must_equal :street
+            street_description.descriptor.must_be_kind_of Descriptor::String
+          end
+        end
+      end
+
+      describe 'array descriptor' do
+        subject do
+          Description.new('test', ::Array, {}) do
+            param :name, String
+          end
+        end
+
+        describe_validator([{:name => "valid"}], [{:name => :invalid}], /Must be a string/)
+      end
+
+      describe 'undef descriptor' do
+        subject { Description.new('test', :undef, {}) }
+
+        describe 'valid value' do
+          let(:value) { 'whatever' }
+
+          it 'succeeds' do
+            subject.validate!(value)
+          end
+        end
+
+      end
+
+      describe 'number descriptor' do
+        subject { Description.new('test', :number, {}) }
+        describe_validator('123', 'a23', /Must be a number/)
+      end
+
+      describe 'boolean descriptor' do
+        subject { Description.new('test', :bool, {}) }
+        describe_validator('true', 'no', /Must be 'true' or 'false'/)
+      end
+
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,13 @@
+if ENV['SIMPLECOV']
+  require 'simplecov'
+  SimpleCov.start do
+    add_filter '/test/'
+  end
+end
+
+require 'test/unit'
+
+
+require 'minitest/spec'
+
+require 'apipie-params'

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: apipie-params
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Ivan Necas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Allows defining structure of data and perform validation against it using
+  json-schema
+email:
+- inecas@redhat.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README.md
+- Rakefile
+- apipie-params.gemspec
+- lib/apipie-params.rb
+- lib/apipie/params.rb
+- lib/apipie/params/description.rb
+- lib/apipie/params/descriptor.rb
+- lib/apipie/params/dsl.rb
+- lib/apipie/params/errors.rb
+- lib/apipie/params/version.rb
+- test/description_test.rb
+- test/descriptor_test.rb
+- test/test_helper.rb
+homepage: http://github.com/iNecas/apipie-params
+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.25
+signing_key: 
+specification_version: 3
+summary: DSL for describing data structures
+test_files:
+- test/description_test.rb
+- test/descriptor_test.rb
+- test/test_helper.rb