mvz-dnote 1.7.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 98fb559fd41018e820045b6bc49f6d8bba90b0fb
+  data.tar.gz: 3d6ebc561fd714f6ff33ecb45f9e55396b8fb6c7
+SHA512:
+  metadata.gz: 571aec135e69a01abab0658f214f9ac0baa3913081598a5026e73f6660efc31f80c14b22b7291521f8e6a1c7be5fb3c88a862f4c86ac98e87351b9497c6b5975
+  data.tar.gz: 413450876f72af24fb04d3a81e62a86f28d459ac504931a5d8856eabe77d7638ad0f0e795b244a98ffc73460521fc5d45003db1aa718388ea07e118ab8f3a45a

data/COPYING.rdoc

@@ -0,0 +1,31 @@
+= COPYRIGHT NOTICES
+
+== DNote
+
+Copyright:: (c) 2006 Thomas Sawyer, Rubyworks
+License:: BSD-2-Clause
+Website:: http://rubyworks.github.com/tapout
+
+    Copyright 2006 Thomas Sawyer, Rubyworks. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+    AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/HISTORY.rdoc

@@ -0,0 +1,171 @@
+= RELEASE HISTORY
+
+
+== 1.7.0 / 2011-10-25
+
+This release finishes adding code context support to all formats. Use the `-c`
+option to set the number of lines to include. Note also that the rake task has
+been moved to `dnote/rake/dnotetask`.
+
+Changes:
+
+* Support code contexts in all formats.
+* Rake task moved to `dnote/rake/dnotetask`.
+
+
+== 1.6.1 / 2011-05-18
+
+Last release reused the `-c` option for context lines. This clobbered
+the shortcut option for `--custom`. To fix, this release capitalizes
+the custom shortcut to `-C`.
+
+Changes:
+
+* Capitalize custom shortcut option (-c becomes -C).
+
+
+== 1.6.0 / 2011-05-17
+
+This release adds code conext output. Select the number of
+context lines to display with the `-c` option. Currently
+only the HTML, YAML and JSON formats support context.
+
+This release also fixes the false note match that can arise when
+a class or module name with double-colons starts a comment line.
+We have changed the regex to ALWAYS REQUIRE a space after the
+label colon. Please make a note of it!
+
+Changes:
+
+* Add code context count option and output.
+* Regex changed to REQUIRE space after label colon.
+
+
+== 1.5.0 / 2010-11-27
+
+This release adds a `--url` option for defining a URL template
+string used in certain HTML/XML formats. In addition a parsing
+bug was corrected that limited some notes to one line.
+
+Changes:
+
+* Add support for configurable URLs.
+* Fix multi-line note parsing bug.
+
+
+== 1.4.0 / 2010-06-26
+
+This release adds auto-determination of marker based on file
+extension. This means DNote can now scan multiple file types
+in a single pass. The supported types are fairly small at this
+point, but cover the command cases and will expand in the future.
+The fallback marker is '#'. You can still force a particular
+marker using the --marker option.
+
+Changes:
+
+* Add support for automatic markers.
+
+
+== 1.3.1 / 2010-06-11
+
+This release fixes a simple bug. Some version of Ruby do not have
+the Enumerable#group_by method. This release provides it if it is
+missing. 
+
+Changes:
+
+* Bug fix, provide #group_by when it is not present.
+
+
+== 1.3.0 / 2010-06-04
+
+This release adds support for alternate comment markers. Simply
+supply the marker with the -m option.
+
+Changes:
+
+* Add support for languages other than Ruby.
+
+
+== 1.2.0 / 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.0 / 2010-02-06
+
+This relase primarily adjusts the way output it rendered
+underthehood. Serialization formats are rendered as
+before but markup formats now use Erb. In the process
+two new serialization formats have been added: soap and xoxo.
+
+Also, this release renames the lib/plugin directory to
+lib/plugins (plural) per the new convention of the latest
+Plugin gem. This only matters to Syckle users.
+
+Changes:
+
+* Add Soap and XOXO formats.
+* Add actual --output option.
+* Move lib/plugin to lib/plugins.
+
+
+== 1.0.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.0 / 2009-10-10
+
+This release adds a syckle plugin and improves output.
+
+Changes:
+
+* Add syckle plugin, based on old Notes plugin.
+* Improved HTML output (</div> tag should have been </ol>).
+* If output not specified, sends rdoc to stdout.
+* If no paths specified, will scan '**/*.rb'
+
+
+== 0.8.0 / 2009-10-09
+
+This is the initial release of DNote. DNote is a spin-off
+of a Syckle (formerlly Reap) plugin which scans source
+code and compiles a list of developer notes.
+
+Changes:
+
+* Happy Birthday!
+

data/README.rdoc

@@ -0,0 +1,113 @@
+= DNote
+
+* {Homepage}[http://rubyworks.github.com/dnote]
+* {Mailing List}[http://googlegroups.com/group/rubyworks-mailinglist]
+* {Source Code}[http://github.com/rubyworks/dnote]
+
+
+== DESCRIPTION
+
+Extract development notes from source code and generate some nice
+output formats for them.
+
+
+== SYNOPSIS
+
+=== Note Structure
+
+DNote scans for the common note patterns used by developers of many languages in the form of an
+all-caps labels followed by a colon. To be more specific, for DNote to recognize a note,
+it needs to follow this simple set of rules:
+
+1) Notes start with an all-caps label punctuated with a colon, followed by the note's text.
+
+  # LABEL: description ...
+
+2) 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 <code>pre</code> block if it is indented.
+
+  # LABEL: description ...
+  # continue ...
+
+3) An alternative to the previous limitation is to indent the whole note, making it 
+a <tt>&lt;pre&gt;</tt> block when rendered by RDoc. Then the text layout is free-form.
+
+  # This is a description of something...
+  #
+  #   LABEL: description ...
+  #          continue ...
+
+That's all there is to it, if I can convince the developers of RDoc to recognize labels,
+we may eventually be able to relax the flush rule too, which would be very nice.
+
+There is also a command-line option, <code>--no-colon</code>, which deactives the need for
+a colon after the note label. However this often produces false positives, so it's use is
+discouraged.
+
+
+=== Generating Notes
+
+As you can see the commandline interface is pretty straight-forward.
+
+  USAGE:
+
+    dnote [OPTIONS] path1 [path2 ...]
+   
+  OUTPUT FORMAT: (choose one)
+      -f, --format NAME                select a format [text]
+      -c, --custom FILE                use a custom ERB template
+          --file                       shortcut for text/file format
+          --list                       shortcut for text/list format
+   
+  OTHER OPTIONS:
+      -l, --label LABEL                labels to collect
+          --[no-]colon                 match labels with/without colon suffix
+      -m, --marker MARK                alternative remark marker
+      -u  --url TEMPLATE               url template for line entries (for HTML)
+      -x, --exclude PATH               exclude file or directory
+      -i, --ignore NAME                ignore based on any part of the pathname
+      -t, --title TITLE                title to use in header
+      -o, --output PATH                name of file or directory
+      -n, --dryrun                     do not actually write to disk
+          --debug                      debug mode
+   
+  COMMAND OPTIONS:
+      -T, --templates                  list available format templates
+      -h, --help                       show this help information
+
+The default path is <tt>**/*.rb</tt> and the default format is <tt>-f 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 often
+  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
+
+  * TODO: Should this service be part of the +site+ cycle? (18)
+
+  (4 TODOs)
+
+
+== INSTALLATION
+
+The usual RubyGem's command will do the trick.
+
+  $ sudo gem install dnote
+
+
+== COPYRIGHT
+
+Copyright (c) 2006 Thomas Sawyer, Rubyworks
+
+DNote is distributable in accordance with the terms of the *FreeBSD* license.
+
+See COPYING.rdoc for details.

data/bin/dnote

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

data/lib/dnote.rb

@@ -0,0 +1,4 @@
+require 'dnote/version'
+require 'dnote/session'
+
+# TEST: This is a test of an arbitrary label.

data/lib/dnote.yml

@@ -0,0 +1 @@
+lib/../.ruby

data/lib/dnote/core_ext.rb

@@ -0,0 +1,92 @@
+module Enumerable
+
+  # Taken from Ruby Facets.
+  def group_by #:yield:
+    #h = k = e = nil
+    r = Hash.new
+    each{ |e| (r[yield(e)] ||= []) << e }
+    r
+  end unless method_defined?(:group_by)
+
+end
+
+module DNote
+
+  # Extensions for String class.
+  # These methods are taken directly from Ruby Facets.
+  #
+  module String
+
+    # Provides a margin controlled string.
+    #
+    #   x = %Q{
+    #         | This
+    #         |   is
+    #         |     margin controlled!
+    #         }.margin
+    #
+    #
+    #   NOTE: This may still need a bit of tweaking.
+    #
+    #  CREDIT: Trans
+
+    def margin(n=0)
+      #d = /\A.*\n\s*(.)/.match( self )[1]
+      #d = /\A\s*(.)/.match( self)[1] unless d
+      d = ((/\A.*\n\s*(.)/.match(self)) ||
+          (/\A\s*(.)/.match(self)))[1]
+      return '' unless d
+      if n == 0
+        gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, '')
+      else
+        gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, ' ' * n)
+      end
+    end
+
+    # Preserves relative tabbing.
+    # The first non-empty line ends up with n spaces before nonspace.
+    #
+    #  CREDIT: Gavin Sinclair
+
+    def tabto(n)
+      if self =~ /^( *)\S/
+        indent(n - $1.length)
+      else
+        self
+      end
+    end
+
+    # Indent left or right by n spaces.
+    # (This used to be called #tab and aliased as #indent.)
+    #
+    #  CREDIT: Gavin Sinclair
+    #  CREDIT: Trans
+
+    def indent(n)
+      if n >= 0
+        gsub(/^/, ' ' * n)
+      else
+        gsub(/^ {0,#{-n}}/, "")
+      end
+    end
+
+    #
+    #
+    def tabset(n) 
+      i = lines.map do |line|
+        line.strip.empty? ? nil : line.index(/\S/)
+      end
+      x = i.compact.min
+      t = n - x.to_i
+      t = 0 if t < 0
+      indent(t)
+    end
+
+  end
+
+  class ::String #:nodoc:
+    include DNote::String
+  end
+
+end
+

data/lib/dnote/format.rb

@@ -0,0 +1,173 @@
+module DNote
+
+  # = Notes Formatter
+  #
+  #--
+  #   TODO: Need good CSS file.
+  #
+  #   TODO: Need XSL?
+  #++
+  class Format
+
+    require 'fileutils'
+    require 'erb'
+    require 'rexml/text'
+    require 'dnote/core_ext'
+
+    #DEFAULT_OUTPUT_DIR = "log/dnote"
+
+    EXTENSIONS = { 'text'=>'txt', 'soap'=>'xml', 'xoxo'=>'xml' }
+
+    #
+    attr :notes
+
+    #
+    attr_accessor :format
+
+    #
+    attr_accessor :subtype
+
+    #
+    attr_accessor :output
+
+    #
+    attr_accessor :template
+
+    #
+    attr_accessor :title
+
+    #
+    attr_accessor :dryrun
+
+    #
+    def initialize(notes, options={})
+      @notes   = notes
+      @format  = 'text'
+      @subtype = 'label'
+      @title   = "Developer's Notes"
+      @dryrun  = false
+      options.each{ |k,v| __send__("#{k}=", v) if v }
+      yield(self) if block_given?
+    end
+
+    #
+    def render
+      if notes.empty?
+        $stderr << "No #{notes.labels.join(', ')} notes.\n"
+      else
+        case format
+        when 'custom'
+          render_custom
+        else
+          render_template
+        end
+      end
+    end
+
+    # C U S T O M
+
+    #
+    def render_custom
+      #raise ArgumentError unless File.exist?(template)
+      result = erb(template)
+      publish(result)    
+    end
+
+    # T E M P L A T E
+
+    #
+    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)  
+    end
+
+  private
+
+    #
+    def erb(file)
+      scope = ErbScope.new(:notes=>notes, :title=>title)
+      scope.render(file)
+    end
+
+    #
+    def publish(result, fname=nil)
+      if output
+        write(result, fname)
+      else
+        puts(result)
+      end
+      $stderr << "(" + notes.counts.map{|l,n| "#{n} #{l}s"}.join(', ') + ")\n"
+    end
+
+    #
+    def write(result, fname=nil)
+      if output.to_s[-1,1] == '/' || File.directory?(output)
+        fmt  = format.split('/').first
+        ext  = EXTENSIONS[fmt] || fmt
+        file = File.join(output, fname || "notes.#{ext}")
+      else
+        file = output
+      end
+      if dryrun?
+        puts "mkdir: #{File.dirname(file)}"
+        puts "write: #{file}"
+      else
+        dir = File.dirname(file)
+        fu.mkdir(dir) unless File.exist?(dir)
+        File.open(file, 'w'){ |f| f << result }
+      end
+      return file
+    end
+
+    #
+    def dryrun?
+      @dryrun
+    end
+
+    #
+    def debug?
+      $DEBUG
+    end
+
+    #
+    def fu
+      @fu ||= (
+        if dryrun? and debug?
+          FileUtils::DryRun
+        elsif dryrun?
+          FileUtils::Noop
+        elsif debug?
+          FileUtils::Verbose
+        else
+          FileUtils
+        end
+      )
+    end
+
+    #
+    class ErbScope 
+      #
+      def initialize(data={})
+        @data = data
+      end
+      #
+      def render(file)
+        erb = ERB.new(File.read(file), nil, '<>')
+        erb.result(binding)
+      end
+      #
+      def h(string)
+        REXML::Text.normalize(string)
+      end
+      #
+      def method_missing(s, *a)
+        @data[s.to_sym]
+      end
+    end
+
+  end
+
+end
+