strongtyping 2.0.6 → 2.0.7

data/MANIFEST

@@ -1,9 +1,11 @@
-./t/functest.rb
-./t/timetest.rb
-./Makefile
-./README.en
-./extconf.rb
-./strongtyping.c
-./LGPL
-./MANIFEST
-./strongtyping.h
+CHANGES
+LGPL
+MANIFEST
+README
+Rakefile
+strongtyping.gemspec
+ext/extconf.rb
+ext/strongtyping.c
+ext/strongtyping.h
+test/functest.rb
+test/timetest.rb

data/README

@@ -0,0 +1,330 @@
+= Description
+  The strongtyping library is a provides a convenient way for Ruby methods
+  to check parameter types, and also dynamically query them. In addition to
+  merely checking a single set of types, it allows easy overloading based on
+  a number of different templates.
+
+= Installation
+  gem install strongtyping
+
+= Synopsis
+  Let's say you have the following function:
+
+    def foo(a, b)
+      ...
+    end
+
+  Now let's say this function wants 'a' to always be a String, and 'b'
+  should be Numeric:
+
+    require 'strongtyping'
+    include strongtyping
+
+    def foo(a, b)
+      expect(a, String, b, Numeric)
+      ...
+    end
+
+  If 'a' or 'b' is of the wrong type, an ArgumentTypeError will be raised.
+
+  Overloading is just as easy:
+
+    require 'strongtyping'
+    include strongtyping
+
+    def bar(*args)
+      overload(args, String, String){ |s1,s2|
+        ...
+        return
+      }
+
+      overload(args, String, Integer){ |s,i|
+        ...
+        return
+      }
+
+      overload_default args
+    end
+
+  If someone calls 'bar' with two Strings, or a String and an Integer,
+  the appropriate block will be called.  Otherwise, an OverloadError
+  is raised.
+
+  How about default parameters? Say we have the following function:
+
+    def baz(a, b = nil)
+      action  = "You baz #{a}";
+      action += " with a #{b}"  if b
+
+      print action, "\n"
+    end
+
+  Now, b can either be nil or a String.  We don't want to have two
+  full overload cases... that would duplicate code.  So, expect()
+  allows an array of types:
+
+    expect(a, String, b, [String, NilClass]);
+
+  This takes care of the above case nicely.
+
+  What if your code is curious about which types are allowed?  The
+  get_arg_types function is provided for just this purpose.  Given the
+  above definitions for 'foo' and 'bar', consider the following code:
+
+    p get_arg_types(method(:foo))  # => [[String, Numeric]]
+    p get_arg_types(method(:bar))  # => [[String, String], [String, Integer]]
+    p get_arg_types(method(:baz))  # => [[String, [String, NilClass]]]
+      
+  This is useful if you're converting user input into a form that the
+  method expects.  (If you get "1234", should you convert it to an
+  integer, or is it best left a string? Now you know.)
+
+  What if you have an array of arguments, 'arr', and you're worried
+  that the method 'bar' won't accept them?  You can check ahead of
+  time:
+
+    if not verify_args_for(method(:bar), arr)
+      print "I can't let you do that, Dave\n"
+    end
+
+= Reference
+  Module: strongtyping
+
+  Methods:
+  
+    expect(obj0, Module0[, obj1, Module1[,...objN, ModuleN]])
+
+       Verify the parameters obj0..objN are of the given class (or
+       module) Module0..ModuleN
+
+    overload(args, [Module0[, Module1[,...ModuleN]]]) { | o0, o1,..oN | }
+
+       Call the block with 'args' if they match the pattern
+       Module0..ModuleN.  The block should _always_ call return at the
+       end.
+
+    overload_exception(args, [Module0[,...ModuleN]]]) { | o0, o1,..oN | }
+
+       This acts identically to overload(), except the case specified
+       is considered invalid, and thus not returned by get_arg_types().
+       It is expected that the specified block will throw an exception.
+
+    overload_default(args)       
+    overload_error(args)
+    
+       Raise OverloadError.  This should _always_ be called after the
+       last overload() block.  In addition to raising the exception,
+       it aids in checking parameters.  As of 2.0, the overload_error
+       name is deprecated; use overload_default.
+
+    get_arg_types(Method)
+
+       Return an array of parameter templates.  This is an array of
+       arrays, and will have multiple indices for functions using
+       multiple overload() blocks.
+
+    verify_args_for(method, args)
+
+       Verify the method 'method' will accept the arguments in array
+       'args', returning a boolean result.
+
+  Exceptions:
+
+    ArgumentTypeError < ArgumentError
+
+      This exception is raised by expect() if the arguments do not
+      match the expected types.
+
+    OverloadError < ArgumentTypeError
+
+      This exception is raised by overload_default() if no overload()
+      template matches the given arguments.
+       
+= Q & A
+  This section written by Ryan Pavlik.
+
+  Q: Why?
+  A: Because it was originally needed for the Mephle library.
+
+  Q: No really, why bother with static typing? Isn't ruby dynamic?
+  A: This is not 'static typing'.  This is 'strong typing'.  Static
+     typing is what you get when a variable can only be of a certain
+     type, as in C or C++.  Strong typing is enforcing types. These may
+     seem similar, but they are actually not directly related.
+
+     Some other languages, such as Common Lisp, allow for dynamic,
+     strong typing. Strong typing and dynamic typing are not mutually
+     exclusive.
+
+  Q: Yeah, but really, why bother?  Why not just let ruby sort out the
+     errors as they occur?  
+  A: This is incorrect thinking. Allowing errors to just occur when
+     they happen is naive programming. Consider the following:
+
+       # Wait N seconds, then open the bridge for M seconds
+       def sendMsg(bridge, n, m)
+         sleep(n)
+         bridge.open
+         sleep(m)
+         bridge.close
+       end
+
+     Now say 'm' is pased in as a string.  Oops!  A TypeError is
+     raised. Now the bridge is open, and somewhere (hopefully!) someone
+     caught the exception so the program didn't crash, but the bridge
+     opening wasn't reversed, so it's going to stay open and back up
+     traffic until someone fixes the problem.
+
+     This is an academic example, but there are many cases when just
+     letting an error happen will lead to an inconsistent system state.
+     Ruby (and most systems) are not transactional, and inconsistent
+     states are unacceptable.
+
+     In addition, it is desireable to know _programmatically_ why
+     something failed, as specific action can be taken if desired.
+
+     "Wait," someone in the audience says, "you could just check to see
+     if 'm' and 'n' are of the correct type!"
+
+     Yes, yes you could.
+
+     That's what this module is for. ;-)
+
+  Q: Isn't it up to the caller to call my function correctly?
+  A: The caller cannot know and deal with errors that may occur in your
+     code.  That's your job.  Checking for errors ahead of time and
+     informing the caller about problems is also your job.  This module
+     just makes it easy.
+
+     In addition, it's nice for the caller to be able to ask and check
+     what your method expects ahead of time to guard against error.
+     The strongtyping module also provides functionality for this.
+
+  Q: OK, but strong typing is baaad.  What if I want to pass something
+     that acts like something else, or responds to a given symbol?
+     Doesn't ruby have "duck" typing?
+  A: First, what you're suggesting is evil. If you want that, go
+     write C++. :-)
+
+     Second, you should never depend on a function's implementation.  If
+     the documentation says "pass me a hash" and you pass it anything
+     that responds to :[], your code may break when the next version
+     comes out.
+
+     Third, if you pass something that responds accurately to the
+     _interface_ (methods provided by class or module) specified, then
+     that should be _of_ that class or module.  This may not be the case
+     with all ruby objects yet; for instance, anything responding to :[]
+     being something like a Mappable.  You can make this the case in
+     your code, or urge developers to create a standard set of interface
+     mixins for just this purpose.
+
+     "Duck" typing just a term for this sort of "maybe" behavior, much
+     like what C++ STL templates use.  However, the problem is that even
+     if an object responds to a method, there is no guarantee that the
+     method acts in an expected manner---and the interface may still
+     change without notice.  "Duck" typing sounds much like 'duct
+     taping' depending on your accent, and I think duct-taping is a good
+     description of this is in practice. :-)
+
+     Another argument is that ruby allows one to change the behavior of
+     methods at any time:
+
+       a = String.new;
+       def a.split
+         print "hello world\n"
+       end
+
+     For this, I have two responses:  first, if a method is deprecated
+     or changed dramatically, strongtyping can aid in letting the code
+     know:
+
+        a = String.new;
+        def a.split(*args)
+           overload(args) { print "hello world\n" }
+           overload_default args
+        end
+
+     This case will drop any normal calls through to overload_default,
+     raising an exception, which can be caught and analyzed.  You can
+     even provide another case that calls the superclass.
+
+     Second, either you're changing the method in a subtle manner (it
+     does what it used to, with added effect), or an outrageous manner
+     (it acts nothing like it did before).  In the former case, code
+     should work fine anyway.  In the latter case, as in the above
+     example, you should ask yourself why you're changing it.  The
+     function no longer splits, why is it called split?  This is not
+     good design; the strongtyping module is here to aid in good design,
+     not prevent poor design.
+
+     A more realistic example would be the academic "Shape" class
+     example of inheritance, with "Ellipse" and "Circle".  Ruby properly
+     allows one to make Circle a subclass of Ellipse, and redefine
+     "setSize" to the constrained definition of a circle.  This change
+     is visible to code---an ArgumentError will be raised (2 arguments
+     for 1), or setSize can throw a ConstraintError.  strongtyping
+     provides a useful function, overload_exception, for just this case:
+
+        class Circle < Ellipse
+           :
+           def setSize(*args)
+              overload(args, Integer) {
+                 | r |
+                 @radius = r
+                 return
+              }
+
+              overload_exception(args, Integer, Integer) {
+                 | a, b |
+                 raise ConstraintError
+              }
+              
+              overload_default args
+           end
+           :
+        end
+
+     Of course, there are a number of good choices for handling
+     this... you may still allow #setSize(a, b) if a == b.  The
+     important part is that the change in behavior can now be determined
+     by code.
+
+  Q: But I always write perfect code.  I know what my functions do, and
+     what they take, and what I'm passing them.
+  A: No one writes perfect code.  Additionally, not all environments are
+     as controlled as yours may be.  Especially in a networked
+     environment when someone may be invoking a method remotely, you
+     can't depend on calling code not to be malicious.
+
+  Q: OK, OK.  But, uh... what is Mephle?
+  A: Mephle is a soon-to-be-released network-transparent persistant
+     object system written in ruby.  It uses many of the Unity concepts
+     (http://unity-project.sf.net/).  It will be on the RAA when
+     released.
+
+= License
+  strongtyping - Method parameter checking for Ruby
+  Copyright (C) 2003-2011 Ryan Pavlik
+
+  This library is free software; you can redistribute it and/or
+  modify it under the terms of the GNU Lesser General Public
+  License as published by the Free Software Foundation; either
+  version 2.1 of the License, or (at your option) any later version.
+
+  This library is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public
+  License along with this library; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+
+= Future Plans
+  There's some odd C code that is causing a couple of warnings, but it
+  does not appear to be harmful. I want to clean this code up eventually.
+
+= Authors
+* Ryan Pavlik (original author)
+* Daniel Berger (maintenance)

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rbconfig'
+include Config
+
+CLEAN.include(
+  '**/*.gem',               # Gem files
+  '**/*.rbc',               # Rubinius
+  '**/*.o',                 # C object file
+  '**/*.log',               # Ruby extension build log
+  '**/Makefile',            # C Makefile
+  '**/conftest.dSYM',       # OS X build directory
+  "**/*.#{CONFIG['DLEXT']}" # C shared object
+)
+
+desc "Build the strongtyping source"
+task :build => [:clean] do
+  make = File::ALT_SEPARATOR ? "nmake" : "make"
+  Dir.chdir('ext') do
+    ruby 'extconf.rb'
+    sh "#{make}"
+  end
+end
+
+namespace 'gem' do
+  desc 'Create the strongtyping gem'
+  task :create => [:clean] do
+    Dir["*.gem"].each{ |f| File.delete(f) } # Clean first
+    spec = eval(IO.read('strongtyping.gemspec'))
+    Gem::Builder.new(spec).build
+  end
+
+  desc 'Install the strongtyping gem'
+  task :install => [:create] do
+    file = Dir["*.gem"].first
+    sh "gem install #{file}"
+  end
+end
+
+Rake::TestTask.new do |t|
+  task :test => :build
+  t.libs << 'ext'
+  t.verbose = true
+  t.warning = true
+end
+
+task :default => :test

data/{extconf.rb → ext/extconf.rb}

@@ -1,3 +1,3 @@
-require 'mkmf'
-
-create_makefile "strongtyping"
+require 'mkmf'
+
+create_makefile "strongtyping"

data/ext/strongtyping.c

@@ -0,0 +1,283 @@
+/*
+  StrongTyping - Method parameter checking for Ruby
+  Copyright (C) 2003  Ryan Pavlik
+
+  This library is free software; you can redistribute it and/or
+  modify it under the terms of the GNU Lesser General Public
+  License as published by the Free Software Foundation; either
+  version 2.1 of the License, or (at your option) any later version.
+
+  This library is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+  Lesser General Public License for more details.
+
+  You should have received a copy of the GNU Lesser General Public
+  License along with this library; if not, write to the Free Software
+  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+*/
+
+#include "ruby.h"
+#include "strongtyping.h"
+
+/* Ruby 1.9.x */
+#ifndef RSTRING_PTR
+#define RSTRING_PTR(s) (RSTRING(s)->ptr)
+#endif
+#ifndef RSTRING_LEN
+#define RSTRING_LEN(s) (RSTRING(s)->len)
+#endif
+
+#ifndef RARRAY_PTR
+#define RARRAY_PTR(a) (RARRAY(a)->ptr)
+#endif
+#ifndef RARRAY_LEN
+#define RARRAY_LEN(a) (RARRAY(a)->len)
+#endif
+
+static int check_args(int argc, VALUE *obj, VALUE *mod);
+
+static VALUE strongtyping_expect(int argc, VALUE *argv, VALUE self UNUSED) {
+  int i = 0;
+  VALUE obj[MAXARGS], mod[MAXARGS];
+  VALUE typestr;
+
+  if(!argc)
+    return Qnil;
+
+  if(argc % 2)
+    rb_raise(rb_eSyntaxError, "expect() requires argument pairs");
+
+#ifndef __GNUC__
+  if(argc*2 > MAXARGS*2)
+    rb_raise(rb_eSyntaxError, "too many arguments to expect()");
+#endif
+
+  for(i = 0; i < argc; i += 2) {
+    obj[i/2]     = argv[i];
+    mod[(i+1)/2] = argv[i+1];
+  }
+
+  if(rb_funcall(obj[0], id_isa, 1, cQueryParams)) {
+    rb_funcall(obj[0], rb_intern("<<"), 1, rb_ary_new4(argc/2, mod));
+    rb_raise(eArgList, ""); // TODO: Why an empty string? Causes a warning in 1.9.x.
+  }
+    
+  i = check_args(argc / 2, obj, mod);
+
+  if(i < 0)
+    return Qnil;
+
+  typestr = rb_funcall(mod[i], id_inspect, 0);
+
+  rb_raise(
+    eArgumentTypeError,
+    "Expecting %s as argument %d, got %s",
+    RSTRING_PTR(typestr), i + 1,
+    rb_class2name(rb_funcall(obj[i], id_class, 0))
+  );
+}
+
+static VALUE strongtyping_overload(int argc, VALUE *argv, VALUE self UNUSED) {
+  struct RArray *q;
+    
+  if(argc < 1)
+    rb_raise(rb_eArgError, "At least one parameter required");
+
+  Check_Type(argv[0], T_ARRAY);
+  q = RARRAY(argv[0]);
+
+  if(RARRAY_LEN(q) && rb_funcall(RARRAY_PTR(q)[0], id_isa, 1, cQueryParams)) {
+    rb_funcall(RARRAY_PTR(q)[0], rb_intern("<<"), 1, rb_ary_new4(argc - 1, argv + 1));
+    return Qnil;
+  }
+
+  if(RARRAY_LEN(q) != (argc - 1))
+    return Qnil;
+
+  if(check_args(argc - 1, RARRAY_PTR(q), argv + 1) < 0){
+    if(argc == 2)
+      rb_yield(*RARRAY_PTR(*argv));
+    else
+      rb_yield(*argv);
+  }
+
+  return Qnil;
+}
+
+static VALUE strongtyping_overload_exception(int argc, VALUE *argv, VALUE self UNUSED) {
+  struct RArray *q;
+    
+  if(argc < 1)
+    rb_raise(rb_eArgError, "At least one parameters required");
+
+  Check_Type(argv[0], T_ARRAY);
+  q = RARRAY(argv[0]);
+
+  if(RARRAY_LEN(q) && (argc - 1) == 0)
+    return Qnil;
+
+  if(check_args(argc - 1, RARRAY_PTR(q), argv + 1) < 0)
+    rb_yield(argv[0]);
+
+  return Qnil;
+}
+
+static VALUE strongtyping_overload_error(VALUE self UNUSED, VALUE args) {
+  struct  RArray *q;
+  VALUE           classlist;
+  const char      *name = 0;
+  int             i    = 0;
+    
+  Check_Type(args, T_ARRAY);
+  q = RARRAY(args);
+    
+  if(RARRAY_LEN(q) && rb_funcall(RARRAY_PTR(q)[0], id_isa, 1, cQueryParams))
+    rb_raise(eArgList, "");
+
+  classlist = rb_str_new2("");
+
+  for(i = 0; i < RARRAY_LEN(q); i++) {
+    if(i > 0)
+      rb_str_cat(classlist, ", ", 2);
+
+    name = rb_class2name(rb_funcall(RARRAY_PTR(q)[i], id_class, 0));
+    rb_str_cat(classlist, name, strlen(name));
+  }
+
+  rb_raise(
+    eOverloadError,
+    "No matching template for arguments: [%s]",
+    RSTRING_PTR(classlist)
+  );
+}
+
+static int check_args(int argc, VALUE *obj, VALUE *mod) {
+  int i = 0;
+  VALUE ret;
+    
+  for(i = 0; i < argc; i++){
+    if(TYPE(mod[i]) == T_ARRAY){
+      int j = 0, ok = 0;
+
+      for(j = 0; j < RARRAY_LEN(mod[i]); j++){
+        if(rb_funcall(obj[i], id_isa, 1, RARRAY_PTR(mod[i])[j]) == Qtrue)
+          ok = 1;
+      }
+
+      if(ok)
+        continue;
+      else
+        return i;
+    }
+    else{
+      ret = rb_funcall(obj[i], id_isa, 1, mod[i]);
+      if(ret == Qfalse) return i;
+    }
+  }
+
+  return -1;
+}
+
+static VALUE call_method(VALUE ary) {
+  VALUE  method = RARRAY_PTR(ary)[0],
+         query  = RARRAY_PTR(ary)[1];
+  VALUE *argv   =  NULL;
+  VALUE  ret;
+  int    argc   =  0,
+         i      =  0;
+
+  argc = FIX2INT(rb_funcall(method, rb_intern("arity"), 0));
+
+  if(argc == 0) {
+    rb_funcall(query, rb_intern("<<"), 1, rb_ary_new());
+    rb_raise(eArgList, "");
+  }
+  else if(argc < 0)
+    argc = -argc;
+
+  argv    = malloc(sizeof(VALUE) * argc);
+  argv[0] = query;
+
+  for(i = 1; i < argc - 1; i++)
+    argv[i] = Qnil;
+
+  ret = rb_funcall2(method, rb_intern("call"), argc, argv);
+  free(argv);
+
+  return ret;
+}
+
+static VALUE grab_types(VALUE query) {
+  return query;
+}
+
+static VALUE strongtyping_get_arg_types(VALUE obj UNUSED, VALUE method) {
+  VALUE query, ary;
+  query = rb_funcall(cQueryParams, rb_intern("new"), 0);
+  ary   = rb_ary_new3(2, method, query);
+    
+  return rb_rescue2(call_method, ary, grab_types, query, eArgList, 0);
+}
+
+static VALUE strongtyping_verify_args_for(VALUE self, VALUE method, VALUE args) {
+  struct RArray *list = NULL;
+  struct RArray *t    = NULL;
+  struct RArray *a    = NULL;
+  int i    = 0;
+  VALUE template = strongtyping_get_arg_types(self, method);
+
+  list = RARRAY(template);
+  a    = RARRAY(args);
+
+  for(i = 0; i < RARRAY_LEN(list); i++){
+    t = RARRAY_PTR(list)[i];
+
+    if(RARRAY_LEN(a) != RARRAY_LEN(t))
+      continue;
+
+    if(check_args(RARRAY_LEN(a), RARRAY_PTR(a), RARRAY_PTR(t)) < 0)
+      return Qtrue;
+  }
+    
+  return Qfalse;
+}
+
+void Init_strongtyping() {
+    mStrongTyping = rb_define_module("StrongTyping");
+    id_isa        = rb_intern("is_a?");
+    id_class      = rb_intern("class");
+    id_inspect    = rb_intern("inspect");
+
+    /* 2.0.7: The version of the strongtyping library */
+    rb_define_const(mStrongTyping, "VERSION", rb_str_new2("2.0.7"));
+
+    cQueryParams       = rb_define_class_under(mStrongTyping,
+                                               "%QueryParams",
+                                               rb_cArray);
+
+    eArgumentTypeError = rb_define_class_under(mStrongTyping,
+                                               "ArgumentTypeError",
+                                               rb_eArgError);
+    eOverloadError     = rb_define_class_under(mStrongTyping,
+                                               "OverloadError",
+                                               eArgumentTypeError);
+    eArgList           = rb_define_class_under(mStrongTyping,
+                                               "%ArgList",
+                                               rb_eException);
+
+    rb_define_module_function(mStrongTyping, "expect",
+                              strongtyping_expect, -1);
+    rb_define_module_function(mStrongTyping, "overload",
+                              strongtyping_overload, -1);
+    rb_define_module_function(mStrongTyping, "overload_exception",
+                              strongtyping_overload_exception, -1);
+    rb_define_module_function(mStrongTyping, "overload_default",
+                              strongtyping_overload_error, 1);
+    rb_define_module_function(mStrongTyping, "overload_error",
+                              strongtyping_overload_error, 1);
+    rb_define_module_function(mStrongTyping, "get_arg_types",
+                              strongtyping_get_arg_types, 1);
+    rb_define_module_function(mStrongTyping, "verify_args_for",
+                              strongtyping_verify_args_for, 2);
+}