mvz-dnote 1.7.2 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: eac8890fe30005d8b91d2435f22b6b147eb824e3
-  data.tar.gz: 3095d7ed25f4a5bcf188c8d678a01567b8588934
+SHA256:
+  metadata.gz: 8f69fc38b3682fab8db2aa937fcde974c166e74e0a72c7ce3fef709f9660fde7
+  data.tar.gz: f26dac2be30677f1ce05be309e4b41f178988dd926512fe534168fe4a5e44702
 SHA512:
-  metadata.gz: 9d4b828d589ed5157db324540356362017e3be0f6cace8cedc548be8a5673da817d2e0daa91f8cf8cbd167ac03ecda97641a34e06177ae7d58316a7a19130d75
-  data.tar.gz: a7e26ab03120551110e03e5a81154b7aa6064c6e70ae10d70a4b64eb03cf1b925ab6e41250f370fad735bd7227361683292bc29118ac578e46e681f62573a09a
+  metadata.gz: df50e819949330f599cdd53ecba7ef7751f4908336e7c26d9be747ea33f3144e465c993e5318bc653aaee70ba8259b70d73c1f0dc0313eb5de2f6cf1bbbc665e
+  data.tar.gz: 69256f599091253c91a76f36681960160cf08c0e6a6eb8bfdf811750ee1a9bc9b681d69212998f220853581c93e846249a215b433a3f3349c92a99e4d15165ad

data/HISTORY.rdoc

@@ -1,5 +1,23 @@
 = RELEASE HISTORY
 
+== 1.10.0 / 2022-04-10
+
+* Add support for Ruby 3.1
+* Drop support for Ruby 2.5
+* Loosen development dependencies
+
+== 1.9.0 / 2021-09-17
+
+* Drop support for Ruby 2.3 and 2.4
+* Officially support Ruby 2.7 and 3.0
+* Update development dependencies
+* Improve code quality
+
+== 1.8.0 / 2018-12-29
+
+* Officially support CRuby 2.5 and 2.6
+* Drop support for CRuby 2.1 and 2.2
+
 == 1.7.2 / 2017-03-05
 
 * Support CRuby 2.4

data/README.md

@@ -0,0 +1,116 @@
+# DNote
+
+* [Homepage](http://rubyworks.github.com/dnote)
+* [Mailing List](http://googlegroups.com/group/rubyworks-mailinglist)
+* [Source Code](http://github.com/rubyworks/dnote)
+
+[![Gem Version](https://badge.fury.io/rb/mvz-dnote.svg)](https://badge.fury.io/rb/mvz-dnote)
+[![Maintainability](https://api.codeclimate.com/v1/badges/608621bbad5de3a98e3b/maintainability)](https://codeclimate.com/github/mvz/dnote/maintainability)
+
+## 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 `pre` block if it is indented.
+
+        # LABEL: description ...
+        # continue ...
+
+3. An alternative to the previous limitation is to indent the whole note, making it
+a `<pre>` 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, `--no-colon`, which deactives the need for
+a colon after the note label. However this often produces false positives, so its 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 `**/*.rb` and the default format is `-f text`.
+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 rubygems command will do the trick.
+
+    $ gem install mvz-dnote
+
+
+## COPYRIGHT
+
+Copyright (c) 2006 Thomas Sawyer, Rubyworks
+
+Copyright (c) 2017-2018 Matijs van Zuijlen
+
+DNote is distributable in accordance with the terms of the *FreeBSD* license.
+
+See COPYING.rdoc for details.

data/bin/dnote

@@ -1,4 +1,13 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 require "dnote"
-DNote::Session.main(*ARGV)
 
+begin
+  DNote::Session.main(*ARGV)
+rescue StandardError => e
+  raise e if $DEBUG
+
+  puts e
+  exit 1
+end

data/lib/dnote/core_ext.rb

@@ -1,92 +1,36 @@
-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
+# frozen_string_literal: true
 
 module DNote
-
   # Extensions for String class.
   # These methods are taken directly from Ruby Facets.
   #
   module StringExt
-
-    # 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.
+    # Indent left or right by num spaces.
     # (This used to be called #tab and aliased as #indent.)
     #
     #  CREDIT: Gavin Sinclair
     #  CREDIT: Trans
 
-    def indent(n)
-      if n >= 0
-        gsub(/^/, ' ' * n)
+    def indent(num)
+      if num >= 0
+        gsub(/^/, " " * num)
       else
-        gsub(/^ {0,#{-n}}/, "")
+        gsub(/^ {0,#{-num}}/, "")
       end
     end
 
-    #
-    #
-    def tabset(n) 
+    def tabset(num)
       i = lines.map do |line|
         line.strip.empty? ? nil : line.index(/\S/)
       end
       x = i.compact.min
-      t = n - x.to_i
+      t = num - x.to_i
       t = 0 if t < 0
       indent(t)
     end
-
   end
-
-  class ::String #:nodoc:
-    include DNote::StringExt
-  end
-
 end
 
+String.class_eval do
+  include DNote::StringExt
+end

data/lib/dnote/format.rb

@@ -1,5 +1,6 @@
-module DNote
+# frozen_string_literal: true
 
+module DNote
   # = Notes Formatter
   #
   #--
@@ -8,55 +9,35 @@ module DNote
   #   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?
+    require "fileutils"
+    require "erb"
+    require "rexml/text"
+    require "dnote/core_ext"
+
+    EXTENSIONS = {"text" => "txt", "soap" => "xml", "xoxo" => "xml"}.freeze
+
+    attr_reader :notes, :format, :output, :template, :title, :dryrun
+
+    def initialize(notes,
+                   format: "text",
+                   title: "Developer's Notes",
+                   template: nil,
+                   output: nil,
+                   dryrun: false)
+      @notes = notes
+      @format = format
+      @title = title
+      @dryrun = dryrun
+      @template = template
+      @output = output
     end
 
-    #
     def render
       if notes.empty?
-        $stderr << "No #{notes.labels.join(', ')} notes.\n"
+        $stderr << "No #{notes.labels.join(", ")} notes.\n"
       else
         case format
-        when 'custom'
+        when "custom"
           render_custom
         else
           render_template
@@ -64,48 +45,43 @@ module DNote
       end
     end
 
+    private
+
     # C U S T O M
 
-    #
     def render_custom
-      #raise ArgumentError unless File.exist?(template)
       result = erb(template)
-      publish(result)    
+      publish(result)
     end
 
     # T E M P L A T E
 
-    #
     def render_template
-      template = File.join(File.dirname(__FILE__), 'templates', "#{format}.erb")
+      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
-
-    #
     def erb(file)
-      scope = ErbScope.new(:notes=>notes, :title=>title)
+      scope = ErbScope.new(notes: notes, title: title)
       scope.render(file)
     end
 
-    #
-    def publish(result, fname=nil)
+    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"
+      $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
+    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
@@ -116,25 +92,22 @@ module DNote
       else
         dir = File.dirname(file)
         fu.mkdir(dir) unless File.exist?(dir)
-        File.open(file, 'w'){ |f| f << result }
+        File.open(file, "w") { |f| f << result }
       end
-      return file
+      file
     end
 
-    #
     def dryrun?
       @dryrun
     end
 
-    #
     def debug?
       $DEBUG
     end
 
-    #
     def fu
-      @fu ||= (
-        if dryrun? and debug?
+      @fu ||=
+        if dryrun? && debug?
           FileUtils::DryRun
         elsif dryrun?
           FileUtils::Noop
@@ -143,31 +116,34 @@ module DNote
         else
           FileUtils
         end
-      )
     end
 
-    #
-    class ErbScope 
-      #
-      def initialize(data={})
+    # Evaluation scope for ERB templates
+    class ErbScope
+      def initialize(data = {})
         @data = data
       end
-      #
+
       def render(file)
-        erb = ERB.new(File.read(file), nil, '<>')
+        contents = File.read(file)
+        erb = ERB.new(contents, trim_mode: "<>")
         erb.result(binding)
       end
-      #
+
       def h(string)
         REXML::Text.normalize(string)
       end
-      #
-      def method_missing(s, *a)
-        @data[s.to_sym]
+
+      def method_missing(method, *_args)
+        sym = method.to_sym
+        return @data.fetch(sym) if @data.key? sym
+
+        super
+      end
+
+      def respond_to_missing?(method)
+        @data.key?(method.to_sym) || super
       end
     end
-
   end
-
 end
-

data/lib/dnote/note.rb

@@ -1,45 +1,41 @@
-module DNote
+# frozen_string_literal: true
 
+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
+    attr_reader :notes
 
     # The file in which the note is made.
-    attr :file
+    attr_reader :file
 
     # The type of note.
-    attr :label
+    attr_reader :label
 
     # The line number of the note.
-    attr :line
+    attr_reader :line
 
     # The verbatim text of the note.
-    attr :text
+    attr_reader :text
 
     # Remark marker used in parsing the note.
-    attr :mark
+    attr_reader :mark
 
     # Contextual lines of code.
-    attr :capture
+    attr_reader :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
+      @notes = notes
+      @file = file
+      @label = label
+      @line = line
+      @text = text.rstrip
+      @mark = mark
       @capture = []
     end
 
@@ -55,13 +51,14 @@ module DNote
 
     # Remove newlines from note text.
     def textline
-      text.gsub("\n", " ")
+      text.tr("\n", " ")
     end
 
     # Sort by file name and line number.
     def <=>(other)
       s = file <=> other.file
       return s unless s == 0
+
       line <=> other.line
     end
 
@@ -71,12 +68,12 @@ module DNote
     # TODO: Add +code+? Problem is that xml needs code in CDATA.
     #++
     def to_h
-      { 'label'=>label, 'text'=>textline, 'file'=>file, 'line'=>line }
+      {"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 }
+      {"label" => label, "text" => text, "file" => file, "line" => line, "code" => code}
     end
 
     # Convert to JSON.
@@ -91,15 +88,16 @@ module DNote
 
     # Return line URL based on URL template. If no template was set, then
     # returns the file.
+    #
+    # FIXME: Move out of Note so we can drop the reference to notes
     def url
       if notes.url
-        notes.url % [file, line]
+        format(notes.url, file, line)
       else
         file
       end
     end
 
-    #
     def code
       unindent(capture).join
     end
@@ -109,42 +107,20 @@ module DNote
       !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
+        if (md = /^(\ *)/.match(line))
           dents << md[1]
         end
       end
-      dent = dents.min{ |a,b| a.size <=> b.size }
+      dent = dents.min_by(&:size)
       lines.map do |line|
-        line.sub(dent, '')
+        line.sub(dent, "")
       end
     end
-
   end
-
 end