Implementations and Type Patterns

This page is devoted to the design and documentation of the primary entity that can be exported to (partially) define a nanomath method: the Implementation. Before getting into the details, some technical perspective will be useful. We take the position that we have true n-ary functions, that take multiple arguments, rather than considering all functions to be unary, just with some sort of tuple or vector arguments. As a result, the argument list to a function call determines a finite sequence of Types, namely that produced by calling typeOf on each actual argument in turn. Note that in operation, the resulting sequence will only consist of "ground" types, that have no indeterminate type parameters, and moreover of "most specialized" ground types: if an actual argument a of a function is reported as being of type T, then there is no subtype U of T known to the nanomath instance such that a is also of type U. Thus, an argument type might be of DenseMatrix(bigint) but it can't be just DenseMatrix (a generic type) nor even Matrix(bigint) since there is no Matrix that is not actually one of its subtypes, e.g. DenseMatrix or SparseMatrix. Similarly, we do have a type Union(Number, BigInt) that might be necessary, for example, to describe the return type of some function, but no actual argument is ever of type Union(Number, BigInt), as any such entity would either be of type Number or of type BigInt. In particular, nanomath has no facility for creating arbitrary enumerated subtypes of its types.

Further, we take the perspective that a "sequence of types" is not itself a type. To be sure, we expect to have various tuple or tuple-like types, such as Array, but that these types represent unitary entities, that could only constitute a single actual argument. In other words, foo([1, 2, 3]) has a single Array(Number) argument, but foo(1, 2, 3) has three actual arguments, each of which is a Number; there is no way for a single typed parameter to span multiple actual arguments, and we do not suppose that the argument(s), as a whole, to foo(1,2,3) are (collectively or otherwise) of type Array(Number).

On the other hand, we do want to be able to write functions that can operate on arbitrarily many actual arguments, or that may accept any arguments described by certain conditions. For this purpose, nanomath supports the concept of a Type Pattern. A Type Pattern is basically a predicate that can match against a sequence of most specialized ground types.

The currently supported and/or planned Type Patterns are as follows:

Any ground type may be considered a pattern that matches a single-element sequence of itself or a subtype of itself.
Any generic type may be considered a pattern that matches a single-element sequence of any instantiation of itself or subtype of an instantiation of itself.
The built-in pattern Any (note it is disallowed to have a type named Any) matches any single-element sequence of types.
If P1, P2, ..., Pn are patterns, then the sequence of patterns [P1, P2, ..., Pn] matches any sequence of argument types that can be partitioned into n subsequences, the first of which matches P1, the second matches P2, and so on, up to the final subsequence matching Pn. Note that when the actual arguments that match such a sequence of patterns is conveyed to an associated behavior (see below), they are always transmitted as exactly n arguments -- the portions of the actual argument sequence each of the patterns matched. Note that generally, single-argument portions are passed simply as the single corresponding value, except as noted below, whereas 0-length and ≥2-length portions are always passed as ordinary arrays of the corresponding values.
If P is a pattern, then Multiple(P) is a pattern that matches any number of repeats of matches to P, including zero. For convenience, a match to Multiple(P) is always conveyed to an associated behavior as an Array of the underlying matches, even if there is only one match. Note that Multiple patterns match greedily, and there is no backtracking. For example, in the pattern [Multiple(Number), Multiple(Number)], the second match would always be empty, and the patterns [Multiple(Number), Number] can never match anything, as the matching of the first pattern would use up all initial Number arguments, so the next remaining argument, if any, would definitely not be a number.
If P is a pattern, then Optional(P) is a pattern that will match 0 or 1 occurrences of matches to P. As with Multiple(P), a match to Optional(P) will always be conveyed as an ordinary Array of length 1 or 0. This convention is necessary because any value that could be used as a "sentinel" that no match to P occurred might, for some pattern P, also constitute an ("unboxed") single match to P. E.g., if [] were used for no match, then receiving an argument [] from a match to Optional(Array(Boolean)) would be ambiguous between no match and matching an actual argument of [].

Some consequences of these definitions:

The patterns Optional(Multiple(P)) and Multiple(Optional(P)) would be useless and in fact the latter might hang, generating arbitrarily many "no match" results, each using up none of the actual argument list. Stick with just Multiple(P) or Optional(P).
There is no requirement that the P in Multiple(P) match just a single argument type in the sequence. In particular, Multiple([String, Any]) matches any sequence of argument types in which every other argument starting from the first is a String, and returns it as an array of pairs of actual arguments -- exactly what's needed as the argument to Object.from(), for example.
There is no requirement that a Multiple(P) pattern occur last in a sequence of patterns. For example, [Multiple(Number), String] matches zero or more Numbers followed by a String.
[P1, P2, P3] and [P1, [P2, P3]] match the same sequences of argument types, but differ in how they are conveyed to an associated behavior: the first pattern will always result in the behavior being called with exactly three arguments, the matches to P1, P2, and P3, respectively, whereas the second pattern will result in a call with exactly two arguments, the second of which will always be a two-element Array consisting of the match to P2 and the match to P3.
The pattern Multiple(Any) matches any sequence of argument types whatsoever. If a function is encountered where an Implementation is expected, it is treated as the pattern Multiple(Any) with the function as the associated behavior. When the function is invoked, it will receive an Array of all of the actual arguments as its single argument.
At the other end of the spectrum, [] matches only the empty sequence of argument types.

We can now state precisely what an Implementation is: it consists of a collection of pairs of a Type Pattern and an associated behavior. The associated behavior may either be a factory, which will be called with the nanomath instance from which it can extract dependencies, and the Array of actual (most specific ground) argument types, subdivided as per the pattern match, and can use them to return a return-type-labeled specific behavior, or a direct return-type-labeled behavior which will have no dependencies. Either way, the ultimate return-type-labeled behavior will be called with the actual arguments, again split up as per the pattern match as described above.

Finally, for convenience, if no pattern matches (other than Multiple(Any), if there is a behavior for that), then nanomath will check if automatic type conversions can be applied to some of the arguments to produce a sequence of argument types that will match one of the patterns (except for Multiple(Any)). If it finds at least one, it will choose the lexicographically last sequence of positions in which to perform conversions. In such a case, the conversions will automatically be applied before calling the associated behavior

If there is no match of any pattern, even with automatic conversions, the method resolution will throw a TypeError.