= README

release::   $Release$
copyright:: $Copyright: copyright(c) 2010 kuwata-lab.com all rights reserved $
license::   $License: MIT License $



== About

'annotation.rb' is a very small but pretty good library to introduce Java's
annotation or Python's function decorator into Ruby.
Using 'annotatin.rb', you can write your code more declarative, like:

    class MyController < Controller

      GET('/')
      def index; ...; end

      GET('/:id')
      def show(id); ...; end

      PUT('/:id')
      login_required
      def update(id); ...; end

    end



== Install

Install rubygems at first and:

    $ gem install annotation



== Examples


ex1. my_controller.rb:

    require 'annotation'


    module ControllerAnnotation
      extend Annotation

      def GET(imethod, path)
        (@__routes ||= []) << [path, :GET, imethod]
      end

      def POST(imethod, path)
        (@__routes ||= []) << [path, :POST, imethod]
      end

      def login_required(imethod)
        alias_method "__orig_#{imethod}", imethod
        s = "def #{imethod}(*args)
               raise '302 Found' unless @current_user
               __orig_#{imethod}(*args)
             end"
        self.class_eval s    # not 'eval(s)'
      end

      annotation :GET, :POST, :login_required         # !!!!!!

    end


    class Controller
      extend ControllerAnnotation
    end


    class MyController < Controller

      GET('/')
      def index
        "index() called."
      end

      GET('/:id')
      def show(id)
        "show(#{id}) called."
      end

      POST('/:id')
      login_required
      def update(id)
        "update(#{id}) called."
      end

      p @__routes   #=> [["/", :GET, :index],
                    #    ["/:id", :GET, :show],
                    #    ["/:id", :POST, :update]]
    end


    p MyController.new.update(123)   #=> 302 Found (RuntimeError)



ex2. memoize.rb

    require 'annotation'

    module Memoize
      extend Annotation

      def memoize(func_name)
        aliased = "_orig_#{func_name}"   # or "_#{func_name}_#{rand().to_s[2..9]}"
        alias_method aliased, func_name
        s = "def #{func_name}(*args)
               @_memos ||= {}
               hash = (@_memos[:#{func_name}] ||= {})
               hash[args] = __send__(:#{aliased}, *args) unless hash.key?(args)
               return hash[args]
             end"
        class_eval s
      end
      annotation :memoize         # !!!!!!

    end

    class Fib
      extend Memoize

      def fib1(n)
        n <= 2 ? 1 : fib1(n-1) + fib1(n-2)
      end

      memoize                     # !!!!
      def fib2(n)
        n <= 2 ? 1 : fib2(n-1) + fib2(n-2)
      end

    end

    require 'benchmark'
    fib = Fib.new
    Benchmark.bm(20) do |x|
      x.report('fib1(30)') { ret = fib.fib1(30) }
      x.report('fib2(30)') { ret = fib.fib2(30) }
    end

    ### Result:
    # $ ruby memoize.rb
    #                           user     system      total        real
    # fib1(30)              1.060000   0.000000   1.060000 (  1.063110)
    # fib2(30)              0.000000   0.000000   0.000000 (  0.000327)



ex3. obsolete.rb

    require 'annotation'

    module Obsolete
      extend Annotation

      def obsolete(method)
        aliased = "_orig_#{method}"  # or "_#{method}_#{rand().to_s[2..9]}"
        alias_method aliased, method
        s = "def #{method}(*args)
               warn %Q`*** warning: #{method} is obsolete.`
               __send__(:#{aliased}, *args)
             end"
        class_eval s
      end
      annotation :obsolete          # !!!!!!

    end

    class Hello
      extend Obsolete

      obsolete                      # !!!!!!
      def hello(name)
        puts "Hello #{name}!"
      end

    end


    Hello.new.hello('World')   #=> *** warning: hello is obsolete.



ex4. my_test.rb

    require 'test/unit'
    require 'annotation'

    module DummyFiles
      extend Annotation

      def dummy_files(method_name, files={})
        aliased = "__#{method_name}_#{rand().to_s[2..10]}"
        alias_method aliased, method_name
        define_method method_name do
          begin
            files.each do |filename, content|
              next unless content
              File.open(filename, 'w') {|f| f.write(content) }
            end
            __send__(aliased)
          ensure
            files.each do |filename, _|
              File.unlink(filename) if File.exist?(filename)
            end
          end
        end
      end
      annotation :dummy_files         # !!!!!!

    end


    class MyTestCase < Test::Unit::TestCase
      extend DummyFiles

      dummy_files 'A.txt'=>'AAA', 'B.txt'=>'BBB'   # !!!!!!
      def test_something
        assert_equal 'AAA', File.read('A.txt')
        assert_equal 'BBB', File.read('B.txt')
      end

    end



== Known Issues

* Annotation and RDoc cannot be good friends.

      ## ...document...
      GET('/')   # this annotation prevent RDoc to generate document!
      def index()
        ...
      end