RubyGems - smart_diff - Versions diffs - 0.0.1 → 0.0.3 - Mend

smart_diff 0.0.1 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

checksums.yaml +7 -0
data/Example.html +506 -0
data/README.md +5 -5
data/doc/Htmlize.html +927 -250
data/doc/SmartDiff.html +188 -37
data/doc/Tag.html +132 -29
data/doc/Utils.html +247 -40
data/doc/_index.html +1 -1
data/doc/file.README.html +13 -8
data/doc/index.html +13 -8
data/doc/top-level-namespace.html +1 -1
data/{foo.rb-bar.rb.html → example/foo.rb-bar.rb.html} +3 -3
data/lib/smart_diff/htmlize.rb +124 -0
data/lib/smart_diff/utils.rb +40 -0
data/lib/smart_diff.rb +21 -0
data/spec/smart_diff/htmlize_spec.rb +1 -1
metadata +6 -16

data/lib/smart_diff/htmlize.rb CHANGED Viewed

@@ -1,21 +1,55 @@
 require "cgi"
 require_relative "utils.rb"
+#
+# A Tag wrapping an element in an HTML file.
+# It contains information about the node wrapped inside
+# it such as the start and end offset. The `tag` attr contains
+# the actual HTML, and includes information used to style the nodes
+# based on whether its an insertion, deletion or modification.
+# Matching modifications are wrapped in anchor tags so they can be
+# linked to their matches.
+#
+#
 class Tag
   attr_accessor :tag, :idx, :start
+  #
+  # Construct a new tag.
+  #
+  # @param  tag [String] An HTML tag.
+  # @param  idx [Fixnum] The start of the node's offset for an opening tag,
+  # The end offset of the node if it is a closing tag.
+  # @param  start [Fixnum] Left -1 for an open tag, the node's start offset
+  # for a closing tag.
+  #
+  # @return [Tag] The Tag which was constructed.
   def initialize(tag, idx, start=-1)
     @tag = tag
     @idx = idx
     @start = start
   end
+  #
+  # String representation of the Tag object.
+  #
+  # @return [String] Tag as string.
   def to_s
     "tag: #{@tag}, idx: #{@idx} start: #{@start}"
   end
 end
+#
+# Given information about two Ruby files, and their
+# semantic diff, creates an HTML file to represent the
+# diff information in an intuitive and appealing visual
+# format.
+#
 class Htmlize
   include Utils
   attr_accessor :uid_count, :uid_hash
@@ -30,6 +64,15 @@ class Htmlize
     @uid_hash = {}
   end
+  #
+  # Give the node a uid, place it in the uid hash and
+  # up the count. If it already has one, fetch it from the hash
+  # and return it.
+  #
+  # @param  node [org.jrubyparser.Node] A node in the AST.
+  #
+  # @return [Fixnum] The uid of the node passed in.
   def uid(node)
     if @uid_hash.has_key?(node)
       return @uid_hash[node]
@@ -39,6 +82,11 @@ class Htmlize
     @uid_hash[node] = @uid_count.to_s
   end
+  #
+  # Construct the HTML for the top of the file.
+  #
+  # @return [String] HTML header.
   def html_header
     install_path = get_install_path
@@ -61,11 +109,24 @@ class Htmlize
     <body>\n}
   end
+  #
+  # Create the html for the bottom of the page.
+  #
+  # @return [String] the html footer.
   def html_footer
     out = %Q{</body>\n
              </html>\n}
   end
+  #
+  # Takes in the text and outputs html.
+  #
+  # @param  text [String] the text from either side of the diff, w/ html tags.
+  # @param  side [String] left or right
+  #
+  # @return [String] All the html for one side of the diff.
   def write_html(text, side)
     out = ""
@@ -83,6 +144,17 @@ class Htmlize
     out << '</div>'
   end
+  #
+  # Takes in the information about the diff and writes out a file of HTML.
+  #
+  # @param  changes [Array] An array of Changes, the diff
+  # @param  file1 [String] path to the first file.
+  # @param  file2 [String] path to the second file.
+  # @param  text1 [String] the text from the first file
+  # @param  text2 [String] the text from the second file.
+  #
+  # @return [String] The name of the HTML file that was written.
   def create_html(changes, file1, file2, text1, text2)
     tags1 = change_tags(changes, 'left')
     tags2 = change_tags(changes, 'right')
@@ -100,6 +172,15 @@ class Htmlize
   end
+  #
+  # Does HTML escaping on both tags and text, and places the tags around the
+  # appropriate text.
+  #
+  # @param  s [String] The text from one of the files.
+  # @param  tags [String] The tags belonging to one of the files.
+  #
+  # @return [String] The tagged text.
   def apply_tags(s, tags)
     tags = tags.sort_by { |x| [x.idx, -x.start] }
     curr = 0
@@ -118,6 +199,15 @@ class Htmlize
     return out
   end
+  #
+  # Works through the Change objects in the diff, creating the
+  # appropriate HTML tags for each.
+  #
+  # @param  changes [Array] An array of Change objects.
+  # @param  side [String] Tells us which side of the page to create tags for.
+  #
+  # @return [Array] The tags to place around the text.
   def change_tags(changes, side)
     tags = []
     changes.each do |c|
@@ -131,15 +221,19 @@ class Htmlize
           if inside_anchor?(tags, nd_start, nd_end)
             if change_class(c) =~ /c/
               # no op
+              # we don't nest anchors inside other anchors
             else
+              # In this case, we have an insertion or deletion
               tags << Tag.new(span_start(c), nd_start)
               tags << Tag.new('</span>', nd_end, nd_start)
             end
           else
+            # Link up the matching nodes with anchor tags
             tags << Tag.new(link_start(c, side), nd_start)
             tags << Tag.new('</a>', nd_end, nd_start)
           end
         else
+          # Wrap a span around the insertion or deletion.
           tags << Tag.new(span_start(c), nd_start)
           tags << Tag.new('</span>', nd_end, nd_start)
         end
@@ -148,6 +242,13 @@ class Htmlize
     return tags
   end
+  #
+  # Determines whether the change is an insertion, deletion or modification.
+  #
+  # @param  change [Change] The Change object to be checked.
+  #
+  # @return [String] Either a 'c', 'd', or 'i'
   def change_class(change)
     if !change.old_node
       return 'd'
@@ -158,10 +259,26 @@ class Htmlize
     end
   end
+  #
+  # Takes a Change and creates a span tag.
+  #
+  # @param  change [Change] A single change from the diff representing either
+  # an insertion or deletion.
+  #
+  # @return [String] A span tag based on the Change passed in.
   def span_start(change)
     "<span class=#{qs(change_class(change))}>"
   end
+  #
+  # Create anchor tags for a Change object.
+  #
+  # @param  change [Change] The Change object to be wrapped.
+  # @param  side [String] Which side of the page, in other words, which file?
+  #
+  # @return [String] An anchor tag.
   def link_start(change, side)
     cls = change_class(change)
@@ -174,6 +291,13 @@ class Htmlize
     "<a id=#{qs(uid(me))} tid=#{qs(uid(other))} class=#{qs(cls)}>"
   end
+  #
+  # Takes a string and returns it in quotes.
+  #
+  # @param  s [String] A string to be quoted.
+  #
+  # @return [String] The quoted string.
   def qs(s)
     "'#{s}'"
   end

data/lib/smart_diff/utils.rb CHANGED Viewed

@@ -3,20 +3,60 @@ require "pathname"
 module Utils
   module_function
+  #
+  # Where in the file-system is smart_diff installed?
+  #
+  # @return [Pathname] the path to the installation of smart_diff
   def get_install_path
     utils_path = Pathname.new(__FILE__).dirname
     # There should be a more elegant way to do this
     install_path = utils_path.parent.parent
   end
+  #
+  # Get a node's start position,
+  #
+  # @param  node [org.jrubyparser.Node] a node in an abstract syntax tree
+  #
+  # @return [Fixnum] Number representing the node's start offset.
   def node_start(node)
     node.position.start_offset
   end
+  #
+  # Get a node's end position.
+  #
+  # @param  node [org.jrubyparser.Node] a node in an abstract syntax tree
+  #
+  # @return [Fixnum] Number representing the node's end offset.
   def node_end(node)
     node.position.end_offset
   end
+  #
+  # Determines if the node beginning with nd_start and ending with nd_end
+  # falls inside an anchor. In other words, is the current node inside
+  # another node _which also changed_ and has a match in the other file. (If it
+  # is an insertion or deletion it gets wrapped in a span so we aren't
+  # concerned with those.)
+  #
+  # In a pair of tags, the opening tag only has some of the position
+  # information, so they are marked with a meaningless -1. But the closing tags
+  # have the information needed- start and end offsets.
+  #
+  # Subnodes were added to the array after the outer nodes, so we check them
+  # here, once, against each tag, and decide how to process them as we
+  # generate the HTML.
+  #
+  # @param  tags [Array] A list of all tags so far recorded.
+  # @param  nd_start [Fixnum] Number representing the node's starting position.
+  # @param  nd_end [Fixnum] Number representing the node's ending position.
+  #
+  # @return [TrueClass, FalseClass] Is it inside an anchor?
   def inside_anchor?(tags, nd_start, nd_end)
       tags.each do |t|
         if nd_end < t.idx && nd_start > t.start && t.start != -1

data/lib/smart_diff.rb CHANGED Viewed

@@ -22,6 +22,13 @@ class SmartDiff
     @node_diff = diff()
   end
+  #
+  # Read the source code into a string.
+  #
+  # @param  file_name [String] the path to a file containing ruby source
+  #
+  # @return [String] The code read in from the file path passed in.
   def read(file_name)
     path = Pathname.new(file_name).expand_path
     if path.exist?
@@ -31,10 +38,24 @@ class SmartDiff
     end
   end
+  #
+  # Parse the source into an abstract syntax tree.
+  # @param  code_to_parse [String] Ruby source code.
+  # @param  file_name [String] The path to the file containing code_to_parse
+  #
+  # @return [org.jrubyparser.Node] A Node object representing the code as an
+  # AST.
   def parse(code_to_parse, file_name)
     JRubyParser.parse(code_to_parse, { :filename => file_name })
   end
+  #
+  # Create a diff of the two AST objects.
+  #
+  # @return [java.util.ArrayList] An ArrayList containing
+  # org.jrubyparser.DeepDiff objects.
   def diff()
     @code_one = read(@file_one)
     @code_two = read(@file_two)

data/spec/smart_diff/htmlize_spec.rb CHANGED Viewed

@@ -26,7 +26,7 @@ describe "Htmlize" do
   it "should return the entry for a previously set hash" do
     html = Htmlize.new
-    html.uid_hash = { banana: "cow" }
+    html.uid_hash = { :banana => "cow" }
     html.uid(:banana).should =~ /cow/
   end

metadata CHANGED Viewed

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smart_diff
 version: !ruby/object:Gem::Version
-  prerelease:
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Eric West
@@ -18,13 +17,11 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.5.1
-    none: false
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: 0.5.1
-    none: false
   prerelease: false
   type: :runtime
 - !ruby/object:Gem::Dependency
@@ -34,13 +31,11 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-    none: false
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-    none: false
   prerelease: false
   type: :development
 - !ruby/object:Gem::Dependency
@@ -50,13 +45,11 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-    none: false
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-    none: false
   prerelease: false
   type: :development
 description: Create Semantic Diffs of Ruby source code based on the AST.
@@ -86,6 +79,7 @@ files:
 - doc/top-level-namespace.html
 - example/bar.rb
 - example/foo.rb
+- example/foo.rb-bar.rb.html
 - lib/smart_diff.rb
 - lib/smart_diff/htmlize.rb
 - lib/smart_diff/utils.rb
@@ -96,11 +90,12 @@ files:
 - web/nav.js
 - bin/smart_diff
 - README.md
-- foo.rb-bar.rb.html
+- Example.html
 - Rakefile
 homepage: http://github.com/edubkendo/smart_diff.git
 licenses:
 - GPL
+metadata: {}
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -109,22 +104,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
     - !ruby/object:Gem::Version
-      segments:
-      - 0
-      hash: 2
       version: '0'
-  none: false
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-  none: false
 requirements: []
 rubyforge_project:
-rubygems_version: 1.8.24
+rubygems_version: 2.1.3
 signing_key:
-specification_version: 3
+specification_version: 4
 summary: Ruby clone of psydiff
 test_files:
 - spec/smart_diff/htmlize_spec.rb