methlab 0.0.3 → 0.0.4

data/README

@@ -0,0 +1,152 @@
+Yo dawg, I heard you liked methods.
+
+Meth Lab is a method construction toolkit intended to ease parameter
+validation and a number of common "method definition patterns" seen in
+ruby code.
+
+=== SYNOPSIS
+--------
+
+A lot of times in the programming world, especially in dynamically
+typed languages, we see this pattern:
+
+  def foo(arg1, arg2, arg3)
+    unless arg1.kind_of?(SomeObject)
+      raise "Incorrect object"
+    end
+
+    unless arg2 ... 
+    end
+  end
+
+You get the idea. Additionally, with the use of hashes for emulating
+named parameters, we see a ton of this in the ruby world:
+
+  def bar(*args)
+    args = args[0]
+
+    raise "not a hash" unless args.kind_of?(Hash)
+
+    unless args.has_key?(:some_parameter)
+      raise "'some parameter' does not exist"
+    end
+
+    unless args[:some_parameter].kind_of?(SomeObject)
+      raise "'some parameter' is not a kind of SomeObject"
+    end
+  end
+
+Meth Lab is intended to strip your methods of this wordy, but
+important boilerplate, by making it ideally less wordy and slamming it
+right in the prototype to easily evaluate what it does. Also, it has
+an awesomely apropos name.
+
+=== USAGE
+--------
+
+So, let's do something like this:
+
+  class Awesome
+    def_ordered(:foo, String, [Integer, :optional]) do |params|
+      str, int = params
+      puts "I received #{str} as a String and #{int} as an Integer!"
+    end
+
+    def_named(:bar, :foo => String, :bar => [Integer, :required]) do |params|
+      puts "I received #{params[:foo]} as a String and #{params[:bar]} as an Integer!"
+    end
+  end
+
+Which yields these opportunities:
+
+  a = Awesome.new
+  a.foo(1, "str") # raises
+  a.foo("str", 1) # prints the message
+  a.foo("str")    # prints the message with nil as the integer
+
+  a.bar(:foo => 1, :bar => "str") # raises
+  a.bar(:foo => "str")            # raises (:bar is required)
+  a.bar(:bar => 1)                # prints message, with nil string
+  a.bar(:foo => "str", :bar => 1) # prints message
+
+See the MethLab module documentation for details.
+
+=== FAQ
+--------
+
+1) OMG OMG OMG OMG DUCK TYPING, you don't need this at all.
+
+a) Then don't use it. I will offer a little opinion though: if you
+think duck typing can solve everything, chances are you aren't hitting
+a whole class of edge cases in your code. Also, punk rock is dead, get
+with the times and think for yourself.
+
+2) Exceptions; how do I debug validation failures?
+
+a) Meth Lab works hard to not raise until the last possible minute for
+validation failures. Generally you will see a trace like this:
+
+(lines wrapped for sanity)
+
+    lib/methlab.rb:95:in `bar': value of argument '1' is an invalid
+        type. Requires 'Integer' (ArgumentError)
+            from lib/my-actual-file.rb:126
+
+What's important to understand here is that, short of making you, the
+user, handle raising validation errors yourself (which would kind of
+defeat the point), we raise just above where your code would execute.
+This means that both parts of this trace are significant; the first
+line is the error and the method the error was raised from, but the
+second line is the place that the method was called.
+
+I will not even pretend this is anything other than a "misfeature",
+but it is a consequence to working with a library like this.
+
+MethLab will always raise ArgumentError, which is standard for good
+ruby programs.
+
+3) Don't you solve this with blocks? Are closures an issue?
+
+a) The short, proper answer to this is "yes". The pragmatic answer to
+this is "probably not". Closures are created and there is a
+performance impact to relying on them. I would argue that if
+performance is your concern, you shouldn't be using ruby at all. Meth
+Lab does make every effort possible to not use proc objects where
+possible, e.g., the check methods themselves live in the MethLab
+namespace and are not anonymously injected into your methods (which
+would be very expensive, and cause inconsistency if someone were to
+redefine them).
+
+4) I don't want to use MethLab everywhere, but I'd like to use it in
+a specific class or module.
+
+a) "extend MethLab" in your namespace before using the definition
+syntax.
+
+5) I want to use MethLab everywhere.
+
+a) MethLab.integrate does this. If you want it to happen at require
+time, set the global $METHLAB_AUTOINTEGRATE to a true value before
+doing so. These both pollute ::Module and ::main, so be aware of the
+consequences.
+
+=== TODO
+--------
+
+* #respond_to? checks.
+* multiplexed array/hash methods.
+* construction of methods that can take inline blocks 
+  (e.g., "def foo(&block)"). Proc can be used now, but it's
+  not very "rubyish" syntax for the user.
+* Better handling in Modules (def self.meth(...))
+
+=== THANKS
+--------
+
+* James Tucker (raggi) and "saywatmang" for inspiration and a bit of
+  opinion and code review.
+* Eric Hodel (drbrain) for lots and lots of mentoring and generally being a
+  standup dude.
+* Params::Validate and Method::Signatures from CPAN for doing it right
+  first. Imitation is the sincerest form of flattery and good ideas
+  should not be kept in an ivory tower, so prematurely shut it plox.

data/Rakefile

@@ -0,0 +1,65 @@
+begin
+    require 'rubygems'
+rescue LoadError
+end
+
+$:.unshift 'lib'
+require 'methlab'
+$:.shift
+
+require 'rake/testtask'
+require 'rdoc/task'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+
+spec = Gem::Specification.new do |s|
+  s.name = "methlab"
+  s.version = MethLab::VERSION
+  s.author = "Erik Hollensbe"
+  s.email = "erik@hollensbe.org"
+  s.summary = "A method construction and validation toolkit."
+  s.homepage = "http://github.com/erikh/methlab"
+
+  s.files = Dir["lib/**/*"] + Dir["test/**/*"] + Dir["Rakefile"] + Dir["README"]
+
+  s.has_rdoc = true
+end
+
+Rake::GemPackageTask.new(spec) do |s|
+end
+
+Rake::PackageTask.new(spec.name, spec.version) do |p|
+    p.need_tar_gz = true
+    p.need_zip = true
+    p.package_files.include("./bin/**/*")
+    p.package_files.include("./Rakefile")
+    p.package_files.include("./lib/**/*.rb")
+    p.package_files.include("./test/**/*")
+    p.package_files.include("README")
+end
+
+Rake::TestTask.new do |t|
+    t.libs << 'lib'
+    t.test_files = FileList['test/test*.rb']
+    t.verbose = true 
+end
+
+RDoc::Task.new do |rd|
+    rd.rdoc_dir = "rdoc"
+    rd.main = "README"
+    rd.title = "MethLab: A method toolkit for Ruby"
+    rd.rdoc_files.include("./lib/**/*.rb")
+    rd.rdoc_files.include("README")
+    rd.options = %w(-a)
+end
+
+task :fixperms do
+    chmod(0644, Dir['**/*'])  
+end
+
+task :default => [:clean, :test, :build]
+desc "Build Packages"
+task :build => [:gem, :repackage]
+task :distclean => [:clobber_package, :clobber_rdoc]
+desc "Clean the source tree"
+task :clean => [:distclean]

data/lib/methlab.rb

@@ -55,7 +55,7 @@
 #
 module MethLab
 
-    VERSION = "0.0.3"
+    VERSION = "0.0.4"
 
     # Integrates MethLab into all namespaces. It does this by patching itself
     # into ::main and Module.

data/test/test_checks.rb

@@ -0,0 +1,145 @@
+begin
+    require 'rubygems'
+    gem 'test-unit'
+rescue LoadError
+end
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'test/unit'
+require 'methlab'
+
+MethLab.integrate
+
+class CheckedClass
+    def_named(:named, :stuff => String, :stuff2 => [ /pee/, :required ], :stuff3 => :required) do |params| 
+        [:stuff, :stuff2, :stuff3].collect { |x| params[x] }
+    end
+
+    def_ordered(:sequential, String, [Integer, :optional]) do |params|
+        params
+    end
+
+    def_ordered(:ranged, (0..9)) do |params|
+        params
+    end
+
+    def_ordered(:proc_nil, proc { |x| x.nil? }) do |params|
+        params
+    end
+
+    def_ordered(:proc_raise, proc { |x| ArgumentError.new("foo") }) do |params|
+        params
+    end
+end
+
+$named_proc = build_named(:stuff => String) do |params|
+    params
+end
+
+$ordered_proc = build_ordered((0..9)) do |params|
+    params
+end
+
+# FIXME module tests
+
+class TestChecks < Test::Unit::TestCase
+    def setup
+        @checked = CheckedClass.new
+    end
+
+    def test_01_named
+        assert(@checked.respond_to?(:named))
+        
+        assert_raises(ArgumentError.new("value of argument 'stuff' is an invalid type. Requires 'String'")) do
+            @checked.named(:stuff => 1, :stuff2 => "pee", :stuff3 => 1)
+        end
+        
+        assert_raises(ArgumentError.new("value of argument 'stuff2' does not match this regexp: '(?-mix:pee)'")) do
+            @checked.named(:stuff => "foo", :stuff2 => "bar", :stuff3 => 1)
+        end
+
+        assert_raises(ArgumentError.new("argument(s) 'stuff2' were not found but are required by the prototype")) do
+            @checked.named(:stuff => "foo", :stuff3 => 1)
+        end
+
+        assert_raises(ArgumentError.new("argument(s) 'stuff2, stuff3' were not found but are required by the prototype")) do
+            @checked.named(:stuff => "foo")
+        end
+
+        assert_raises(ArgumentError.new("argument(s) 'stuff2' were not found but are required by the prototype")) do
+            @checked.named(:stuff => "foo", :stuff3 => nil)
+        end
+
+        assert_equal(
+            @checked.named(:stuff => "foo", :stuff2 => "poopee", :stuff3 => 1), 
+            ["foo", "poopee", 1]
+        )
+
+        assert_equal($named_proc.call(:stuff => "foo"), { :stuff => "foo" })
+    end
+
+    def test_02_checked
+        assert(@checked.respond_to?(:sequential))
+
+        assert_raises(ArgumentError.new("value of argument '0' is an invalid type. Requires 'String'")) do
+            @checked.sequential(nil)
+        end
+        
+        assert_raises(ArgumentError.new("value of argument '1' is an invalid type. Requires 'Integer'")) do
+            @checked.sequential("foo", "bar")
+        end
+        
+        assert_raises(ArgumentError.new("value of argument '1' is an invalid type. Requires 'Integer'")) do
+            @checked.sequential("foo", nil)
+        end
+
+        assert_raises(ArgumentError.new("too many arguments (3 for 2)")) do
+            @checked.sequential("foo", 1, nil)
+        end
+
+        assert_raises(ArgumentError.new("not enough arguments (0 for minimum 1)")) do
+            @checked.sequential()
+        end
+
+        assert_equal(@checked.sequential("foo"), ["foo"])
+        assert_equal(@checked.sequential("foo", 1), ["foo", 1])
+    end
+
+    def test_03_ranges
+        assert(@checked.respond_to?(:ranged))
+
+        assert_raises(ArgumentError.new("value of argument '0' does not match range '0..9'")) do
+            @checked.ranged(-1)
+        end
+
+        assert_raises(ArgumentError.new("value of argument '0' does not match range '0..9'")) do
+            @checked.ranged("foo")
+        end
+
+        assert_raises(ArgumentError.new("value of argument '0' does not match range '0..9'")) do
+            @checked.ranged(10)
+        end
+
+        assert_equal(@checked.ranged(5), [5])
+        assert_equal($ordered_proc.call(5), [5])
+    end
+
+    def test_04_procs
+        assert(@checked.respond_to?(:proc_nil))
+
+        assert_raises(ArgumentError.new("value of argument '0' does not pass custom validation.")) do
+            @checked.proc_nil(true)
+        end
+
+        assert_equal(@checked.proc_nil(nil), [nil])
+        
+        assert(@checked.respond_to?(:proc_nil))
+
+        assert_raises(ArgumentError.new("foo")) do
+            @checked.proc_raise(true)
+        end
+
+        assert_equal(@checked.proc_nil(nil), [nil])
+    end
+end

data/test/test_integrate.rb

@@ -0,0 +1,30 @@
+begin
+    require 'rubygems'
+    gem 'test-unit'
+rescue LoadError
+end
+
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'test/unit'
+require 'methlab'
+
+class TestIntegrate < Test::Unit::TestCase
+    def test_01_integration
+        main = eval("self", TOPLEVEL_BINDING)
+        MethLab.integrate
+
+        module_methods = Module.instance_methods
+        main_methods   = main.methods
+
+        assert(module_methods.include?(:def_named)     || module_methods.include?("def_named"))
+        assert(module_methods.include?(:def_ordered)   || module_methods.include?("def_ordered"))
+        assert(module_methods.include?(:build_named)   || module_methods.include?("build_named"))
+        assert(module_methods.include?(:build_ordered) || module_methods.include?("build_ordered"))
+
+        assert(main_methods.include?(:def_named)     || main_methods.include?("def_named"))
+        assert(main_methods.include?(:def_ordered)   || main_methods.include?("def_ordered"))
+        assert(main_methods.include?(:build_named)   || main_methods.include?("build_named"))
+        assert(main_methods.include?(:build_ordered) || main_methods.include?("build_ordered"))
+    end
+end

metadata

@@ -1,7 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: methlab
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 4
+  version: 0.0.4
 platform: ruby
 authors: 
 - Erik Hollensbe
@@ -23,8 +28,14 @@ extra_rdoc_files: []
 
 files: 
 - lib/methlab.rb
+- test/test_checks.rb
+- test/test_integrate.rb
+- Rakefile
+- README
 has_rdoc: true
 homepage: http://github.com/erikh/methlab
+licenses: []
+
 post_install_message: 
 rdoc_options: []
 
@@ -34,20 +45,22 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.1
+rubygems_version: 1.3.6
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: A method construction and validation toolkit.
 test_files: []