yadtfp 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dc0e6391243b1ba24c96baf22543c06008664671
+  data.tar.gz: d704c04bc9e32111dacd3af5e3f1cb78c9f4a6f4
+SHA512:
+  metadata.gz: 75acbe5a35c0c8abfb6da4c2d433a4cf0fbfbc677bc0785c3fb9dec6dcd79440a4583f51df82a2f14887562fcde63f7ec4a34a2ed52471f4e2ce55684aaec5d9
+  data.tar.gz: 4c760dfd15403f535f6b4304fcd411e48d36fdf6239585a799ded329fe5643903bdc8766fe78c24e90b498913803382911819a542a866341274ba85574a95b8e

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.yardopts

@@ -0,0 +1,9 @@
+--charset     utf-8
+--readme      README.md
+--markup      markdown
+--title       "Yadtfp Documentation"
+--protected 
+--private
+- 
+MIT-LICENSE.txt
+CONTRIBUTING.md

data/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Contributions are welcome.
+
+1. Fork it ( https://github.com/vinodadhikary/yadtfp/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in yadtfp.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,16 @@
+guard :rspec, cmd: 'rspec --color --format doc' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^spec/fabricators/.+_fabricator\.rb$})     { 'spec' }
+  watch(%r{^spec/support/.+\.rb$})                    { 'spec' }
+  watch('spec/spec_helper.rb')                        { 'spec' }
+
+  watch(%r{^lib/(.+)\.rb$})           { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^lib/(.+)/(.+)\.rb$})      { |m| "spec/#{m[2]}_spec.rb" }
+  watch(%r{^lib/(.+)/(.+)/(.+)\.rb$}) { |m| "spec/#{m[2]}/#{m[3]}_spec.rb" }
+end
+
+
+# Run `yard` documentation server
+guard 'yard', port: '8808' do
+  watch(%r{^(.+)\.md|rb$})          { 'yardoc' }
+end

data/MIT-LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) Vinod Adhikary 2014.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,285 @@
+# Yadtfp
+
+`yadtfp` is a diff tool that takes two [well formed](http://en.wikipedia.org/wiki/Well-formed_document) 
+[xml](https://en.wikipedia.org/wiki/XML) documents and generates the differences in an easy to read, concise output.
+The difference algorithm operates on element values producing a very precise diff possible.
+
+The name is an acronym for "Yet Another Diff Tool For Param".  The original motivation of `yadtfp` was to make it a
+[`CLI`](http://en.wikipedia.org/wiki/Command-line_interface) tool to compare two xml files containing application
+configuration parameters, which is how it got it's name, we think.
+
+`yadtfp` parses each input XML into an array of flat hashes, applies filter and compares the two.  The result is an 
+array of difference hashes.  The result array is then passed to the selected outputter which prints the output to 
+console.
+
+
+## Installation
+
+    $ gem install yadtfp
+
+
+## Documentation
+
+The code base documentation is [available here](/_index.html).
+
+
+## Parsers
+
+Currently `yadtfp` supports [`Ox`](https://github.com/ohler55/ox) parser which is the default.
+
+
+## Outputters
+
+Currently `yadtfp` supports `Yadtfp::Outputters::Pretty` outputter which is the default.
+
+
+### Pretty Outputter
+
+Pretty outputter generates the output in the following format: 
+
+    Changes (Replace left value with right value)
+    ---------------------------------------------
+
+    Appends (Add values to left)
+    ----------------------------
+
+    Deletes (Remove values from left)
+    ---------------------------------
+        
+    Summary of differences
+    ----------------------
+    Number of differences: x
+    Changes 'c': x
+    Appends 'a': x
+    Deletes 'd': x
+
+*where `x` is an integer value for each difference.*
+
+**Note**: In "Summary of differences", Changes, Appends and Deletes are included only if the diff contains respective
+difference, i.e. if a diff does not contain "Deletes" then "Summary of differences" excludes "Deletes", and likewise for
+"Appends" and "Changes".
+
+
+## Other topics of interest
+
+
+### Path generation
+
+Path to each XML component, e.g. attribute, comment, cdata, text are based on the following:
+
+**1. Attribute**
+
+Attributes are prefixed with `@` sign. 
+
+    # Input XML
+    <xml id='foo' />
+
+    # Path to attribute `id`
+    /xml/@id
+
+**2. Comment**
+
+Comments are denoted by `comment()`.
+
+    # Input XML
+    <xml>
+      <!-- Root node -->
+    </xml>
+
+    # Path to comment
+    /xml/comment()
+
+**3. CData**
+
+CData are denoted by `cdata()`.
+
+    # Input XML
+    <xml>
+      <![CDATA[ Foo ]]>
+    </xml>
+
+    # Path to cdata
+    /xml/cdata()
+
+**4. Text**
+
+Texts are denoted by path to the node containing the text.
+
+    # Input XML
+    <xml>Foo</xml>
+
+    # Path to text
+    /xml
+
+
+### Flat hash
+
+Each input xml document is parsed into an array of hashes.  This hash's key is the path to the element from the path 
+specified in the filter and it's value is the text or value in the xml.  If no filter is specified, the default filter
+is used.
+
+Example of flat hash data structure, given an input xml:
+
+    # Input XML
+    <xml id='root'>
+      <!-- Root node -->
+      <child id='child'>Foo</child>
+      <![CDATA[ Bar ]]>
+    </xml>
+
+    # Output Array of hashes
+    [
+      { '/xml/@id' => 'root' },
+      { '/xml/comment()' => [ 'Root node' ] }, 
+      { '/xml/cdata()' => [ 'Bar' ] }, 
+      { '/xml/child/@id' => 'child' }, 
+      { '/xml/child' => 'Foo' }
+    ]
+
+
+### Difference hash
+
+There are altogether three types of differences: 
+
+  1. Change - `c`
+  2. Append - `a`
+  3. Delete - `d`
+
+Example difference hash for each difference type is as follows: 
+
+    # Change 
+    { type: `c`, path: '', lvalue: '', rvalue: '' }
+
+    # Append
+    { type: 'a', path: '', lvalue: '', rvalue: '' }
+
+    # Delete
+    { type: 'd', path: '', lvalue: '', rvalue: '' }
+
+
+
+### Configuration options
+
+`yadtfp` supports the following three parameters: 
+
+1. `--filter` to filter content of xml.  This is usually applied to perform diff on a subset of input xml.
+Defaults to `"*"`.
+
+2. `--parser` to parse input xml.  Defaults to `:ox`.
+
+3. `--outputter` to output result diff.  Defaults to `:pretty`.
+
+
+Each filter option has a shorthand to save a little typing! but **only in the CLI**.  The shorthand mapping of each
+options are: 
+
+1. `--filter`: `-f`
+2. `--parser`: `-p`
+3. `--outputter`: `-o`
+
+Each configuration option is prefixed with double dash `--` except for shorthand notations which are prefixed by a
+single dash `-`.
+
+
+### Filters
+
+Filters are based on [`::Ox::Element#locate()`](http://www.ohler.com/ox/Ox/Element.html#locate-instance_method)
+
+Examples sourced from documentation for `#Ox::Element#locate()`:
+
+    Family/Pete/*       - All children of Pete element
+    Family/?[1]         - First element in Family element
+    Family/?[<3]*       - First 3 elements in Family element
+    Family/?/@age       - Age attribute for each child in Family element
+    Family/*/@type      - Type attribute value for decendents of Family element
+    Family/^Comment     - Comment children of Family element
+
+
+
+## CLI Usage
+
+**1. `yadtfp` two xml strings using default options**
+
+    $ yadtfp -- "<xml id='root' />" "<xml name='root_node' />"
+    Changes (Replace left value with right value)
+    ---------------------------------------------
+
+    Appends (Add values to left)
+    ----------------------------
+
+    1. Path: /xml/@name
+       Left: 
+       Right: root_node
+
+    Deletes (Remove values from left)
+    ---------------------------------
+
+    1. Path: /xml/@id
+       Left: root
+       Right: 
+
+
+    Summary of differences
+    ----------------------
+    Number of differences: 2
+     Appends 'a': 1
+     Deletes 'd': 1
+
+  The above command can be substituted with: 
+
+    $ yadtfp --filter "*" --parser "ox" --outputter "pretty" "<xml id='root' />" "<xml name='root_node' />"
+
+  or using shorthand options: 
+
+    $ yadtfp -f "*" -p "ox" -o "pretty" "<xml id='root' />" "<xml name='root_node' />"
+
+
+**2. `yadtfp` two xml files using default options**
+
+  Given two xml files `file1.xml` and `file2.xml`:
+
+    # file1.xml
+    <?xml version='1.0' encoding='utf-8' ?>
+    <xml>Foo</xml>
+
+    # file2.xml
+    <?xml version='1.0' encoding='utf-8' ?>
+    <xml>Bar</xml>
+
+  Execute `yadtfp diff`:
+
+    $ yadtfp -- file1.xml file2.xml
+    Changes (Replace left value with right value)
+    ---------------------------------------------
+
+    1. Path: /xml
+       Left: Foo
+       Right: Bar
+
+    Appends (Add values to left)
+    ----------------------------
+
+    Deletes (Remove values from left)
+    ---------------------------------
+
+
+    Summary of differences
+    ----------------------
+    Number of differences: 1
+     Changes 'c': 1
+ 
+
+  The above command can be substituted with: 
+    
+    $ yadtfp --filter "*" -parser "ox" -outputter "pretty" file1.xml file2.xml
+
+  or using shorthand options:
+
+    $ yadtfp -f "*" -p "ox" -o "pretty" file1.xml file2.xml
+
+  **Note**: File paths may be absolute or relative from the present working directory.
+
+
+## Contributing
+
+Please see [CONTRIBUTING.md](file.CONTRIBUTING.html)

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bin/yadtfp

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+require 'yadtfp/cli'
+Yadtfp::CLI.start

data/lib/yadtfp.rb

@@ -0,0 +1,21 @@
+require 'yadtfp/version'
+require 'yadtfp/configuration'
+require 'yadtfp/parsers'
+require 'yadtfp/outputters'
+
+
+
+module Yadtfp
+
+  def self.configuration
+    @configuration = Configuration.instance
+  end
+
+
+
+
+  def self.configure
+    yield(configuration)
+  end
+
+end

data/lib/yadtfp/cli.rb

@@ -0,0 +1,55 @@
+require 'thor'
+require 'yadtfp'
+
+module Yadtfp
+
+  class CLI < Thor
+
+
+    class_option :filter, aliases: '-f', type: :string, desc: 'FILTER is path to the node in unix directory structure format'
+    class_option :parser, aliases: '-p', type: :string, desc: "PARSER is either 'ox' or 'nokogiri'"
+    class_option :outputter, aliases: '-o', type: :string, desc: "OUTPUTTER is 'pretty'"
+
+
+
+    desc "diff [OPTIONS]... LEFT RIGHT", "Diff left and right xml documents"
+    long_desc <<-LONGDESC
+      `diff LEFT RIGHT` will compare `LEFT` and `RIGHT` and print the result to the terminal.
+
+      When none of the options are specified the default options will apply.
+
+      The default for each options are:
+        \x5 --filter="/"
+        \x5 --parser="ox"
+        \x5 --outputter="pretty"
+
+      Examples:
+        diff file1.xml file2.xml    - Diffs two xml files using default options and pretty prints the result to the terminal.
+    LONGDESC
+    def diff(file1, file2)
+
+      # Load config
+      config = Yadtfp::Configuration.parse_options(options)
+
+
+      # Parse
+      parser = Yadtfp::ParsersFactory.create(config.parser)
+
+      left = parser.parse(file1)
+      right = parser.parse(file2)
+
+
+      # Diff
+      diff = parser.diff(left, right)
+
+
+      # Output
+      out = Yadtfp::OutputtersFactory.create(config.outputter, diff)
+      out.print
+
+    end
+
+    default_task :diff
+
+  end
+end