arstotzka 1.0.3 → 1.0.4

data/lib/arstotzka/reader.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 module Arstotzka
+  # @api private
+  #
   # Reads a value from a hash using the path as list of keys
   class Reader
+    # Creates a new instance of Reader
+    #
     # @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
+    #
+    # @return [Aristotzka::Reader]
     def initialize(path:, case_type:)
       @case_type = case_type
       @path = path.map(&method(:change_case))
@@ -18,7 +24,7 @@ module Arstotzka
     # @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
+    # @return [Object] The value fetched from the hash
     #
     # @example
     #   hash = {
@@ -55,6 +61,8 @@ module Arstotzka
       hash.key?(key) ? hash[key] : hash[key.to_sym]
     end
 
+    # @private
+    #
     # Checks if index is within path range
     #
     # @example
@@ -67,17 +75,52 @@ module Arstotzka
 
     private
 
+    # @private
     attr_reader :path, :case_type
 
+    # @private
+    #
+    # Checks if a hash contains or not the key
+    #
+    # if the key is not found, an execption is raised
+    #
+    # @raise Arstotzka::Exception::KeyNotFound
+    #
+    # @return [NilClass]
+    #
+    # @see #key?
     def check_key!(hash, key)
       return if key?(hash, key)
       raise Exception::KeyNotFound
     end
 
+    # @private
+    #
+    # Checks if a hash contains or not the key
+    #
+    # The check first happens using String key and,
+    # in case of not found, searches as symbol
+    #
+    # @param [Hash] hash Hash where the key will be found
+    # @param [String] key The key to be checked
+    #
+    # @return [Boolean]
+    #
+    # @see #check_key!
     def key?(hash, key)
       hash&.key?(key) || hash&.key?(key.to_sym)
     end
 
+    # @private
+    #
+    # Transforms the key to have the correct case
+    #
+    # the possible case_types (instance attribute) are
+    # - lower_camel: for cammel case with first letter lowercase
+    # - upper_camel: for cammel case with first letter uppercase
+    # - snake: for snake case
+    #
+    # @param [String] key the key to be transformed
     def change_case(key)
       case case_type
       when :lower_camel

data/lib/arstotzka/type_cast.rb

@@ -1,27 +1,140 @@
 # frozen_string_literal: true
 
 module Arstotzka
+  # @api public
+  #
   # 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
+  #
+  # TypeCast can also be extended to include more types
+  #
+  # Supported types:
+  # - integer
+  # - string
+  # - float
+  #
+  # @example (see #to_integer)
+  #
+  # @example (see #to_string)
+  #
+  # @example (see #to_float)
+  #
+  # @example Extending typecast
+  #   class Car
+  #     attr_reader :model, :maker
+  #
+  #     def initialize(model:, maker:)
+  #       @model = model
+  #       @maker = maker
+  #     end
+  #   end
+  #
+  #   module Arstotzka
+  #     module TypeCast
+  #       def to_car(hash)
+  #         Car.new(hash.symbolize_keys)
+  #       end
+  #     end
+  #   end
+  #
+  #   class CarCollector
+  #     include Arstotzka
+  #
+  #     attr_reader :json
+  #
+  #     expose :cars, full_path: 'cars.unit', type: :car
+  #     def initialize(hash)
+  #       @json = hash
+  #     end
+  #   end
+  #
+  #   hash = {
+  #     cars: [{
+  #       unit: { model: 'fox', maker: 'volkswagen' }
+  #     }, {
+  #       unit: { 'model' => 'focus', 'maker' => 'ford' }
+  #     }]
+  #   }
+  #
+  #   model = CarCollector.new(hash)
+  #
+  #   model.cars              # returns [<Car>, <Car>]
+  #   model.cars.map(&:model) # returns ['fox', 'focus']
   module TypeCast
     extend ActiveSupport::Concern
 
-    # converts a value to integer
+    # Converts a value to integer
+    #
     # @return [Integer]
+    #
+    # @example Casting to Integer
+    #   class TypeCaster
+    #     include Arstotzka
+    #
+    #     expose :age,     type: :integer, json: :@hash
+    #
+    #     def initialize(hash)
+    #       @hash = hash
+    #     end
+    #   end
+    #
+    #   hash = {
+    #     age: '10',
+    #   }
+    #
+    #   TypeCaseter.new(age: '10').age
     def to_integer(value)
       value.to_i if value.present?
     end
 
     # converts value to string
+    #
     # @return [String]
+    #
+    # @example Casting to String
+    #   class TypeCaster
+    #     include Arstotzka
+    #
+    #     expose :payload, type: :string, json: :@hash
+    #
+    #     def initialize(hash)
+    #       @hash = hash
+    #     end
+    #   end
+    #
+    #   hash = {
+    #     payload: { 'key' => 'value' },
+    #   }
+    #
+    #   model.TypeCaseter.new(hash)
+    #
+    #   model.payload # returns '{"key"=>"value"}'
     def to_string(value)
       value.to_s
     end
 
     # converts value to float
+    #
     # @return [Float]
+    #
+    # @example Casting to Float
+    #   class TypeCaster
+    #     include Arstotzka
+    #
+    #     expose :price,   type: :float, json: :@hash
+    #
+    #     def initialize(hash)
+    #       @hash = hash
+    #     end
+    #   end
+    #
+    #   hash = {
+    #     price: '1.75'
+    #   }
+    #
+    #   TypeCaseter.new(price: '1.75').price # returns 1.75
     def to_float(value)
       value.to_f if value.present?
     end

data/lib/arstotzka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Arstotzka
-  VERSION = '1.0.3'
+  VERSION = '1.0.4'
 end

data/lib/arstotzka/wrapper.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 module Arstotzka
+  # @api private
+  #
   # Class responsible for wrapping / parsing a value fetched
   class Wrapper
     include Arstotzka::TypeCast
 
+    # Returns a new instance of Wrapper
+    #
     # @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}
@@ -15,7 +19,9 @@ module Arstotzka
 
     # wrap a value
     #
-    # @example
+    # @return [Object]
+    #
+    # @example Wrapping in a class
     #   class Person
     #     attr_reader :name
     #
@@ -27,9 +33,23 @@ module Arstotzka
     #   wrapper = Arstotzka::Wrapper.new(clazz: Person)
     #   wrapper.wrap('John') # retruns Person.new('John')
     #
-    # @example
+    # @example Casting type
     #   wrapper = Arstotzka::Wrapper.new(type: :integer)
     #   wrapper.wrap(['10', '20', '30']) # retruns [10, 20, 30]
+    #
+    # @example Casting and Wrapping
+    #   class Request
+    #     attr_reader :payload
+    #
+    #     def initialize(payload)
+    #       @payload = payload
+    #     end
+    #   end
+    #
+    #   wrapper = Arstotzka::Wrapper.new(type: :string, clazz: Request)
+    #   request = wrapper.wrap(value)
+    #
+    #   request.payload  # returns '{"key"=>"value"}'
     def wrap(value)
       return wrap_array(value) if value.is_a?(Array)
       wrap_element(value)
@@ -37,8 +57,14 @@ module Arstotzka
 
     private
 
+    # @private
     attr_reader :clazz, :type
 
+    # @private
+    #
+    # Wraps an element with a class and perform typecasting
+    #
+    # @return [Object]
     def wrap_element(value)
       value = cast(value) if type? && !value.nil?
       return if value.nil?
@@ -46,14 +72,33 @@ module Arstotzka
       clazz ? clazz.new(value) : value
     end
 
+    # @private
+    #
+    # Wraps each element of the array
+    #
+    # @see #wrap_element
+    #
+    # @return [Arra]
     def wrap_array(array)
       array.map { |v| wrap v }
     end
 
+    # @private
+    #
+    # Check if type was given
+    #
+    # @return [Boolean]
     def type?
       type.present? && type != :none
     end
 
+    # @private
+    #
+    # Performs type casting
+    #
+    # @see Arstotzka::TypeCaster
+    #
+    # @return [Object]
     def cast(value)
       public_send("to_#{type}", value)
     end

data/spec/integration/readme/arstotzka_spec.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Arstotzka do
+  describe 'default option' do
+    subject(:star_gazer) do
+      StarGazer.new(hash).favorite_star
+    end
+
+    let(:hash) { {} }
+
+    context 'when node is not found' do
+      it 'returns the default before wrapping' do
+        expect(star_gazer.name).to eq('Sun')
+      end
+
+      it 'wraps the returned value in a class' do
+        expect(star_gazer).to be_a(Star)
+      end
+    end
+
+    context 'when node is not missing' do
+      let(:hash) do
+        {
+          universe: {
+            star: { name: 'Antares' }
+          }
+        }
+      end
+
+      it 'returns the value before wrapping' do
+        expect(star_gazer.name).to eq('Antares')
+      end
+
+      it 'wraps the returned value in a class' do
+        expect(star_gazer).to be_a(Star)
+      end
+    end
+  end
+end

data/spec/integration/readme/my_parser_spec.rb

@@ -3,7 +3,7 @@
 require 'spec_helper'
 
 describe MyParser do
-  subject { described_class.new(hash) }
+  subject(:parser) { described_class.new(hash) }
 
   let(:hash) do
     {
@@ -27,62 +27,63 @@ describe MyParser do
 
   describe 'id' do
     it 'returns the parsed id' do
-      expect(subject.id).to eq(10)
+      expect(parser.id).to eq(10)
     end
   end
 
   describe 'name' do
     it 'returns the parsed name' do
-      expect(subject.name).to eq('Robert')
+      expect(parser.name).to eq('Robert')
     end
 
     context 'when person is missing' do
-      subject { described_class.new }
+      subject(:parser) { described_class.new }
 
       it do
-        expect { subject.name }.not_to raise_error
+        expect { parser.name }.not_to raise_error
       end
 
       it do
-        expect(subject.name).to be_nil
+        expect(parser.name).to be_nil
       end
     end
   end
 
   describe 'age' do
     it do
-      expect(subject.age).to be_a(Integer)
+      expect(parser.age).to be_a(Integer)
     end
 
     it 'returns the parsed age' do
-      expect(subject.age).to eq(22)
+      expect(parser.age).to eq(22)
     end
   end
 
   describe '#total_money' do
     it do
-      expect(subject.total_money).to be_a(Float)
+      expect(parser.total_money).to be_a(Float)
     end
 
     it 'summs all the balance in the accounts' do
-      expect(subject.total_money).to eq(1050.36)
+      expect(parser.total_money).to eq(1050.36)
     end
 
     context 'when there is a node missing' do
       let(:hash) { {} }
+
       it 'returns nil' do
-        expect(subject.total_money).to be_nil
+        expect(parser.total_money).to be_nil
       end
     end
   end
 
   describe '#total_owed' do
     it do
-      expect(subject.total_owed).to be_a(Float)
+      expect(parser.total_owed).to be_a(Float)
     end
 
     it 'summs all the balance in the accounts' do
-      expect(subject.total_owed).to eq(550.84)
+      expect(parser.total_owed).to eq(550.84)
     end
   end
 end

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

@@ -4,7 +4,7 @@ require 'spec_helper'
 
 describe Arstotzka::Crawler do
   describe 'yard' do
-    subject do
+    subject(:crawler) do
       described_class.new(path: path, **options)
     end
 
@@ -21,13 +21,13 @@ describe Arstotzka::Crawler do
     end
 
     it 'crawls to find the value' do
-      expect(subject.value(hash)).to eq('John')
+      expect(crawler.value(hash)).to eq('John')
     end
 
     describe '#value' do
       context 'when hash contains the path' do
         it 'crawls to find the value' do
-          expect(subject.value(hash)).to eq('John')
+          expect(crawler.value(hash)).to eq('John')
         end
       end
 
@@ -51,24 +51,24 @@ describe Arstotzka::Crawler do
         end
 
         it 'crawls to find the value' do
-          expect(subject.value(hash)).to eq([['Rakhar']])
+          expect(crawler.value(hash)).to eq([['Rakhar']])
         end
 
-        context 'and we set a default value' do
+        context 'with default value' do
           let(:options) { { compact: true, case_type: :snake, default: 'NO HERO' } }
 
           it 'return default value for missed keys' do
-            expect(subject.value(hash)).to eq([['NO HERO', 'Rakhar'], 'NO HERO'])
+            expect(crawler.value(hash)).to eq([['NO HERO', 'Rakhar'], 'NO HERO'])
           end
         end
 
-        context 'and we give a block' do
-          subject do
+        context 'when block is given' do
+          subject(:crawler) do
             described_class.new(path: path, **options) { |value| value&.to_sym }
           end
 
           it 'returns the post processed values' do
-            expect(subject.value(hash)).to eq([[:Rakhar]])
+            expect(crawler.value(hash)).to eq([[:Rakhar]])
           end
         end
       end

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

@@ -5,7 +5,7 @@ require 'spec_helper'
 describe Arstotzka::Fetcher do
   describe 'yard' do
     describe '#fetch' do
-      subject { described_class.new(hash, instance, path: path, **options) }
+      subject(:fetcher) { described_class.new(hash, instance, path: path, **options) }
 
       let(:instance) { Account.new }
       let(:path) { 'transactions' }
@@ -31,11 +31,11 @@ describe Arstotzka::Fetcher do
 
       describe 'incoming transactions' do
         it 'returns only the income payments' do
-          expect(subject.fetch.count).to eq(2)
+          expect(fetcher.fetch.count).to eq(2)
         end
 
         it 'returns Transactions' do
-          expect(subject.fetch.map(&:class).uniq).to eq([Transaction])
+          expect(fetcher.fetch.map(&:class).uniq).to eq([Transaction])
         end
 
         it 'returns results wrapped in Transactions' do
@@ -43,7 +43,7 @@ describe Arstotzka::Fetcher do
             Transaction.new(value: 1000.53, type: 'income'),
             Transaction.new(value: 50.23, type: 'income')
           ]
-          expect(subject.fetch).to eq(expected)
+          expect(fetcher.fetch).to eq(expected)
         end
       end
     end

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

@@ -4,7 +4,7 @@ require 'spec_helper'
 
 describe Arstotzka::Reader do
   describe 'yard' do
-    subject { described_class.new(path: path, case_type: case_type) }
+    subject(:reader) { described_class.new(path: path, case_type: case_type) }
 
     let(:path) { %w[person full_name] }
     let(:case_type) { :snake }
@@ -23,7 +23,7 @@ describe Arstotzka::Reader do
 
       context 'when using snake_case' do
         it 'fetches the value using snake case key' do
-          expect(subject.read(hash, 1)).to eq('John')
+          expect(reader.read(hash, 1)).to eq('John')
         end
 
         context 'when key is missing' do
@@ -31,7 +31,7 @@ describe Arstotzka::Reader do
 
           it do
             expect do
-              subject.read(hash, 1)
+              reader.read(hash, 1)
             end.to raise_error(Arstotzka::Exception::KeyNotFound)
           end
         end
@@ -46,7 +46,7 @@ describe Arstotzka::Reader do
             { maker: 'Ford', 'model' => 'Model A' },
             { maker: 'BMW', 'model' => 'Jetta' }
           ]
-          expect(subject.read(hash, 1)).to eq(expected)
+          expect(reader.read(hash, 1)).to eq(expected)
         end
       end
 
@@ -55,7 +55,7 @@ describe Arstotzka::Reader do
         let(:path) { %w[person age] }
 
         it 'fetches the value using uper camel case key' do
-          expect(subject.read(hash, 1)).to eq(23)
+          expect(reader.read(hash, 1)).to eq(23)
         end
       end
     end
@@ -63,13 +63,13 @@ describe Arstotzka::Reader do
     describe '#ended?' do
       context 'when the fetches have not ended' do
         it do
-          expect(subject.ended?(1)).to be_falsey
+          expect(reader).not_to be_ended(1)
         end
       end
 
       context 'when the fetches have ended' do
         it do
-          expect(subject.ended?(2)).to be_truthy
+          expect(reader).to be_ended(2)
         end
       end
     end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+describe Arstotzka::TypeCast do
+  subject(:model) { TypeCaster.new(hash) }
+
+  let(:hash) do
+    {
+      age: '10',
+      payload: { 'key' => 'value' },
+      price: '1.75'
+    }
+  end
+
+  describe 'yard' do
+    describe 'integer' do
+      it 'converts string to integer' do
+        expect(model.age).to eq(10)
+      end
+    end
+
+    describe 'string' do
+      it 'converts value to string' do
+        expect(model.payload).to eq('{"key"=>"value"}')
+      end
+    end
+
+    describe 'float' do
+      it 'converts value to string' do
+        expect(model.price).to eq(1.75)
+      end
+    end
+
+    describe 'extending' do
+      subject(:model) { CarCollector.new(hash) }
+
+      let(:hash) do
+        {
+          cars: [{
+            unit: { model: 'fox', maker: 'volkswagen' }
+          }, {
+            unit: { 'model' => 'focus', 'maker' => 'ford' }
+          }]
+        }
+      end
+
+      it 'converts each unit to be a car' do
+        expect(model.cars.first).to be_a(Car)
+      end
+
+      it 'converts using the given hash' do
+        expect(model.cars.map(&:model)).to eq(%w[fox focus])
+      end
+    end
+  end
+end