check_please 0.2.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f794a7a96790b642f2afc6f66bebb761a788c2b2a95025662e4ec8e654e612ef
-  data.tar.gz: 98a088234aa843abf60668d8ee6722de318f60d19e29352f8332338d28268e7c
+  metadata.gz: fe333e55fbfdb89d0ea68b3f9ceefde98f3aa4b798792e9dd13745b76757a499
+  data.tar.gz: cf8cfc0205d3b8d7a3d10ec1c0c5487ac140dd7bc41c0c640eb2d72ec3d1e3f7
 SHA512:
-  metadata.gz: 376fe8e75cf2c952d0cbaf42c32ca659c4f96488919eda781fc29cb50b259ddd3a91d60aa4bbae48022ccce96ab04148e60938079920a7657b7e288061b707dc
-  data.tar.gz: dd4c24bd01c391fa70e626bd9753efd3601a4a9a92dfe92956ce5742c0d8771e53a32a3ef05cbd1e45ac75eff30342230ba2b3dd238274fbe00bea2291f7d148
+  metadata.gz: 918e8b6edec715a8096872c46fa12adc029244b886525c704e9b769fecae6595d38d0b658ebe64a53ebe3474d6ddba76f7d8222baefbef582da4c7dec27e686e
+  data.tar.gz: 4e0da6a791cc4e539ed75f893a3950336bcf5703e6dbb6435e02bac23f94e3207c06dca5cf13551a4a81980474e4e796a911ea333bfec42b5d97aa1e6ef0f3c8

data/.gitignore

@@ -10,4 +10,6 @@
 # rspec failure tracking
 .rspec_status
 /vendor/
-spec/examples.txt
+spec/examples.txt
+README.md.orig.*
+README.md.toc.*

data/Gemfile.lock

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

data/README.md

@@ -3,7 +3,36 @@
 Check for differences between two JSON documents, YAML documents, or Ruby data
 structures parsed from either of those.
 
-## Installation
+<!-- start of auto-generated TOC; see https://github.com/ekalinin/github-markdown-toc -->
+<!--ts-->
+   * [check_please](#check_please)
+   * [Installation](#installation)
+   * [Terminology](#terminology)
+   * [Usage](#usage)
+      * [From the Terminal / Command Line Interface (CLI)](#from-the-terminal--command-line-interface-cli)
+      * [From RSpec](#from-rspec)
+      * [From Ruby](#from-ruby)
+      * [Understanding the Output](#understanding-the-output)
+         * [Diff Types](#diff-types)
+         * [Paths](#paths)
+         * [Output Formats](#output-formats)
+      * [Flags](#flags)
+         * [Setting Flags in the CLI](#setting-flags-in-the-cli)
+         * [Setting Flags in Ruby](#setting-flags-in-ruby)
+         * ["Reentrant" Flags](#reentrant-flags)
+         * [Expanded Documentation for Specific Flags](#expanded-documentation-for-specific-flags)
+            * [Flag: match_by_key](#flag-match_by_key)
+   * [TODO (maybe)](#todo-maybe)
+   * [Development](#development)
+   * [Contributing](#contributing)
+   * [License](#license)
+   * [Code of Conduct](#code-of-conduct)
+
+
+<!--te-->
+<!-- end of auto-generated TOC -->
+
+# Installation
 
 Add this line to your application's Gemfile:
 
@@ -19,11 +48,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
@@ -36,7 +64,14 @@ CheckPlease uses a few words in a jargony way:
   **reference** and the **candidate**.  More on this in "Understanding the Output",
   below.
 
-### CLI
+Also, even though this gem was born from a need to compare JSON documents, I'll
+be talking about "hashes" instead of "objects", because I assume this will
+mostly be used by Ruby developers.  Feel free to substitute "object" wherever
+you see "hash" if that's easier for you.  :)
+
+# Usage
+
+## From the Terminal / Command Line Interface (CLI)
 
 Use the `bin/check_please` executable.  (To get started, run it with the '-h' flag.)
 
@@ -47,21 +82,28 @@ 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!
+
+## From Ruby
+
+See also: [./usage_examples.rb](usage_examples.rb).
 
-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).)
+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.
 
-(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!
+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
+## Understanding the Output
 
 CheckPlease follows the Unix philosophy of "no news is good news".  If your
 **candidate** matches your **reference**, you'll get an empty message.
@@ -71,9 +113,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.
 
@@ -117,7 +157,7 @@ mismatch      | /meta/foo | spam       | foo
 
 Let's start with the leftmost column...
 
-#### Diff Types
+### Diff Types
 
 The above example is intended to illustrate every possible type of diff that
 CheckPlease defines:
@@ -125,23 +165,23 @@ 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**.
+  value at the given path, and neither value was an Array or a Hash, and the
+  two values were not equal.
+* **extra** means that, inside an Array or a Hash, the **candidate** contained
+  elements 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**.
+  **reference** contained elements that were not found in the **candidate**.
 
-#### Paths
+### 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
@@ -152,33 +192,265 @@ _**Being primarily a Ruby developer, I'm quite ignorant of conventions in the
 JS community; if there's an existing convention for paths, please open an
 issue!**_
 
-#### Output Formats
+### Output Formats
 
 CheckPlease produces tabular output by default.  (It leans heavily on the
 amazing [table_print](http://tableprintgem.com) gem for this.)
 
 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.
+print diffs as JSON to facilitate parsing.  How you do this depends on whether
+you're using CheckPlease from the command line or in Ruby, which is a good time
+to talk about...
+
+## Flags
+
+CheckPlease has several flags that control its behavior.
+
+For quick help on which flags are available, as well as some terse help text,
+you can run the `check_please` executable with no arguments (or the `-h` or
+`--help` flags if that makes you feel better).
+
+While of course we aspire to keep this README up to date, it's probably best to
+believe things in the following priority order:
+
+* observed behavior
+* the code (start from `./lib/check_please.rb` and search for `Flags.define`,
+  then trace through as needed)
+* the tests (`spec/check_please/flags_spec.rb` describes how the flags work;
+	from there, you'll have to search on the flag's name to see how it shows up
+	in code)
+* the output of `check_please --help`
+* this README :)
+
+All flags have exactly one "Ruby name" and one or more "CLI names".  When the
+CLI runs, it parses the values in `ARGV` (using Ruby's native `OptionParser`)
+and uses that information to build a `CheckPlease::Flags` instance.  After that
+point, a flag will be referred to within the CheckPlease code exclusively by
+its "Ruby name".
+
+For example, the flag that controls the format in which diffs are displayed has
+a Ruby name of `format`, and CLI names of `-f` and `--format`.
+
+### Setting Flags in the CLI
+
+This should behave more or less as an experienced Unix CLI user might expect.
+
+As such, you can specify, e.g., that you want output in JSON format using
+either `--format json` or `-f json`.
+
+(I might expand this section some day.  In the meantime, if you are not yet an
+experienced Unix CLI user, feel free to ask for help!  You can either open an
+issue or look for emails in the `.gemspec` file...)
+
+### Setting Flags in Ruby
+
+All external API entry points allow you to specify flags using their Ruby names
+in the idiomatic "options Hash at the end of the argument list" that should be
+familiar to most Rubyists.  (Again, I assume that, if you're using this tool, I
+don't need to explain this further, but feel free to ask for help if you need
+it.)
+
+(Internally, CheckPlease immediately converts that options hash into a
+`CheckPlease::Flags` object, but that should be considered an implementation
+detail unless you're interested in hacking on CheckPlease itself.)
+
+For example, to get back a String containing the diffs between two data
+structures in JSON format, you might do:
+
+```
+reference = { "foo" => "wibble" }
+candidate = { "bar" => "wibble" }
+puts CheckPlease.render_diff(
+  reference,
+  candidate,
+  format: :json # <--- flags
+)
+```
+
+### Repeatable Flags
+
+Several flags **may** be specified more than once when invoking the CLI.  I've
+tried to make both the CLI and the Ruby API follow their respective
+environment's conventions.
+
+For example, if you want to specify a path to ignore using the
+`--reject-paths` flag, you'd invoke the CLI like this:
+
+* `[bundle exec] check_please reference.json candidate.json --select-paths /foo`
+
+And if you want to specify more than one path, that would look like:
+
+* `[bundle exec] check_please reference.json candidate.json --select-paths /foo --select-paths /bar`
+
+In Ruby, you can specify this in the options hash as a single key with an Array
+value:
+
+* `CheckPlease.render_diff(reference, candidate, select_paths: [ "/foo", "/bar" ])`
+
+_(NOTE TO MAINTAINERS: internally, the way `CheckPlease::CLI::Parser` uses
+Ruby's `OptionParser` leads to some less than obvious behavior.  Search
+[./spec/check_please/flags_spec.rb](spec/check_please/flags_spec.rb) for the
+word "surprising" for details.)_
+
+### Expanded Documentation for Specific Flags
+
+#### Flag: `match_by_key`
+
+> **I know this looks like a LOT of information, but it's really not that
+> bad!**  This feature just requires specific examples to describe, and talking
+> about it in English (rather than code) is hard.  Take a moment for some deep
+> breaths if you need it.  :)
+
+> _If you're comfortable reading RSpec and/or want to check out all the edge
+> cases, go look in `./spec/check_please/comparison_spec.rb` and check out the
+> `describe` block labeled `"comparing arrays by keys"`._
+
+The `match_by_key` flag allows you to match up arrays of hashes using the value
+of a single key that is treated as the identifier for each hash.
+
+There's a lot going on in that sentence, so let's unpack it a bit.
+
+Imagine you're comparing two documents that contain the same data, but in
+different orders.  To use a contrived example, let's say that both documents
+consist of a single array of two simple hashes, but the reference array and the
+candidate array are reversed:
 
-## TODO
+```ruby
+# REFERENCE
+[ { "id" => 1, "foo" => "bar" },  { "id" => 2, "foo" => "spam" } ]
+
+# CANDIDATE
+[ { "id" => 2, "foo" => "spam" }, { "id" => 1, "foo" => "bar" }  ]
+```
+
+By default, CheckPlease will match up array elements by their position in the
+array, resulting in a diff report like this:
+
+```
+TYPE     | PATH   | REFERENCE | CANDIDATE
+---------|--------|-----------|----------
+mismatch | /1/id  | 1         | 2
+mismatch | /1/foo | "bar"     | "bat"
+mismatch | /2/id  | 2         | 1
+mismatch | /2/foo | "bat"     | "bar"
+```
+
+To solve this problem, CheckPlease adds a **key expression** to its (very
+simple) path syntax that lets you specify a **key** to use to match up elements
+in both lists, rather than simply comparing elements by position.
+
+Continuing with the above example, if we give `match_by_key` a value of
+`["/:id"]`, it will use the "id" value in both hashes (remember, A's `id` is
+`1` and B's `id` is `2`) to identify every element in both the reference array
+and the candidate array, and correctly match A and B, giving you an empty list
+of diffs.
+
+Please note that the CLI and Ruby implementations of these are a bit different
+(see "Setting Flags in the CLI" versus "Setting Flags in Ruby"), so if you're
+doing this from the command line, it'll look like: `--match-by-key /:id`
+
+Here, have another example.  If you want to specify a match_by_key expression
+below the root of the document, you can put the **key expression** further down
+the path: `/books/:isbn`
+
+This would correctly match up the following documents:
+
+```ruby
+# REFERENCE
+{
+  "books" => [
+    { "isbn" => "12345", "title" => "Who Am I, Really?" },
+    { "isbn" => "67890", "title" => "Who Are Any Of Us, Really?" },
+  ]
+}
+
+# CANDIDATE
+{
+  "books" => [
+    { "isbn" => "67890", "title" => "Who Are Any Of Us, Really?" },
+    { "isbn" => "12345", "title" => "Who Am I, Really?" },
+  ]
+}
+```
 
+Finally, if you have deeply nested data with arrays of hashes at multiple
+levels, you can specify more than one **key expression** in a single path,
+like: `/authors/:id/books/:isbn`
+
+This would correctly match up the following documents:
+
+```ruby
+# REFERENCE
+{
+  "authors" => [
+    {
+      "id"    => 1,
+      "name"  => "Anne Onymous",
+      "books" => [
+        { "isbn" => "12345", "title" => "Who Am I, Really?" },
+        { "isbn" => "67890", "title" => "Who Are Any Of Us, Really?" },
+      ]
+    },
+  ]
+}
+
+# CANDIDATE
+{
+  "authors" => [
+    {
+      "id"    => 1,
+      "name"  => "Anne Onymous",
+      "books" => [
+        { "isbn" => "67890", "title" => "Who Are Any Of Us, Really?" },
+        { "isbn" => "12345", "title" => "Who Am I, Really?" },
+      ]
+    },
+  ]
+}
+```
+
+Finally, if there are any diffs to report, CheckPlease uses a **key/value
+expression** to report mismatches.
+
+Using the last example above (the one with `/authors/:id/books/:isbn`), if the
+reference had Anne Onymous' book title as "Who Am I, Really?" and the candidate
+listed it as "Who The Heck Am I?", CheckPlease would show the mismatch using
+the following path expression: `/authors/id=1/books/isbn=12345`
+
+**This syntax is intended to be readable by humans first.**  If you need to
+build tooling that consumes it... well, I'm open to suggestions.  :)
+
+-----
+
+# TODO (maybe)
+
+* document flags for rspec matcher
 * command line flags for :allthethings:!
+  * change display width for table format
+    (for example, "2020-07-16T19:42:41.312978" gets cut off)
   * 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
+-----
+
+# 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
@@ -190,22 +462,21 @@ release a new version, update the version number in `version.rb`, and then run
 git commits and tags, and push the `.gem` file to
 [rubygems.org](https://rubygems.org).
 
-## Contributing
+# Contributing
 
 Bug reports and pull requests are welcome on GitHub at
-https://github.com/[USERNAME]/check_please. This project is intended to be a
+https://github.com/RealGeeks/check_please. This project is intended to be a
 safe, welcoming space for collaboration, and contributors are expected to
 adhere to the [code of
-conduct](https://github.com/[USERNAME]/check_please/blob/master/CODE_OF_CONDUCT.md).
-
+conduct](https://github.com/RealGeeks/check_please/blob/master/CODE_OF_CONDUCT.md).
 
-## License
+# License
 
 The gem is available as open source under the terms of the [MIT
 License](https://opensource.org/licenses/MIT).
 
-## Code of Conduct
+# Code of Conduct
 
 Everyone interacting in the CheckPlease project's codebases, issue trackers,
 chat rooms and mailing lists is expected to follow the [code of
-conduct](https://github.com/[USERNAME]/check_please/blob/master/CODE_OF_CONDUCT.md).
+conduct](https://github.com/RealGeeks/check_please/blob/master/CODE_OF_CONDUCT.md).