arstotzka 1.0.1 → 1.0.2

data/lib/arstotzka/exception.rb

@@ -1,3 +1,8 @@
-module Arstotzka::Exception
-  class KeyNotFound < StandardError; end
+# frozen_string_literal: true
+
+module Arstotzka
+  module Exception
+    # Exception raised when a key in the hash is not found
+    class KeyNotFound < StandardError; end
+  end
 end

data/lib/arstotzka/fetcher.rb

@@ -1,50 +1,107 @@
-class Arstotzka::Fetcher
-  include Sinclair::OptionsParser
+# frozen_string_literal: true
 
-  attr_reader :path, :json, :instance
+module Arstotzka
+  # Class responsible for orquestrating the fetch value from the hash
+  # and post-processing it
+  class Fetcher
+    include Sinclair::OptionsParser
 
-  delegate :after, :flatten, to: :options_object
-  delegate :wrap, to: :wrapper
+    # @param hash [Hash] Hash to be crawled for value
+    # @param instance [Object] object whose methods will be called after for processing
+    # @param path [String/Symbol] complete path for fetching the value from hash
+    # @param options [Hash] options that will be passed to {Crawler}, {Wrapper} and {Reader}
+    def initialize(hash, instance, path:, **options)
+      @path = path.to_s.split('.')
+      @hash = hash
+      @instance = instance
+      @options = options
+    end
 
-  def initialize(json, instance, path:, **options)
-    @path = path.to_s.split('.')
-    @json = json
-    @instance = instance
-    @options = options
-  end
+    # Crawls the hash for the value, applying then the final transformations on the final
+    # result (collection not value)
+    #
+    # @example
+    #   class Transaction
+    #     attr_reader :value, :type
+    #
+    #     def initialize(value:, type:)
+    #       @value = value
+    #       @type = type
+    #     end
+    #
+    #     def positive?
+    #       type == 'income'
+    #     end
+    #   end
+    #
+    #   class Account
+    #     private
+    #
+    #     def filter_income(transactions)
+    #       transactions.select(&:positive?)
+    #     end
+    #   end
+    #
+    #   hash = {
+    #     transactions: [
+    #       { value: 1000.53, type: 'income' },
+    #       { value: 324.56,  type: 'outcome' },
+    #       { value: 50.23,   type: 'income' },
+    #       { value: 150.00,  type: 'outcome' },
+    #       { value: 10.23,   type: 'outcome' },
+    #       { value: 100.12,  type: 'outcome' },
+    #       { value: 101.00,  type: 'outcome' }
+    #     ]
+    #   }
+    #   instance = Account.new
+    #   fetcher = Arstotzka::Fetcher.new(hash, instance,
+    #     path: 'transactions',
+    #     clazz: Transaction,
+    #     after: :filter_income
+    #   )
+    #
+    #   fetcher.fetch # retruns [
+    #                 #   Transaction.new(value: 1000.53, type: 'income'),
+    #                 #   Transaction.new(value: 50.23, type: 'income')
+    #                 # ]
+    def fetch
+      value = crawler.value(hash)
+      value.flatten! if flatten && value.respond_to?(:flatten!)
+      value = instance.send(after, value) if after
+      value
+    end
 
-  def fetch
-    value = crawler.value(json)
-    value.flatten! if flatten && value.respond_to?(:flatten!)
-    value = instance.send(after, value) if after
-    value
-  end
+    private
 
-  private
+    attr_reader :path, :hash, :instance
 
-  def crawler
-    @crawler ||= buidl_crawler
-  end
+    delegate :after, :flatten, to: :options_object
+    delegate :wrap, to: :wrapper
 
-  def buidl_crawler
-    Arstotzka::Crawler.new(crawler_options) do |value|
-      wrap(value)
+    def crawler
+      @crawler ||= buidl_crawler
     end
-  end
 
-  def crawler_options
-    options.slice(:case_type, :compact, :default).merge(path: path)
-  end
+    def buidl_crawler
+      Arstotzka::Crawler.new(crawler_options) do |value|
+        wrap(value)
+      end
+    end
 
-  def wrapper
-    @wrapper ||= build_wrapper
-  end
+    def crawler_options
+      options.slice(:case_type, :compact, :default).merge(path: path)
+    end
 
-  def build_wrapper
-    Arstotzka::Wrapper.new(wrapper_options)
-  end
+    def wrapper
+      @wrapper ||= build_wrapper
+    end
 
-  def wrapper_options
-    options.slice(:clazz, :type)
+    def build_wrapper
+      Arstotzka::Wrapper.new(wrapper_options)
+    end
+
+    def wrapper_options
+      options.slice(:clazz, :type)
+    end
   end
 end

data/lib/arstotzka/reader.rb

@@ -1,33 +1,81 @@
+# frozen_string_literal: true
+
 module Arstotzka
+  # Reads a value from a hash using the path as list of keys
   class Reader
-    attr_reader :path, :case_type
-
+    # @param path [Array] path of keys broken down as array
+    # @param case_type [Symbol] Case of the keys
+    #   - lower_camel: keys in the hash are lowerCamelCase
+    #   - upper_camel: keys in the hash are UpperCamelCase
+    #   - snake: keys in the hash are snake_case
     def initialize(path:, case_type:)
       @case_type = case_type
-      @path = path.map(&self.method(:change_case))
+      @path = path.map(&method(:change_case))
     end
 
-    def read(json, index)
+    # Reads the value of one key in the hash
+    #
+    # @param hash [Hash] hash to be read
+    # @param index [Integer] Index of the key (in path) to be used
+    #
+    # @return Object The value fetched from the hash
+    #
+    # @example
+    #   hash = {
+    #     full_name: 'John',
+    #     'Age' => 23,
+    #     'carCollection' => [
+    #       { maker: 'Ford', 'model' => 'Model A' },
+    #       { maker: 'BMW', 'model' => 'Jetta' }
+    #     ]
+    #   }
+    #
+    #   reader = Arstotzka::Reader.new(%w(person full_name), case_type: :snake)
+    #   reader.read(hash, 1) # returns 'John'
+    #
+    # @example
+    #   reader = Arstotzka::Reader.new(%w(person age), case_type: :upper_camel)
+    #   reader.read(hash, 1) # returns 23
+    #
+    # @example
+    #   reader = Arstotzka::Reader.new(%w(person car_collection model), case_type: :snake)
+    #   reader.read(hash, 1) # raises {Arstotzka::Exception::KeyNotFound}
+    #
+    # @example
+    #   reader = Arstotzka::Reader.new(%w(person car_collection model), case_type: :lower_camel)
+    #   reader.read(hash, 1) # returns [
+    #                        #   { maker: 'Ford', 'model' => 'Model A' },
+    #                        #   { maker: 'BMW', 'model' => 'Jetta' }
+    #                        # ]
+    def read(hash, index)
       key = path[index]
 
-      check_key!(json, key)
+      check_key!(hash, key)
 
-      json.key?(key) ? json[key] : json[key.to_sym]
+      hash.key?(key) ? hash[key] : hash[key.to_sym]
     end
 
-    def is_ended?(index)
+    # Checks if index is within path range
+    #
+    # @example
+    #   reader = Arstotzka::Reader.new(%w(person full_name), case_type: :snake)
+    #   reader.read(hash, 1) # returns false
+    #   reader.read(hash, 2) # returns true
+    def ended?(index)
       index >= path.size
     end
 
     private
 
-    def check_key!(json, key)
-      return if has_key?(json, key)
+    attr_reader :path, :case_type
+
+    def check_key!(hash, key)
+      return if key?(hash, key)
       raise Exception::KeyNotFound
     end
 
-    def has_key?(json, key)
-      json&.key?(key) || json&.key?(key.to_sym)
+    def key?(hash, key)
+      hash&.key?(key) || hash&.key?(key.to_sym)
     end
 
     def change_case(key)

data/lib/arstotzka/type_cast.rb

@@ -1,15 +1,29 @@
-module Arstotzka::TypeCast
-  extend ActiveSupport::Concern
+# frozen_string_literal: true
 
-  def to_integer(value)
-    value.to_i if value.present?
-  end
+module Arstotzka
+  # Concern with all the type cast methods to be used by {Wrapper}
+  #
+  # Usage of typecast is defined by the configuration of {Builder} by the usage of
+  # option type
+  module TypeCast
+    extend ActiveSupport::Concern
 
-  def to_string(value)
-    value.to_s
-  end
+    # converts a value to integer
+    # @return [Integer]
+    def to_integer(value)
+      value.to_i if value.present?
+    end
+
+    # converts value to string
+    # @return [String]
+    def to_string(value)
+      value.to_s
+    end
 
-  def to_float(value)
-    value.to_f if value.present?
+    # converts value to float
+    # @return [Float]
+    def to_float(value)
+      value.to_f if value.present?
+    end
   end
 end

data/lib/arstotzka/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Arstotzka
-  VERSION = '1.0.1'
+  VERSION = '1.0.2'
 end

data/lib/arstotzka/wrapper.rb

@@ -1,36 +1,61 @@
-class Arstotzka::Wrapper
-  include Arstotzka::TypeCast
-
-  attr_reader :clazz, :type
-
-  def initialize(clazz: nil, type: nil)
-    @clazz = clazz
-    @type = type
-  end
-
-  def wrap(value)
-    return wrap_array(value) if value.is_a?(Array)
-    wrap_element(value)
-  end
-
-  private
-
-  def wrap_element(value)
-    value = cast(value) if has_type? && !value.nil?
-    return if value.nil?
-
-    clazz ? clazz.new(value) : value
-  end
-
-  def wrap_array(array)
-    array.map { |v| wrap v }
-  end
-
-  def has_type?
-    type.present? && type != :none
-  end
-
-  def cast(value)
-    public_send("to_#{type}", value)
+# frozen_string_literal: true
+
+module Arstotzka
+  # Class responsible for wrapping / parsing a value fetched
+  class Wrapper
+    include Arstotzka::TypeCast
+
+    # @param clazz [Class] class to wrap the value
+    # @param type [String/Symbol] type to cast the value. The
+    #   possible type_cast is defined by {TypeCast}
+    def initialize(clazz: nil, type: nil)
+      @clazz = clazz
+      @type = type
+    end
+
+    # wrap a value
+    #
+    # @example
+    #   class Person
+    #     attr_reader :name
+    #
+    #     def initialize(name)
+    #       @name = name
+    #     end
+    #   end
+    #
+    #   wrapper = Arstotzka::Wrapper.new(clazz: Person)
+    #   wrapper.wrap('John') # retruns Person.new('John')
+    #
+    # @example
+    #   wrapper = Arstotzka::Wrapper.new(type: :integer)
+    #   wrapper.wrap(['10', '20', '30']) # retruns [10, 20, 30]
+    def wrap(value)
+      return wrap_array(value) if value.is_a?(Array)
+      wrap_element(value)
+    end
+
+    private
+
+    attr_reader :clazz, :type
+
+    def wrap_element(value)
+      value = cast(value) if type? && !value.nil?
+      return if value.nil?
+
+      clazz ? clazz.new(value) : value
+    end
+
+    def wrap_array(array)
+      array.map { |v| wrap v }
+    end
+
+    def type?
+      type.present? && type != :none
+    end
+
+    def cast(value)
+      public_send("to_#{type}", value)
+    end
   end
 end

data/spec/integration/readme/default_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe 'default option' do

data/spec/integration/readme/my_parser_spec.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe MyParser do

data/spec/integration/yard/arstotzka/builder_spec.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Arstotzka::Builder do
+  describe 'yard' do
+    let!(:instance) { klass.new(hash) }
+    let(:hash) do
+      {
+        'name' => { first: 'John', last: 'Williams' },
+        :age => '20',
+        'cars' => 2.0
+      }
+    end
+
+    describe '#first_name' do
+      let(:klass)    { Class.new(MyModel) }
+      let(:builder)  { described_class.new([:first_name], klass, full_path: 'name.first') }
+
+      before do
+        builder.build
+      end
+
+      it 'crawls into the hash to find the value of the first name' do
+        expect(instance.first_name).to eq('John')
+      end
+    end
+
+    describe '#age' do
+      let(:klass)    { Class.new(MyModel) }
+      let(:builder)  { described_class.new([:age, 'cars'], klass, type: :integer) }
+
+      before do
+        builder.build
+      end
+
+      it 'crawls into the hash to find the value of the age' do
+        expect(instance.age).to eq(20)
+      end
+
+      it do
+        expect(instance.age).to be_a(Integer)
+      end
+    end
+
+    describe '#cars' do
+      let(:klass)    { Class.new(MyModel) }
+      let(:builder)  { described_class.new([:age, 'cars'], klass, type: :integer) }
+
+      before do
+        builder.build
+      end
+
+      it 'crawls into the hash to find the value of the age' do
+        expect(instance.cars).to eq(2)
+      end
+
+      it do
+        expect(instance.cars).to be_a(Integer)
+      end
+    end
+  end
+end