strongtyping 2.0.6 → 2.0.7

data/README.en

@@ -1,420 +0,0 @@
-StrongTyping 2.0
-================
-
-  StrongTyping is a little ruby module that 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.
-
-Changes
--------
-
-   2.0.6b  - Bugfix: Shouldn't get "too many arguments" on gcc
-             anymore.
-
-   2.0.6a  - Bugfix: Portability issues (zero-sized arrays and UNUSED
-             for non-GNU platforms fixed).
-   
-   2.0.6   - Bugfix: Types given after lists of types were not being
-             checked, as in the following:
-   
-                expect(a, String, b, [Integer, String], d, String)
-   
-             Before, 'd' could be any type and pass; now this is fixed.
-   
-   2.0.5   - Bugfix: overload "No matching template" was broken, and
-             I didn't notice.
-   
-             Bugfix: get_arg_types fixed for no arguments; now returns []
-             in the right places for both overload() and expect().
-   
-             Mod: Should compile without warnings with -W -Wall, at least
-             on gcc.
-   
-             Mod: Added unit tests.
-   
-   2.0.4   - Bugfix: Optional arguments are now handled correctly
-             when doing get_arg_types.
-   
-   2.0.3   - It's a bit of a hack, but overload_default's "No matching
-             template" error now displays the given types, which makes
-             debugging a lot easier.
-   
-   2.0.2   - Change Object#type to Object#class for conformance with
-             Ruby 1.8
-   
-             Bugfix: overload() range check that caused a segfault on
-             some systems
-             
-             Bugfix: verify_args_for() should work now
-     
-   2.0.1   - Bugfix: overload() blocks with one parameter now receive the
-             parameter instead of an array
-   
-   2.0     - Rewritten in C for speed.
-               * As in 1.0.1, expect (and overload, etc) take arrays of
-                 classes/modules
-   
-               * overload_error is deprecated (but still available) in
-                 favor of overload_default
-                 
-               * overload_exception acts as overload, but acts as an
-                 "invalid" case; useful for invalid cases where a
-                 specific exception should be thrown
-   
-               * More on "duck typing" in the FAQ
-     
-   1.0.1   - [Not officially released] Added support for arrays of types
-             to expect(), as in expect(a, [Integer, NilClass])
-   1.0     - First release
-   
-Requirements
-------------
-
-  * ruby 1.6
-  * C compiler
-
-Install
--------
-
-  De-Compress archive and enter its top directory.
-  Then type:
-
-    $ ruby extconf.rb
-    $ make
-   ($ su)
-    # make install
-
-Usage
------
-
-  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.
-       
-FAQ
----
-These aren't actually FAQs (yet), but some issues that _have_ been
-brought up.
-
-Q: Why?
-A: Because I need it for Mephle. :-)
-
-
-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  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
-
-
-Ryan Pavlik <rpav@mephle.com>

data/strongtyping.c

@@ -1,247 +0,0 @@
-/*
-    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"
-
-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, "");
-    }
-    
-    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(typestr)->ptr, 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(q->len && rb_funcall(q->ptr[0], id_isa, 1, cQueryParams)) {
-        rb_funcall(q->ptr[0], rb_intern("<<"), 1,
-                   rb_ary_new4(argc - 1, argv + 1));
-        return Qnil;
-    }
-
-    if(q->len != (argc - 1))
-        return Qnil;
-
-    if(check_args(argc - 1, q->ptr, argv + 1) < 0) {
-        if(argc == 2) rb_yield(*RARRAY(*argv)->ptr);
-        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(q->len && (argc - 1) == 0)
-        return Qnil;
-
-    if(check_args(argc - 1, q->ptr, argv + 1) < 0)
-        rb_yield(argv[0]);
-
-    return Qnil;
-}
-
-static VALUE
-strongtyping_overload_error(VALUE self UNUSED, VALUE args) {
-    struct  RArray *q;
-    VALUE           classlist;
-    char           *name = 0;
-    int             i    = 0;
-    
-    Check_Type(args, T_ARRAY);
-    q = RARRAY(args);
-    
-    if(q->len && rb_funcall(q->ptr[0], id_isa, 1, cQueryParams))
-        rb_raise(eArgList, "");
-
-    classlist = rb_str_new2("");
-    for(i = 0; i < q->len; i++) {
-        if(i > 0) rb_str_cat(classlist, ", ", 2);
-        name = rb_class2name(rb_funcall(q->ptr[i], id_class, 0));
-        rb_str_cat(classlist, name, strlen(name));
-    }
-    rb_raise(eOverloadError, "No matching template for arguments: [%s]",
-             RSTRING(classlist)->ptr);
-}
-
-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(mod[i])->len; j++)
-                if(rb_funcall(obj[i], id_isa, 1, RARRAY(mod[i])->ptr[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(ary)->ptr[0],
-           query  = RARRAY(ary)->ptr[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,
-                  *t        = NULL,
-                  *a        = NULL;
-    int            i        = 0;
-    VALUE          template = strongtyping_get_arg_types(self, method);
-
-    list = RARRAY(template);
-    a    = RARRAY(args);
-
-    for(i = 0; i < list->len; i++) {
-        t = RARRAY(list->ptr[i]);
-
-        if(a->len != t->len)                        continue;
-        if(check_args(a->len, a->ptr, t->ptr) < 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");
-
-    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);
-}