docbook_files 0.4.0 → 0.5.0

data/Gemfile

@@ -3,14 +3,22 @@ source "http://rubygems.org"
 gem "libxml-ruby", :require => 'xml'
 gem "term-ansicolor"
 gem "wand"
-gem "json"
+gem "zucker"
+gem "json", :platforms => :ruby_18
+gem "win32console", :platforms => :mingw
 
 group :development do
   gem "bones"
-  gem 'turn'
   gem 'rspec'
   gem 'guard'
-  gem 'rb-fsevent'
-  gem 'growl_notify'
   gem 'guard-rspec'
 end
+group :darwin do
+  gem 'rb-fsevent', :require => false
+  gem 'growl_notify', :require => false
+end
+group :linux do
+  gem 'rb-inotify', :require => false
+  gem 'libnotify', :require => false
+end
+

data/Gemfile.lock

@@ -1,12 +1,12 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    ansi (1.3.0)
     bones (3.7.1)
       little-plugger (>= 1.1.2)
       loquacious (>= 1.8.1)
       rake (>= 0.8.7)
     diff-lcs (1.1.3)
+    ffi (1.0.9)
     growl_notify (0.0.3)
       rb-appscript
     guard (0.8.4)
@@ -14,6 +14,7 @@ GEM
     guard-rspec (0.5.0)
       guard (>= 0.8.4)
     json (1.6.1)
+    libnotify (0.5.7)
     libxml-ruby (2.2.2)
     little-plugger (1.1.2)
     loquacious (1.9.0)
@@ -21,6 +22,8 @@ GEM
     rake (0.9.2)
     rb-appscript (0.6.1)
     rb-fsevent (0.4.3.1)
+    rb-inotify (0.8.8)
+      ffi (>= 0.5.0)
     rspec (2.6.0)
       rspec-core (~> 2.6.0)
       rspec-expectations (~> 2.6.0)
@@ -32,11 +35,10 @@ GEM
     safe_shell (1.0.1)
     term-ansicolor (1.0.7)
     thor (0.14.6)
-    turn (0.8.3)
-      ansi
     wand (0.4)
       mime-types
       safe_shell (~> 1.0.0)
+    zucker (11)
 
 PLATFORMS
   ruby
@@ -47,9 +49,12 @@ DEPENDENCIES
   guard
   guard-rspec
   json
+  libnotify
   libxml-ruby
   rb-fsevent
+  rb-inotify
   rspec
   term-ansicolor
-  turn
   wand
+  win32console
+  zucker

data/History.txt

@@ -1,3 +1,13 @@
+== 0.5.0 / 2011-10-19
+
+* A file can now manage multiple inclusions and/or references.
+* The YAML and JSON output contains now two sections, hierarchy and  details, just like the terminal output.
+* The details contain new fields for multiple references: includes, included_by and references, referenced_by
+
+* Minor changes
+** Removed JSON dependency. It is used when available.
+** Color support is now optional on Windows
+
 == 0.4.0 / 2011-10-14
 
 * Added JSON and YAML output formats

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2011 Rainer Volz
+
+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

@@ -29,29 +29,41 @@ If you don't like the screen output or want to integrate docbook_file into a cer
 
     docbook_files --outputformat=yaml myproject.xml
 
-The result is printed to STDOUT. The structure returned is equivalent to the normal terminal output, except that you always get the details. The structure returned is an array, where each entry contains the following key-value pairs: 
-
- * type - file type (main, inc-luded, or ref-erenced)
- * name - file name
- * full_name - path relative to the main file
- * level - the level in the file hierarchy, starting with 0
- * parent - parent file that included or referenced this file
- * status - error status: 0 = ok, 1 = file not found, 2 = processing error (see error_string)
- * error_string - contains an error message, if status > 0
- * namespace - XML namespace, if applicable
- * version - XML version attribute, of applicable
- * docbook - true for DocBook 5 files, else false
- * tag - start tag for XML files (chapter, book, article ...)  
- * ts - file modification time
- * size - fiel size in byte
- * checksum - SHA1 checksum
- * mime - MIME type
- 
+The result is printed to STDOUT. The structure returned is equivalent to the normal terminal output, except that you always get the details. 
+
+ * hierarchy - an array of entries for each step in the file hierarchy
+ ** type - file type (main, inc-luded, or ref-erenced)
+ ** name - file name
+ ** path - path relative to the main file
+ ** status - error status: 0 = ok, 1 = file not found, 2 = processing error (see error_string)
+ ** size - file size in bytes
+ ** level - the level in the file hierarchy, starting with 0
+
+ * details - an array of entries for each file used in the hierarchy
+ ** name - file name
+ ** path - path relative to the main file
+ ** status - error status: 0 = ok, 1 = file not found, 2 = processing error (see error_string)
+ ** error_string - contains an error message, if status > 0
+ ** namespace - XML namespace, if applicable
+ ** version - XML version attribute, if applicable
+ ** docbook - true for DocBook 5 files, else false
+ ** tag - start tag for XML files (chapter, book, article ...)  
+ ** ts - file modification time
+ ** size - file size in byte
+ ** checksum - SHA1 checksum
+ ** mime - MIME type
+ ** includes - files that are included by this file, an array of file names
+ ** included_by - files that include this file, an array of file names
+ ** references - files that are referenced by this file, an array of file names
+ ** referenced_by - files that reference this file, an array of file names 
+
 
 Requirements
 ------------
 
 * libxml2
+* json (optional, if you want JSON output on Ruby 1.8)
+* win32console (optional, if you want color support on MS Windows)
 
 Install
 -------

data/Rakefile

@@ -21,5 +21,19 @@ Bones {
   depend_on    'libxml-ruby'
   depend_on    'term-ansicolor'
   depend_on    'wand'
-  depend_on    'json'
+  depend_on    'zucker'
+  depend_on    'rspec', :development => true
+  gem.extras[:license] = 'MIT'
+  gem.extras[:post_install_message] = <<-POST_INSTALL_MSG
+
+Please note:
+
+- docbook_files uses color to mark problematic files.
+On Windows, you should additionally install the gem 'win32console'
+to enable color output in the terminal.
+
+- JSON output is optional for Ruby 1.8. Please install the gem 'json'
+if you are running Ruby 1.8 and want JSON output.
+
+POST_INSTALL_MSG
 }

data/lib/docbook_files/app.rb

@@ -2,21 +2,48 @@
 
 require 'optparse'
 require 'yaml'
-require 'json'
-require 'term/ansicolor'
+require 'zucker/env'
 
-class String
-  include Term::ANSIColor
+# Windows (RubyInstaller) needs the additional gem.
+# If not present create dummies for the color routines.
+if OS.windows?
+  begin
+    require 'win32console'
+    require 'term/ansicolor'
+    class String
+      include Term::ANSIColor
+    end
+  rescue LoadError
+    class String
+      def red; self; end
+      def green; self; end
+      def magenta; self; end
+      def bold; self; end
+    end
+  end
+else
+  require 'term/ansicolor'
+  class String
+    include Term::ANSIColor
+  end
 end
   
 module DocbookFiles
   
   # Create a new instance of App, and run the +docbook_files+ application given
-  # the command line _args_.
+  # the command line _args_. Check also for JSON availability.
   #
   def self.run( args = nil )
     args ||= ARGV.dup.map! { |v| v.dup }
-    ::DocbookFiles::App.new.run args
+    opts = {}
+    # For Windows and/or Ruby 1.8
+    begin
+      require 'json'      
+      opts[:json_available] = true
+    rescue LoadError
+      opts[:json_available] = false
+    end    
+    ::DocbookFiles::App.new(opts).run args
   end
 
   ##
@@ -28,6 +55,14 @@ module DocbookFiles
   # * 2 - processing error
   #
   class App
+
+    # Replacement for empty values
+    EMPTYVAL = '-'
+
+    # Replacement for monstrously large files sizes
+    XXL_SIZE = "XXL"
+    
+    # Help banner
     @@banner = <<EOB
 docbook_files, Version #{DocbookFiles::VERSION}
 
@@ -37,6 +72,7 @@ Files with problems (not found, invalid ...) are marked red.
 Usage: docbook_files [options] <DOCBOOK-FILE>
 EOB
 
+    # Initialize options and reset the FileData storage
     def initialize(opts = {})
       opts[:stdout] ||= $stdout
       opts[:stderr] ||= $stderr
@@ -45,22 +81,28 @@ EOB
       @stderr = opts[:stderr]
       @opts[:output_format] ||= :screen
       @opts[:details] ||= false
-      @props = [:name, :full_name, :namespace, :docbook,
-                :version, :tag, :parent, :status, :ts, :size, :checksum, :mime, :error_string]
+      @opts[:json_available] ||= opts[:json_available]
+      @props = [:name, :path, :status, :size]
+      FileData.reset()
     end
 
     def run(args)
       opts = OptionParser.new
       opts.on('--details','List file details') {|val| @opts[:details] = true}
-      opts.on('--outputformat=yaml|json',['json','yaml'],
+      opts.on('--outputformat=yaml|json',['yaml','json'],
               'Return the result in YAML or JSON format') {|format|
         case
         when format == 'yaml'
           @opts[:output_format] = :yaml
         when format == 'json'
-          @opts[:output_format] = :json
+          if @opts[:json_available]
+            @opts[:output_format] = :json
+          else
+            @stderr.puts "Error: JSON not available. Please install the json gem first."
+            exit 1
+          end
         else
-          @stderr.puts "Warning: Unknown output format #{format}. Using screen output.".orange
+          @stderr.puts "Error: Unknown output format #{format}."
         end
       }        
       opts.banner = @@banner
@@ -83,6 +125,7 @@ EOB
       begin
         dbf = DocbookFiles::Docbook.new(rest[0])
         table = dbf.list_as_table(@props)
+        files = FileData.files
       rescue => exc
         @stderr.puts "Something unexpected happend while docbook_files was running ..."
         @stderr.puts exc.inspect.red
@@ -91,27 +134,29 @@ EOB
       unless table.nil?
         case @opts[:output_format]
         when :json
-          mpath = table[0][:full_name]
-          ntable = table.map{|t|
-            t[:full_name] = relative2main(t[:full_name], mpath)
-            t
-          }
-          @stdout.puts ntable.to_json
+          out = {:hierarchy => table, :details => files2table(files)}
+          @stdout.puts out.to_json
         when :yaml
-          mpath = table[0][:full_name]
-          ntable = table.map{|t|
-            t[:full_name] = relative2main(t[:full_name], mpath)
-            t
-          }
-          YAML.dump(ntable,@stdout)
+          out = {:hierarchy => table, :details => files2table(files)}
+          YAML.dump(out,@stdout)
         else
-          output(table)
+          output_hierarchy(table)
+          output_details(files) if @opts[:details]        
         end
       end
     end
 
-    # Terminal output to @stdout
-    def output(table)
+    # Transform the files into something YAML/JSON can handle
+    def files2table(files)
+      files.map { |f|
+        f.to_hash([:name, :path, :status, :error_string, :namespace,
+                   :version, :docbook, :tag, :ts, :size, :checksum,
+                   :mime, :includes, :included_by, :references, :referenced_by])
+      }
+    end
+        
+    # Terminal output for file hierarchy
+    def output_hierarchy(table)
       output_string = "%3d %-60s %4s %10s" 
       @stdout.puts
       @stdout.puts 'File Hierarchy'.bold
@@ -122,7 +167,7 @@ EOB
       sum_xml_err = 0
       table.each do |t|
         output = output_string % [t[:level],
-                                  format_name(t[:level],t[:full_name],table[0][:full_name]),
+                                  format_name(t[:level],t[:path]),
                                   t[:type].to_s,
                                   format_size(t[:size])]
         sum_size += t[:size]
@@ -145,36 +190,44 @@ EOB
         summary += " #{sum_xml_err} file(s) with errors.".red
       end
       @stdout.puts summary
-      if @opts[:details]
-        @stdout.puts
-        @stdout.puts "Details".bold
-        table.each do |t|
-          fname = format_name(0,t[:full_name],table[0][:full_name])
-          @stdout.puts "File: %s" % [((t[:status] == FileData::STATUS_OK) ? fname : fname.red)]
-          if (t[:type] == FileData::TYPE_MAIN)
-            @stdout.puts "Main file"
-          elsif (t[:type] == FileData::TYPE_INCLUDE)
-            @stdout.puts "Included by: %s" % [t[:parent]]
+    end
+
+    # Print the FileData representation to the terminal
+    def output_details(files)      
+      @stdout.puts
+      @stdout.puts "Details".bold
+      files.each do |t|
+        fname = t.path
+        @stdout.puts "File: %s" % [((t.status == FileData::STATUS_OK) ? fname : fname.red)]
+        @stdout.puts "Includes: %s" % [format_fds(t.includes)] unless t.includes.empty?
+        @stdout.puts "Included by: %s" % [format_fds(t.included_by)] unless t.included_by.empty?
+        @stdout.puts "References: %s" % [format_fds(t.references)] unless t.references.empty?
+        @stdout.puts "Referenced by: %s" % [format_fds(t.referenced_by)] unless t.referenced_by.empty?
+        unless t.status == FileData::STATUS_NOT_FOUND
+          # show that part only if file exists
+          @stdout.puts "Size: %s (%d)" % [format_size(t.size),t.size]
+          if (t.docbook)
+            @stdout.puts "Type: DocBook, Version #{t.version}, Tag: #{t.tag}"
           else
-            @stdout.puts "Referenced by: %s" % [t[:parent]]
-          end
-          unless t[:status] == FileData::STATUS_NOT_FOUND
-            # show that part only if file exists
-            @stdout.puts "Size: %s (%d)" % [format_size(t[:size]),t[:size]]
-            if (t[:docbook])
-              @stdout.puts "Type: DocBook, Version #{t[:version]}, Tag: #{t[:tag]}"
-            else
-              @stdout.puts "MIME: #{val_s(t[:mime])}"
-            end
-            @stdout.puts "Timestamp: %s" % [t[:ts]]
-            @stdout.puts "Checksum: %s" % [t[:checksum]]
+            @stdout.puts "MIME: #{val_s(t.mime)}"
           end
-          @stdout.puts "Error: %s" % [t[:error_string].to_s.red] unless (t[:error_string].nil?)            
-          @stdout.puts
+          @stdout.puts "Timestamp: %s" % [t.ts]
+          @stdout.puts "SHA1: %s" % [t.checksum]
         end
+        @stdout.puts "Error: %s" % [t.error_string.to_s.red] unless (t.error_string.nil?)            
+        @stdout.puts
       end
     end
 
+    
+    # Format a list of FileDatas
+    def format_fds(fds)
+      if (fds.nil? || fds.empty?)
+        EMPTYVAL
+      else
+        fds.map {|p| p.path}.join ','
+      end
+    end
 
     # Format the filename to indicate the level in the hierarchy.
     # Indentation = two spaces per level.
@@ -183,9 +236,8 @@ EOB
     # relative part of the path is shown, else the full path.
     # If the resulting string is too long for display it is shortened.
     #
-    def format_name(level, full_name, main_name)
-      nname = relative2main(full_name, main_name)
-      lnname = '  '*level+nname
+    def format_name(level, full_name)
+      lnname = '  '*level+full_name
       if (lnname.length > 60)
         lnname[0..3]+'...'+lnname[-54,lnname.length-1]
       else
@@ -193,18 +245,6 @@ EOB
       end
     end
 
-    # Try to find the path of _file_name_ that is relative to the _main file_.
-    # If there is no common part return the _file_name_.
-    def relative2main(file_name,main_name)
-      main_dir = File.dirname(main_name)
-      md = file_name.match("^#{main_dir}/")
-      if md.nil?
-        file_name
-      else
-        md.post_match
-      end
-    end
-
     # :stopdoc:
     KB = 1024
     MB = 1048576
@@ -217,7 +257,7 @@ EOB
     # Sizes >= 1PB will return 'XXL'
     def format_size(sz)
       if (emptyval?(sz))
-        '-'
+        EMPTYVAL
       else
         case
         when sz < KB then  "#{sz}B"
@@ -226,18 +266,14 @@ EOB
         when sz >= GB && sz < TB then "#{sz/GB}GB"
         when sz >= TB && sz < PB then "#{sz/TB}TB"
         else
-          "XXL"
+          XXL_SIZE
         end
       end
     end
 
-    # Return a string for the value, '<>' if there is none.
+    # Return a string for the value, '-' if there is none.
     def val_s(val)
-      if emptyval?(val)
-        '-'
-      else
-        val.to_s
-      end
+      emptyval?(val) ? EMPTYVAL : val.to_s
     end
 
     # Check whether the value is nil or empty.
@@ -245,12 +281,9 @@ EOB
       if val.nil?
         true
       else
-        if (val.class == String)
-          val.empty?
-        else
-          false
-        end
+        (val.class == String) ? val.empty? : false
       end
     end
+    
   end
 end