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

smart_diff 0.0.1 → 0.0.3

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