qig 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f7c37c8a295eb210423179f2f0e7770dade31d4ceaabde0c1332b34e11ab443
-  data.tar.gz: 8cfc282e7cbc383686f132030b4f07adbce7738475d7bfd3b88b04f221d1f371
+  metadata.gz: 56ef9b278c456d21a26c5aa5c4af9c3fd44ac5c5b8ebc6f680d528c2380e1af3
+  data.tar.gz: c5bee04e6937170225b362ae777a7456c488b85afec37695fd5167530d0eaa13
 SHA512:
-  metadata.gz: b8c7bf8e33ecc7f57e9fa3f7760c4c89ebd7150bc446d32ef3062b415be2db4a7df198595c8cd8c54655fe62a745092294227e905fb4efad4f477ad5c0c37631
-  data.tar.gz: dbeb18f978e6db504841031529e138d958583a3d683abb1c15b0fce0f597ee7e1bc7ef7e22aa0b05e9368bba45c229b84b01825984fddc791180fb62ad383e8b
+  metadata.gz: f01814583296ea94b8839b6fb057b27880c92dc23870d533c192d1ed36a34a6d9650a58390f1c5e85cc2a6d92ed3356678f7bb069419015416087df208890d19
+  data.tar.gz: c4b2a0d910a66ba27e2b6f24963e015b404759c092f1915126d3c7aebccdf50205d6ab96e6ee480ef20709e361e475bf27b9702f0918b7fded24762e12766526

data/.rubocop.yml

@@ -1,5 +1,12 @@
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 2.7
+  NewCops: enable
 
 Layout/LineLength:
   Max: 120
+
+Metrics/BlockLength:
+  IgnoredMethods: ['describe', 'context']
+
+Style/DocumentationMethod:
+  Enabled: true

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/CHANGELOG.md

@@ -1,3 +1,64 @@
+# 0.4.0 (Jan 27, 2022)
+
+## Features
+
+- `Qig::Qiggable` mixin for adding chainable `.qig` syntax to subject classes.
+- Allow stepping into enumerables.
+
+## Fixes
+
+- make unboxing (`[]`) compatible with `Enumerable`. Previously in collection-context this used `flatten(1)`, which
+  `Enumerable` does not support. Now uses `flat_map(&:itself)` instead
+
+## Documentation
+
+- Literate spec covering compatibility with lazy enumerators.
+
+# 0.3.0 (January 24, 2022)
+
+## BREAKING CHANGES
+
+- drop ruby 2.6 support, because Ruby 2.6 will be EOL in 2 months, and Ruby 2.7 pattern matching syntax makes
+  command parsing cases *much* easier to maintain, keeping the main switching logic a single-level `case`
+
+## Features
+
+- method invocation syntax (e.g. for filtering)
+- quoting syntax to use operators as literal keys
+- reboxing operator or value collection operator, inverse of the value iteration operator
+
+## Documentation
+
+- Reorganize and explain literate specs
+- Specs for dig conformance
+
+## Fixes
+
+- On invalid access to struct, return nil, for better conformance to Struct#dig. Previously this raised error.
+
+# 0.2.0 (January 14, 2022)
+
+## Features
+
+- Value iteration(`[]` over hashes)
+
+## Documentation
+
+- Initial yard documentation on method and module
+- Document and spec that we can qig into Structs and OpenStructs
+
+# 0.1.3 (January 13, 2022)
+
+## Documentation
+
+- fix changelog uri (again)
+
+# 0.1.2 (January 13, 2022)
+
+## Documentation
+
+- fix changelog uri
+
 # 0.1.1 (January 13, 2022)
 
 ## Documentation
@@ -10,4 +71,4 @@
 ## Features
 
 - Ability to qig into arrays and hashes
-- Value iteration (`[]`) over arrays
+- Value iteration (`[]`) over arrays

data/Gemfile

@@ -5,10 +5,11 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in qig.gemspec
 gemspec
 
+gem 'pry', '~> 0.14.1'
 gem 'rake', '~> 13.0'
-
 gem 'rspec', '~> 3.0'
-
+gem 'rspec_junit_formatter', '~> 0.5.1'
 gem 'rubocop', '~> 1.21'
-
-gem "pry", "~> 0.14.1"
+gem 'rubocop-rake', '~> 0.6.0'
+gem 'rubocop-rspec', '~> 2.7'
+gem 'yard', '~> 0.9.27'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    qig (0.1.2)
+    qig (0.4.0)
 
 GEM
   remote: https://rubygems.org/
@@ -33,6 +33,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.3)
+    rspec_junit_formatter (0.5.1)
+      rspec-core (>= 2, < 4, != 2.12.0)
     rubocop (1.24.1)
       parallel (~> 1.10)
       parser (>= 3.0.0.0)
@@ -44,8 +46,15 @@ GEM
       unicode-display_width (>= 1.4.0, < 3.0)
     rubocop-ast (1.15.1)
       parser (>= 3.0.1.1)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (2.7.0)
+      rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
     unicode-display_width (2.1.0)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   x86_64-linux
@@ -55,7 +64,11 @@ DEPENDENCIES
   qig!
   rake (~> 13.0)
   rspec (~> 3.0)
+  rspec_junit_formatter (~> 0.5.1)
   rubocop (~> 1.21)
+  rubocop-rake (~> 0.6.0)
+  rubocop-rspec (~> 2.7)
+  yard (~> 0.9.27)
 
 BUNDLED WITH
    2.3.4

data/README.md

@@ -1,17 +1,39 @@
 # Qig
 
-qig is dig extended with jq's "value iterator" `[]` operator.
+[![Gem Version](https://badge.fury.io/rb/qig.svg)](https://badge.fury.io/rb/qig)
+[![CircleCI](https://circleci.com/gh/NAR8789/qig-ruby/tree/main.svg?style=shield)](https://circleci.com/gh/NAR8789/qig-ruby/tree/main)
+
+qig is dig extended with jq's "value iterator" `[]` operator and some other goodies.
+
+## Usage
+
+```ruby
+Qig.qig(subject, *path) # => contents of subject at path
+```
+
+examples:
+```ruby
+# dig-like usage
+Qig.qig({a: { b: { c: 1 } } }, :a, :b, :c) # => 1
+
+# dig-like usage augmented with jq's [] operator
+Qig.qig({a: { b: [ { c: 1 }, { c: 2 } ] } }, :a, :b, [], :c) # => [1, 2]
+
+# after expanding values, collect them back into an array for indexing into with `[[]]`
+Qig.qig({ a: { b: [{ c: 1 }, { c: 2 }] } }, :a, :b, [], :c, [[]], 1) # => 2
+```
+
+More documentation in the [literate specs](spec/literate)
 
 ## Features
 
-- [x] qig into arrays and hashes
-- [ ] qig into structs
-- [ ] qig into OpenStructs
-- [ ] qig into CSV::Tables
-- [ ] qig into CSV::Rows
-- [x] value iteration over arrays
-- [ ] value iteration over hashes
-- [ ] option to monkey patch this for more dig-like `subject.qig(*path)` syntax
+- [x] compatible with dig (see (dig conformance specs)[spec/literate/qig/02_conformance/dig_conformance_spec.rb])
+- [x] jq-like value iteration (`[]` operator)
+- [x] invoke ruby methods during inside the filter chain
+- [x] value collect: `[[]]`, inverse of the `[]` operator. Collect streamed values back into an array
+- [x] `Qig::Qiggable` mixin for more dig-like `subject.qig(*path)` syntax
+- [ ] extensive literate specs
+  - [ ] works with lazy collections
 
 ## Installation
 
@@ -29,18 +51,6 @@ Or install it yourself as:
 
     $ gem install qig
 
-## Usage
-
-```ruby
-Qig.qig(subject, *path) # => contents of subject at path
-```
-
-examples:
-```ruby
-Qig.qig({a: { b: { c: 1 } } }, :a, :b, :c) # => 1
-Qig.qig({a: { b: [ { c: 1 }, { c: 2 } ] } }, :a, :b, [], :c) # => [1, 2]
-```
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/bin/console

@@ -7,5 +7,5 @@ require 'qig'
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
-require "pry"
+require 'pry'
 Pry.start

data/lib/qig/qiggable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Qig
+  # mix-in to add a `.qig` method to any class.
+  # NOTE: Target class should support `#[]`, `#map`, and either `#flat_map` or `#values` for full qig functionality
+  # - `#[]`: used for stepping in unit context
+  # - `#map`: used for stepping in collection context
+  # - `#flat_map` or `#values`: used for unboxing in collection context
+  module Qiggable
+    # @param path [Array<String, Symbol, Array, Object>] retrieval path to apply to `subject`
+    #
+    # @return [Object, Array<Object>] the value(s) of `self` located at `path`
+    def qig(*path)
+      Qig.qig(self, *path)
+    end
+
+    # see Enumerable#lazy
+    #
+    # This version extends the underlying lazy enumerable with Qig::Qiggable
+    def lazy
+      super.extend(Qig::Qiggable)
+    end
+  end
+end

data/lib/qig/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Qig
-  VERSION = '0.1.2'
+  VERSION = '0.4.0'
 end

data/lib/qig.rb

@@ -2,39 +2,100 @@
 
 require_relative 'qig/version'
 
+# Combining the powers of `dig` and `jq`.
+# Qig is dig extended with jq's value iteration `[]` operator.
 module Qig
-  def self.qig(*args)
-    unit_qig(*args)
-  end
+  autoload :Qiggable, 'qig/qiggable.rb'
 
-  def self.unit_qig(subject, *path)
-    return subject if subject.nil?
-
-    head, *rest = path
-    case head
-    when nil
-      subject
-    when []
-      collection_qig(subject, *rest)
-      # hmm... what should happen if I [] on something not an array?
-    else
-      unit_qig(subject[head], *rest)
+  class << self
+    # @param subject [Array, Hash, #[]] `subject` to be qug into.
+    # @param path [Array<String, Symbol, Array, Object>] retrieval path to apply to `subject`
+    #
+    # @return [Object, Array<Object>] the value(s) of `subject` located at `path`
+    def qig(subject, *path)
+      unit_qig(subject, *path)
+    end
+
+    # "values" as in jq's "value iterator".
+    #
+    # Coerce to array by taking the .values. Intuitively, get all possible values of `arrayish[x]`.
+    #
+    # @param arrayish [Array, Hash, #values, Object] array or hash or other to coerce to values
+    # @return [Array, Array, Array, Object] array of coerced values
+    def values(arrayish)
+      arrayish.respond_to?(:values) ? arrayish.values : arrayish
+    end
+
+    private
+
+    def unit_qig(subject, *path) # rubocop:disable Metrics/MethodLength
+      head, *rest = path
+      case head
+      in nil
+        subject
+      in []
+        collection_qig(values(subject), *rest)
+      in [[]]
+        unit_qig([subject], *rest)
+      in ['', key]
+        unit_qig(step(subject, key), *rest)
+      in [[method, [*args], block]]
+        unit_qig(subject.public_send(method, *args, &block), *rest)
+      in [[method, [*args]]]
+        unit_qig(subject.public_send(method, *args), *rest)
+      in [[method]]
+        unit_qig(subject.public_send(method), *rest)
+      in [method, *]
+        raise ArgumentError, 'stream method invocation not applicable in unit context'
+      else
+        unit_qig(step(subject, head), *rest)
+      end
+    end
+
+    def collection_qig(subjects, *path) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity
+      head, *rest = path
+      case head
+      in nil
+        subjects
+      in []
+        collection_qig(subjects.map(&method(:values)).flat_map(&:itself), *rest)
+      in [[]]
+        unit_qig(subjects, *rest)
+      in ['', key]
+        collection_qig(subjects.map { |s| step(s, key) }, *rest)
+      in [[method, [*args], block]]
+        collection_qig(subjects.map { |s| s.public_send(method, *args, &block) }, *rest)
+      in [[method, [*args]]]
+        collection_qig(subjects.map { |s| s.public_send(method, *args) }, *rest)
+      in [[method]]
+        collection_qig(subjects.map { |s| s.public_send(method) }, *rest)
+      in [method, [*args], block]
+        collection_qig(subjects.public_send(method, *args, &block), *rest)
+      in [method, [*args]]
+        collection_qig(subjects.public_send(method, *args), *rest)
+      in [method]
+        collection_qig(subjects.public_send(method), *rest)
+      else
+        collection_qig(subjects.map { |s| step(s, head) }, *rest)
+      end
     end
-  end
 
-  def self.collection_qig(subjects, *path)
-    return subjects if subjects.empty?
-
-    head, *rest = path
-    case head
-    when nil
-      subjects
-    when []
-      collection_qig(subjects.flatten(1), *rest)
-      # not sure this is quite jq-compliant... [] refuses to iterate over atoms, but flatten will just preserve them.
-      # maybe more in the spirit of `dig` though?
-    else
-      collection_qig(subjects.map { |e| e.nil? ? e : e[head] }, *rest)
+    def step(subject, key)
+      case subject
+      in Enumerable unless subject.respond_to?(:[])
+        case key
+        in Integer
+          subject.drop(key).first
+        in Range
+          subject.drop(key.begin).take(key.count)
+        end
+      else
+        subject&.[](key)
+      end
+    rescue NameError, IndexError
+      # Struct's [] is strict and raises on missing key.
+      # TODO: more efficient / prettier way of doing this. How does struct itself implement dig?
+      nil
     end
   end
 end

data/qig.gemspec

@@ -12,11 +12,11 @@ Gem::Specification.new do |spec|
   # spec.description = "TODO: Write a longer description or delete this line."
   spec.homepage = 'https://github.com/NAR8789/qig-ruby'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 2.6.0'
+  spec.required_ruby_version = '>= 2.7.0'
 
   spec.metadata['homepage_uri'] = spec.homepage
   spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata['changelog_uri'] = "#{spec.homepage}/CHANGELOG.md"
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -34,4 +34,5 @@ Gem::Specification.new do |spec|
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qig
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Xiao Fan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-01-13 00:00:00.000000000 Z
+date: 2022-01-27 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -29,6 +30,7 @@ files:
 - bin/console
 - bin/setup
 - lib/qig.rb
+- lib/qig/qiggable.rb
 - lib/qig/version.rb
 - qig.gemspec
 - sig/qig.rbs
@@ -38,7 +40,8 @@ licenses:
 metadata:
   homepage_uri: https://github.com/NAR8789/qig-ruby
   source_code_uri: https://github.com/NAR8789/qig-ruby
-  changelog_uri: https://github.com/NAR8789/qig-ruby/CHANGELOG.md
+  changelog_uri: https://github.com/NAR8789/qig-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -47,7 +50,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="