mvz-dnote 1.7.1

data/lib/dnote/note.rb

@@ -0,0 +1,150 @@
+module DNote
+
+  # The Note class encapsulates a single note made in a source file.
+  #
+  # Each note instance holds a reference, +notes+, to the set of notes
+  # being generated for a given session. This allows the note to access
+  # general options applicable to all notes.
+  class Note
+
+    # Number of lines to provide in source context.
+    #CONTEXT_DEPTH = 5
+
+    # Set of notes to which this note belongs.
+    attr :notes
+
+    # The file in which the note is made.
+    attr :file
+
+    # The type of note.
+    attr :label
+
+    # The line number of the note.
+    attr :line
+
+    # The verbatim text of the note.
+    attr :text
+
+    # Remark marker used in parsing the note.
+    attr :mark
+
+    # Contextual lines of code.
+    attr :capture
+
+    # Initialize new Note instance.
+    def initialize(notes, file, label, line, text, mark)
+      @notes   = notes
+
+      @file    = file
+      @label   = label
+      @line    = line
+      @text    = text.rstrip
+      @mark    = mark
+      @capture = []
+    end
+
+    # Convert to string representation.
+    def to_s
+      "#{label}: #{text}"
+    end
+
+    # Convert to string representation.
+    def to_str
+      "#{label}: #{text}"
+    end
+
+    # Remove newlines from note text.
+    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
+
+    # Convert to Hash.
+    #--
+    # TODO: Add +url+?
+    # TODO: Add +code+? Problem is that xml needs code in CDATA.
+    #++
+    def to_h
+      { 'label'=>label, 'text'=>textline, 'file'=>file, 'line'=>line }
+    end
+
+    # Convert to Hash, leaving the note text verbatim.
+    def to_h_raw
+      { 'label'=>label, 'text'=>text, 'file'=>file, 'line'=>line, 'code'=>code }
+    end
+
+    # Convert to JSON.
+    def to_json(*args)
+      to_h_raw.to_json(*args)
+    end
+
+    # Convert to YAML.
+    def to_yaml(*args)
+      to_h_raw.to_yaml(*args)
+    end
+
+    # Return line URL based on URL template. If no template was set, then
+    # returns the file.
+    def url
+      if notes.url
+        notes.url % [file, line]
+      else
+        file
+      end
+    end
+
+    #
+    def code
+      unindent(capture).join
+    end
+
+    # Is there code to show?
+    def code?
+      !capture.empty?
+    end
+
+=begin
+    # This isn't being used currently b/c the URL solution as deeemd better,
+    # but the code is here for custom templates.
+    def capture
+      @context ||= (
+        lines = file_cache(file) #.lines.to_a
+        count = line()
+        count +=1 while /^\s*#{mark}/ =~ lines[count]
+        lines[count, context_depth]
+      )
+    end
+
+    # Read in +file+, parse into lines and cache.
+    def file_cache(file)
+      @@file_cache ||= {}
+      @@file_cache[file] ||= File.read(file).lines.to_a
+    end
+=end
+
+    private
+
+    # Remove blank space from lines.
+    def unindent(lines)
+      dents = []
+      lines.each do |line|
+        if md = /^([\ ]*)/.match(line)
+          size = md[1].size
+          dents << md[1]
+        end
+      end
+      dent = dents.min{ |a,b| a.size <=> b.size }
+      lines.map do |line|
+        line.sub(dent, '')
+      end
+    end
+
+  end
+
+end

data/lib/dnote/notes.rb

@@ -0,0 +1,320 @@
+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 all-cap single word prefixes
+  # to a comment ending in a colon.
+  #
+  # Special labels do not require the colon. By default these are
+  # +TODO+, +FIXME+, +OPTIMIZE+, +THINK+ and +DEPRECATE+.
+  #
+  #--
+  #   TODO: Add ability to read header notes. They often
+  #         have a outline format, rather then the single line.
+  #++
+  class Notes
+    include Enumerable
+
+    # Default paths (all ruby scripts).
+    DEFAULT_PATHS  = ["**/*.rb"]
+
+    # Default note labels to look for in source code. (NOT CURRENTLY USED!)
+    DEFAULT_LABELS = ['TODO', 'FIXME', 'OPTIMIZE', 'THINK', 'DEPRECATE']
+
+    # Files to search for notes.
+    attr_accessor :files
+
+    # Labels to document. Defaults are: +TODO+, +FIXME+, +OPTIMIZE+ and +DEPRECATE+.
+    attr_accessor :labels
+
+    # Require label colon? Default is +true+.
+    attr_accessor :colon
+
+    # Specific remark marker (+nil+ for auto).
+    attr_accessor :marker
+
+    # Link template.
+    attr_accessor :url
+
+    # Number of lines of context to show.
+    attr_accessor :context
+
+    # New set of notes for give +files+ and optional special labels.
+    def initialize(files, options={})
+      @files   = [files].flatten
+      @labels  = [options[:labels] || DEFAULT_LABELS].flatten.compact
+      @colon   = options[:colon].nil? ? true : options[:colon]
+      @marker  = options[:marker] #|| '#'
+      @url     = options[:url]
+      @context = options[:context] || 0
+
+      @remark  = {}
+
+      parse
+    end
+
+    # Array of notes.
+    def notes
+      @notes
+    end
+
+    # Notes counts by label.
+    def 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
+
+    # Gather notes.
+    #--
+    # TODO: Play golf with Notes#parse.
+    #++
+    def parse
+      records = []
+      files.each do |fname|
+        next unless File.file?(fname)
+        #next unless fname =~ /\.rb$/      # TODO: should this be done?
+        mark = remark(fname)
+        lineno, note, text, capt = 0, nil, nil, nil
+        File.readlines(fname).each do |line|
+          #while line = f.gets
+            lineno += 1
+            note = match(line, lineno, fname)
+            if note
+              #file = fname
+              text = note.text
+              capt = note.capture
+              #note = {'label'=>label,'file'=>file,'line'=>line_no,'note'=>text}
+              records << note
+            else
+              if text
+                case line
+                when /^\s*#{mark}+\s*$/, /^\s*#{mark}\-\-/, /^\s*#{mark}\+\+/
+                  text.strip!
+                  text = nil
+                when /^\s*#{mark}/
+                  if text[-1,1] == "\n"
+                    text << line.gsub(/^\s*#{mark}\s*/,'')
+                  else
+                    text << "\n" << line.gsub(/^\s*#{mark}\s*/,'')
+                  end
+                else
+                  text.strip!
+                  text = nil
+                end
+              else
+                if line !~ /^\s*#{mark}/
+                  capt << line if capt && capt.size < context
+                end
+              end
+            end
+          #end
+        end
+      end
+
+      @notes  = records.sort
+    end
+
+    # Is this line a note?
+    def match(line, lineno, file)
+      if labels.empty?
+        match_general(line, lineno, file)
+      else
+        match_special(line, lineno, file)
+      end
+    end
+
+    # Match special notes.
+    def match_special(line, lineno, file)
+      rec = nil
+      labels.each do |label|
+        if md = match_special_regex(label, file).match(line)
+          text = md[1]
+          #rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
+          rec = Note.new(self, file, label, lineno, text, remark(file))
+        end
+      end
+      rec
+    end
+
+    #--
+    # TODO: ruby-1.9.1-p378 reports: `match': invalid byte sequence in UTF-8 
+    #++
+    def match_special_regex(label, file)
+      mark = remark(file)
+      if colon
+        /#{mark}\s*#{Regexp.escape(label)}[:]\s+(.*?)$/
+      else
+        /#{mark}\s*#{Regexp.escape(label)}[:]?\s+(.*?)$/
+      end
+    end
+
+    # Match notes that are labeled with a colon.
+    def match_general(line, lineno, file)
+      rec = nil
+      if md = match_general_regex(file).match(line)
+        label, text = md[1], md[2]
+        #rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
+        rec = Note.new(self, file, label, lineno, text, remark(file))
+      end
+      return rec
+    end
+
+    # Keep in mind that general non-colon matches have a higher potential
+    # of false positives.
+    def match_general_regex(file)
+      mark = remark(file)
+      if colon
+        /#{mark}\s*([A-Z]+)[:]\s+(.*?)$/
+      else 
+        /#{mark}\s*([A-Z]+)\s+(.*?)$/
+      end
+    end
+
+    # 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
+
+    # 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
+
+    # 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
+
+    # Convert to an array of hashes.
+    def to_a
+      notes.map{ |n| n.to_h }
+    end
+
+    # Same as #by_label.
+    def to_h
+      by_label
+    end
+
+    #
+    def remark(file)
+      @remark[File.extname(file)] ||= (
+        mark = guess_marker(file)
+        Regexp.escape(mark)
+      )
+    end
+
+    # Guess marker based on file extension. Fallsback to '#'
+    # if the extension is unknown.
+    #
+    # TODO: Continue to add comment types.
+    def guess_marker(file)
+      return @marker if @marker # forced marker
+      case File.extname(file)
+      when '.js', '.c', 'cpp', '.css'
+        '//'
+      when '.bas'
+        "'"
+      when '.sql', '.ada'
+        '--'
+      when '.asm'
+        ';'
+      else
+        '#'        
+      end
+    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
+