check_please 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c16110449be99d5ff509c720c4365b2fe6f176f23094784628db2de0e5f3bf9
-  data.tar.gz: b45c9d1b7dea9b4405f4ca80dbce5f04d0aec14ad50e4e919802e09b469c86c8
+  metadata.gz: 889dea37051513ced2de5a716db086a1ad1793af6e095704be6cc39a0fc64822
+  data.tar.gz: 2a21aeeb5a686b46a4657dd2d50163b07e0e6e2f1effb8fdbe652bbc835f5c02
 SHA512:
-  metadata.gz: 023b9fdd6f227f8381dfba06a82d30961adab9b2ab5a2b5a0d820c8b8697d300f59d416c801808e88e7e625720776f1cec4cf0a6f57d1eec07e6cb656881d4b8
-  data.tar.gz: eca955971798d00dd45bf5e068779aebeb33b304fe592d84534081d0068eaa981f6b765fd5c4ea9a30e7d65b2edd456ed9093c039964e3691c646e0c7d23b2b0
+  metadata.gz: 72b705dc899a841fadce3a9d67c538012d83d7e9fce7e69d8b7da4d6795eb84ac6eb4c8feedc8f721b07c0894c4a87079584081350ade4a3a184aa7ba7fad0d2
+  data.tar.gz: c13e453a1032c1ad9b57e7e20c272851044dce1c80ca63bde5b173e05f547b2f43c39c3910cd1decebbe4da28eb2e71ba2fbeb4c23f145c40176bf3391292431

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    check_please (0.2.0)
+    check_please (0.3.0)
       table_print
 
 GEM

data/README.md

@@ -1,6 +1,7 @@
 # check_please
 
-Check for differences between two JSON strings (or Ruby data structures parsed from them).
+Check for differences between two JSON documents, YAML documents, or Ruby data
+structures parsed from either of those.
 
 ## Installation
 
@@ -18,11 +19,10 @@ Or install it yourself as:
 
     $ gem install check_please
 
-## Usage
-
-### Terminology
+## Terminology
 
-CheckPlease uses a few words in a jargony way:
+I know, you just want to see how to use this thing.  Feel free to scroll down,
+but be aware that CheckPlease uses a few words in a jargony way:
 
 * **Reference** is always used to refer to the "target" or "source of truth."
   We assume you're comparing two things because you want one of them to be like
@@ -35,7 +35,9 @@ CheckPlease uses a few words in a jargony way:
   **reference** and the **candidate**.  More on this in "Understanding the Output",
   below.
 
-### CLI
+## Usage
+
+### From the Terminal
 
 Use the `bin/check_please` executable.  (To get started, run it with the '-h' flag.)
 
@@ -46,19 +48,16 @@ of giving it a second filename as the argument.  (This is especially useful if
 you're copying an XHR response out of a web browser's dev tools and have a tool
 like MacOS's `pbpaste` utility.)
 
-### RSpec Matcher
+### From RSpec
 
 See [check_please_rspec_matcher](https://github.com/RealGeeks/check_please_rspec_matcher).
 
-### From Within Ruby
-
-Create two JSON strings and pass them to `CheckPlease.render_diff`.  You'll get
-back a third string containing a nicely formatted report of all the differences
-CheckPlease found in the two JSON strings.  (See also:  [./usage_examples.rb](usage_examples.rb).)
+### From Ruby
 
-(You can also parse the JSON strings yourself and pass the resulting data
-structures in, if you're into that.  I mean, I wrote this to help compare JSON
-data that's too big and complicated to scan through visually, but you do you!
+Create two strings, each containing a JSON or YAML document, and pass them to
+`CheckPlease.render_diff`.  You'll get back a third string containing a report
+of all the differences CheckPlease found in the two JSON strings.  (See also:
+[./usage_examples.rb](usage_examples.rb).)
 
 ### Understanding the Output
 
@@ -70,9 +69,7 @@ tool because you want a human-friendly summary of all the places that your
 **candidate** fell short.
 
 When CheckPlease compares your two samples, it generates a list of diffs to
-describe any discrepancies it encounters.  (By default, it prints that list in a
-tabular format, but if you want to incorporate this into another toolchain,
-CheckPlease can also print these diffs as JSON to facilitate parsing.)
+describe any discrepancies it encounters.
 
 An example would probably help here.
 
@@ -124,23 +121,22 @@ CheckPlease defines:
 * **type_mismatch** means that both the **reference** and the **candidate** had
   a value at the given path, but one value was an Array or a Hash and the other
   was not.  **When CheckPlease encounters a type mismatch, it does not compare
-  anything "below" the given path.** producing a lot of "garbage" diffs.
-  _(Technical note:  CheckPlease uses a "recursive descent" strategy to
-  traverse the **reference** data structure, and it stops when it encounters a
-  type mismatch in order to avoid producing a lot of "garbage" diff output.
-  Also, the way these get displayed is likely to change.)_
+  anything "below" the given path.**  _(Technical note:  CheckPlease uses a
+  "recursive descent" strategy to traverse the **reference** data structure,
+  and it stops when it encounters a type mismatch in order to avoid producing a
+  lot of "garbage" diff output.)_
 * **mismatch** means that both the **reference** and the **candidate** had a
   value at the given path, and neither value was an Array or a Hash.
-* "**extra**" means that, inside an Array or a Hash, the **candidate**
-  contained values that were not found in the **reference**.
-* "**missing**" is the opposite of **extra**:  inside an Array or a Hash, the
+* **extra** means that, inside an Array or a Hash, the **candidate** contained
+  values that were not found in the **reference**.
+* **missing** is the opposite of **extra**:  inside an Array or a Hash, the
   **reference** contained values that were not found in the **candidate**.
 
 #### Paths
 
-The second column contains a path expression.  This is extremely basic:
+The second column contains a path expression.  This is extremely lo-fi:
 
-* The first element in the data structure is defined as "/".
+* The root of the data structure is defined as "/".
 * If an element in the data structure is an array, its child elements will have
   a **one-based** index appended to their parent's path.
 * If an element in the data structure is an object ("Hash" in Ruby), the key
@@ -163,10 +159,7 @@ print diffs as JSON to facilitate parsing.  In Ruby, pass `format: :json` to
 ## TODO
 
 * command line flags for :allthethings:!
-  * --fail-fast
-  * limit to first N
   * sort by path?
-  * max depth (for iterative refinement?)
 * detect timestamps and compare after parsing?
   * ignore sub-second precision (option / CLI flag)?
   * possibly support plugins for other folks to add custom coercions?

data/Rakefile

@@ -1,6 +1,21 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+namespace :spec do
+  RSpec::Core::RakeTask.new(:all)
+
+  RSpec::Core::RakeTask.new(:not_cli) do |t|
+    t.rspec_opts = "--tag ~cli"
+  end
+  task fast: :not_cli
+
+  # These are much slower than the rest, since they use Kernel#`
+  RSpec::Core::RakeTask.new(:cli) do |t|
+    t.rspec_opts = "--tag cli"
+  end
+end
+
+# By default, `rake spec` should run fast specs first, then cli if those all pass
+task :spec => [ "spec:not_cli", "spec:cli" ]
 
 task :default => :spec

data/{bin → exe}/check_please

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
 
-require_relative '../lib/check_please'
+require 'check_please'
 CheckPlease::CLI.run(__FILE__)

data/lib/check_please.rb

@@ -7,17 +7,20 @@ require_relative "check_please/diffs"
 require_relative "check_please/printers"
 require_relative "check_please/cli"
 
+require 'yaml'
+require 'json'
+
 module CheckPlease
   ELEVATOR_PITCH = "Tool for parsing and diffing two JSON documents."
 
-  def self.diff(reference, candidate)
+  def self.diff(reference, candidate, options = {})
     reference = maybe_parse(reference)
     candidate = maybe_parse(candidate)
-    Comparison.perform(reference, candidate)
+    Comparison.perform(reference, candidate, options)
   end
 
   def self.render_diff(reference, candidate, options = {})
-    diffs = diff(reference, candidate)
+    diffs = diff(reference, candidate, options)
     Printers.render(diffs, options)
   end
 
@@ -25,16 +28,17 @@ module CheckPlease
     private
 
     # Maybe you gave us JSON strings, maybe you gave us Ruby objects.
-    # We just don't know!  That's what makes it so exciting!
-    def maybe_parse(maybe_json)
+    # Heck, maybe you even gave us some YAML!  We just don't know!
+    # That's what makes it so exciting!
+    def maybe_parse(document)
 
-      case maybe_json
-      when String ; JSON.parse(maybe_json) # don't worry, if this raises we'll assume you've already parsed it
-      else        ; maybe_json
+      case document
+      when String ; return YAML.load(document) # don't worry, if this raises we'll assume you've already parsed it
+      else        ; return document
       end
 
-    rescue JSON::ParserError
-      return maybe_json
+    rescue JSON::ParserError, Psych::SyntaxError
+      return document
     end
   end
 end

data/lib/check_please/cli.rb

@@ -13,17 +13,33 @@ module CheckPlease
 
 
     FLAGS = []
-    def self.flag(*args, &block)
-      flag = Flag.new(*args, &block)
+    def self.flag(long:, short: nil, &block)
+      flag = Flag.new(short, long, &block)
       FLAGS << flag
     end
 
     ##### Define CLI flags here #####
 
-    flag "-f FORMAT", "--format FORMAT" do |f|
+    flag short: "-f FORMAT", long: "--format FORMAT" do |f|
       f.desc = "format in which to present diffs (available options: [#{CheckPlease::Printers::FORMATS.join(", ")}])"
       f.set_key :format, :to_sym
     end
+
+    flag short: "-n MAX_DIFFS", long: "--max-diffs MAX_DIFFS" do |f|
+      f.desc = "Stop after encountering a specified number of diffs"
+      f.set_key :max_diffs, :to_i
+    end
+
+    flag long: "--fail-fast" do |f|
+      f.desc = "Stop after encountering the very first diff"
+      f.set_key(:max_diffs) { 1 }
+    end
+
+    flag short: "-d MAX_DEPTH", long: "--max-depth MAX_DEPTH" do |f|
+      f.desc = "Limit the number of levels to descend when comparing documents (NOTE: root has depth=1)"
+      f.set_key :max_depth, :to_i
+    end
+
   end
 
 end

data/lib/check_please/cli/flag.rb

@@ -12,6 +12,7 @@ module CLI
       yield self if block_given?
 
       missing = ATTR_NAMES.select { |e| self.send(e).nil? }
+      missing -= %i[ short ] # short is optional!
       if missing.any?
         raise ArgumentError, "Missing attributes: #{missing.join(', ')}"
       end

data/lib/check_please/comparison.rb

@@ -3,16 +3,22 @@ module CheckPlease
   module Comparison
     extend self
 
-    def perform(reference, candidate)
+    def perform(reference, candidate, options = {})
       root = CheckPlease::Path.new
-      diffs = Diffs.new
-      compare reference, candidate, root, diffs
+      diffs = Diffs.new(options: options)
+      catch(:max_diffs_reached) do
+        compare reference, candidate, root, diffs
+      end
       diffs
     end
 
     private
 
     def compare(ref, can, path, diffs)
+      if (d = diffs.options[:max_depth])
+        return if path.depth > d + 1
+      end
+
       case types(ref, can)
       when [ :array, :array ] ; compare_arrays ref, can, path, diffs
       when [ :hash,  :hash  ] ; compare_hashes ref, can, path, diffs

data/lib/check_please/diff.rb

@@ -11,14 +11,6 @@ module CheckPlease
       @path      = path.to_s
     end
 
-    def ref_display
-      reference.inspect
-    end
-
-    def can_display
-      candidate.inspect
-    end
-
     def attributes
       Hash[ COLUMNS.map { |name| [ name, send(name) ] } ]
     end
@@ -28,8 +20,8 @@ module CheckPlease
       s << self.class.name
       s << " type=#{type}"
       s << " path=#{path}"
-      s << " ref=#{ref_display}"
-      s << " can=#{can_display}"
+      s << " ref=#{reference.inspect}"
+      s << " can=#{candidate.inspect}"
       s << ">"
       s
     end

data/lib/check_please/diffs.rb

@@ -5,7 +5,9 @@ module CheckPlease
   # Custom collection class for Diff instances.
   # Can retrieve members using indexes or paths.
   class Diffs
-    def initialize(diff_list = nil)
+    attr_reader :options
+    def initialize(diff_list = nil, options: {})
+      @options = options
       @list = []
       @hash = {}
       Array(diff_list).each do |diff|
@@ -27,6 +29,11 @@ module CheckPlease
     end
 
     def <<(diff)
+      if (n = options[:max_diffs])
+        # It seems no one can help me now / I'm in too deep, there's no way out
+        throw :max_diffs_reached if length >= n
+      end
+
       @list << diff
       @hash[diff.path] = diff
     end

data/lib/check_please/path.rb

@@ -11,6 +11,10 @@ module CheckPlease
       self.class.new( Array(@segments) + Array(new_basename.to_s) )
     end
 
+    def depth
+      1 + @segments.length
+    end
+
     def to_s
       SEPARATOR + @segments.join(SEPARATOR)
     end

data/lib/check_please/printers/json.rb

@@ -1,5 +1,3 @@
-require 'json'
-
 module CheckPlease
 module Printers
 

data/lib/check_please/printers/table_print.rb

@@ -4,21 +4,30 @@ module CheckPlease
 module Printers
 
   class TablePrint < Base
+    InspectStrings = Object.new.tap do |obj|
+      def obj.format(value)
+        value.is_a?(String) ? value.inspect : value
+      end
+    end
+
+    PATH_MAX_WIDTH = 250 # if you hit this limit, you have other problems
+
     TP_OPTS = [
-      :type,
-      { :path => { width: 250 } }, # if you hit this limit, you have other problems
-      :reference,
-      :candidate,
+      { type:      { display_name: "Type" } },
+      { path:      { display_name: "Path",      width: PATH_MAX_WIDTH } },
+      { reference: { display_name: "Reference", formatters: [ InspectStrings ] } },
+      { candidate: { display_name: "Candidate", formatters: [ InspectStrings ] } },
     ]
 
     def to_s
       return "" if diffs.empty?
 
-      build_string do |io|
+      out = build_string do |io|
         switch_tableprint_io(io) do
           tp diffs.data, *TP_OPTS
         end
       end
+      strip_trailing_whitespace(out)
     end
 
     private
@@ -31,6 +40,10 @@ module Printers
     ensure
       config.io = @old_io
     end
+
+    def strip_trailing_whitespace(s)
+      s.lines.map(&:rstrip).join("\n")
+    end
   end
 
 end

data/lib/check_please/version.rb

@@ -1,5 +1,5 @@
 module CheckPlease
   # NOTE: 'check_please_rspec_matcher' depends on this,
   #       so try to keep them roughly in sync
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: check_please
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Sam Livingston-Gray
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-13 00:00:00.000000000 Z
+date: 2020-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: table_print
@@ -56,7 +56,8 @@ description: Check for differences between two JSON strings (or Ruby data struct
   parsed from them)
 email:
 - geeksam@gmail.com
-executables: []
+executables:
+- check_please
 extensions: []
 extra_rdoc_files: []
 files:
@@ -69,10 +70,10 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- bin/check_please
 - bin/console
 - bin/setup
 - check_please.gemspec
+- exe/check_please
 - lib/check_please.rb
 - lib/check_please/cli.rb
 - lib/check_please/cli/flag.rb