dnote 0.9 → 1.0

data/HISTORY

@@ -1,5 +1,17 @@
 = RELEASE HISTORY
 
+== 1.0 / 2009-10-25
+
+This relase adds support for arbitrary note labels.
+Any all-caps word followed by a colon will be
+picked-up. Common labels like TODO and FIXME are
+recognized  without the trailing ':'.
+
+Changes:
+
+* Added support for arbitrary labels.
+
+
 == 0.9 / 2009-10-10
 
 This release adds a syckle plugin and improves output.
@@ -11,6 +23,7 @@ Changes:
 * If output not specified, sends rdoc to stdout.
 * If no paths specified, will scan '**/*.rb'
 
+
 == 0.8 / 2009-10-09
 
 This is the initial release of DNote. DNote is a spin-off

data/README.rdoc

@@ -13,38 +13,83 @@ output formats for them.
 
 == SYNOPSIS
 
-Developer notes it the source code must be formatted as follows: 
+=== Note Structure
+
+D'Note scans for the common noting pattern used by develepors of many laguages of an all-caps label
+followed bt a colon. To be more specific, for D'Note to recogznie a note, it needs ot follow this 
+simple set of rules:
+
+1) Notes start with an all-caps label puctuated with a colon, followed by the note's text.
 
   # LABEL: description ...
 
-Any description that takes up more than one line must remain flush to the left
-margin (if the first line is flush to the left margin too) b/c RDoc will mistake
-of formatting the remaining lines as a +pre+ block it if is not. So...
+2) Specially designated notes can omit the colon. By default these are +TODO+,
++FIXME+ and +OPTIMIZE+.
 
-  # LABEL: ... description ...
-  # continue ...
+  # TODO description ...
 
-All consecutive notes must be separated by a blank lines.
+3) Any note that requires more than one line must remain flush to the left
+margin (the margin is set by the first line). This is done because RDoc will mistake
+the note for a <tt>&lt;pre&gt;</tt> block if it is indented.
 
   # LABEL: description ...
-  # 
-  # LABEL: description ...
-
-Without the blank line the second note will be taken to be part of the first.
+  # continue ...
 
-Alternately the whole note can be made a +pre+ block by indention. Then the
-layout if freed-form.
+4) An alternative to the limitation of the last rule is to indent the whole note, making it 
+a <tt>&lt;pre&gt;</tt> block. Then the text layout is free-form.
 
   # This is a description of something...
   #
   #   LABEL: description ...
-  #          continued ...
+  #          continue ...
+
+That's all there is to it, if I can convince the developers of RDoc to add recognize labels,
+we may eventually be able to relax the flush rule, which would be very nice.
+
+
+=== Generating Notes
+
+As you can see the commandline interface is quite straight-forward.
+
+  Usage: dnote [OPTIONS] path1 [path2 ...]
+   
+  OUTPUT FORMAT: (choose one)
+          --rdoc                       RDoc comment format
+          --markdown                   Markdown wiki format
+          --xml                        XML markup format
+          --html                       HTML markup format
+          --yaml                       YAML serialization format
+          --json                       JSON serialization format
+   
+  OTHER OPTIONS:
+          --label                      labels to collect
+      -t, --title [TITLE]              title to use in headers
+   
+  STANDARD OPTIONS:
+      -v, --verbose                    extra verbose output
+          --debug                      debug mode
+      -h, --help                       show this help information
+
+The default path is <tt>**/*.rb</tt> and the default format <tt>--rdoc</tt>. 
+Here is an example of DNote's current notes in RDoc format:
+
+  = Development Notes
+
+  == TODO
+
+  === file://lib/dnote/notes.rb
+
+  * TODO: Add ability to read header notes. They oftern
+  have a outline format, rather then the single line. (19)
+  * TODO: Need good CSS file. (22)
+  * TODO: Need XSL? (24)
+
+  === file://plug/syckle/services/dnote.rb
 
-With properly formatted notes, we then use the +dnote+ command line tool.
+  * TODO: Should this service be part of the +site+ cycle? (18)
 
-  $ dnote
+  (4 TODOs)
 
-And lo! Pretty output. See <tt>dnote --help</tt> for more options.
 
 
 == INSTALLATION

data/lib/dnote.rb

@@ -1,10 +1,12 @@
 require 'dnote/notes'
 
 module DNote
-  VERSION = "0.9"  #:till: VERSION = "<%= version %>"
+  VERSION = "1.0"  #:till: VERSION = "<%= version %>"
 
   def self.new(*args)
     Notes.new(*args)
   end
 end
 
+# TEST: This is a test of arbitraty note labels.
+

data/lib/dnote/notes.rb

@@ -125,42 +125,31 @@ module DNote
 
     # Gather and count notes. This returns two elements,
     # a hash in the form of label=>notes and a counts hash.
-    def parse
-      files = self.paths.map do |path|
-        if File.directory?(path)
-          Dir.glob(File.join(path, '**/*'))
-        else
-          Dir.glob(path)
-        end
-      end.flatten.uniq
 
-      #
+    def parse
       records, counts = [], Hash.new(0)
-
-      # iterate through files extracting notes
       files.each do |fname|
         next unless File.file?(fname)
-        #next unless fname =~ /\.rb$/      # TODO should this be done?
+        #next unless fname =~ /\.rb$/      # TODO: should this be done?
         File.open(fname) do |f|
-          line_no, save, text = 0, nil, nil
+          lineno, save, text = 0, nil, nil
           while line = f.gets
-            line_no += 1
-            labels.each do |label|
-              if line =~ /^\s*#\s*#{Regexp.escape(label)}[:]?\s*(.*?)$/
-                file = fname
-                text = ''
-                save = {'label'=>label,'file'=>file,'line'=>line_no,'note'=>text}
-                records << save
-                counts[label] += 1
-              end
-            end
-            if text
-              if line =~ /^\s*[#]{0,1}\s*$/ or line !~ /^\s*#/ or line =~ /^\s*#[+][+]/
-                text.strip!
-                text = nil
-                #records << save
-              else
-                text << line.gsub(/^\s*#\s*/,'')
+            lineno += 1
+            save = match_common(line, lineno, fname) || match_arbitrary(line, lineno, fname)
+            if save
+              #file = fname
+              text = save['note']
+              #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*#[+][+]/
+                  text.strip!
+                  text = nil
+                else
+                  text << ' ' << line.gsub(/^\s*#\s*/,'')
+                end
               end
             end
           end
@@ -172,6 +161,43 @@ module DNote
       @notes, @counts = notes, counts
     end
 
+    #
+    def files
+      @files ||= (
+        self.paths.map do |path|
+          if File.directory?(path)
+            Dir.glob(File.join(path, '**/*'))
+          else
+            Dir.glob(path)
+          end
+        end.flatten.uniq
+      )
+    end
+
+    #
+    def match_common(line, lineno, file)
+      rec = nil
+      labels.each do |label|
+        if md = /\#\s*#{Regexp.escape(label)}[:]?\s*(.*?)$/.match(line)
+          text = md[1]
+          rec = {'label'=>label,'file'=>file,'line'=>lineno,'note'=>text}
+        end
+      end
+      return rec
+    end
+
+    #
+    def match_arbitrary(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
+      end
+      return rec
+    end
+
     # Organize records in heirarchical form.
     #
     def organize(records)
@@ -302,7 +328,7 @@ module DNote
 
     #
     def to_json
-      require 'json'
+      require 'json'  # TODO: fallback to json_pure
       notes.to_json
     end
 

data/meta/version

@@ -1 +1 @@
-0.9
+1.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dnote
 version: !ruby/object:Gem::Version 
-  version: "0.9"
+  version: "1.0"
 platform: ruby
 authors: []
 
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-24 00:00:00 -04:00
+date: 2009-10-25 00:00:00 -04:00
 default_executable: 
 dependencies: []