notes 0.1.0.pre → 0.1.0

data/CHANGELOG.rdoc

@@ -1,4 +1,10 @@
-== 0.1.0-pre1
+== 0.1.0
+
+* improve scanner and executable
+* some compatibility fixes
+* change -t option into -a
+
+== 0.1.0-pre
 
 Complete refactoring of Notes: LESS IS MORE!
 

data/LICENSE

@@ -1,6 +1,4 @@
-----------------------------------------------------------------------------
 "THE BEER-WARE LICENSE" (Revision 42):
 <vivien@didelot.org> wrote this code. As long as you retain this notice you
 can do whatever you want with this stuff. If we meet some day, and you think
 this stuff is worth it, you can buy me a beer in return Vivien Didelot
-----------------------------------------------------------------------------

data/README.rdoc

@@ -0,0 +1,92 @@
+= Notes
+
+<b>Stupidly grep tags in source code.</b>
+
+This gem provides a command line tool and a Ruby library to find tags in
+source code. Defaults tags are *TODO*, *FIXME*, and *XXX*.
+Custom tags can be found as well.
+
+It's kind of a generic version of the Ruby on Rails <tt>rake notes</tt> command,
+for any project/source.
+
+== Command line tool
+
+Usage:
+
+    $ notes [options] [file...]
+
+With no argument, <tt>notes</tt> will search recursively in the current
+directory. For details, see <tt>notes --help</tt>.
+
+Examples:
+
+    $ notes
+    $ notes foo.h src/
+    $ notes --tag @@@
+    $ notes --no-{todo,fixme,xxx} --tag FOO
+
+=== Integration with Git
+
+A cool thing to do is to add a Git alias to parse every versionned files:
+
+    $ git config --global alias.n '!git ls-files | xargs notes'
+
+Now, running <tt>git n</tt> in any Git repository will search
+notes in every files under version control!
+
+=== Convention over configuration
+
+No custom output.
+
+It uses a grep-style display, which makes it easy to fit your
+needs. <tt>cut</tt> is great:
+
+    $ notes | cut -d: -f3,4-
+
+will display this:
+
+    TODO:    /* add a cool feature */
+
+instead of the normal output:
+
+    foo.c:42:TODO:    /* add a cool feature */
+
+And colors will still be displayed.
+
+Notes won't filter.
+
+<tt>find</tt>, <tt>xargs</tt> are your friends:
+
+    $ find . -name '*.rb' | xargs notes
+
+Or get the list of tagged files in the current directory with:
+
+    $ notes | cut -d: -f1 | sort -u
+
+== Installation
+
+Notes is available on Rubygems.org[http://rubygems.org/gems/notes] and
+can be installed with:
+
+    $ [sudo] gem install notes
+
+Or you can install from the source directory with:
+
+    $ rake install
+
+== The Notes library
+
+The Notes module provides convenient methods.
+
+    require 'notes'
+    
+    Notes.scan_file("foo.c") do |note|
+      puts "#{note.tag} found at line #{note.line}!"
+    end
+
+Notes can also extend an object to add a new method (see Notes#notes),
+or allow you to create your own scanner (see the Notes::Scanner).
+
+== License
+
+That's free and friendly for sure! See the LICENSE file.

data/bin/notes

@@ -1,40 +1,13 @@
 #!/usr/bin/env ruby
 
-# ----------------------------------------------------------------------------
-# "THE BEER-WARE LICENSE" (Revision 42):
-# <vivien@didelot.org> wrote this file. As long as you retain this notice you
-# can do whatever you want with this stuff. If we meet some day, and you think
-# this stuff is worth it, you can buy me a beer in return Vivien Didelot
-# ----------------------------------------------------------------------------
-
+require 'rubygems'
 require 'notes'
 require 'optparse'
 require 'paint'
 require 'find'
 
-# grep-style display
-def pretty_print(note, colors)
-  col = Paint[':', :cyan]
-  format = Paint['%s', :magenta] + col
-  format << Paint['%s', :green] + col
-  format << Paint['%s', colors[note.tag] || colors[:custom], :bold] + col
-  format << "%s\n"
-  printf(format,
-         note.source,
-         note.line,
-         note.tag,
-         note.text.rstrip)
-end
-
-tags = Notes::TAGS.dup
-colors = {
-  "TODO"  => 'green',
-  "FIXME" => 'yellow',
-  "XXX"   => 'red',
-  :custom => 'cyan'
-}
-
 usage = 'Usage: notes [OPTION]... [FILE]...'
+tags = Notes::TAGS.dup
 
 ARGV.options do |o|
   o.version = Notes::VERSION
@@ -42,12 +15,17 @@ ARGV.options do |o|
   o.on(      '--no-todo',  'Do not search TODO tags')  { tags -= ['TODO'] }
   o.on(      '--no-fixme', 'Do not search FIXME tags') { tags -= ['FIXME'] }
   o.on(      '--no-xxx',   'Do not search XXX tags')   { tags -= ['XXX'] }
-  o.on('-t', '--tag=TAG',  'Search TAG tags')          { |tag| tags |= [tag] }
+  o.on('-a', '--tag=TAG',  'Search TAG tags')          { |tag| tags |= [tag] }
   o.on(      '--no-color', 'Do not colorize ouput')    { Paint.mode = 0 }
 end
 
 begin
   ARGV.options.parse!
+  if ARGV.empty?
+    paths = [Dir.pwd]
+  else
+    paths = ARGV.map { |p| File.exist? p or raise Errno::ENOENT, p ; p }
+  end
 rescue => e
   STDERR.puts "notes: #{e.message}"
   STDERR.puts usage
@@ -55,15 +33,23 @@ rescue => e
   exit 1
 end
 
+# grep-style display
+c = Paint[':', :cyan]
+format = Paint['%s', :magenta] + c + Paint['%s', :green] + c + '%s' + c + "%s\n"
+colors = {
+  'TODO'  => 'green',
+  'FIXME' => 'yellow',
+  'XXX'   => 'red',
+  :custom => 'cyan'
+}
+
 scanner = Notes::Scanner.new
-scanner.look_for tags
+scanner.tags = tags
 scanner.on_note do |note|
-  pretty_print(note, colors)
+  tag = Paint[note.tag, colors[note.tag] || colors[:custom], :bold]
+  printf(format, note.file, note.line, tag, note.text.rstrip)
 end
 
-paths = ARGV.dup
-paths.empty? and paths << Dir.pwd
-
 Find.find(*paths) do |path|
   unless paths.include? path
     Find.prune if File.basename(path).start_with? '.'
@@ -72,6 +58,8 @@ Find.find(*paths) do |path|
 
   begin
     scanner.scan_file(path)
+  rescue Errno::ENOENT => e
+    STDERR.puts "notes: #{e.message} (broken symlink?)"
   rescue => e
     STDERR.puts "notes: #{path}: #{e.message}"
   end

data/lib/notes.rb

@@ -1,35 +1,91 @@
-# ------------------------------------------------------------------------------
-# "THE BEER-WARE LICENSE" (Revision 42):
-# <vivien.didelot@gmail.com> wrote this file. As long as you retain this notice
-# you can do whatever you want with this stuff. If we meet some day, and you
-# think this stuff is worth it, you can buy me a beer in return. Vivien Didelot
-# ------------------------------------------------------------------------------
-
 require 'notes/version'
 require 'notes/scanner'
 
 module Notes
 
   # Default tags to grep in source code.
+  # They are *TODO*, *FIXME*, and *XXX*.
   TAGS = %w[TODO FIXME XXX]
 
-  Note = Struct.new(:tag, :text, :line, :source)
+  # The Note class. This is basically an object with accessors to four attributes:
+  # * tag: Tag the line is marked with;
+  # * text: The line of text containing the tag;
+  # * line: The line number;
+  # * file: The filename of the input source.
+  Note = Struct.new(:tag, :text, :line, :file)
 
-  # TODO doc
+  # Scan a source string
+  #
+  # @example
+  #   Notes.scan("...\nXXX fix this asap!") do |note|
+  #     puts note.text
+  #   end
+  #
+  # @param [String] source
+  #   input source to scan
+  #
+  # @params [Array] tags
+  #   tags to look for
+  #   if nil, tags will be the defaults (TODO, FIXME, XXX)
+  #
+  # @params [Proc] block
+  #   callback to execute when a note is found
+  #
+  # @return [Enumerator]
+  #   an enumerator on notes when no block is given
   def self.scan(source, tags = nil, &block)
     block.nil? and return enum_for(__method__, source, tags, &block)
     scanner = Scanner.new(tags, &block)
     scanner.scan(source)
   end
 
-  # TODO doc
+  # Scan a file
+  #
+  # @example
+  #   Notes.scan_file("src/foo.c") do |note|
+  #     puts note.text
+  #   end
+  #   
+  #   Notes.scan_file("bar.hs", ['@@@']) do |note|
+  #     puts "File to fix: #{note.file}!"
+  #   end
+  #
+  # @param [String] filename
+  #   name of the file to scan
+  #
+  # @params [Array] tags
+  #   tags to look for
+  #   if nil, tags will be the defaults (TODO, FIXME, XXX)
+  #
+  # @params [Proc] block
+  #   callback to execute when a note is found
+  #
+  # @return [Enumerator]
+  #   an enumerator on notes when no block is given
   def self.scan_file(file, tags = nil, &block)
     block.nil? and return enum_for(__method__, file, tags, &block)
     scanner = Scanner.new(tags, &block)
     scanner.scan_file(file)
   end
 
-  # TODO doc
+  # Add a :notes method to an object
+  #
+  # @example
+  #   file = File.new("foo.c")
+  #   file.extend Notes
+  #   file.notes do |note|
+  #     puts note.text
+  #   end
+  #
+  # @params [Array] tags
+  #   tags to look for
+  #   if nil, tags will be the defaults (TODO, FIXME, XXX)
+  #
+  # @params [Proc] block
+  #   callback to execute when a note is found
+  #
+  # @return [Enumerator]
+  #   an enumerator on notes when no block is given
   def notes(tags = nil, &block)
     block.nil? and return enum_for(__method__, tags, &block)
     scanner = Scanner.new(tags, &block)

data/lib/notes/scanner.rb

@@ -1,45 +1,84 @@
 module Notes
   class Scanner
 
-    attr_accessor :tags, :action
+    # The array of tags to look for
+    #
+    # @example
+    #   scanner.tags << "FOO"
+    #
+    # @return [Array]
+    #   the tags list
+    attr_accessor :tags
 
-    # TODO doc
+    # The block to execute when a note is found
+    #
+    # @example
+    #   scanner.callback = proc { |note| puts note.file }
+    #
+    # @see :on_note
+    attr_accessor :callback
+
+    # Create a new scanner
+    #
+    # @example
+    #   scan = Notes::Scanner.new(["TODO", "@@@"]) do |note|
+    #     puts "#{note.file} contains notes!"
+    #   end
+    #   
+    #   class NotesCounter < Notes::Scanner
+    #     attr_reader :notes
+    #
+    #     def initialize tags = nil
+    #       super(tags)
+    #       @notes = []
+    #       @callback = proc { |note| @notes << note }
+    #     end
+    #   end
     def initialize tags = nil, &block
       @tags = tags || TAGS.dup
-      @action = block || proc { |note| tag(note) }
+      @callback = block
     end
 
-    # TODO doc
-    alias look_for tags=
-
-    # TODO doc
+    # Define the callback to execute when a note is given
+    #
+    # @example
+    #   scanner.on_note do |note|
+    #     puts note.text
+    #   end
+    #
+    # @see :callback=
     def on_note &block
-      @action = block
+      @callback = block
     end
 
-    # TODO doc
+    # Scan a source string
+    #
+    # @example
+    #   scanner.scan("...//XXX urgent fix!")
     def scan source
+      return if tags.empty? || callback.nil?
+      rxp = regexp
       source.split("\n").each_with_index do |line, i|
-        if line =~ regexp
-          @action.call Note.new($1, line, i + 1)
+        if rxp =~ line
+          callback.call Note.new($1, line, i + 1)
         end
       end
     end
 
-    # TODO doc
+    # Scan a file
+    #
+    # @example
+    #   scanner.scan_file("foo.c")
     def scan_file path
-      file = File.open(path, 'r')
-      file.each_with_index do |line, i|
-        if line =~ regexp
-          @action.call Note.new($1, line, i + 1, path)
+      return if tags.empty? || callback.nil?
+      rxp = regexp
+      File.open(path, 'r') do |file|
+        file.each_with_index do |line, i|
+          if rxp =~ line
+            callback.call Note.new($1, line, i + 1, path)
+          end
         end
       end
-      file.close
-    end
-
-    # TODO doc
-    def tag note
-      puts "#{note.type} on line #{note.line}: #{note.text.strip}"
     end
 
     private

data/lib/notes/version.rb

@@ -1,4 +1,4 @@
 module Notes
-  VERSION = "0.1.0.pre"
+  VERSION = "0.1.0"
 end
 

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: notes
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre
-  prerelease: 6
+  version: 0.1.0
+  prerelease: 
 platform: ruby
 authors:
 - Vivien Didelot
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-09 00:00:00.000000000 Z
+date: 2012-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: paint
-  requirement: &20331680 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,12 @@ dependencies:
         version: 0.8.4
   type: :runtime
   prerelease: false
-  version_requirements: *20331680
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.8.4
 description: 
 email: vivien.didelot@gmail.com
 executables:
@@ -32,10 +37,11 @@ files:
 - lib/notes.rb
 - lib/notes/scanner.rb
 - lib/notes/version.rb
-- README.md
+- README.rdoc
 - CHANGELOG.rdoc
 - LICENSE
-- bin/notes
+- !binary |-
+  YmluL25vdGVz
 homepage: 
 licenses: []
 post_install_message: 
@@ -51,13 +57,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
-summary: A Ruby gem to grep tags in source files.
+summary: Stupidly grep tags in source code.
 test_files: []

data/README.md

@@ -1,105 +0,0 @@
-# Notes
-
-grep tags in source files
-
-This gem provides a command line tool and a Ruby library to find tags in
-source code. Defaults tags are *TODO*, *FIXME*, and *XXX*.
-Custom tags can be found as well.
-
-It's kind of a generic version of the `rake notes` command,
-which is only available in Ruby on Rails applications.
-
-## Command line tool
-
-Usage:
-
-    $ notes [options] [file...]
-
-With no argument, `notes` will search recursively in the current
-directory. For details, see `notes --help`.
-
-Examples:
-
-    $ notes
-    $ notes foo.h src/
-    $ notes --tag @@@
-    $ notes --no-{todo,fixme,xxx} --tag FOO
-
-### Convention over configuration
-
-Notes won't filter. `find`, `xargs` are here for you:
-
-    $ find . -name '*.rb' | xargs notes
-
-No custom output. It uses a grep-style display, which makes it easy to
-fit your needs. Try:
-
-    $ notes | cut -d: -f3,4-
-
-Or get the list of tagged files in the current directory with:
-
-    $ notes | cut -d: -f1 | sort -u
-
-## Installation
-
-Notes is available on [Rubygems.org](http://rubygems.org/gems/notes) and
-can be installed with:
-
-    $ [sudo] gem install notes
-
-## The Notes library
-
-Module functions:
-
-    require 'notes'
-    
-    Notes.scan_file("foo.c") do |note|
-      puts "#{note.tag} found at line #{note.line}!"
-    end
-    
-    Notes.scan("...\nXXX: an urgent note!") do |note|
-      putes note.text
-    end
-
-Extending the Notes module:
-
-    require 'notes'
-    
-    file = File.new("foo.c")
-    file.extend Notes
-    file.notes { |note| puts note.text }
-
-Using the Notes scanner:
-
-    require 'notes'
-    
-    scan = Notes::Scanner.new
-    scan.tags = Notes::TAGS + "FOO"
-    scan.on_note do |note|
-      puts "found!"
-    end
-    scan.scan_file("foo.c")
-    scan.scan_file("bar.c")
-
-Create your own scanner:
-
-    require 'notes'
-    
-    class Foo < Notes::Scanner
-      attr_reader :notes
-
-      def initialize tags = nil
-        super(tags)
-        @notes = []
-      end
-    
-      # Called if no action block set. So override it.
-      def tag note
-        @notes << note
-      end
-    end
-
-License
--------
-
-That's free for sure! See the LICENSE file.