cp-sparrow 0.0.12 → 0.0.14

data/lib/sparrow/strategies/ignore.rb

@@ -1,17 +1,33 @@
 module Sparrow
   module Strategies
+    ##
+    # This strategy is called when the HTTP message shall +not+ be transformed,
+    # i.e. ignored.
+    # This is inspired by the NullObject-Pattern to be convenient.
     class Ignore
       include Transformable
 
+      ##
+      # Create a new IgnoreStrategy
+      # @param [Hash] env the Rack environment
+      # @param [Symbol] type HTTP message type. Must be either :request or
+      #   :response
+      # @param [Hash] params The HTTP message params if not given in the env
       def initialize(env, type = :request, params = nil)
         @env    = env
         @params = params
         @type   = type
       end
 
+      ##
+      # Although we are ignoring any kind of conversion we still need to read
+      # the parameters from the environment to be convenient with all other
+      # calls in the chains and architecture *sigh*
+      # Checks env['rack.input']
+      # @return [Hash] the params
       def params
-        ret = @params || @env['rack.input'].send(:read)
-        @env['rack.input'].rewind
+        ret = @params || @env[HttpMessage::RACK_INPUT_KEY].send(:read)
+        @env[HttpMessage::RACK_INPUT_KEY].rewind
         ret
       end
 
@@ -19,25 +35,37 @@ module Sparrow
         new(env, type).handle
       end
 
+      ##
+      # handles the conversion, i.e. here "do nothing"
+      # Which is not strictly true - at write the rack.input to the form hash
+      # key for convenience reasons to enable further middlewares to work with
+      # it
+      # @return [Hash] the rack env
       def handle
         # synchronize rack.input and form hash values
-        input = @env['rack.input'].gets
+        input = @env[HttpMessage::RACK_INPUT_KEY].gets
 
         begin
-          @env['rack.request.form_hash'] = MultiJson.load(input)
+          @env[HttpMessage::FORM_HASH_KEY] = MultiJson.load(input)
         rescue MultiJson::ParseError
           # ignore
         ensure
-          @env['rack.input'].rewind
+          @env[HttpMessage::RACK_INPUT_KEY].rewind
         end if input.present?
 
         @env
       end
 
+      ##
+      # Alias for #params
+      # @see #params
       def json_body
         params
       end
 
+      ##
+      # Transforms the params to a Ruby JSON Hash representation
+      # @return [Hash] the JSON
       def transform_params
         ensure_json
       end

data/lib/sparrow/strategies/json_format_strategies.rb

@@ -0,0 +1,4 @@
+require 'sparrow/strategies/json_format_strategies/default_json_format_strategy'
+require 'sparrow/strategies/json_format_strategies/json_format_strategy'
+require 'sparrow/strategies/json_format_strategies/array_json_format_strategy'
+require 'sparrow/strategies/json_format_strategies/rack_body_json_format_strategy'

data/lib/sparrow/strategies/json_format_strategies/array_json_format_strategy.rb

@@ -0,0 +1,23 @@
+module Sparrow
+  module Strategies
+    class ArrayJsonFormatStrategy < JsonFormatStrategy
+      register_json_format
+
+      ##
+      # Matches if input is an Array
+      # @param [Object] input the JSON object
+      # @return true if the input is an Array
+      def match?(input)
+        input.is_a? Array
+      end
+
+      ##
+      # Takes the first element from the Array and returns it
+      # @param [Array] input the input Array
+      # @return [String] the first element of the input as a String
+      def convert(input)
+        input.first.to_s
+      end
+    end
+  end
+end

data/lib/sparrow/strategies/json_format_strategies/default_json_format_strategy.rb

@@ -1,14 +1,23 @@
-require 'singleton'
-
 module Sparrow
   module Strategies
+    ##
+    # NullObject JSON Format Strategy
+    # Does no direct conversion except casting the given object to a string
     class DefaultJsonFormatStrategy
       include Singleton
 
+      ##
+      # Matches always since this is the NullObjectStrategy and thus the
+      # fallback.
+      # @param [Object] input the JSON input
+      # @return [Boolean] True
       def match?(input)
         true
       end
 
+      ##
+      # @param [#to_s] input the JSON object
+      # @return [String] the input as a String
       def convert(input)
         input.to_s
       end

data/lib/sparrow/strategies/json_format_strategies/json_format_strategy.rb

@@ -1,22 +1,37 @@
-require 'sparrow/strategies/json_format_strategies/default_json_format_strategy'
-require 'active_support/core_ext/object/blank'
-
 module Sparrow
   module Strategies
+    ##
+    # Superclass for all JSON format strategies.
+    # Contains no own instance logic, but keeps track of the registration
+    # of all JSON format strategies with its Singleton class methods.
+    # @abstract Not exactly a abstract class but contains no own logic but
+    #   singleton class methods
     class JsonFormatStrategy
+      ##
+      # Empty constructor. Does nothing.
       def initialize(*args)
-
       end
 
+      ##
+      # Register a new JSON Format strategy
+      # @param [Object] args the arguments for the new strategy
+      # @return [Array] args the updated registered JSON Format strategies
+      #   available
       def self.register_json_format(*args)
         init(args)
         @@json_format_strategies << self.new(args)
       end
 
+      ##
+      # Start a JSON conversion by its given string
+      # @param [Object] body a JSON object representation.
+      #  can be any type a JSON format strategy is registered,
+      #  i.e. an Array, a String or a RackBody
+      # @return [String] the formatted JSON
       def self.convert(body)
-        strategy = json_format_strategies.select do |strategy|
+        strategy = json_format_strategies.detect do |strategy|
           strategy.match?(body)
-        end.first
+        end
         strategy.convert(body)
       end
 

data/lib/sparrow/strategies/json_format_strategies/rack_body_json_format_strategy.rb

@@ -0,0 +1,22 @@
+module Sparrow
+  module Strategies
+    class RackBodyJsonFormatStrategy < JsonFormatStrategy
+      register_json_format
+
+      ##
+      # Checks if the input is a RackBody
+      # @param [#body] input the possible JSON input object
+      # @return [Boolean] True if the given input responds to #body
+      def match?(input)
+        input.respond_to?(:body)
+      end
+
+      ##
+      # @param [#body] input the JSON input object
+      # @return [String] the input body
+      def convert(input)
+        input.body
+      end
+    end
+  end
+end

data/lib/sparrow/strategies/key_transformation.rb

@@ -0,0 +1,2 @@
+require 'sparrow/strategies/key_transformation/underscore_key'
+require 'sparrow/strategies/key_transformation/camelize_key'

data/lib/sparrow/strategies/key_transformation/camelize_key.rb

@@ -1,25 +1,53 @@
-require File.dirname(__FILE__) + '/key_normalizer'
-
 module Sparrow
   module Strategies
-    class CamelizeKey
-      include KeyNormalizer
+    module KeyTransformation
+      ##
+      # Strategy class for converting JSON to a camelized format.
+      # Meaning snake_case => snakeCase
+      class CamelizeKey
+        ##
+        # @return [Symbol] the camelizing strategy
+        # @see #initialize
+        attr_accessor :strategy
 
-      attr_accessor :strategy
+        ##
+        # @return [Boolean] Defines whether complete uppercased keys will be
+        #   transformed
+        # @see #initialize
+        attr_accessor :camelize_ignore_uppercase_keys
 
-      def initialize(strategy = :lower)
-        self.strategy = strategy
-      end
+        ##
+        # Initialize a new CamelizeKey strategy
+        # @param [Hash] options camelize options
+        # @option options [Symbol] :strategy ('lower') defines the camelizing
+        #   strategy type. Defines how to camelize, which comes down to starting
+        #   with a lowercased character or with an uppercased character.
+        #   Thus possible values are :lower and :upper.
+        #
+        # @option options [Boolean] :camelize_ignore_uppercase_keys (true)
+        #   Defines if already completely uppercased keys should not be
+        #   transformed. I.e. JSON stays JSON if
+        #   this is set to true. If it is set to false JSON will be transformed
+        #   to Json.
+        def initialize(options = {})
+          self.strategy                       = options.fetch(:strategy, :lower)
+          self.camelize_ignore_uppercase_keys =
+              options.fetch(:camelize_ignore_uppercase_keys, true)
+        end
 
-      def transform_key(key)
-        # dont touch all_Upper Keys (like "DE")
-        # unless configuration.default_ignore_all_uppercase_keys
-        # is set to false
-        if Sparrow.configuration.camelize_ignore_uppercase_keys &&
-           key.upcase == key
-          normalize_key(key)
-        else
-          normalize_key(key).camelize(strategy)
+        ##
+        # Transform the given key to camelCase based on the configuration
+        # options set on initialization.
+        # @see #initialize
+        # @param [String, #to_s] key the key value to be transformed
+        # @return [String] the transformed key
+        def transform_key(key)
+          key = key.to_s
+          if camelize_ignore_uppercase_keys && key.upcase == key
+            key
+          else
+            key.camelize(strategy)
+          end
         end
       end
     end

data/lib/sparrow/strategies/key_transformation/underscore_key.rb

@@ -1,12 +1,23 @@
-require File.dirname(__FILE__) + '/key_normalizer'
-
 module Sparrow
   module Strategies
-    class UnderscoreKey
-      include KeyNormalizer
+    module KeyTransformation
+      ##
+      # Strategy class for snake_casing keys
+      class UnderscoreKey
+        ##
+        # Create a new UnderscoreKey Strategy
+        # Does nothing except returning a plain instance.
+        def initialize(*args)
+          # no initialization needed
+        end
 
-      def transform_key(key)
-        normalize_key(key).underscore
+        ##
+        # Transforms the given key to snake_case format
+        # @param [String] key the key to be transformed
+        # @return [String] the snake_cased key
+        def transform_key(key)
+          key.to_s.underscore
+        end
       end
     end
   end

data/lib/sparrow/strategies/raw_input.rb

@@ -1,32 +1,54 @@
-require 'active_support/core_ext/object/blank'
-
 module Sparrow
   module Strategies
+    ##
+    # Handles plain JSON input parameter conversion which is sent via
+    # env['rack.input']
     class RawInput
       include Transformable
 
-      attr_reader :env, :type
+      # @return [Hash] the Rack environment
+      # @see #initialize
+      attr_reader :env
+      # @return [Symbol] the HTTP message type
+      # @see #initialize
+      attr_reader :type
 
+      ##
+      # Do the transformation
+      # @return [Hash] the converted JSON as a Hash representation
       def self.handle(env, type)
         self.new(env, type).handle
       end
 
+      # Create a new RawInput Strategy
+      # @param [Hash] env the Rack environment
+      # @param [Symbol] type the HTTP message type. Must be either :request or
+      #  :response
+      # @param [Hash] params the HTTP message parameters to be transformed
+      #   if not already present in the env
       def initialize(env, type = :request, params = nil)
         @env    = env || {}
         @params = params
         @type   = type
       end
 
+      ##
+      # Starts the conversion
+      # @return [Hash] the converted Rack environment
       def handle
         super
         handle_raw_rack
       end
 
+      ##
+      # The parameters to be transformed
+      # @return [Hash] the JSON parameters
+      # @see #initialize
       def params
         if @params
           @params
         else
-          input_io = @env['rack.input']
+          input_io = @env[HttpMessage::RACK_INPUT_KEY]
           params   = input_io.send(:read)
           input_io.rewind
           params
@@ -37,9 +59,9 @@ module Sparrow
 
       def handle_raw_rack
         if params.present?
-          new_raw_input      = json_body.force_encoding("BINARY")
-          @env['rack.input'] = StringIO.new(new_raw_input)
-          @env['rack.input'].rewind
+          new_raw_input        = json_body.force_encoding("BINARY")
+          @env[HttpMessage::RACK_INPUT_KEY] = StringIO.new(new_raw_input)
+          @env[HttpMessage::RACK_INPUT_KEY].rewind
           @env['CONTENT_LENGTH'] = new_raw_input.length
         end
       end

data/lib/sparrow/strategies/transform_params.rb

@@ -1,37 +1,62 @@
-require 'active_support/core_ext/string'
-if ActiveSupport::VERSION::STRING.match(/3\.\d+\.\d+/)
-  require 'sparrow/core_ext/hash'
-end
-
-require 'sparrow/strategies/key_transformation/underscore_key'
-require 'sparrow/strategies/key_transformation/camelize_key'
-
 module Sparrow
   module Strategies
+    ##
+    # Core class to trigger the conversion
     class TransformParams
+      ##
+      # the strategy stating how to convert the JSON
+      # @return [KeyTransformation] key transformation strategy
+      # @see #initialize
       attr_accessor :key_transformation_strategy
 
-      def initialize(key_transformation_strategy_buzzword)
-        key_transformation_strategy = create_key_transformation_strategy(
-            key_transformation_strategy_buzzword)
+      ##
+      # Key Transformation Strategy options. Possible values differ by
+      # the specific strategy. E.g. for CamelizeKey options may be
+      # the strategy and camlize_uppercase_params
+      # @see KeyTransformationStrategy::CamelizeKey
+      # @see KeyTransformationStrategy::UnderscoreKey
+      attr_accessor :options
+
+      ##
+      # Create a new TransformParams instance
+      # @param [String] key_transformation_strategy_buzzword the strategy
+      #   buzzword stating how to transform. Must be either 'camelize' or
+      #   'underscore'
+      # @param [Hash] options options for the key transformation strategy
+      def initialize(key_transformation_strategy_buzzword, options = {})
+        self.options                     = options
+        key_transformation_strategy      = create_key_transformation_strategy(
+        key_transformation_strategy_buzzword)
         self.key_transformation_strategy = key_transformation_strategy
       end
 
+      ##
+      # Do the transformation
+      # @param [Array|Hash] collection_or_hash the object to be transformed
+      #   if it is an Array each object inside of it will be transformed, i.e.
+      #   each Hash's keys
+      #   if it is a Hash each key will be transformed. Recursively.
+      # @return [Array|Hash] the transformed input
       def transform(collection_or_hash)
         case collection_or_hash
-        when Array
-          collection_or_hash.map { |element| transform(element) }
-        when Hash
-          collection_or_hash.deep_transform_keys do |key|
-            key_transformation_strategy.transform_key(key)
-          end
+          when Array
+            collection_or_hash.map { |element| transform(element) }
+          when Hash
+            collection_or_hash.deep_transform_keys do |key|
+              key_transformation_strategy.transform_key(key)
+            end
         end
       end
 
-      def create_key_transformation_strategy(key_transformation_strategy_buzzword)
-        class_name = "#{key_transformation_strategy_buzzword.to_s}_key".camelize
-        strategy_class = "Sparrow::Strategies::#{class_name}".constantize
-        strategy_class.new
+      private
+
+      def create_key_transformation_strategy(key_transformation_strategy)
+        class_name = "#{key_transformation_strategy.to_s}_key"
+        class_name = class_name.camelize
+        full_strategy_class_name =
+            "Sparrow::Strategies::KeyTransformation::#{class_name}"
+        strategy_class           = full_strategy_class_name.constantize
+        strategy_class.new(options)
       end
     end
   end