(PUP-1799) Add new Function API
(maint) Change infer_set of Array to produce PTupleType

The infer_set was written before PTupleType was implemented and
used an ArrayType with a single PVariantType with the convention
that the PVariant described a sequence. This was a crutch and
not semantically correct. Only code that knew that the result came
from an infer_set could make this assumption about the PVariantType's
content.

The change is to instead use a PTupleType which correctly describes
a sequence of the types in an Array.
(maint) Add method size_range, and repeat_last_range to collections

(resolve conflict from cherry pick to stable and merge to master
back into the implementation work for PUP-1799)

For PCollectionType (PArrayType and PHashType) the method size_range
now returns a range [min, max] count of entries accepted in the
collection. A result is always given even if no size constraint has
been set.

For PTupleType, the method size_range gives the total accepted
parameter range, and the method repeat_last_range returns the range
of the last parameter. For a tuple, if the size is not constrained
the repeat_last_range is always [1,1]. For a tuple type, the
range of the last parameter is considered in the size_range.

These methods helps answering questions about these types without having
to know anything about their internal semantics.
(PUP-1799) First working version of new Function API (simple dispatch)

This adds the new function API with support for simple dispatching
and a reasonable error message, showing expected signature
and actual types.
(PUP-1799) Make Function handle dispatch directly instead of nested

This changes the API to allow direct calls to dispatch and then
nest parameter specification instead of having to nest all dispatch in
a define_dispatch call.

This also adds support for naming the parameters.
(PUP-1799) Add support for parameter names

This also contains some refactoring and documentation of methods
(PUP-1799) Make new Function API report parameter names.

This makes the function API include the names of parameters if
they are available. When names are available the signatures
show the names (for both array and tuple based signatures).

This also handles the changes made to the TupleType (size constraint
is for the entire type, not just the last entry).
(PUP-1799) Add support for multiple dispatch entries

This adds tests for multiple dispatch (overloaded signatures), and
fixes issues with error reporting for this scenario.
(PUP-1799) Add marking of optional and varargs count in error message

When an error is raised becuse of no matching signature, the 
expected signatures are printed with each parameter on the form:

Type name<count>

where count is ? for an optional {0,1} parameter, and with a range
{from, to} if from and to are not both 1 (in which case count is an 
empty string), and only a comma is shown if to is INFINITY. 

e.g. a message may show:

  foo(Integer a, String b?, String{0,}) - arg count {1,}

The trailing arg count shows required min, and allowed max as a short
hand notation.
(PUP-1799) Change default inferred param type to Object (no undef)

This changes the default inferred parameter type to Object from
Optional[Object], since this is by far more common than accepting
that values are undef. (If undef values should be expected that is
stated explicitly.
(PUP-1799) Modify how required/optional/varargs count is specified

This changes the somewhat complex setting of argument count.
If nothing is specified it is derived from the specified parameters.
If something else than exact count is wanted, the arg_count method
is called with min, max where :default is used to denote infinite.
(PUP-1799) Add support for injection of Function class attributes

This adds support to inject attributes (via defined lazy accessors
that performs the lookup). The methods attr_injected, and
attr_injecteted_producer defines the injection of a value, and of a
producer. The function logic can access these via method calls.
(PUP-1799) Add support for injection of parameters and weaving

This adds injection of parameters and weaving of them when
dispatching. The dispatching logic is also somewhat refactored
from using anonymous arrays to a Dispatch object.

The methods injected_param, injected_producer_param specifies
that additional parameters should be injected when a call is made.
Their position defines where they are injected and the ruby method
signature should be matched to handle them.

The injection of parameters works for both regular and polymorphic
dispatch.

This makes use of injection more declarative, and it is easy to
test a Function class' methods.
(PUP-1799) Yardoc and dead code removal in Function API
(PUP-1799) Fix issue when running under Ruby 1.8.7 (typo)

This fixes a typo in the Ruby 1.8.7 branch of the logic that
introspects a method.
(PUP-1799) Fix argument count adjustment for Ruby 1.8.7

There was a problem with PArrayType based signature string
when there are no parameter names - the adjustment resulted
in off by one error in the displayed string.
(PUP-1799) Fix test of function API for Ruby 1.8.7

The tests when running under Ruby 1.8.7 have to be different since
the parameter names are not available in the API for method. The
generated error messages therefore looks different. Also, since the
parameter arity is quite broken in Ruby 1.8.7 it is not possible to
represent a signature with a good type - the result is that an
PArrayType is used to represent the signature, and it is always
Object{to, from}.

The change is to compare against different messages in the 3 test cases
that failed on Ruby 1.8.7.
Merge pull request #2465 from hlindberg/pup-1799_add-new-function-api

(PUP-1799) add new function api
(maint) Remove commented out code
(maint) Pin rake for acceptance to the last 1.8 compatible version