dnote 1.1.4 → 1.2.0

data/HISTORY

@@ -1,5 +1,34 @@
 = RELEASE HISTORY
 
+== 1.2 / 2010-02-18
+
+By request this release adds additional formats, allowing notes to be
+sorted by filename as well a label. In addition, paths can now be
+excluded from the search. To implement these changes it was necessary
+to makes some significant under-the-hood adjustments, and this required
+making some adjustments to the design of the templates and the
+command-line interface.
+
+If are using any of your own custom templates you will have to make
+adjustments accordingly --which basically entails exchanging +notes.each+
+for +notes.by_label_file.each+. Also, notice that the serialization formats
+have changed accordingly to match the improved underlying model.
+
+On the command-line, the format type itself is no longer used as the
+option name, e.g. "--yaml", but instead use "-f", e.g. "-f yaml". This
+opens DNote up to many more templates. Use "-T" to get a list of all
+template format available.
+
+Changes:
+
+* Improve underlying model by adding a Note class.
+* Add --exclude and --ignore options.
+* Add new formats and rename "gnu" formats to "text".
+* Use --format/-f to designate formats.
+* Renamed --template/-t option to --custom/-c.
+* Add --templates/-T to list all format templates.
+
+
 == 1.1 / 2010-02-06
 
 This relase primarily adjusts the way output it rendered

data/bin/dnote

@@ -1,4 +1,4 @@
 #!/usr/bin/env ruby
-require "dnote/command"
-DNote.run
+require "dnote"
+DNote::Session.main(*ARGV)
 

data/lib/dnote.rb

@@ -1,8 +1,7 @@
 module DNote
-  VERSION = "1.1.3"  #:till: VERSION = "<%= version %>"
+  VERSION = "1.2.0"  #:till: VERSION = "<%= version %>"
 
-  require 'dnote/notes'
-  require 'dnote/format'
+  require 'dnote/session'
 
   # NOTE: Toying with the idea of making DNote a class.
 

data/lib/dnote/format.rb

@@ -24,6 +24,9 @@ module DNote
     #
     attr_accessor :format
 
+    #
+    attr_accessor :subtype
+
     #
     attr_accessor :output
 
@@ -38,12 +41,12 @@ module DNote
 
     #
     def initialize(notes, options={})
-      @notes  = notes
-      @format = :gnu
-      @title  = "Developer's Notes"
-      options.each do |k,v|
-        __send__("#{k}=", v) if v
-      end
+      @notes   = notes
+      @format  = 'text'
+      @subtype = 'label'
+      @title   = "Developer's Notes"
+      options.each{ |k,v| __send__("#{k}=", v) if v }
+      yield(self) if block_given?
     end
 
     #
@@ -51,78 +54,32 @@ module DNote
       if notes.empty?
         $stderr << "No #{notes.labels.join(', ')} notes.\n"
       else
-        raise ArgumentError unless respond_to?("render_#{format}")
-        __send__("render_#{format}")
+        case format
+        when 'custom'
+          render_custom
+        else
+          render_template
+        end
       end
     end
 
-    # S E R I A L I Z A T I O N
-
-    def render_yaml
-      result = notes.to_yaml
-      publish(result)
-    end
-
-    def render_json
-      result = notes.to_json
-      publish(result)
-    end
-
-    # M L  M A R K U P
-
-    def render_soap
-      result = notes.to_soap
-      publish(result)
-    end
-
-    def render_xoxo
-      result = notes.to_xoxo
-      publish(result)
-    end
-
-    def render_xml
-      template = File.join(File.dirname(__FILE__), 'templates/xml.erb')
-      result = erb(template)
-      publish(result)
-    end
-
-    def render_html
-      template = File.join(File.dirname(__FILE__), 'templates/html.erb')
-      result = erb(template)
-      publish(result)
-    end
-
-    def render_index
-      template = File.join(File.dirname(__FILE__), 'templates/html.erb')
-      result = erb(template)
-      publish(result, 'index.html')
-    end
-
-    # W I K I  M A R K U P
-
-    def render_gnu
-      template = File.join(File.dirname(__FILE__), 'templates/gnu.erb')
-      result = erb(template)
-      publish(result)
-    end
+    # C U S T O M
 
-    def render_rdoc
-      template = File.join(File.dirname(__FILE__), 'templates/rdoc.erb')
-      result = erb(template)
-      publish(result)
-    end
-
-    def render_markdown
-      template = File.join(File.dirname(__FILE__), 'templates/markdown.erb')
+    #
+    def render_custom
+      #raise ArgumentError unless File.exist?(template)
       result = erb(template)
-      publish(result)
+      publish(result)    
     end
 
-    # C U S T O M  T E M P L A T E
+    # T E M P L A T E
 
-    def render_custom
+    #
+    def render_template
+      template = File.join(File.dirname(__FILE__), 'templates', "#{format}.erb")
+      raise "No such format - #{format}" unless File.exist?(template)
       result = erb(template)
-      publish(result)    
+      publish(result)  
     end
 
   private

data/lib/dnote/note.rb

@@ -0,0 +1,57 @@
+module DNote
+
+  #
+  class Note
+    attr :file
+    attr :label
+    attr :line
+    attr :text
+
+    def initialize(file, label, line, text)
+      @file  = file
+      @label = label
+      @line  = line
+      @text  = text.rstrip
+    end
+
+    #
+    def to_s
+      "#{label}: #{text}"
+    end
+
+    #
+    def to_str
+      "#{label}: #{text}"
+    end
+
+    #
+    def textline
+      text.gsub("\n", " ")
+    end
+
+    # Sort by file name and line number.
+    def <=>(other)
+      s = file <=> other.file
+      return s unless s == 0
+      line <=> other.line
+    end
+
+    def to_h
+      { 'label'=>label, 'text'=>textline, 'file'=>file, 'line'=>line }
+    end
+
+    def to_h_raw
+      { 'label'=>label, 'text'=>text, 'file'=>file, 'line'=>line }
+    end
+
+    def to_json(*args)
+      to_h_raw.to_json(*args)
+    end
+
+    def to_yaml(*args)
+      to_h_raw.to_yaml(*args)
+    end
+  end
+
+end
+

data/lib/dnote/notes.rb

@@ -1,15 +1,16 @@
 require 'pathname'
+require 'dnote/note'
 
 module DNote
 
   # = Developer Notes
   #
   # This class goes through you source files and compiles a list
-  # of any labeled comments. Labels are single word prefixes to
-  # a comment ending in a colon.
+  # of any labeled comments. Labels are all-cap single word prefixes
+  # to a comment ending in a colon.
   #
-  # By default the labels supported are TODO, FIXME, OPTIMIZE
-  # and DEPRECATE.
+  # Special labels do require the colon. By default these are +TODO+,
+  # +FIXME+, +OPTIMIZE+ and +DEPRECATE+.
   #
   #--
   #   TODO: Add ability to read header notes. They often
@@ -21,59 +22,58 @@ module DNote
     # Default paths (all ruby scripts).
     DEFAULT_PATHS  = ["**/*.rb"]
 
-    # Default note labels to look for in source code.
+    # Default note labels to look for in source code. (NOT CURRENTLY USED!)
     DEFAULT_LABELS = ['TODO', 'FIXME', 'OPTIMIZE', 'DEPRECATE']
 
-    # Paths to search.
-    attr_accessor :paths
+    # Files to search for notes.
+    attr_accessor :files
 
-    # Labels to document. Defaults are: TODO, FIXME, OPTIMIZE and DEPRECATE.
+    # Labels to document. Defaults are: +TODO+, +FIXME+, +OPTIMIZE+ and +DEPRECATE+.
     attr_accessor :labels
 
-    #
-    def initialize(paths, labels=nil)
-      @paths  = [paths  || DEFAULT_PATHS ].flatten
-      @labels = [labels || DEFAULT_LABELS].flatten
+    # Require label colon? Default is +true+.
+    attr_accessor :colon
+
+    # New set of notes for give +files+ and optional special labels.
+    def initialize(files, options={})
+      @files  = [files].flatten
+      @labels = [options[:labels]].flatten.compact
+      @colon  = options[:colon].nil? ? true : options[:colon]
       parse
     end
 
-    #
+    # Array of notes.
     def notes
       @notes
     end
 
-    #
+    # Notes counts by label.
     def counts
-      @counts
+      @counts ||= (
+        h = {}
+        by_label.each do |label, notes|
+          h[label] = notes.size
+        end
+        h
+      )
     end
 
-    #
+    # Iterate through notes.
     def each(&block)
       notes.each(&block)
     end
 
-    #
+    # No notes?
     def empty?
       notes.empty?
     end
 
-    #
-    def labels=(labels)
-      @labels = (
-        case labels
-        when String
-          labels.split(/[:;,]/)
-        else
-          labels = [labels].flatten.compact.uniq.map{ |s| s.to_s }
-        end
-      )
-    end
-
-    # Gather and count notes. This returns two elements,
-    # a hash in the form of label=>notes and a counts hash.
-
+    # Gather notes.
+    #--
+    # TODO: Play gold with Notes#parse.
+    #++
     def parse
-      records, counts = [], Hash.new(0)
+      records = []
       files.each do |fname|
         next unless File.file?(fname)
         #next unless fname =~ /\.rb$/      # TODO: should this be done?
@@ -81,13 +81,12 @@ module DNote
           lineno, save, text = 0, nil, nil
           while line = f.gets
             lineno += 1
-            save = match_common(line, lineno, fname) || match_arbitrary(line, lineno, fname)
+            save = match(line, lineno, fname)
             if save
               #file = fname
-              text = save['note']
+              text = save.text
               #save = {'label'=>label,'file'=>file,'line'=>line_no,'note'=>text}
               records << save
-              counts[save['label']] += 1
             else
               if text
                 if line =~ /^\s*[#]{0,1}\s*$/ or line !~ /^\s*#/ or line =~ /^\s*#[+][+]/
@@ -105,98 +104,160 @@ module DNote
           end
         end
       end
-      # organize the notes
-      notes = organize(records)
-      #
-      @notes, @counts = notes, counts
+
+      @notes  = records.sort
     end
 
     #
-    def files
-      @files ||= (
-        [self.paths].flatten.map do |path|
-          if File.directory?(path)
-            Dir.glob(File.join(path, '**/*'))
-          else
-            Dir.glob(path)
-          end
-        end.flatten.uniq
-      )
+    def match(line, lineno, file)
+      if labels.empty?
+        match_general(line, lineno, file)
+      else
+        match_special(line, lineno, file)
+      end
     end
 
-    # TODO: ruby-1.9.1-p378 reports: notes.rb:131:in `match': invalid byte sequence in UTF-8 
-    def match_common(line, lineno, file)
+    # Match special notes.
+    def match_special(line, lineno, file)
       rec = nil
       labels.each do |label|
-        if md = /\#\s*#{Regexp.escape(label)}[:]?\s*(.*?)$/.match(line)
+        if md = match_special_regex(label).match(line)
           text = md[1]
-          rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
+          #rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
+          rec = Note.new(file, label, lineno, text)
         end
       end
-      return rec
+      rec
     end
 
-    #
-    def match_arbitrary(line, lineno, file)
+    #--
+    # TODO: ruby-1.9.1-p378 reports: `match': invalid byte sequence in UTF-8 
+    #++
+    def match_special_regex(label)
+      if colon
+        /\#\s*#{Regexp.escape(label)}[:]\s*(.*?)$/
+      else
+        /\#\s*#{Regexp.escape(label)}[:]?\s*(.*?)$/
+      end
+    end
+
+    # Match notes that are labeled with a colon.
+    def match_general(line, lineno, file)
       rec = nil
-      labels.each do |label|
-        if md = /\#\s*([A-Z]+)[:]\s*(.*?)$/.match(line)
-          label, text = md[1], md[2]
-          rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
-        end
+      if md = match_general_regex.match(line)
+        label, text = md[1], md[2]
+        #rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
+        rec = Note.new(file, label, lineno, text)
       end
       return rec
     end
 
-    # Organize records in heirarchical form.
     #
-    def organize(records)
-      orecs = {}
-      records.each do |record|
-        label = record['label']
-        file  = record['file']
-        line  = record['line']
-        note  = record['note'].rstrip
-        orecs[label] ||= {}
-        orecs[label][file] ||= []
-        orecs[label][file] << [line, note]
+    def match_general_regex
+      if colon
+        /\#\s*([A-Z]+)[:]\s+(.*?)$/
+      else
+        /\#\s*([A-Z]+)[:]?\s+(.*?)$/
       end
-      orecs
     end
 
-    #
-    def to(format)
-      __send__("to_#{format}")
+    # Organize notes into a hash with labels for keys.
+    def by_label
+      @by_label ||= (
+        list = {}
+        notes.each do |note|
+          list[note.label] ||= []
+          list[note.label] << note
+          list[note.label].sort #!{ |a,b| a.line <=> b.line }
+        end
+        list
+      )
     end
 
-    #
-    def to_yaml
-      require 'yaml'
-      notes.to_yaml
+    # Organize notes into a hash with filename for keys.
+    def by_file
+      @by_file ||= (
+        list = {}
+        notes.each do |note|
+          list[note.file] ||= []
+          list[note.file] << note
+          list[note.file].sort! #!{ |a,b| a.line <=> b.line }
+        end
+        list
+      )
     end
 
-    #
-    def to_json
-      begin
-        require 'json'
-      rescue LoadError
-        require 'json_pure'
-      end
-      notes.to_json
+    # Organize notes into a hash with labels for keys, followed
+    # by a hash with filename for keys.
+    def by_label_file
+      @by_label ||= (
+        list = {}
+        notes.each do |note|
+          list[note.label] ||= {}
+          list[note.label][note.file] ||= []
+          list[note.label][note.file] << note
+          list[note.label][note.file].sort! #{ |a,b| a.line <=> b.line }
+        end
+        list
+      )
+    end
+
+    # Organize notes into a hash with filenames for keys, followed
+    # by a hash with labels for keys.
+    def by_file_label
+      @by_file ||= (
+        list = {}
+        notes.each do |note|
+          list[note.file] ||= {}
+          list[note.file][note.label] ||= []
+          list[note.file][note.label] << note
+          list[note.file][note.label].sort! #{ |a,b| a.line <=> b.line }
+        end
+        list
+      )
     end
 
-    # Soap envelope XML.
-    def to_soap
-      require 'soap/marshal'
-      SOAP::Marshal.marshal(notes)
+    # Convert to an array of hashes.
+    def to_a
+      notes.map{ |n| n.to_h }
     end
 
-    # XOXO microformat.
-    def to_xoxo
-      require 'xoxo'
-      notes.to_xoxo
+    # Same as #by_label.
+    def to_h
+      by_label
     end
 
+    # Convert to array of hashes then to YAML.
+    #def to_yaml
+    #  require 'yaml'
+    #  to_a.to_yaml
+    #end
+
+    # Convert to array of hashes then to JSON.
+    #def to_json
+    #  begin
+    #    require 'json'
+    #  rescue LoadError
+    #    require 'json_pure'
+    #  end
+    #  to_a.to_json
+    #end
+
+    # Convert to array of hashes then to a SOAP XML envelope.
+    #def to_soap
+    #  require 'soap/marshal'
+    #  SOAP::Marshal.marshal(to_a)
+    #end
+
+    # XOXO microformat.
+    #--
+    # TODO: Would to_xoxo be better organized by label and or file?
+    #++
+    #def to_xoxo
+    #  require 'xoxo'
+    #  to_a.to_xoxo
+    #end
+
   end
 
 end