notes 0.0.3 → 0.1.0.pre

data/CHANGELOG.rdoc

@@ -1,3 +1,17 @@
+== 0.1.0-pre1
+
+Complete refactoring of Notes: LESS IS MORE!
+
+* Defaults tags are now TODO, FIXME, and XXX.
+* Drop the Rak gem.
+* Yield on each note instead of returning the whole result set.
+* Grep style result display.
+* Notes now provides #scan or #scan_file methods, and a Scanner class.
+* An object (which respond to #read or #to_s) can extend Notes to add a #notes method.
+* Use the Paint gem for coloring.
+* Add an option not to colorize output.
+* Use minitest for test cases.
+
 == 0.0.3
 
 Force rak version to 1.0

data/LICENSE

@@ -1,7 +1,6 @@
--------------------------------------------------------------------------------
- "THE BEER-WARE LICENSE" (Revision 42):
- <vivien.didelot@gmail.com> wrote this gem. 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
--------------------------------------------------------------------------------
-
+----------------------------------------------------------------------------
+"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.md

@@ -0,0 +1,105 @@
+# 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.

data/bin/notes

@@ -1,65 +1,80 @@
 #!/usr/bin/env ruby
 
-# ------------------------------------------------------------------------------
+# ----------------------------------------------------------------------------
 # "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
-# ------------------------------------------------------------------------------
-
-# Command line tool to grep annotations from source files.
-# Author:: Vivien 'v0n' Didelot <vivien.didelot@gmail.com>
+# <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 'notes'
-
-require 'rainbow'
 require 'optparse'
+require 'paint'
+require 'find'
 
-def display(list)
-  list.each do |a|
-    color = case a.tag
-            when "TODO" then :yellow
-            when "FIXME" then :red
-            when "OPTIMIZE" then :green
-            else :blue
-            end
-
-    printf("%s:%s: %s: %s\n",
-           a.file.color(:magenta), a.line, a.tag.color(color), a.text)
-  end
+# 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 = []
-source = []
-file = nil
+tags = Notes::TAGS.dup
+colors = {
+  "TODO"  => 'green',
+  "FIXME" => 'yellow',
+  "XXX"   => 'red',
+  :custom => 'cyan'
+}
 
-ARGV.options do |o|
-  o.banner = "Usage: #{File.basename $0} [options] [file...]\n"
-  o.banner << "Search recursively for annotations in source code.\n"
-  o.banner << "By default, #{File.basename $0} will search for all annotations in current directory.\n"
-
-  o.on_head("Available options:")
-  o.on("-a", "--all",                "Search TODO, FIXME and OPTIMIZE annotations") { tags << AnnotationExtractor::TAGS }
-  o.on("-t", "--todo",               "Search TODO annotations")                     { tags << "TODO" }
-  o.on("-f", "--fixme",              "Search FIXME annotations")                    { tags << "FIXME" }
-  o.on("-z", "--optimize",           "Search OPTIMIZE annotations")                 { tags << "OPTIMIZE" }
-  o.on("-c", "--custom=TAG", String, "Search TAG annotations")                      { |v| tags << v }
-  o.on("-o", "--out=FILE",   String, "Save output in FILE")                         { |v| file = v }
-  o.on("-v", "--version",            "Print notes version")                         { puts "notes: version #{AnnotationExtractor::VERSION}" ; exit }
+usage = 'Usage: notes [OPTION]... [FILE]...'
 
-  o.on_tail("Example: #{File.basename $0} -ac IMPROVE test.c lib\nwill search for TODO, FIXME, OPTIMIZE and IMPROVE annotations in test.c lib directory.")
+ARGV.options do |o|
+  o.version = Notes::VERSION
+  o.banner = usage
+  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(      '--no-color', 'Do not colorize ouput')    { Paint.mode = 0 }
 end
 
 begin
   ARGV.options.parse!
-  AnnotationExtractor.tags = tags.flatten unless tags.empty?
-  source = ARGV
+rescue => e
+  STDERR.puts "notes: #{e.message}"
+  STDERR.puts usage
+  STDERR.puts "Try `notes --help' for more information."
+  exit 1
+end
+
+scanner = Notes::Scanner.new
+scanner.look_for tags
+scanner.on_note do |note|
+  pretty_print(note, colors)
+end
 
-  notes = AnnotationExtractor.new(source)
+paths = ARGV.dup
+paths.empty? and paths << Dir.pwd
 
-  file.nil? ? display(notes.list) : notes.write(file)
-rescue => e
-  STDERR.puts "error: #{e}"
+Find.find(*paths) do |path|
+  unless paths.include? path
+    Find.prune if File.basename(path).start_with? '.'
+  end
+  next if File.directory? path
+
+  begin
+    scanner.scan_file(path)
+  rescue => e
+    STDERR.puts "notes: #{path}: #{e.message}"
+  end
 end
 
 exit

data/lib/notes.rb

@@ -5,108 +5,36 @@
 # think this stuff is worth it, you can buy me a beer in return. Vivien Didelot
 # ------------------------------------------------------------------------------
 
-# Useless, but informs that rak should be installed.
-require 'rubygems'
-require 'rak'
+require 'notes/version'
+require 'notes/scanner'
 
-class AnnotationExtractor
-  VERSION = "0.0.3"
+module Notes
 
-  # An annotation class.
-  class Annotation
-    attr_accessor :file, :line, :tag, :text
+  # Default tags to grep in source code.
+  TAGS = %w[TODO FIXME XXX]
 
-    # Instanciate a new Annotation from a hash.
-    def initialize(args)
-      @file = args[:file]
-      @line = args[:line]
-      @tag = args[:tag]
-      @text = args[:text]
-    end
-  end
-
-  # Default tags list
-  TAGS = ["TODO", "FIXME", "OPTIMIZE"]
+  Note = Struct.new(:tag, :text, :line, :source)
 
-  # Trick not to use @@tags class variable, but works the same way.
-  # Custom tags can be added with AnnotationExtractor.tags << "FOO".
-  @tags = TAGS.clone
-  class << self
-    attr_reader :tags
-    def tags=(tags)
-      @tags = tags.is_a?(Array) ? tags : [tags]
-    end
+  # TODO doc
+  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
 
-  # The list of all notes.
-  attr_reader :list
-
-  # Instanciate a new extractor for the given target files.
-  def initialize(source = Dir.pwd)
-    @source = [].push(source).flatten
-    @list = Array.new
-
-    extract
+  # TODO doc
+  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
 
-  # Get annotation with tag 'tag' from the list.
-  def get(tag)
-    @list.find_all { |a| a.tag == tag }
-  end
-
-  # Write all annotations to the file 'file'.
-  def write(file)
-    longest_tag = @list.max { |a, b| a.tag.size <=> b.tag.size }.tag.size
-
-    File.open(file, 'w') do |f|
-      @list.each do |a|
-        f.write(sprintf(" * [%-#{longest_tag}s] %s (%s): %s\n",
-                        a.tag, a.file, a.line, a.text))
-      end
-    end
+  # TODO doc
+  def notes(tags = nil, &block)
+    block.nil? and return enum_for(__method__, tags, &block)
+    scanner = Scanner.new(tags, &block)
+    source = (self.respond_to? :read) ? self.read : self.to_s
+    scanner.scan(source)
   end
 
-  private
-
-  # Extract annotations.
-  def extract
-    tags = self.class.tags.join("|")
-    suffix = "\s?:?" # Allowed annotation suffix.
-    source = @source.join(" ")
-
-    # Because of different rak versions,
-    # rak system call outputs are not similar.
-    if `rak --version` =~ /rak (\d\.\d)/
-      rak_version = $1
-    else
-      raise "Can't get rak version"
-    end
-
-    # 0.9 is the current rak version from rubygems.
-    # 1.1 is the current rak version from the github repo.
-    if rak_version == "1.1"
-      #TODO /^(.+):(\d+):...?
-      regex = /^(.*):(\d*):.*(#{tags})#{suffix}(.*)$/
-    else
-      regex = /^([^\s]+)\s+(\d+)\|.*(#{tags})#{suffix}(.*)$/
-    end
-    # TODO extract first matching annotation if there're many on a line.
-    # e.g. "TODO: Rename $TODOLIST variable."
-
-    out = `rak '(#{tags})#{suffix}\s+' #{source}`.strip
-
-    @list = out.split("\n").map do |l|
-      if l =~ regex
-        Annotation.new({
-          :file => $1,
-          :line => $2.to_i,
-          :tag => $3,
-          :text => $4.strip
-        })
-      else
-        # Just for a debug purpose
-        raise "notes: does not match regexp => \"#{l}\""
-      end
-    end
-  end
-end
+end # Notes

data/lib/notes/scanner.rb

@@ -0,0 +1,52 @@
+module Notes
+  class Scanner
+
+    attr_accessor :tags, :action
+
+    # TODO doc
+    def initialize tags = nil, &block
+      @tags = tags || TAGS.dup
+      @action = block || proc { |note| tag(note) }
+    end
+
+    # TODO doc
+    alias look_for tags=
+
+    # TODO doc
+    def on_note &block
+      @action = block
+    end
+
+    # TODO doc
+    def scan source
+      source.split("\n").each_with_index do |line, i|
+        if line =~ regexp
+          @action.call Note.new($1, line, i + 1)
+        end
+      end
+    end
+
+    # TODO doc
+    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)
+        end
+      end
+      file.close
+    end
+
+    # TODO doc
+    def tag note
+      puts "#{note.type} on line #{note.line}: #{note.text.strip}"
+    end
+
+    private
+
+    def regexp
+      /\b(#{@tags.join('|')})\b/
+    end
+
+  end # Scanner
+end # Notes

data/lib/notes/version.rb

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

metadata

@@ -1,38 +1,27 @@
 --- !ruby/object:Gem::Specification
 name: notes
 version: !ruby/object:Gem::Version
-  version: 0.0.3
-  prerelease: 
+  version: 0.1.0.pre
+  prerelease: 6
 platform: ruby
 authors:
 - Vivien Didelot
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-12-09 00:00:00.000000000Z
+date: 2012-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: rak
-  requirement: &83676280 !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - =
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: *83676280
-- !ruby/object:Gem::Dependency
-  name: rainbow
-  requirement: &83675860 !ruby/object:Gem::Requirement
+  name: paint
+  requirement: &20331680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: 0.8.4
   type: :runtime
   prerelease: false
-  version_requirements: *83675860
+  version_requirements: *20331680
 description: 
 email: vivien.didelot@gmail.com
 executables:
@@ -41,9 +30,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/notes.rb
-- test/notes_test.rb
-- test/data/sample.c
-- README.rdoc
+- lib/notes/scanner.rb
+- lib/notes/version.rb
+- README.md
 - CHANGELOG.rdoc
 - LICENSE
 - bin/notes
@@ -62,13 +51,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>='
+  - - ! '>'
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.6
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
-summary: A Ruby gem to grep annotations in source files.
+summary: A Ruby gem to grep tags in source files.
 test_files: []

data/README.rdoc

@@ -1,90 +0,0 @@
-= Notes
-
-== grep annotations in source files
-
-This lib provides a Ruby library and command line tool to find annotations in source files such as:
-* TODO
-* FIXME
-* OPTIMIZE
-Custom tags can also be found.
-
-The purpose of this code is to get a generic version of the `rake notes' command (only used for Ruby on Rails applications).
-It will look for tags recursively in every given files (or in current directory by default).
-
-== Installation
-
-Notes is available on Rubygems.org[http://rubygems.org/gems/notes] and can be installed with:
-
-  $ gem install notes
-
-This command needs Rubygems (rubygems package on Ubuntu).
-
-Note: it depends on rak version = 1.0 and rainbow version >= 1.1.
-
-== Usage
-
-=== Command line tool
-
-  notes [options] [file...]
-
-For details, see the help.
-
-  $ ruby notes --help
-  Usage: notes [options] [file...]
-  Search recursively for annotations in source code.
-  By default, notes will search for all annotations in current directory.
-  Available options:
-      -a, --all                        Search TODO, FIXME and OPTIMIZE annotations
-      -t, --todo                       Search TODO annotations
-      -f, --fixme                      Search FIXME annotations
-      -z, --optimize                   Search OPTIMIZE annotations
-      -c, --custom=TAG                 Search TAG annotations
-      -o, --out=FILE                   Save output in FILE
-      -v, --version                    Print notes version
-  Example: notes -ac IMPROVE test.c lib
-  will search for TODO, FIXME, OPTIMIZE and IMPROVE annotations in test.c file and lib directory.
-
-Another example:
-
-  $ notes test/data/sample.c
-  ../test/data/sample.c:16: TODO: first thing to do
-  ../test/data/sample.c:26: FIXME: first fixme thing
-  ../test/data/sample.c:32: TODO: second todo thing!
-  ../test/data/sample.c:42: OPTIMIZE: make it better
-  ../test/data/sample.c:47: TODO: hello world
-
-If the terminal allows it, colors will be displayed for files and tags.
-
-Another again:
-
-  $ notes -o TODO.txt test/data/sample.c
-
-will write all notes to a TODO.txt file. It will look like that:
-
-   * [TODO    ] ../test/data/sample.c (16): first thing to do
-   * [FIXME   ] ../test/data/sample.c (26): first fixme thing
-   * [TODO    ] ../test/data/sample.c (32): second todo thing!
-   * [OPTIMIZE] ../test/data/sample.c (42): make it better
-   * [TODO    ] ../test/data/sample.c (47): hello world
-
-=== Lib
-
-This code can be used as a Ruby lib. Let's see how it works in irb:
-
-  $ irb
-  >> require 'notes'
-  >> AnnotationExtractor.tags << "FOO"                    # Add custom tag
-  >> notes = AnnotationExtractor.new "test/data/sample.c" # Parse file
-  >> notes.list                                           # Return the array of annotations
-  >> notes.get "FIXME"                                    # Return the array of FIXME annotations only
-  >> notes.write "TODO.rdoc"                              # Write all annotations in a file
-
-== License
-
-  ------------------------------------------------------------------------------
-   "THE BEER-WARE LICENSE" (Revision 42):
-   <vivien.didelot@gmail.com> wrote this gem. 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/test/data/sample.c

@@ -1,58 +0,0 @@
-/*
- * -----------------------------------------------------------------------------
- * "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
- * -----------------------------------------------------------------------------
- */
-
-/* UDP Server */
-
-#include <netinet/in.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-//TODO first thing to do
-#define STEP sizeof(char)
-
-int main()
-{
-    int sock;
-    size_t size = STEP;
-    size_t a_size = sizeof(struct sockaddr_in);
-    void *buffer = malloc(STEP);
-
-    //FIXME: first fixme thing
-    int port = 4242;
-
-    /* address server sock */
-    struct sockaddr_in addr = {AF_INET, htons(port), {htonl(INADDR_ANY)}};
-
-    //TODO : second todo thing!
-    /* client sock */
-    struct sockaddr_in client;
-
-    /* socket declaration */
-    sock = socket(AF_INET, SOCK_DGRAM, 0);
-
-    /* bind socket to local */
-    bind(sock, (struct sockaddr*) &addr, sizeof(struct sockaddr_in));
-
-    //OPTIMIZE make it better  
-    while(1)
-    {
-        //FOO a custom tag
-        //FOOBAR this should not be found if 'FOO' is asked. Same thing for:
-        //TODOLIST blah blah
-        //TODO_LIST etc.
-        while (recvfrom(sock, buffer, size, MSG_PEEK, NULL, NULL) == size)
-            buffer = realloc(buffer, size += STEP); //TODO hello world
-
-        recvfrom(sock, buffer, size, 0, (struct sockaddr*) &client, &a_size);
-
-        printf("Server receive: \"%s\"\n", (char*) buffer);
-    }
-
-    return 0;
-}

data/test/notes_test.rb

@@ -1,63 +0,0 @@
-# ------------------------------------------------------------------------------
-# "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 "test/unit"
-require "notes"
-require "tempfile"
-
-class NotesTest < Test::Unit::TestCase
-  def setup
-    @sample = "#{File.join "..", "test", "data", "sample.c"}"
-  end
-
-  def test_new
-    notes = AnnotationExtractor.new(@sample)
-    assert_equal 5, notes.list.size
-    notes.list.each { |a| assert_kind_of AnnotationExtractor::Annotation, a }
-
-    AnnotationExtractor.tags << "FOO"
-    notes = AnnotationExtractor.new(@sample)
-    assert_equal 6, notes.list.size
-
-    # Test exact text
-    assert_equal "first thing to do", notes.list[0].text
-    assert_equal "first fixme thing", notes.list[1].text
-    assert_equal "second todo thing!", notes.list[2].text
-    assert_equal "make it better", notes.list[3].text
-    assert_equal "a custom tag", notes.list[4].text
-    assert_equal "hello world", notes.list[5].text
-
-    AnnotationExtractor.tags = "OPTIMIZE"
-    notes = AnnotationExtractor.new(@sample)
-    assert_equal 1, notes.list.size
-    assert_equal "make it better", notes.list.first.text
-
-    AnnotationExtractor.tags = "FOO"
-    notes = AnnotationExtractor.new(@sample)
-    assert_equal 1, notes.list.size
-    assert_equal "a custom tag", notes.list.first.text
-  end
-
-  def test_get
-    notes = AnnotationExtractor.new(@sample)
-    assert_equal 3, notes.get("TODO").size
-    assert_equal 1, notes.get("FIXME").size
-    assert_equal 1, notes.get("OPTIMIZE").size
-  end
-
-  def test_write
-    tempfile = Tempfile.new("notes").path
-
-    AnnotationExtractor.tags = AnnotationExtractor::TAGS
-    notes = AnnotationExtractor.new(@sample)
-    notes.write tempfile
-
-    assert_equal 5, File.readlines(tempfile).size
-
-    File.delete tempfile
-  end
-end