define_exception 0.0.2

data/lib/define_exception.rb

@@ -0,0 +1,139 @@
+# = Introduction
+#
+# Simple mixin that provides a way of defining custom exception classes
+# with default messages that dries up your code.
+#
+# = The Problem of Laborious Exception Class Definitions
+#
+# Typically you would write the following in your code to define a custom exception
+#
+#    class MyError < RuntimeError; end #nodoc
+#
+# This seems simple enough until you have to raise it many times throughout your code
+# and have to provide an error message:
+#
+#    raise( MyError, 'You shall not do what you just did' )
+#
+# It gets harder when you get tired of writing the same message to the <i>raise</i> command.
+# You can define a hash constant to keep track of common error messages:
+#
+#    ERRORS = { :myerror => 'You shall not do what you just did', ... }
+#
+# and then reference it
+#
+#    raise( MyError, ERRORS[:myerror] )
+#
+# but this just doesn't seem very rubyish.  You can also define the message when you write
+# the custom exception class:
+#
+#    class MyError < RuntimeError
+#      def message
+#        'You shall not do what you just did' )
+#      end
+#    end
+#
+# The problem is that this always uses this message even when overridden in <i>raise</i>
+#
+#    raise( MyError, 'Use this instead' ) # <= 'You shall not do what you just did'
+#
+# The real solution for you class is to override the constructor:
+#
+#    class MyError < RuntimeError
+#      def intialize( message = nil )
+#        super( message || 'Default Error Message' )
+#      end
+#    end
+#
+#    raise MyError                      # <= 'Default Error Message'
+#    raise MyError, 'Not the Default'   # <= 'Not the Default'
+#
+# = A Better Way
+#
+# Though this accomplishes the goal it is laborious to write all this code especially
+# as the number of custom exception definitions grow.  A better solution would be to make
+# a class method available that simply handles creating the exception for use automatically
+# thus drying up our code:
+#
+#    class TestMe
+#      define_exception 'MyError', 'The Default Message'
+#      define_exception 'AnotherError', 'Another Default Message'
+#      define_exception 'WorstError', 'Worst Default Message'
+#      ...
+#      def tester( args )
+#        raise MyError unless ...
+#        raise AnotherError unless ...
+#      end
+#
+#      def worst( args )
+#        raise( WorstError, 'You really messed up' ) unless ...
+#      end
+#    end
+#
+# = Usage
+#
+# The standard ruby practice of requiring the gem and then use <i>include DefineException</i> to
+# make the class method available.
+#
+# = Example
+#
+#    require 'rubygems'
+#    require 'define_exception'
+#
+#    include DefineException
+#
+#    class Test
+#      define_exception 'TestMe', 'this is the default message'
+#
+#      def test
+#        raise TestMe
+#      end
+#
+#      def test2
+#        raise( TestMe, 'You shall not do that again' )
+#      end
+#    end
+#
+#    t = Test.new
+#
+#    begin
+#      t.test
+#    rescue Test::TestMe => e
+#      puts e.message
+#    end
+#
+#    t.test2
+#
+# running the above example would correctly produce
+#
+#    wes:~/Define-Exception> ruby test.rb
+#    this is the default message
+#    test.rb:14:in `test2': You shall not do that again (Test::TestMe)
+#        from test.rb:26
+#
+# = Information
+#
+# Author:: Wes Bailey, wes@verticalresponse.com
+# License:: Ruby License
+
+module DefineException
+  module ClassMethods
+    def define_exception( exception_name, default_message = 'Application Error Occurred' )
+      exception_name = exception_name.to_s.split( '_' ).inject( '' ) { |s,v| s << v.capitalize } if /\_/.match( exception_name.to_s )
+
+      class_eval <<-EOD
+        class #{exception_name} < RuntimeError
+          def initialize( message = nil )
+            super( message || "#{default_message}" )
+          end
+        end
+      EOD
+    end
+  end
+
+  class << self
+    def included( base )
+      #base.extend( self )
+      base.extend( ClassMethods )
+    end
+  end
+end

data/test/define_exception_spec.rb

@@ -0,0 +1,39 @@
+$: << File.dirname( File.join( __FILE__, '..' ) )
+
+require 'rubygems'
+require 'define_exception'
+require 'spec/test/unit'
+
+include DefineException
+
+describe "Define Exception" do
+  it "should enable a class to define a custom exception" do
+    MESSAGE = 'This is the default message'
+
+    class TestDefineException
+      define_exception 'TestException', MESSAGE
+
+      def test
+        raise TestException
+      end
+    end
+
+    lambda {
+      tde = TestDefineException.new
+      tde.test
+    }.should raise_error( TestDefineException::TestException, MESSAGE )
+
+    class AnotherTest
+      define_exception :another_exception, MESSAGE
+    
+      def test
+        raise AnotherException
+      end
+    end
+
+    lambda {
+      tde = AnotherTest.new
+      tde.test
+    }.should raise_error( AnotherTest::AnotherException, MESSAGE )
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+name: define_exception
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Wes Bailey
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-24 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: wes@verticalresponse.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/define_exception.rb
+has_rdoc: true
+homepage: http://github.com/wbailey/define_exception
+post_install_message: 
+rdoc_options: 
+- --title
+- Define Exception Mixin
+- --main
+- lib/define_exception.rb
+- --line-numbers
+- --inline-source
+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.1
+signing_key: 
+specification_version: 2
+summary: A simple way of defining exceptions for use in your ruby classes
+test_files: 
+- test/define_exception_spec.rb