ryanlowe-save_or_raise 0.1.1

data/CHANGELOG

@@ -0,0 +1,15 @@
+
+== 0.1.1
+
+May 26
+= add the MIT license
+
+== 0.1.0
+
+May 26
+= add GitHub gemspec file
+= finished first rough implementation
+
+May 25
+= add the needed parts of the Rails framework to run tests
+= README: the raison d'être

data/MIT-LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2008 Ryan Lowe
+
+http://ryanlowe.ca
+http://disruptiveagility.com
+
+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,81 @@
+= save_or_raise
+
+  This plugin includes one new method for ActiveRecord::Base called
+  save_or_raise which does almost the same thing as
+  ActiveRecord::Base#save!
+  
+  == save vs save!
+  
+    The ActiveRecord::Base save method returns true if the model save
+    is successful and false if it is not successful.  The save! method
+    returns true if the model save is successful and raises an exception
+    if it is not successful.
+  
+  == utility
+  
+    The save method is useful for control flow in cases where a failed
+    save can be handled gracefully:
+  
+      if model.save
+        ...
+      else
+        ...
+      end
+    
+    Sometimes the control flow - often within or called by a controller -
+    cannot handle an unsuccessful save gracefully.  The programmer's
+    choices are:
+  
+      1. Do not branch on the save call and ignore failures.
+      2. Throw an exception:
+    
+           raise "Save failed!" unless model.save
+      
+      3. Call save! which does the same as 2
+      
+    The exception thrown by 2 and 3 will generate a 500 HTTP code for the user
+    in production but it will also notify an admin by email when used in combination
+    with a plugin like exception_notification.  Result of choice 1 is possible data
+    corruption and invalid application state.
+    
+    So doing 1 is just not a good idea!
+  
+  == The problem with save!
+  
+    ...is that is poorly named.  Ruby methods that end with an exclamation
+    point are a signal that they change the object they operate on.
+  
+    An irb example:
+  
+      >> a = " hello "
+      => " hello "
+      >> b = a.strip!
+      => "hello"
+      >> a
+      => "hello"
+      
+      The method strip! returns the result to b but also changes a.
+    
+    The save! method does not change the ActiveRecord model it is called on any more
+    than the save method does.  Also the name save! does not hint that it throws an
+    exception in the failure case.
+  
+    Both of these things make the code that uses save! less readable.
+  
+  == A Solution
+  
+    This plugin implements a new ActiveRecord#Base method
+    
+      save_or_raise(raiseable = ActiveRecord::RecordNotSaved)
+  
+    which can be used the following ways:
+    
+      model.save_or_raise                   # instead of model.save!
+      model.save_or_raise "Save failed!"    # raises RuntimeError with this message on failure
+      model.save_or_raise CustomException   # raises CustomException on failure
+      
+    In all three cases the raised exception presents a 500 HTTP error to
+    the user in production if the save fails.
+    
+    The save! method remains untouched and can still be used.
+    

data/Rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'

data/init.rb

@@ -0,0 +1 @@
+require 'save_or_raise'

data/lib/save_or_raise.rb

@@ -0,0 +1,10 @@
+class ActiveRecord::Base
+  
+  def save_or_raise(raiseable = ActiveRecord::RecordNotSaved)
+    raiseable = ActiveRecord::RecordNotSaved if raiseable.nil?
+    success = save
+    raise raiseable unless success
+    success
+  end
+  
+end

data/save_or_raise.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |s|
+  s.name = "save_or_raise"
+  s.version = "0.1.1"
+  s.date = "2008-05-25"
+  s.summary = "A replacement for ActiveRecord::Base#save! for Ruby on Rails"
+  s.email = "rails@ryanlowe.ca"
+  s.homepage = "http://github.com/ryanlowe/save_or_raise"
+  s.description = "A replacement for ActiveRecord::Base#save! for Ruby on Rails"
+  s.has_rdoc = false
+  s.authors = ["Ryan Lowe"]
+  s.files = ["README", "CHANGELOG", "MIT-LICENSE","Rakefile", "save_or_raise.gemspec", "init.rb","lib/save_or_raise.rb"]
+  s.test_files = []
+  s.rdoc_options = ["--main", "README"]
+  s.extra_rdoc_files = ["README","CHANGELOG"]
+  s.add_dependency("rails", ["> 2.0.0"])
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: ryanlowe-save_or_raise
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Ryan Lowe
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-05-25 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rails
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 2.0.0
+    version: 
+description: A replacement for ActiveRecord::Base#save! for Ruby on Rails
+email: rails@ryanlowe.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- CHANGELOG
+files: 
+- README
+- CHANGELOG
+- MIT-LICENSE
+- Rakefile
+- save_or_raise.gemspec
+- init.rb
+- lib/save_or_raise.rb
+has_rdoc: false
+homepage: http://github.com/ryanlowe/save_or_raise
+post_install_message: 
+rdoc_options: 
+- --main
+- README
+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.0.1
+signing_key: 
+specification_version: 2
+summary: A replacement for ActiveRecord::Base#save! for Ruby on Rails
+test_files: []
+