arstotzka 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58ec63d9c1394d610f41adbefff57f81ad2dbc66
-  data.tar.gz: 27ad6c08193eafb763a220a2ef9eec7dfba9ce96
+  metadata.gz: c670a2581e68a1b7e54d5451b6b425fde3cde0db
+  data.tar.gz: 0f2d973a287534f68be841ebcbb63fc0e5f5babb
 SHA512:
-  metadata.gz: 29771997f5279078a4647f780be36b36a4dc1a407ff7fb3b88b232ca81447b7debf7fe4f74e9d81f6e3147e5003bb3e438e4347be4746d2ff9df36d9024739c9
-  data.tar.gz: 6413b13c996a55776327d951e9ec5b9adbc3d978374a0bb946abc799f0933160cb1c8d6c8718eb0f194faba273a3876581da0a1ecd5e4b7ad8b7b8f62ee6cd3a
+  metadata.gz: 1826c6c9b9017ce2f302ed930856acb4889eede6a203b25dc1674f1dfe545bae8407acbfaad4cee294782e2afaa11aca50ee39f95700756d6e62ab8cbf18bdc9
+  data.tar.gz: 29f5570b7d161c62069512a9605fde0424c6ac9083ad7dc15d25b6a36e86afe747b6e3ad0abefd1a8d908c86b2b9df34415ea23543d8f2744286a017727ea012

data/.circleci/config.yml

@@ -10,4 +10,5 @@ jobs:
       - run: ./cc-test-reporter before-build
       - run: bundle install
       - run: bundle exec rspec
+      - run: rubocop
       - run: ./cc-test-reporter after-build --exit-code $?

data/.gitignore

@@ -1,3 +1,4 @@
 coverage
 Gemfile.lock
-
+.yardoc
+doc

data/.rubocop.yml

@@ -0,0 +1,11 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 2.4
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*_spec.rb'
+
+Metrics/LineLength:
+  Max: 100

data/.rubocop_todo.yml

@@ -0,0 +1,20 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2018-07-22 21:24:28 +0000 using RuboCop version 0.58.0.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 1
+# Configuration parameters: CountKeywordArgs.
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/arstotzka/builder.rb'
+
+# Offense count: 1
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'test/**/*'
+    - 'lib/arstotzka.rb'

data/Gemfile

@@ -1,8 +1,9 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 gemspec
 
 group :test do
   gem 'safe_attribute_assignment', '0.0.3'
 end
-

data/Guardfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # More info at https://github.com/guard/guard#readme
 
 guard 'bundler' do
@@ -8,6 +10,5 @@ end
 guard :rspec, all_after_pass: true, all_on_start: true do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch('spec/spec_helper.rb')  { 'spec' }
 end
-

data/README.md

@@ -4,6 +4,8 @@ Arstotzka
 [![Test Coverage](https://codeclimate.com/github/darthjee/arstotzka/badges/coverage.svg)](https://codeclimate.com/github/darthjee/arstotzka/coverage)
 [![Issue Count](https://codeclimate.com/github/darthjee/arstotzka/badges/issue_count.svg)](https://codeclimate.com/github/darthjee/arstotzka)
 
+![arstotzka](https://raw.githubusercontent.com/darthjee/arstotzka/master/arstotzka.jpg)
+
 This project allows for a quick hash / json data fetching in order to avoid code
 that tries to crawl through a hash and has to constantly check for nil values or missing keys
 
@@ -12,21 +14,38 @@ avoids method missing by aways having the declarated methods, even if that means
 
 Json Parser is also usefull when you need keys case changed or data type cast
 
-Getting started
+Instalation
 ---------------
 1. Add Arstotzka to your `Gemfile` and `bundle install`:
+  - Install it
+
+  ```ruby
+    gem install arstotzka
+  ```
+
+  - Or add Arstotka to you `Gemfile` and `bundle install`
 
   ```ruby
   gem 'arstotzka'
   ```
 
-2. Include in a class that you want to wrap a json/hash
+  ```bash
+    bundle install arstotzka
+  ```
+
+Yard Documentation
+-------------------
+https://www.rubydoc.info/gems/arstotzka/
+
+Getting Started
+---------------
+1. Include in a class that you want to wrap a json/hash
   ```ruby
   class MyParser
     include Arstotzka
   ```
 
-3. Declare the keys you want to crawl
+2. Declare the keys you want to crawl
   ```ruby
   class MyParser
     include Arstotzka
@@ -67,9 +86,9 @@ Getting started
   #returns nil
   ```
 
-  4. fully customise the way you crawl / fetch the information with [Options](#options)
+3. fully customise the way you crawl / fetch the information with [Options](#options)
 
-  5. Create custom [typecast](#TypeCast)
+4. Create custom [typecast](#TypeCast)
 
 Options
 -------

data/Rakefile

@@ -1,7 +1,9 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new
 
-task :default => :spec
+task default: :spec
 task test: :spec

data/arstotzka.gemspec

@@ -1,29 +1,32 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'arstotzka/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "arstotzka"
+  spec.name          = 'arstotzka'
   spec.version       = Arstotzka::VERSION
-  spec.authors       = ["Darthjee"]
-  spec.email         = ["dev@gmail.com"]
-  spec.summary       = "Arstotzka"
+  spec.authors       = ['Darthjee']
+  spec.email         = ['dev@gmail.com']
+  spec.summary       = 'Arstotzka'
   spec.description   = spec.description
-  spec.homepage      = "https://github.com/darthjee/arstotzka"
+  spec.homepage      = 'https://github.com/darthjee/arstotzka'
 
-  spec.files         = `git ls-files`.split($/)
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f)  }
+  spec.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
   spec.add_runtime_dependency 'activesupport', '~> 5.x'
-  spec.add_runtime_dependency 'sinclair'
+  spec.add_runtime_dependency 'sinclair', '>= 1.1.1'
 
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'pry-nav'
+  spec.add_development_dependency 'rake', '>= 12.3.1'
+  spec.add_development_dependency 'rspec', '>= 3.7'
+  spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'safe_attribute_assignment'
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake", ">= 12.3.1"
-  spec.add_development_dependency "rspec", ">= 3.7"
   spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'pry-nav'
+  spec.add_development_dependency 'yard'
 end

data/lib/arstotzka.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'active_support'
 require 'active_support/all'
 require 'sinclair'

data/lib/arstotzka/builder.rb

@@ -1,9 +1,38 @@
-class Arstotzka::Builder < Sinclair
+# frozen_string_literal: true
 
-  attr_reader :attr_names, :path, :full_path, :cached
-
-  def initialize(attr_names, clazz, path: nil, full_path: nil, cached: false, **options)
-    super(clazz, {
+module Arstotzka
+  # Class responsible to orchestrate the addtion of method that will
+  # crawl the hash for value
+  #
+  # @example
+  #   class MyModel
+  #     attr_reader :json
+  #
+  #     def initialize(json)
+  #       @json = json
+  #     end
+  #   end
+  #
+  #   instance = MyModel.new(
+  #     'name' => { first: 'John', last: 'Williams' },
+  #     :age => '20',
+  #     'cars' => 2.0
+  #   )
+  #
+  #   builder = Arstotzka::Builder.new([ :first_name ], MyModel, full_path: 'name.first')
+  #   builder.build
+  #
+  #   instance.first_name # returns 'John'
+  #
+  #   builder = Arstotzka::Builder.new([ :age, :cars ], MyModel, type: :integer)
+  #   builder.build
+  #
+  #   instance.age  # returns 20
+  #   instance.cars # returns 2
+  #
+  # @see https://www.rubydoc.info/gems/sinclair Sinclair
+  class Builder < Sinclair
+    DEFAULT_OPTIONS = {
       after:     false,
       case:      :lower_camel,
       class:     nil,
@@ -12,62 +41,95 @@ class Arstotzka::Builder < Sinclair
       flatten:   false,
       json:      :json,
       type:      :none
-    }.merge(options.symbolize_keys))
-
-    @attr_names = attr_names
-    @path = path
-    @full_path = full_path
-    @cached = cached
-    init
-  end
+    }.freeze
 
-  private
+    # @param attr_names [Array] list of attributes to be fetched from the hash/json
+    # @param clazz [Class] class to receive the methods
+    # @param path [String/Symbol] path of hash attributes to find the root
+    #   where the attribute live (then fetching it using the attribute name)
+    # @param full_path [String/Symbol] path of hash attributes to find exacttly where the
+    #   value live (ignoring the attribute name)
+    # @param cached [Boolean] flag if the result should be memorized instead of repeating
+    #   the crawling
+    # @param json [String/Symbol] name of the method containing the Hash/json to be crawled
+    # @param options [Hash] hash containing extra options
+    # @option options [String/Symbol] case:  {Reader} flag definining on which case will
+    #   the keys be defined
+    #   - lower_camel: keys in the hash are lowerCamelCase
+    #   - upper_camel: keys in the hash are UpperCamelCase
+    #   - snake: keys in the hash are snake_case
+    # @option options [Boolean] compact:  {Crawler} flag to apply Array#compact thus
+    #   removing nil results
+    # @option options [Class] class:  {Fetcher} option thatwhen passed, wraps the result in an
+    #   instance of the given class
+    # @option options [String/Symbol] after:  {Fetcher} option with the name of the method to be
+    #   called once the value is fetched for mapping the value
+    # @option options [Boolean] flatten:  {Fetcher} flag to aplly Array#flatten thus
+    #   avoing nested arrays
+    # @option options [String/Symbol] type:  {Fetcher} option declaring the type of the returned
+    #   value (to use casting)
+    #   - integer
+    #   - string
+    #   - float
+    def initialize(attr_names, clazz,
+                   json: :json, path: nil, full_path: nil, cached: false,
+                   **options)
+      super(clazz, DEFAULT_OPTIONS.merge(options.symbolize_keys))
 
-  def init
-    attr_names.each do |attr|
-      add_attr(attr)
+      @attr_names = attr_names
+      @path = path
+      @full_path = full_path
+      @cached = cached
+      @json_name = json
+      init
     end
-  end
 
-  def real_path(attribute)
-    full_path || [path, attribute].compact.join('.')
-  end
+    private
 
-  def json_name
-    options[:json]
-  end
+    attr_reader :attr_names, :json_name, :path, :full_path, :cached
 
-  def wrapper_clazz
-    options[:class]
-  end
+    def init
+      attr_names.each do |attr|
+        add_attr(attr)
+      end
+    end
 
-  def case_type
-    options[:case]
-  end
+    def real_path(attribute)
+      full_path || [path, attribute].compact.join('.')
+    end
 
-  def fetcher_options(attribute)
-    options.slice(:compact, :after, :type, :flatten, :default).merge({
-      clazz: wrapper_clazz,
-      case_type: case_type,
-      path: real_path(attribute)
-    })
-  end
+    def wrapper_clazz
+      options[:class]
+    end
 
-  def add_attr(attribute)
-    add_method attribute, "#{cached ? cached_fetcher(attribute) : attr_fetcher(attribute)}"
-  end
+    def case_type
+      options[:case]
+    end
+
+    def fetcher_options(attribute)
+      options.slice(:compact, :after, :type, :flatten, :default).merge(
+        clazz: wrapper_clazz,
+        case_type: case_type,
+        path: real_path(attribute)
+      )
+    end
 
-  def attr_fetcher(attribute)
-    <<-CODE
+    def add_attr(attribute)
+      add_method attribute, (cached ? cached_fetcher(attribute) : attr_fetcher(attribute)).to_s
+    end
+
+    def attr_fetcher(attribute)
+      <<-CODE
       ::Arstotzka::Fetcher.new(
         #{json_name}, self, #{fetcher_options(attribute)}
       ).fetch
-    CODE
-  end
+      CODE
+    end
 
-  def cached_fetcher(attribute)
-    <<-CODE
+    def cached_fetcher(attribute)
+      <<-CODE
       @#{attribute} ||= #{attr_fetcher(attribute)}
-    CODE
+      CODE
+    end
   end
 end

data/lib/arstotzka/class_methods.rb

@@ -1,5 +1,39 @@
+# frozen_string_literal: true
+
 module Arstotzka
+  # As Arstotzka extends ActiveSupport::Concern, Arstotzka::ClassMethods define
+  # methods that will be available when defining a class that includes Arstotka
   module ClassMethods
+    # expose a field from the json/hash as a method
+    #
+    # @example
+    #   class MyModel
+    #     include Arstotzka
+    #
+    #     attr_reader :json
+    #
+    #     expose :first_name, full_path: 'name.first'
+    #     expose :age, 'cars', type: :integer
+    #
+    #     def initialize(json)
+    #       @json = json
+    #     end
+    #   end
+    #
+    #   instance = MyModel.new(
+    #     'name' => { first: 'John', last: 'Williams' },
+    #     :age => '20',
+    #     'cars' => 2.0
+    #   )
+    #
+    #   instance.first_name # returns 'John'
+    #   instance.age        # returns 20
+    #   instance.cars       # returns 2
+    #
+    # @see Builder Arstotzka::Builder
+    # @see
+    #   https://www.rubydoc.info/gems/activesupport/5.0.0.1/ActiveSupport/Concern
+    #   ActiveSupport::Concern
     def expose(*attr_names, **options)
       Builder.new(attr_names, self, options).build
     end

data/lib/arstotzka/crawler.rb

@@ -1,28 +1,103 @@
+# frozen_string_literal: true
+
 module Arstotzka
+  # Crawl a hash through the path of keys
+  # @example
+  #   crawler = Arstotzka::Crawler.new(%w(person information first_name))
+  #   hash = {
+  #     person: {
+  #       'information' => {
+  #         'firstName' => 'John'
+  #       }
+  #     }
+  #   }
+  #   crawler.value(hash) # returns 'John'
   class Crawler
-    attr_reader :post_process, :path, :case_type, :compact, :default
-
+    # @param path [Array] path of keys to be crawled
+    # @param case_type [Symbol] case type of the keys
+    #   - snake: snake_cased keys
+    #   - lower_camel: lowerCamelCased keys
+    #   - upper_camel: UperCamelCased keys
+    # @param compact [Boolean] flag signallying if nil values should be removed of an array
+    # @param default [Object] default value to be returned when failing to fetch a value
+    # @param block [Proc] block to be ran over the fetched value before returning it
     def initialize(path:, case_type: :lower_camel, compact: false, default: nil, &block)
       @case_type = case_type
       @compact = compact
       @default = default
       @path = path
-      @post_process = block
+      @post_process = block || proc { |value| value }
     end
 
-    def value(json, index = 0)
-      crawl(json, index)
+    # crawls into the hash looking for all keys in the given path
+    # returning the final value
+    #
+    # @overload value(hash)
+    # @return [Object] value fetched from the last Hash#fetch call using the last part
+    #   of path
+    #
+    # @example
+    #   crawler = Arstotzka::Crawler.new(%w(person information first_name))
+    #   hash = {
+    #     person: {
+    #       'information' => {
+    #         'firstName' => 'John'
+    #       }
+    #     }
+    #   }
+    #   crawler.value(hash) # returns 'John'
+    #
+    # @example
+    #   crawler = Arstotzka::Crawler.new(
+    #     %w(companies games hero),
+    #     compact: true, case_type: :snake
+    #   )
+    #   games_hash = {
+    #     'companies' => [{
+    #       name: 'Lucas Pope',
+    #       games: [{
+    #         'name' => 'papers, please'
+    #       }, {
+    #         'name' => 'TheNextBigThing',
+    #         hero_name: 'Rakhar'
+    #       }]
+    #     }, {
+    #       name: 'Old Company'
+    #     }]
+    #   }
+    #
+    #   crawler.value(games_hash) # returns [['Rakhar']]
+    #
+    # @example
+    #   crawler = Arstotzka::Crawler.new(
+    #     %w(companies games hero),
+    #     compact: true, case_type: :snake, default: 'NO HERO'
+    #   )
+    #
+    #   crawler.value(games_hash) # returns [['NO HERO', 'Rakhar'], 'NO HERO']
+    #
+    # @example
+    #   crawler = Arstotzka::Crawler.new(
+    #     %w(companies games hero),
+    #     compact: true, case_type: :snake
+    #   ) { |value| value.&to_sym }
+    #
+    #   crawler.value(games_hash) # returns [[:Rakhar]]
+    def value(hash, index = 0)
+      crawl(hash, index)
     rescue Exception::KeyNotFound
       wrap(default)
     end
 
     private
 
-    def crawl(json, index = 0)
-      return wrap(json) if reader.is_ended?(index)
-      return crawl_array(json, index) if json.is_a?(Array)
+    attr_reader :post_process, :path, :case_type, :compact, :default
+
+    def crawl(hash, index = 0)
+      return wrap(hash) if reader.ended?(index)
+      return crawl_array(hash, index) if hash.is_a?(Array)
 
-      crawl(reader.read(json, index), index + 1)
+      crawl(reader.read(hash, index), index + 1)
     end
 
     def reader
@@ -32,8 +107,8 @@ module Arstotzka
       )
     end
 
-    def wrap(json)
-      post_process.call(json)
+    def wrap(hash)
+      post_process.call(hash)
     end
 
     def crawl_array(array, index)