action_annotation 1.0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+= 1.0.1
+* first public release

data/MIT-LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2009 Nico Rehwaldt, Arian Treffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,15 @@
+
+= Action Annotation
+
+This plug-in provides means to describe what controller actions are doing in a
+human readable way and the possibility to access these descriptions in a
+computer-friendly way during runtime.
+
+See ActionAnnotation::Annotations::ClassMethods for examples.
+
+== License
+
+Copyright Nico Rehwaldt, Arian Treffer 2009
+
+You may use, copy and redistribute this library under the same terms as
+{Ruby itself}[http://www.ruby-lang.org/en/LICENSE.txt] or under the MIT-License.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+spec = Gem::Specification.new do |s|
+  s.name = 'action_annotation'
+  s.version = '1.0.1'
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README', 'MIT-LICENSE', 'CHANGELOG']
+  s.summary = 'Add descriptions to methods'
+  s.description = 
+    'This gem introduces means for describing the content of methods in a ' +
+    'human readable way. The descriptions are parsed and provided as hashes ' +
+    'at runtime. This feature is intended to be used for controller ' +
+    'actions to automatize parts of your rails application, but it ' +
+    'can be included in other classes as well.'
+  s.author = 'Nico Rehwaldt, Arian Treffer'
+  s.email = 'ruby@nixis.de'
+  s.homepage = 'http://tech.lefedt.de/2010/3/annotation-based-security-for-rails'
+  s.files = %w(CHANGELOG MIT-LICENSE README Rakefile) + Dir.glob("{bin,lib,spec}/**/*")
+  s.require_path = "lib"
+  s.bindir = "bin"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  files = ['README', 'MIT-LICENSE', 'CHANGELOG', 'lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README" # page to start on
+  rdoc.title = "Action Annotation Docs"
+  rdoc.rdoc_dir = 'doc' # rdoc output folder
+  rdoc.options << '--line-numbers'
+end
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end

data/lib/action_annotation.rb

@@ -0,0 +1,10 @@
+# Contains the require definitions for this gem.
+#
+
+module ActionAnnotation # :nodoc:
+end
+
+dir = File.dirname(__FILE__)
+require dir + "/action_annotation/utils"
+require dir + "/action_annotation/annotations"
+require dir + "/extensions/action_controller"

data/lib/action_annotation/annotations.rb

@@ -0,0 +1,199 @@
+# Contains the ActionAnnotation::Annotations module.
+#
+
+#
+module ActionAnnotation # :nodoc:
+
+  # Include this module in your class to enable descriptions.
+  # Is already included in ActionController::Base.
+  #
+  # See ActionAnnotation::Annotations::ClassMethods for more information.
+  #
+  module Annotations
+
+    def self.included(base) # :nodoc:
+      base.extend(ClassMethods)
+      base.send :include, InstanceMethods
+    end
+
+    # This module contains methods for defining descriptions.
+    #
+    # == Syntax of descriptions
+    #
+    # A description always contains an action, which is executed, and optionally
+    # a resource type and a source for the resource, on which the action is
+    # performed.
+    #
+    # A description is specified as a string of the form
+    #  ACTION (* RESOURCE)? ((in|from|by) SOURCE)?
+    # and will be transformed into a corrsponding hash.
+    #
+    # At any point, comments can be inserted using brackets.
+    #
+    # === Examples
+    # * '*show*' -- { :action => :show }
+    # * '*show* *comment*' -- { :action => :show, :resource => :comment }
+    # * '*shows* all *comments*' -- { :action => :show, :resource => :comment }
+    # * '(if necessary) *show* all new *comments* (of this user)' -- { :action => :show, :resource => :comment }
+    # * '*show* a *comment* by :id' -- { :action => :show, :resource => :comment, :source => :id }
+    # * '*show* all *comments* in <b>@comments</b>' -- { :action => :show, :resource => :comment, :source => '@comments' }
+    # Notice that verbs a transformed into infinitive and resources are singularized.
+    # Unless the source starts with a colon, it will be provided as string
+    #
+    # == Defining descriptions
+    #
+    # To add an description to a method, use #describe or #desc.
+    #
+    # Also notice that adding new descriptions at runtime is not possible,
+    # once #descriptions_of was called.
+    #
+    module ClassMethods
+
+      # This module uses the +method_added+ callback. If this method is
+      # overwritten and not called using +super+, +desc+ will not work.
+      #
+      def method_added(method)
+        check_pending_descriptions(method)
+        super(method)
+      end
+
+      # Adds descriptions to a method, but raises an argument error if the
+      # method was already described.
+      # * +method+ symbol or string
+      # * +descriptions+ list of description strings
+      #
+      def describe!(method, *descriptions)
+        raise_if_already_described! method
+        describe method, *descriptions
+      end
+
+      # Adds descriptions to a method.
+      # * +method+ symbol or string
+      # * +descriptions+ list of description strings
+      #
+      # ==== Example
+      #  describe :show, "shows a comment"
+      #  def show
+      #    @comment = Comment.find(params[:id])
+      #  end
+      #
+      def describe(method, *descriptions)
+        plain_descriptions_of(method).push(*descriptions)
+      end
+
+      # Adds descriptions to the method that will be defined next.
+      # * +descriptions+ list of description strings
+      #
+      # ==== Example
+      #  desc "shows a comment"
+      #  def show
+      #    @comment = Comment.find(params[:id])
+      #  end
+      #
+      def desc(*descriptions)
+        unassigned_descriptions.push(*descriptions)
+      end
+
+      # Returns the description strings that were added to a method, returns an
+      # empty array if no descriptions were provided.
+      # * +method+ symbol or string
+      #
+      def plain_descriptions_of(method)
+        plain_descriptions[method.to_sym]
+      end
+
+      def plain_descriptions # :nodoc:
+        @plain_descriptions ||= Hash.new do |h,k|
+          h[k] = fetch_inherited(k)
+        end
+      end
+
+      # Returns the descriptions that were added to a method, returns an empty
+      # array if no descriptions were provided.
+      # * +method+ symbol or string
+      #
+      # ==== Example
+      #  desc "shows a comment"
+      #  def show
+      #    @comment = Comment.find(params[:id])
+      #  end
+      #
+      #  descriptions_of(:show) # == { :action => :show, :resource => :comment }
+      #
+      def descriptions_of(method)
+        parsed_descriptions[method.to_sym]
+      end
+
+      def parsed_descriptions # :nodoc:
+        @parsed_descriptions ||= Hash.new do |h,k|
+          h[k] = parse_descriptions(k)
+        end
+      end
+
+    private
+
+      def fetch_inherited(method) # :nodoc:
+        if superclass.respond_to? :plain_descriptions_of
+          return superclass.plain_descriptions_of(method).dup
+        end
+        []
+      end
+
+      def parse_descriptions(method) # :nodoc:
+        plain_descriptions_of(method).collect \
+            { |desc| ActionAnnotation::Utils.parse_description(desc, true) }
+      end
+
+      def check_pending_descriptions(method) # :nodoc:
+        unless @unassigned_descriptions.nil?
+          describe method, *@unassigned_descriptions
+          @unassigned_descriptions = nil
+        end
+      end
+
+      def unassigned_descriptions # :nodoc:
+        @unassigned_descriptions ||= []
+      end
+
+      def raise_if_already_described!(method) # :nodoc:
+        unless plain_descriptions_of(method).empty?
+          raise ArgumentError, "Description for '#{method}' already set"
+        end
+      end
+
+    end
+
+    # Contains methods for fetching the value as defined by the source-part
+    # of a description.
+    #
+    module InstanceMethods
+
+      # Returns a list of values that is associated with a source
+      # * +source+ Either a symbol or an evaluatable string
+      #
+      def values_of_source(source)
+        value = value_of_source(source)
+        # TODO: what happens in case of a hash?
+        value.is_a?(Array) ? value : [value]
+      end
+
+      # Returns the value that is associated with a source
+      # * +source+ Either a symbol or an evaluatable string
+      #
+      #  value_of_binding(:id)      # == params[:id]
+      #  value_of_binding("@value") # == @value
+      #
+      def value_of_source(source)
+        if source.is_a? String
+          instance_eval(source)
+        elsif source.is_a? Symbol
+          params[source]
+        else
+          raise ArgumentError, "Unknown source #{source}"
+        end
+      end
+
+    end
+
+  end
+end

data/lib/action_annotation/utils.rb

@@ -0,0 +1,50 @@
+#
+
+# Provides some methods that are needed at several locations in the plug-in.
+#
+class ActionAnnotation::Utils
+
+  # Regexp for parsing description strings
+  PARSE_REGEXP = 
+    #  ACTION  any  RESOURCE     (in|from|by)   SOURCE
+    /^([_\w]+)(.*\s([_\w]+))?(\s+(in|from|by)\s+(\S+))?$/ # :nodoc:
+
+  # Parses a description string
+  # * +description+ description of a controller action
+  # * +allow_source+ if false, an exception is raised if the description
+  #   contains a variable
+  # Returns action, resource and source.
+  # See ActionAnnotation::Annotations::ClassMethods for details.
+  #
+  def self.parse_description(description,allow_source=true)
+    # description = "shows all courses in @courses (ignore this comment)"
+    action, resource, source = get_tokens(description)
+    # 'shows', 'courses', '@courses'
+    if source
+      raise ArgumentError, "Found unexpected source in '#{description}'" unless allow_source
+      source = (source.last(-1)).to_sym if source.starts_with? ':'
+    end
+    returning Hash.new do |result|
+      result[:action] = infinitive(action).to_sym
+      result[:resource] = resource.singularize.to_sym if resource
+      result[:source] = source if source
+      # { :action => :show, :resource => :course, :source => '@courses' }
+    end
+  end
+
+  def self.get_tokens(description) # :nodoc:
+    description = description.gsub(/\(.*\)/,'').strip
+    #description = "shows all courses in @courses"
+    matches = PARSE_REGEXP.match(description)
+    raise ArgumentError, "'#{description}' could not be matches" unless matches
+    [matches[1], matches[3], matches[6]]
+  end
+
+  @infinitive_hash = {"is" =>  "be", "has" => "have"} # :nodoc:
+
+  def self.infinitive(verb) # :nodoc:
+    @infinitive_hash[verb] ||
+        (verb.ends_with?("s") ? verb.first(-1) : verb)
+  end
+
+end

data/lib/extensions/action_controller.rb

@@ -0,0 +1,13 @@
+# Extends ActionController::Base to enable action descriptions.
+#
+
+#
+module ActionController # :nodoc:
+
+  class Base # :nodoc:
+
+    include ::ActionAnnotation::Annotations
+
+  end
+
+end

data/spec/actionannotation/annotations_spec.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe CommentController do
+
+  data = [
+    [:index,   [{:action => :list, :resource => :comment}]],
+    [:show,    [{:action => :show, :resource => :comment, :source => :id}]],
+    [:edit,    [{:action => :edit, :resource => :comment},
+                {:action => :show, :resource => :comment}]],
+    [:update,  [{:action => :edit, :resource => :comment},
+                {:action => :show, :resource => :comment, :source => '@comment'}]],
+    [:destroy, [{:action => :delete},
+                {:action => :delete, :source => '@comments'}]],
+  ]
+
+  data.each do |test|
+    it "should have valid description for #{test.first}" do
+      desc = CommentController.descriptions_of(test.first)
+      desc.should == test.second
+    end
+  end
+
+  it "should raise an error on :describe!" do
+    lambda {
+      CommentController.describe! :update, "foo"
+    }.should raise_error(ArgumentError)
+  end
+
+  it "should raise an error on an invalid description" do
+    lambda {
+      CommentController.describe :foo, "show comment using @foo"
+      CommentController.descriptions_of(:foo)
+    }.should raise_error(ArgumentError)
+  end
+
+end

data/spec/actionannotation/utils_spec.rb

@@ -0,0 +1,34 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe ActionAnnotation::Utils do
+
+  it 'should parse descriptions without bindings correctly' do
+    # Test result
+    result = {:action => :show, :resource => :resource}
+    # Test data
+    ['show a resource', 'show with some text ignored a resource',
+     'show pluralized resources', '(ignoring comments) show a resource',
+     'show a resource (with comment at the end)'].each do |s|
+      # Test #parse_descriptions
+      ActionAnnotation::Utils.parse_description(s).should == result
+    end
+  end
+
+  it 'should detect bindings of a description' do
+    { # Test data => test result
+      'show the resource in @res' =>
+        {:action => :show,:resource => :resource,:source => '@res'},
+      'show the resource from :id' =>
+        {:action => :show,:resource => :resource,:source => :id},
+    }.each_pair do |key, value|
+      ActionAnnotation::Utils.parse_description(key,true).should == value
+    end
+  end
+
+  it 'should raise an error if an unexpected binding is detected in a description' do
+    lambda {
+      ActionAnnotation::Utils.parse_description('show the resource :id')
+    }.should raise_error(ArgumentError)
+  end
+
+end

data/spec/helper/comment_controller.rb

@@ -0,0 +1,25 @@
+class CommentController < ActionController::Base
+
+  desc "list all comments"
+  def index
+  end
+
+  describe :show, "shows a comment by :id"
+  def show
+  end
+
+  desc "(invokes the action that) edits the comment",
+       "shows the same comment (as well)"
+  def edit
+  end
+
+  describe :update, "edits a comment",
+                    "shows the same comment (if the value is) in @comment"
+  def update
+  end
+
+  desc "deletes", "deletes from @comments"
+  def destroy
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require "active_support"
+require File.dirname(__FILE__) + '/../lib/action_annotation'
+require File.dirname(__FILE__) + '/helper/comment_controller'

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: action_annotation
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Nico Rehwaldt, Arian Treffer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-13 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: This gem introduces means for describing the content of methods in a human readable way. The descriptions are parsed and provided as hashes at runtime. This feature is intended to be used for controller actions to automatize parts of your rails application, but it can be included in other classes as well.
+email: ruby@nixis.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- MIT-LICENSE
+- CHANGELOG
+files: 
+- CHANGELOG
+- MIT-LICENSE
+- README
+- Rakefile
+- lib/action_annotation/annotations.rb
+- lib/action_annotation/utils.rb
+- lib/action_annotation.rb
+- lib/extensions/action_controller.rb
+- spec/actionannotation/annotations_spec.rb
+- spec/actionannotation/utils_spec.rb
+- spec/helper/comment_controller.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://tech.lefedt.de/2010/3/annotation-based-security-for-rails
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Add descriptions to methods
+test_files: []
+