rspec-apigen 0.0.1

data/README.rdoc

@@ -0,0 +1,186 @@
+== What is this ?
+
+A tool that generates an API documentation using RSpec and some DSL magic.
+If successful I might use it for my own project (neo4j.rb)
+<b>This is an early experiment !</b>
+
+=== How ?
+
+Instead of writing specs like this:
+
+  describe Account do
+      context "transfering money" do
+        it "deposits transfer amount to the other account" do
+          source = Account.new(50, :USD)
+          target = mock('target account')
+          target.should_receive(:deposit).with(Money.new(5, :USD))
+          source.transfer(5, :USD).to(target)
+        end
+
+        it "reduces its balance by the transfer amount" do
+          source = Account.new(50, :USD)
+          target = stub('target account')
+          source.transfer(5, :USD).to(target)
+          source.balance.should == Money.new(45, :USD)
+        end
+      end
+    end
+
+Which generates the following output
+
+    $ spec ./spec/account_spec.rb --format nested
+    Account
+      transfering money
+        deposits transfer amount to the other account
+        reduces its balance by the transfer amount
+  
+    2 examples, 0 failures
+
+I (also) want to generate a detailed API documentation something like this from a RSpec Macro DSL:
+  Account
+    Public Static Methods
+      #new ()
+        Given
+          no arguments
+        Then
+          Return Account with 0 USD
+            has #balance == 0
+            has #currency == 'USD
+      #new (amount,currency)
+        Scenario account and currency has valid values
+          Given
+            arguments 50, USD
+          Then
+            Return an Account with given amount and currency
+              should == 50
+              should == "USD"
+    Public Instance Methods
+      #transfer (amount,currency)
+        Scenario transfer amount and currency have valid values
+          Given
+            arguments 5, USD
+          Then
+            should not change subject
+            Return A transfer of 5 USD from Account with 50 USD
+              should be a kind of TransferDSL
+  Finished in 0.00412 seconds
+  9 examples, 0 failures
+
+  TransferDSL
+    Public Static Methods
+      #new (source_account,amount,currency)
+        Given
+          arguments Account balance: 50 USD, 5, USD
+        Then
+          Return An TransferDSL instance with initialized source account, amount and currency
+            should == 50
+    Public Instance Methods
+      #to (target_account)
+        Given
+          arguments Account balance: 10 USD
+        Then it should add money on the target account
+          should add money to the target account
+
+  Finished in 0.00225 seconds
+  4 examples, 0 failures
+
+The above is generated from the following RSpec file:
+
+  describe Account do
+
+    static_methods do
+      new do
+        Return("Account with 0 USD") do
+          # it_behaves_like "Account with 0 USD" can also be used
+          it("has #balance == 0") { subject.balance.should == 0 }
+          it("has #currency == 'USD") { subject.currency.should == 'USD' }
+        end
+      end
+
+      new(arg(:amount), arg(:currency)) do
+        Scenario 'account and currency has valid values' do
+          Given do
+            arg.amount   = 50
+            arg.currency = 'USD'
+          end
+
+          Return "an Account with given amount and currency" do
+            it { subject.balance.should == 50 } #given.amount }
+            it { subject.currency.should == 'USD' } # given.currency }
+          end
+        end
+      end
+    end
+
+    instance_methods do
+      transfer(arg(:amount), arg(:currency)) do
+  #      Description 'bla bla bla'
+        Scenario 'transfer amount and currency have valid values' do
+          subject { Account.new(50, 'USD') }
+          Given do
+            arg.amount = 5
+            arg.currency = 'USD'
+          end
+          Return "A transfer of 5 USD from Account with 50 USD" do
+            it { should be_kind_of(TransferDSL) }
+          end
+          Then do
+           it "should not change subject" do
+              given.subject.balance.should == subject.balance
+            end
+          end
+        end
+      end
+    end
+  end
+
+
+  describe TransferDSL do
+    static_methods do
+      new(arg(:source_account) do
+        Given do
+          arg.source_account = Account.new(50, 'USD')
+        end
+        Returns("A Transfer DSL with the given source account") do
+           it {subject.source_account.should  == given.source_account}
+        end
+
+    end
+
+    instance_methods do
+      to(arg(:target_account, arg(:amount), arg(:currency)) do
+        Scenario 'source account has enough money' do
+          Given do
+            arg.target_account = Account.new(50, 'USD')
+            arg.amount = 5
+            arg.currency = 'USD'
+            subject{TransferDSL.new(Account.new(50, 'USD')}
+          end
+
+          # the following line describes the subject's source_account method
+          Then "it added money to the target account" do
+             it { subject.target_account.amount.should == given.arg.source_account.amount + given.arg.amount }
+          end
+        end
+
+        Scenario 'source account does NOT have enough money' do
+          Given do
+            arg.target_account = Account.new(50, 'USD')
+            arg.amount = 100
+            arg.currency = 'USD'
+            subject{TransferDSL.new(Account.new(10, 'USD')}
+          end
+          Throws(Error)
+      end
+    end
+
+  end
+
+
+TODO: I will implement a new RSpec HTML formatter which will generate something similar to RDoc. I want
+to write specification in my rspec code instead of using RDoc.
+
+
+=== Example
+ gem install rspec --prerelease (2.0.0.beta.19)
+ rspec -f d -c spec

data/lib/rspec-apigen/apigen.rb

@@ -0,0 +1,114 @@
+module RSpec::ApiGen
+
+  def run_scenario(method, args, block)
+    # have we defined any scenarios ?
+    MetaHelper.create_singleton_method(self, :Scenario) do |*scenario_desc, &scenario_block|
+      context "Scenario #{scenario_desc[0]}" do
+        run_scenario(method, args, scenario_block)
+      end
+    end
+
+    # create method to set the describe_return variable
+    describe_return = nil
+    MetaHelper.create_singleton_method(self, :Return) do |*example_desc, &example|
+      describe_return = {:example => example, :example_desc => example_desc}
+    end
+
+    # create method to set the given_block variable
+    given_block = nil
+    given_caller = nil # so that we can print correct line number if there is an exception
+    MetaHelper.create_singleton_method(self, :Given) { |*a, &b| given_block = b; given_caller = b.send(:caller)}
+
+    MetaHelper.create_singleton_method(self, :Description) { |desc| context(desc){} }
+
+
+    # create method to set the given_block variable
+    then_block = nil
+    then_desc  = nil
+    MetaHelper.create_singleton_method(self, :Then) { |*desc, &b| then_block = b; then_desc = desc[0] if desc.size > 0}
+
+    # eval and set the given_block and describe_return variables
+    self.instance_eval(&block)
+
+    # if there are no then_block or describe_return then there is nothing to do
+    return if describe_return.nil? && then_block.nil? && then_desc.nil?
+
+    given = nil
+    context "Given" do
+      given = Given.new(self, method, args, given_caller, &given_block)
+    end
+
+    # todo should be possible to have several Then
+    context "Then #{then_desc}" do
+      self.send(:define_method, :given) { given }
+      self.send(:define_method, :arg) { given.arg }
+      self.send(:define_method, :fixtures) { given.fixtures }
+
+
+      # use the same subject as we used when calling the method on it in the given block
+      #      self.send(:define_method, :subject) { given.subject }
+
+      context "Return #{describe_return[:example_desc][0]}" do
+        subject { given.return }
+
+        self.instance_eval(&describe_return[:example])
+      end if describe_return
+
+      self.instance_eval(&then_block) if then_block
+    end
+  end
+
+  def create_scenarios_for(method, param, &block)
+    args = param[:args]
+    context "##{method}", Argument.describe(args) do
+      run_scenario(method, args, block)
+    end
+  end
+
+
+  def static_methods(&block)
+    clazz = describes
+    describe "Public Static Methods" do
+      static_context = Method.new
+
+      # TODO - how do I find which methods was defined on the clazz and not inherited ?
+      def_methods = clazz.public_methods - Object.methods + %w[new]
+      current_context = self
+
+      # add methods on the context - one for each public static method
+      def_methods.each do |meth_name|
+        MetaHelper.create_singleton_method(static_context, meth_name) do |*args, &example_group|
+          current_context.subject { clazz }
+          current_context.create_scenarios_for(meth_name, :args => args, &example_group)
+        end
+      end
+      static_context.instance_eval(&block)
+    end
+  end
+
+  def instance_methods(&block)
+    clazz = describes
+    describe "Public Instance Methods" do
+      # Check if we are testing a module - in that case construct a new class that includes that Module
+      # so that we can test this Module
+      subject do
+        x = Class.new
+        x.send(:include, clazz)
+        x.new
+      end if clazz.class == Module
+
+      meth_ctx = Method.new
+
+      # TODO - how do I find which methods was defined on the clazz and not inherited ?
+      def_methods = clazz.public_instance_methods - Object.public_instance_methods
+      current_context = self
+      def_methods.each do |meth_name|
+        MetaHelper.create_singleton_method(meth_ctx, meth_name) do |*args, &example_group|
+          current_context.create_scenarios_for(meth_name, :args => args, &example_group)
+        end
+      end
+      meth_ctx.instance_eval(&block)
+    end
+  end
+
+end

data/lib/rspec-apigen/argument.rb

@@ -0,0 +1,38 @@
+module RSpec::ApiGen
+  class Argument
+    attr_reader :name, :description
+
+    def initialize(name, description, accept_block = false)
+      @name = name
+      @description = description
+      @accept_block = accept_block
+    end
+
+    def accept_block?
+      @accept_block      
+    end
+
+    def to_s
+      "Arg #{name}"
+    end
+
+    def self.inspect_args(args)
+      args.collect do |x|
+        case x
+          when Argument
+            x.name
+          when RSpec::Mocks::Mock
+            x.instance_variable_get('@name')
+          else
+            "#{x}:#{x.class}"
+        end
+      end
+    end
+
+    def self.describe(args)
+      "(#{inspect_args(args).join(', ')})"
+    end
+
+  end
+
+end

data/lib/rspec-apigen/config.rb

@@ -0,0 +1,5 @@
+# Make the RSpec::ApiGen module available in all 'spec/api' test folders automatically'
+
+RSpec.configure do |c|
+ c.extend RSpec::ApiGen, :example_group => { :file_path => %r{\b/spec/api} }
+end

data/lib/rspec-apigen/fixture.rb

@@ -0,0 +1,25 @@
+module RSpec::ApiGen
+  class Fixture
+    attr_reader :description
+    attr_reader :create_proc
+    attr_reader :destroy_proc
+
+    #def initialize(description, create_proc, destroy_proc = nil)
+    def initialize(description, &block)
+      @description = description && ""
+
+      # initialize this instance
+      self.instance_eval &block
+    end
+
+    def create(&block)
+      block.nil? ? @create_proc.call : @create_proc = block
+    end
+
+    def destroy(&block)
+      block.nil? ? @destroy_proc.call : @destroy_proc = block
+    end
+
+  end
+
+end

data/lib/rspec-apigen/formatter.rb

@@ -0,0 +1,56 @@
+module RSpec::ApiGen
+  class Formatter
+    def method_missing(m, *a, &b)
+      puts "CALLED #{m}"
+    end
+
+    def initialize(output )
+    end
+
+    def start(example_count)
+      puts "start #{example_count}"
+      @current_method = nil
+    end
+
+    def example_group_started(example_group)
+      # is it a new class ?
+      if @current_class != example_group.describes
+        @current_class = example_group.describes
+        @current_method = nil
+        puts "#{@current_class.class} #{example_group.describes}"
+      elsif example_group.description == "Public Static Methods"
+        puts "  Static Static Methods"
+      elsif example_group.description == "Public Instance Methods"
+        puts "  Static Instance Methods"
+      elsif @current_method
+        puts "      #{example_group.description}"
+      else
+        puts "     Method #{example_group.description}"
+        @current_method = example_group.description
+      end
+#      puts "example_groupstarted #{example_group.describes.class} #{example_group.describes.object_id} #{example_group.description}"
+    end
+
+    def start_dump
+      puts "start dump"
+    end
+
+    def example_started(example)
+    end
+
+    def example_passed(example)
+      puts "         #{example.metadata[:description]}"
+      #puts "         #{example.pretty_inspect}"
+    end
+
+    def example_failed(example)
+      puts "failed"
+    end
+
+    def example_pending(example)
+      puts "pending"
+    end
+
+
+  end
+end

data/lib/rspec-apigen/given.rb

@@ -0,0 +1,91 @@
+module RSpec::ApiGen
+  class Given
+    attr_reader :args # contains name of argument and its value
+    attr_reader :arg # the DSL object used to set the args
+    attr_reader :fixtures
+    attr_accessor :subject
+    attr_accessor :return
+
+
+    # list_of_args - the list of arguments current method accept
+    # When the given block is evaluated in this method
+    # the Given#args will return a hash of name or argument and its value.
+    def initialize(context, method, list_of_args, given_caller, &block)
+      this = self # so we can access it as closure
+      @arg = Object.new
+      @args = {}
+      @fixtures = {}
+      block_arg = nil
+
+      list_of_args.find_all { |a| a.kind_of?(Argument) }.each do |a|
+        MetaHelper.create_singleton_method(@arg, "#{a.name}=") do |val|
+          this.args[a.name] = val
+        end
+        if (a.accept_block?)
+          MetaHelper.create_singleton_method(@arg, "#{a.name}") do | &bl |
+            block_arg = bl
+          end
+        else
+          MetaHelper.create_singleton_method(@arg, "#{a.name}") do
+            this.args[a.name]
+          end
+        end
+      end
+
+      context.it "no arguments" do
+        # create the arguments
+        MetaHelper.create_singleton_method(self, :arg) { this.arg }
+
+        # accessor for setting fixture
+        MetaHelper.create_singleton_method(self, :fixtures) { this.fixtures }
+
+        begin
+          self.instance_eval &block
+        rescue Exception => e
+          this.set_backtrace(example, e, given_caller)
+        end if block
+
+        list_of_args.delete_if { |a| a.kind_of?(Argument) && a.accept_block? }
+
+        # now, the args hash should have been populated
+        # for each param we replace the args with the real value
+        list_of_args.collect! { |a| a.kind_of?(Argument) ? this.args[a.name] : a }
+
+        example.metadata[:description] = "arguments #{Argument.describe(list_of_args)}" unless list_of_args.empty?
+
+        # get the subject which we will use to test the method on, and store it so we can check it
+        this.subject = subject
+
+        begin
+          example.execution_result[:exception_encountered] = given_caller
+
+          if (block_arg)
+            # call the method on this instance which will will test
+            this.return = this.subject.send(method, *list_of_args, &block_arg)
+          else
+            this.return = this.subject.send(method, *list_of_args)
+          end
+        rescue Exception => e
+          this.set_backtrace(example, e, given_caller)
+        end
+
+      end
+    end
+
+    def set_backtrace(example, e, given_caller)
+      trace = e.backtrace
+
+      # TODO very ugly - don't know how to filter rspec own backtrace
+      # remove all lines containing ../lib/rspec
+      trace.delete_if {|line| line =~ /\/lib\/rspec\//}
+      trace.delete_if {|line| line =~ /\/rubygems\/custom_require/}
+      trace.delete_if {|line| line =~ /\/bin\/rspec/}
+
+      bt = trace + given_caller
+      e.set_backtrace(bt)
+      example.set_exception(e)
+      example.execution_result[:exception_encountered] = bt
+    end
+
+  end
+end

data/lib/rspec-apigen/meta_helper.rb

@@ -0,0 +1,14 @@
+module RSpec::ApiGen
+  module MetaHelper
+    def self.singleton_of(obj)
+      class << obj;
+        self;
+      end
+    end
+
+    def self.create_singleton_method(obj, name, &block)
+      singleton_of(obj).send(:define_method, name, &block)
+    end
+
+  end
+end

data/lib/rspec-apigen/method.rb

@@ -0,0 +1,14 @@
+module RSpec::ApiGen
+
+  class Method
+    def arg(name, description='')
+      Argument.new(name, description)
+    end
+
+    def arg_block(name, description='')
+      Argument.new(name, description, true)
+    end
+
+  end
+  
+end

data/lib/rspec-apigen/version.rb

@@ -0,0 +1,6 @@
+puts "IN VERSION"
+module RSpec
+  module ApiGen
+    VERSION = "0.0.1"
+  end
+end

data/lib/rspec-apigen/version.rb~

@@ -0,0 +1,3 @@
+module RSpec::ApiGen
+  VERSION = 0.0.1
+end

data/lib/rspec-apigen.rb

@@ -0,0 +1,8 @@
+require 'rspec-apigen/meta_helper'
+require 'rspec-apigen/apigen'
+require 'rspec-apigen/method'
+require 'rspec-apigen/argument'
+require 'rspec-apigen/fixture'
+require 'rspec-apigen/given'
+require 'rspec-apigen/config.rb'
+require 'rspec-apigen/formatter'

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification 
+name: rspec-apigen
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+    - 0
+    - 0
+    - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+  - Andreas Ronge
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-03 00:00:00 +02:00
+default_executable: 
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: rspec
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            segments: 
+              - 2
+              - 0
+              - 0
+              - beta
+              - 20
+            version: 2.0.0.beta.20
+    type: :runtime
+    version_requirements: *id001
+description: Write your API documentation using a custom RSpec DSL instead of using RDoc
+email: 
+  - andreas.ronge@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+  - lib/rspec-apigen.rb
+  - lib/rspec-apigen/given.rb
+  - lib/rspec-apigen/config.rb
+  - lib/rspec-apigen/argument.rb
+  - lib/rspec-apigen/version.rb~
+  - lib/rspec-apigen/apigen.rb
+  - lib/rspec-apigen/meta_helper.rb
+  - lib/rspec-apigen/method.rb
+  - lib/rspec-apigen/formatter.rb
+  - lib/rspec-apigen/fixture.rb
+  - lib/rspec-apigen/version.rb
+  - README.rdoc
+has_rdoc: true
+homepage: http://github.com/andreasronge/rspec-apigen
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 0
+        version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 1
+          - 3
+          - 6
+        version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A plugin for RSpec for generating an API documentation
+test_files: []
+