mvz-dnote 1.7.2 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: eac8890fe30005d8b91d2435f22b6b147eb824e3
-  data.tar.gz: 3095d7ed25f4a5bcf188c8d678a01567b8588934
+SHA256:
+  metadata.gz: 5b9675201f53edcd5b27e0121bd08844769047c613d3d92b44b7ec9326e2f49d
+  data.tar.gz: 0b386e81dea084ee1618d6fd13fe48b5a8c15ec6be9a420442880f715956c05a
 SHA512:
-  metadata.gz: 9d4b828d589ed5157db324540356362017e3be0f6cace8cedc548be8a5673da817d2e0daa91f8cf8cbd167ac03ecda97641a34e06177ae7d58316a7a19130d75
-  data.tar.gz: a7e26ab03120551110e03e5a81154b7aa6064c6e70ae10d70a4b64eb03cf1b925ab6e41250f370fad735bd7227361683292bc29118ac578e46e681f62573a09a
+  metadata.gz: dfe4a7bb7d9fb549025519ee59030c863e3a4c9242a55f96bdbb5dc17d93d9eae569f09f16ed39a3fb107382b753fc307cf2c8fad543bc7c819cba85f7a1010b
+  data.tar.gz: 190179a14bcddc1ae626107c05237afc6adce940e2c72047b3a7e4f3348c0646bb82c59ed4984357feb716113c068d749819005d7247f48536e15549efff6fae

data/HISTORY.rdoc

@@ -1,5 +1,10 @@
 = RELEASE HISTORY
 
+== 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,119 @@
+# 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)
+[![Build Status](https://travis-ci.org/mvz/mvz-dnote.svg?branch=master)](https://travis-ci.org/mvz/mvz-dnote)
+[![Coverage Status](https://coveralls.io/repos/github/mvz/mvz-dnote/badge.svg?branch=master)](https://coveralls.io/github/mvz/mvz-dnote?branch=master)
+[![Dependency Status](https://gemnasium.com/badges/github.com/mvz/mvz-dnote.svg)](https://gemnasium.com/github.com/mvz/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
-require "dnote"
-DNote::Session.main(*ARGV)
+# frozen_string_literal: true
 
+require 'dnote'
+
+begin
+  DNote::Session.main(*ARGV)
+rescue StandardError => err
+  raise err if $DEBUG
+
+  puts err
+  exit 1
+end

data/lib/dnote.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'dnote/version'
 require 'dnote/session'
 

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,49 +9,37 @@ 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' }
+    EXTENSIONS = { 'text' => 'txt', 'soap' => 'xml', 'xoxo' => 'xml' }.freeze
 
-    #
-    attr :notes
+    attr_reader :notes
 
-    #
     attr_accessor :format
 
-    #
     attr_accessor :subtype
 
-    #
     attr_accessor :output
 
-    #
     attr_accessor :template
 
-    #
     attr_accessor :title
 
-    #
     attr_accessor :dryrun
 
-    #
-    def initialize(notes, options={})
+    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 }
+      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"
@@ -66,44 +55,39 @@ module DNote
 
     # 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")
       raise "No such format - #{format}" unless File.exist?(template)
+
       result = erb(template)
-      publish(result)  
+      publish(result)
     end
 
-  private
+    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)
+    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}")
@@ -116,25 +100,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 ||= begin
+        if dryrun? && debug?
           FileUtils::DryRun
         elsif dryrun?
           FileUtils::Noop
@@ -143,31 +124,34 @@ module DNote
         else
           FileUtils
         end
-      )
+      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, '<>')
         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
-    end
 
+      def respond_to_missing?(method)
+        @data.key? method.to_sym
+      end
+    end
   end
-
 end
-