check_please 0.2.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b880759afe4d4cfa6b3fda2332fdea92be7a141a2faa4ce24ed1f5952a395953
-  data.tar.gz: 580bb6e7de516510534d315f4d2a0effb539f4e195bb58a30a4f345912591523
+  metadata.gz: 41ad78ce4324c1b5d9c8ac3e336d46108850d6fd7d1d51d30c13b807632d612a
+  data.tar.gz: 9191e6e52c57b6d79761a8a0258a41378cf19af1364a3e8875e727ff8e501f06
 SHA512:
-  metadata.gz: 2c23315e2c734b3d8234c2a8f05c3d7f3626b0d53b255c182f68de20a60df7f28c124260aedb59f015560fc625f4301c48ec29bdf3b772f495c34c6181e114d6
-  data.tar.gz: 973adce53f7fd590bbd478e8727f3f409def0caed3815b049af9613427a866d761426fcd84c481798e73d7da3abd9c9d77a8bc726171f3030ac7d87b481ddb12
+  metadata.gz: 388b93c0277580a37b066b7fa6aade4f8feeb5f677a4ccc2221ac060d23df153c3dc16c6cdacce740448773665200855e653d74f55cfae659511e39a4391b36f
+  data.tar.gz: 44cb45ace2a720d90035eef279f490896a785e76c77bd4bd72c63400a828300332638442599b905dad8e4bde4b329a698fd44f4116f847699b5250c586e27c86

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    check_please (0.2.2)
+    check_please (0.4.1)
       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,26 @@ 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
+If you'd like more control over the output formatting, and especially if you'd
+like to provide custom logic for diffing your own classes, you might be better
+served by the [super_diff](https://github.com/mcmire/super_diff) gem.  Check it
+out!
 
-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!
+See also: [./usage_examples.rb](usage_examples.rb).
+
+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.
+
+Or, if you'd like to inspect the diffs in your own way, use `CheckPlease.diff`
+instead.  You'll get back a `CheckPlease::Diffs` custom collection that
+contains `CheckPlease::Diff` instances.
 
 ### Understanding the Output
 
@@ -70,9 +79,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 +131,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**.
+* **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
@@ -160,22 +166,28 @@ If you want to incorporate CheckPlease into some other toolchain, it can also
 print diffs as JSON to facilitate parsing.  In Ruby, pass `format: :json` to
 `CheckPlease.render_diff`; in the CLI, use the `-f`/`--format` switch.
 
-## TODO
+## TODO (maybe)
 
 * command line flags for :allthethings:!
   * 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?
-* support expressions of specific paths to ignore
-  * wildcards?  `#` for indexes, `**` to match one or more path segments?
-    (This could get ugly fast.)
 * display filters?  (e.g., { a: 1, b: 2 } ==> "Hash#3")
   * shorter descriptions of values with different classes
     (but maybe just the existing :type_mismatch diffs?)
   * another "possibly support plugins" expansion point here
 * more output formats, maybe?
+* [0xABAD1DEA] support wildcards in --select-paths and --reject-paths?
+  * `#` for indexes, `**` to match one or more path segments?
+    (This could get ugly fast.)
+* [0xABAD1DEA] look for a config file in ./.check_please_config or ~/.check_please_config,
+  combine flags found there with those in ARGV in order of precedence:
+  1) ARGV
+  2) ./.check_please
+  3) ~/.check_please
+  * but this may not actually be worth the time and complexity to implement, so
+    think about this first...
 
 ## Development
 

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

@@ -1,40 +1,130 @@
-require_relative "check_please/version"
-require_relative "check_please/error"
-require_relative "check_please/path"
-require_relative "check_please/comparison"
-require_relative "check_please/diff"
-require_relative "check_please/diffs"
-require_relative "check_please/printers"
-require_relative "check_please/cli"
+require 'yaml'
+require 'json'
+
+
+# easier to just require these
+require "check_please/error"
+require "check_please/version"
+
+module CheckPlease
+  autoload :CLI,         "check_please/cli"
+  autoload :Comparison,  "check_please/comparison"
+  autoload :Diff,        "check_please/diff"
+  autoload :Diffs,       "check_please/diffs"
+  autoload :Flag,        "check_please/flag"
+  autoload :Flags,       "check_please/flags"
+  autoload :Path,        "check_please/path"
+  autoload :Printers,    "check_please/printers"
+  autoload :Refinements, "check_please/refinements"
+end
+
+
 
 module CheckPlease
   ELEVATOR_PITCH = "Tool for parsing and diffing two JSON documents."
 
-  def self.diff(reference, candidate, options = {})
+  def self.diff(reference, candidate, flags = {})
     reference = maybe_parse(reference)
     candidate = maybe_parse(candidate)
-    Comparison.perform(reference, candidate, options)
+    Comparison.perform(reference, candidate, flags)
   end
 
-  def self.render_diff(reference, candidate, options = {})
-    diffs = diff(reference, candidate, options)
-    Printers.render(diffs, options)
+  def self.render_diff(reference, candidate, flags = {})
+    diffs = diff(reference, candidate, flags)
+    Printers.render(diffs, flags)
   end
 
   class << self
     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
+
+
+
+  Flags.define :format do |flag|
+    allowed_values = CheckPlease::Printers::FORMATS.sort
+
+    flag.coerce &:to_sym
+    flag.default = CheckPlease::Printers::DEFAULT_FORMAT
+    flag.validate { |flags, value| allowed_values.include?(value) }
+
+    flag.cli_long = "--format FORMAT"
+    flag.cli_short = "-f FORMAT"
+    flag.description = [
+      "Format in which to present diffs.",
+      "  (Allowed values: [#{allowed_values.join(", ")}])",
+    ]
+  end
+
+  Flags.define :max_diffs do |flag|
+    flag.coerce &:to_i
+    flag.validate { |flags, value| value.to_i > 0 }
+
+    flag.cli_long = "--max-diffs MAX_DIFFS"
+    flag.cli_short = "-n MAX_DIFFS"
+    flag.description = "Stop after encountering a specified number of diffs."
+  end
+
+  Flags.define :fail_fast do |flag|
+    flag.default = false
+    flag.coerce { |value| !!value }
+
+    flag.cli_long = "--fail-fast"
+    flag.description = [
+      "Stop after encountering the first diff.",
+      "  (equivalent to '--max-diffs 1')",
+    ]
+  end
+
+  Flags.define :max_depth do |flag|
+    flag.coerce &:to_i
+    flag.validate { |flags, value| value.to_i > 0 }
+
+    flag.cli_long = "--max_depth MAX_DEPTH"
+    flag.cli_short = "-d MAX_DEPTH"
+    flag.description = [
+      "Limit the number of levels to descend when comparing documents.",
+      "  (NOTE: root has depth = 1)",
+    ]
+  end
+
+  Flags.define :select_paths do |flag|
+    flag.reentrant
+    flag.mutually_exclusive_to :reject_paths
+
+    flag.cli_short = "-s PATH_EXPR"
+    flag.cli_long = "--select-paths PATH_EXPR"
+    flag.description = [
+      "ONLY record diffs matching the provided PATH expression.",
+      "  May be repeated; values will be treated as an 'OR' list.",
+      "  Can't be combined with --reject-paths.",
+    ]
+  end
+
+  Flags.define :reject_paths do |flag|
+    flag.reentrant
+    flag.mutually_exclusive_to :select_paths
+
+    flag.cli_short = "-r PATH_EXPR"
+    flag.cli_long = "--reject-paths PATH_EXPR"
+    flag.description = [
+      "DON'T record diffs matching the provided PATH expression.",
+      "  May be repeated; values will be treated as an 'OR' list.",
+      "  Can't be combined with --select-paths.",
+    ]
+  end
+
 end

data/lib/check_please/cli.rb

@@ -1,45 +1,12 @@
-require_relative 'cli/flag'
-# require_relative 'cli/flags'
-require_relative 'cli/parser'
-require_relative 'cli/runner'
-
 module CheckPlease
 
   module CLI
-    def self.run(exe_file_name)
-      Runner.new(__FILE__).run(*ARGV.dup)
-    end
-
-
-
-    FLAGS = []
-    def self.flag(long:, short: nil, &block)
-      flag = Flag.new(short, long, &block)
-      FLAGS << flag
-    end
-
-    ##### Define CLI flags here #####
+    autoload :Runner, "check_please/cli/parser"
+    autoload :Parser, "check_please/cli/runner"
 
-    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
+    def self.run(exe_file_name)
+      Runner.new(exe_file_name).run(*ARGV.dup)
     end
-
   end
 
 end

data/lib/check_please/cli/parser.rb

@@ -4,36 +4,41 @@ module CheckPlease
 module CLI
 
   class Parser
-    class UnrecognizedOption < StandardError
-      include CheckPlease::Error
-    end
-
     def initialize(exe_file_name)
-      @exe_file_name = exe_file_name
-      @optparse = OptionParser.new
-      @optparse.banner = banner
-
-      @options = {} # yuck
-      CheckPlease::CLI::FLAGS.each do |flag|
-        flag.visit_option_parser(@optparse, @options)
-      end
+      @exe_file_name = File.basename(exe_file_name)
     end
 
-    # Unfortunately, OptionParser *really* wants to use closures.
-    # I haven't yet figured out how to get around this...
-    def consume_flags!(args)
-      @optparse.parse!(args) # removes recognized flags from `args`
-      return @options
+    # Unfortunately, OptionParser *really* wants to use closures.  I haven't
+    # yet figured out how to get around this, but at least it's closing on a
+    # local instead of an ivar... progress?
+    def flags_from_args!(args)
+      flags = Flags.new
+      optparse = option_parser(flags: flags)
+      optparse.parse!(args) # removes recognized flags from `args`
+      return flags
     rescue OptionParser::InvalidOption, OptionParser::AmbiguousOption => e
-      raise UnrecognizedOption, e.message, cause: e
+      raise InvalidFlag, e.message, cause: e
     end
 
     def help
-      @optparse.help
+      option_parser.help
     end
 
     private
 
+    # NOTE: if flags is nil, you'll get something that can print help, but will explode when sent :parse
+    def option_parser(flags: nil)
+      OptionParser.new.tap do |optparse|
+        optparse.banner = banner
+        CheckPlease::Flags.each_flag do |flag|
+          args = [ flag.cli_short, flag.cli_long, flag.description ].flatten.compact
+          optparse.on(*args) do |value|
+            flags.send "#{flag.name}=", value
+          end
+        end
+      end
+    end
+
     def banner
       <<~EOF
         Usage: #{@exe_file_name} <reference> <candidate> [FLAGS]

data/lib/check_please/cli/runner.rb

@@ -14,8 +14,8 @@ module CLI
       print_help_and_exit if args.empty?
 
       begin
-        options = @parser.consume_flags!(args)
-      rescue Parser::UnrecognizedOption => e
+        flags = @parser.flags_from_args!(args)
+      rescue InvalidFlag => e
         print_help_and_exit e.message
       end
 
@@ -31,7 +31,7 @@ module CLI
         or print_help_and_exit "Missing <candidate> argument, AND nothing was piped in"
 
       # Looks like we're good to go!
-      diff_view = CheckPlease.render_diff(reference, candidate, options)
+      diff_view = CheckPlease.render_diff(reference, candidate, flags)
       puts diff_view
     end
 

data/lib/check_please/comparison.rb

@@ -1,30 +1,33 @@
 module CheckPlease
+  using Refinements
 
-  module Comparison
-    extend self
+  class Comparison
+    def self.perform(reference, candidate, flags = {})
+      new.perform(reference, candidate, flags)
+    end
+
+    def perform(reference, candidate, flags = {})
+      @flags = Flags(flags) # whoa, it's almost like Java in here
+      @diffs = Diffs.new(flags: @flags)
 
-    def perform(reference, candidate, options = {})
-      root = CheckPlease::Path.new
-      diffs = Diffs.new(options: options)
       catch(:max_diffs_reached) do
-        compare reference, candidate, root, diffs
+        compare reference, candidate, CheckPlease::Path.root
       end
       diffs
     end
 
     private
+    attr_reader :diffs, :flags
 
-    def compare(ref, can, path, diffs)
-      if (d = diffs.options[:max_depth])
-        return if path.depth > d + 1
-      end
+    def compare(ref, can, path)
+      return if path.excluded?(flags)
 
       case types(ref, can)
-      when [ :array, :array ] ; compare_arrays ref, can, path, diffs
-      when [ :hash,  :hash  ] ; compare_hashes ref, can, path, diffs
-      when [ :other, :other ] ; compare_others ref, can, path, diffs
+      when [ :array, :array ] ; compare_arrays ref, can, path
+      when [ :hash,  :hash  ] ; compare_hashes ref, can, path
+      when [ :other, :other ] ; compare_others ref, can, path
       else
-        diffs.record ref, can, path, :type_mismatch
+        record_diff ref, can, path, :type_mismatch
       end
     end
 
@@ -38,7 +41,7 @@ module CheckPlease
         }
       end
 
-      def compare_arrays(ref_array, can_array, path, diffs)
+      def compare_arrays(ref_array, can_array, path)
         max_len = [ ref_array, can_array ].map(&:length).max
         (0...max_len).each do |i|
           n = i + 1 # count in human pls
@@ -48,44 +51,50 @@ module CheckPlease
           can = can_array[i]
 
           case
-          when ref_array.length < n ; diffs.record ref, can, new_path, :extra
-          when can_array.length < n ; diffs.record ref, can, new_path, :missing
-          else                      ; compare ref, can, new_path, diffs
+          when ref_array.length < n ; record_diff ref, can, new_path, :extra
+          when can_array.length < n ; record_diff ref, can, new_path, :missing
+          else
+            compare ref, can, new_path
           end
         end
       end
 
-      def compare_hashes(ref_hash, can_hash, path, diffs)
-        record_missing_keys ref_hash, can_hash, path, diffs
-        compare_common_keys ref_hash, can_hash, path, diffs
-        record_extra_keys   ref_hash, can_hash, path, diffs
+      def compare_hashes(ref_hash, can_hash, path)
+        record_missing_keys ref_hash, can_hash, path
+        compare_common_keys ref_hash, can_hash, path
+        record_extra_keys   ref_hash, can_hash, path
       end
 
-        def record_missing_keys(ref_hash, can_hash, path, diffs)
+        def record_missing_keys(ref_hash, can_hash, path)
           keys = ref_hash.keys - can_hash.keys
           keys.each do |k|
-            diffs.record ref_hash[k], nil, path + k, :missing
+            record_diff ref_hash[k], nil, path + k, :missing
           end
         end
 
-        def compare_common_keys(ref_hash, can_hash, path, diffs)
+        def compare_common_keys(ref_hash, can_hash, path)
           keys = ref_hash.keys & can_hash.keys
           keys.each do |k|
-            compare ref_hash[k], can_hash[k], path + k, diffs
+            compare ref_hash[k], can_hash[k], path + k
           end
         end
 
-        def record_extra_keys(ref_hash, can_hash, path, diffs)
+        def record_extra_keys(ref_hash, can_hash, path)
           keys = can_hash.keys - ref_hash.keys
           keys.each do |k|
-            diffs.record nil, can_hash[k], path + k, :extra
+            record_diff nil, can_hash[k], path + k, :extra
           end
         end
 
-      def compare_others(ref, can, path, diffs)
+      def compare_others(ref, can, path)
         return if ref == can
-        diffs.record ref, can, path, :mismatch
+        record_diff ref, can, path, :mismatch
       end
+
+    def record_diff(ref, can, path, type)
+      diff = Diff.new(type, path, ref, can)
+      diffs << diff
+    end
   end
 
 end

data/lib/check_please/diff.rb

@@ -3,20 +3,12 @@ module CheckPlease
   class Diff
     COLUMNS = %i[ type path reference candidate ]
 
-    attr_reader :type, :reference, :candidate, :path
-    def initialize(type, reference, candidate, path)
+    attr_reader(*COLUMNS)
+    def initialize(type, path, reference, candidate)
       @type      = type
+      @path      = path.to_s
       @reference = reference
       @candidate = candidate
-      @path      = path.to_s
-    end
-
-    def ref_display
-      reference.inspect
-    end
-
-    def can_display
-      candidate.inspect
     end
 
     def attributes
@@ -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

@@ -1,13 +1,14 @@
 require 'forwardable'
 
 module CheckPlease
+  using Refinements
 
   # Custom collection class for Diff instances.
   # Can retrieve members using indexes or paths.
   class Diffs
-    attr_reader :options
-    def initialize(diff_list = nil, options: {})
-      @options = options
+    attr_reader :flags
+    def initialize(diff_list = nil, flags: {})
+      @flags = Flags(flags)
       @list = []
       @hash = {}
       Array(diff_list).each do |diff|
@@ -29,7 +30,11 @@ module CheckPlease
     end
 
     def <<(diff)
-      if (n = options[:max_diffs])
+      if flags.fail_fast && length > 0
+        throw :max_diffs_reached
+      end
+
+      if (n = flags.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
@@ -38,10 +43,6 @@ module CheckPlease
       @hash[diff.path] = diff
     end
 
-    def record(ref, can, path, type)
-      self << Diff.new(type, ref, can, path)
-    end
-
     def data
       @list.map(&:attributes)
     end

data/lib/check_please/error.rb

@@ -6,4 +6,8 @@ module CheckPlease
     # instead....
   end
 
+  class InvalidFlag < ArgumentError
+    include CheckPlease::Error
+  end
+
 end

data/lib/check_please/flag.rb

@@ -0,0 +1,78 @@
+module CheckPlease
+
+  class Flag
+    attr_accessor :name
+    attr_writer   :default # reader is defined below
+    attr_accessor :default_proc
+    attr_accessor :description
+    attr_accessor :cli_long
+    attr_accessor :cli_short
+
+    def initialize(attrs = {})
+      @validators = []
+      attrs.each do |name, value|
+        set_attribute! name, value
+      end
+      yield self if block_given?
+      freeze
+    end
+
+    def default
+      if default_proc
+        default_proc.call
+      else
+        @default
+      end
+    end
+
+    def coerce(&block)
+      @coercer = block
+    end
+
+    def mutually_exclusive_to(flag_name)
+      @validators << ->(flags, _) { flags.send(flag_name).empty? }
+    end
+
+    def reentrant
+      @reentrant = true
+      self.default_proc = ->{ Array.new }
+    end
+
+    def validate(&block)
+      @validators << block
+    end
+
+    protected
+
+    def __set__(value, on:, flags:)
+      val = _coerce(value)
+      _validate(flags, val)
+      if @reentrant
+        on[name] ||= []
+        on[name].concat(Array(val))
+      else
+        on[name] = val
+      end
+    end
+
+    private
+
+    def _coerce(value)
+      return value if @coercer.nil?
+      @coercer.call(value)
+    end
+
+    def _validate(flags, value)
+      return if @validators.empty?
+      return if @validators.all? { |block| block.call(flags, value) }
+      raise InvalidFlag, "#{value.inspect} is not a legal value for #{name}"
+    end
+
+    def set_attribute!(name, value)
+      self.send "#{name}=", value
+    rescue NoMethodError
+      raise ArgumentError, "unrecognized attribute: #{name}"
+    end
+  end
+
+end

data/lib/check_please/flags.rb

@@ -0,0 +1,46 @@
+module CheckPlease
+
+  # NOTE: this gets all of its attributes defined (via .define) in ../check_please.rb
+
+  class Flags
+    BY_NAME = {} ; private_constant :BY_NAME
+
+    def self.[](name)
+      BY_NAME[name.to_sym]
+    end
+
+    def self.define(name, &block)
+      flag = Flag.new(name: name.to_sym, &block)
+      BY_NAME[flag.name] = flag
+      define_accessors flag
+
+      nil
+    end
+
+    def self.each_flag
+      BY_NAME.each do |_, flag|
+        yield flag
+      end
+    end
+
+    def self.define_accessors(flag)
+      getter = flag.name
+      define_method(getter) {
+        @attributes.fetch(flag.name) { flag.default }
+      }
+
+      setter = :"#{flag.name}="
+      define_method(setter) { |value|
+        flag.send :__set__, value, on: @attributes, flags: self
+      }
+    end
+
+    def initialize(attrs = {})
+      @attributes = {}
+      attrs.each do |name, value|
+        send "#{name}=", value
+      end
+    end
+  end
+
+end

data/lib/check_please/path.rb

@@ -3,8 +3,15 @@ module CheckPlease
   class Path
     SEPARATOR = "/"
 
+    def self.root
+      new
+    end
+
+    attr_reader :to_s
     def initialize(segments = [])
       @segments = Array(segments)
+      @to_s = SEPARATOR + @segments.join(SEPARATOR)
+      freeze
     end
 
     def +(new_basename)
@@ -15,12 +22,43 @@ module CheckPlease
       1 + @segments.length
     end
 
-    def to_s
-      SEPARATOR + @segments.join(SEPARATOR)
+    def excluded?(flags)
+      return false if root?
+
+      return true if too_deep?(flags)
+      return true if explicitly_excluded?(flags)
+      return true if implicitly_excluded?(flags)
+
+      false
     end
 
     def inspect
-      to_s
+      "<CheckPlease::Path '#{to_s}'>"
+    end
+
+    def root?
+      to_s == SEPARATOR
+    end
+
+    private
+
+    def explicitly_excluded?(flags)
+      flags.reject_paths.any?( &method(:match?) )
+    end
+
+    def implicitly_excluded?(flags)
+      return false if flags.select_paths.empty?
+      flags.select_paths.none?( &method(:match?) )
+    end
+
+    # leaving this here for a while in case it needs to grow into a public method
+    def match?(path_expr)
+      to_s.include?(path_expr)
+    end
+
+    def too_deep?(flags)
+      return false if flags.max_depth.nil?
+      flags.max_depth + 1 < depth
     end
   end
 

data/lib/check_please/printers.rb

@@ -1,10 +1,11 @@
-require_relative 'printers/base'
-require_relative 'printers/json'
-require_relative 'printers/table_print'
-
 module CheckPlease
+  using Refinements
 
   module Printers
+    autoload :Base,       "check_please/printers/base"
+    autoload :JSON,       "check_please/printers/json"
+    autoload :TablePrint, "check_please/printers/table_print"
+
     PRINTERS_BY_FORMAT = {
       table: Printers::TablePrint,
       json:  Printers::JSON,
@@ -12,9 +13,9 @@ module CheckPlease
     FORMATS = PRINTERS_BY_FORMAT.keys.sort
     DEFAULT_FORMAT = :table
 
-    def self.render(diffs, options = {})
-      format = options[:format] || DEFAULT_FORMAT
-      printer = PRINTERS_BY_FORMAT[format.to_sym]
+    def self.render(diffs, flags = {})
+      flags = Flags(flags)
+      printer = PRINTERS_BY_FORMAT[flags.format]
       printer.render(diffs)
     end
   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/refinements.rb

@@ -0,0 +1,16 @@
+module CheckPlease
+
+  module Refinements
+    refine Kernel do
+      def Flags(flags_or_hash)
+        case flags_or_hash
+        when Flags ; return flags_or_hash
+        when Hash  ; return Flags.new(flags_or_hash)
+        else
+          raise ArgumentError, "Expected either a CheckPlease::Flags or a Hash; got #{flags_or_hash.inspect}"
+        end
+      end
+    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.2"
+  VERSION = "0.4.1"
 end

data/usage_examples.rb

@@ -3,6 +3,10 @@ require 'check_please'
 reference = { foo: "wibble" }
 candidate = { bar: "wibble" }
 
+
+
+##### Printing diffs #####
+
 puts CheckPlease.render_diff(reference, candidate)
 
 # this should print the following to stdout:
@@ -12,3 +16,15 @@ _ = <<EOF
   missing | /foo | wibble    |
   extra   | /bar |           | wibble
 EOF
+
+
+
+##### Doing your own thing with diffs #####
+
+diffs = CheckPlease.diff(reference, candidate)
+
+# `diffs` is a custom collection (type: CheckPlease::Diffs) that contains
+# individual Diff objects for you to inspect as you see fit.
+#
+# If you come up with a useful way to present these, feel free to submit a PR
+# with a new class in `lib/check_please/printers` !

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: check_please
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.1
 platform: ruby
 authors:
 - Sam Livingston-Gray
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-15 00:00:00.000000000 Z
+date: 2020-11-30 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,24 +70,26 @@ 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
 - lib/check_please/cli/parser.rb
 - lib/check_please/cli/runner.rb
 - lib/check_please/comparison.rb
 - lib/check_please/diff.rb
 - lib/check_please/diffs.rb
 - lib/check_please/error.rb
+- lib/check_please/flag.rb
+- lib/check_please/flags.rb
 - lib/check_please/path.rb
 - lib/check_please/printers.rb
 - lib/check_please/printers/base.rb
 - lib/check_please/printers/json.rb
 - lib/check_please/printers/table_print.rb
+- lib/check_please/refinements.rb
 - lib/check_please/version.rb
 - usage_examples.rb
 homepage: https://github.com/RealGeeks/check_please

data/lib/check_please/cli/flag.rb

@@ -1,40 +0,0 @@
-module CheckPlease
-module CLI
-
-  class Flag
-    ATTR_NAMES = %i[ short long desc key block ]
-    attr_accessor(*ATTR_NAMES)
-
-    def initialize(*args)
-      self.short = args.shift if args.any?
-      self.long  = args.shift if args.any?
-
-      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
-    end
-
-    def visit_option_parser(parser, options)
-      parser.on(short, long, desc) do |value|
-        block.call options, value
-      end
-    end
-
-    def set_key(key, message = nil, &b)
-      raise ArgumentError if message && b
-      raise ArgumentError if !message && !b
-
-      self.key = key
-      self.block = ->(options, value) {
-        b ||= message.to_sym.to_proc
-        options[key] = b.call(value)
-      }
-    end
-  end
-
-end
-end