Permalink
Browse files

Add HandlerAborted exception and Handlers::Base#abort! to silently ex…

…it from handler.
  • Loading branch information...
1 parent 6e5af8b commit b2ea907f526a980ef85bcdfe6b7995f9584bff31 Loren Segal committed Nov 21, 2012
View
@@ -127,6 +127,7 @@ module Legacy # Handlers for old Ruby 1.8 parser
end
autoload :Base, __p('handlers/base')
+ autoload :HandlerAborted, __p('handlers/base')
autoload :NamespaceMissingError, __p('handlers/base')
autoload :Processor, __p('handlers/processor')
end
View
@@ -1,5 +1,11 @@
module YARD
module Handlers
+ # Raise this error when a handler should exit before completing.
+ # The exception will be silenced, allowing the next handler(s) in the
+ # queue to be executed.
+ # @since 0.8.4
+ class HandlerAborted < ::RuntimeError; end
+
# Raised during processing phase when a handler needs to perform
# an operation on an object's namespace but the namespace could
# not be resolved.
@@ -340,6 +346,15 @@ def scope=(v); parser.scope=(v) end
def globals; parser.globals end
def extra_state; parser.extra_state end
+ # Aborts a handler by raising {Handlers::HandlerAborted}.
+ # An exception will only be logged in debugging mode for
+ # this kind of handler exit.
+ #
+ # @since 0.8.4
+ def abort!
+ raise Handlers::HandlerAborted
+ end
+
# Executes a given block with specific state values for {#owner},
# {#namespace} and {#scope}.
#
@@ -112,6 +112,9 @@ def process(statements)
find_handlers(stmt).each do |handler|
begin
handler.new(self, stmt).process
+ rescue HandlerAborted => abort
+ log.debug "#{handler.to_s} cancelled from #{caller.last}"
+ log.debug "\tin file '#{file}':#{stmt.line}:\n\n" + stmt.show + "\n"
rescue NamespaceMissingError => missingerr
log.warn "The #{missingerr.object.type} #{missingerr.object.path} has not yet been recognized."
log.warn "If this class/method is part of your source tree, this will affect your documentation results."
@@ -40,6 +40,15 @@ class TestHandler2 < Handlers::Base
end
end
+ describe '#abort! (and HandlerAborted)' do
+ it 'should allow HandlerAborted to be raised' do
+ class AbortHandler1 < Handlers::Ruby::Base
+ process { abort! }
+ end
+ lambda { AbortHandler1.new(nil, nil).process }.should raise_error(HandlerAborted)
+ end
+ end
+
describe 'transitive tags' do
it "should add transitive tags to children" do
Registry.clear
@@ -20,4 +20,15 @@
it "should have a globals structure" do
@proc.globals.should be_a(OpenStruct)
end
-end
+
+ it 'should ignore HandlerAborted exceptions (but print debug info)' do
+ class AbortHandlerProcessor < YARD::Handlers::Ruby::Base
+ process { abort! }
+ end
+ stmt = OpenStruct.new(:line => 1, :show => 'SOURCE')
+ @proc.stub!(:find_handlers).and_return([AbortHandlerProcessor])
+ log.should_receive(:debug).with(/AbortHandlerProcessor cancelled from/)
+ log.should_receive(:debug).with("\tin file '(stdin)':1:\n\nSOURCE\n")
+ @proc.process([stmt])
+ end
+end

0 comments on commit b2ea907

Please sign in to comment.