next | previous | forward | backward | up | top | index | toc | Macaulay2 website
Macaulay2Doc > The Macaulay2 language > making a new method function > method > specifying typical values

specifying typical values

For the purpose of constructing good documentation automatically, it is useful to specify the type of value typically returned by a function or method. For example, the function isModule returns a boolean value, and this is specified when creating the method function with the option TypicalValue as follows.
isModule = method(TypicalValue => Boolean)

Other functions, such as prune, return values of various types, depending on the type of the arguments provided. To install a function f as the handler for prune applied to a matrix, we would normally use the following statement.

prune Matrix := f
To specify that the value typically returned is a matrix (of class Matrix), we replace f by Matrix => f, as follows.
prune Matrix := Matrix => f
Here is the way our code looks.
i1 : code(prune, Matrix)

o1 = -- code for method: prune(Matrix)
     ../../../../../../../Macaulay2/m2/modules2.m2:492:64-497:6: --source code:
     minimalPresentation(Matrix) := prune(Matrix) := Matrix => opts -> (m) -> (
          M := source m;
          if not M.cache.?pruningMap then m = m * (minimalPresentation M).cache.pruningMap;
          N := target m;
          if not N.cache.?pruningMap then m = (minimalPresentation N).cache.pruningMap^-1 * m;
The information is stored in the hash table typicalValues, and can be recovered like this.
i2 : typicalValues#(prune,Matrix)

o2 = Matrix

o2 : Type

Warning: don't imagine that a definition of the form

f = t -> (...)
can be replaced with a declaration of the following form.
f = X => t -> (...)
The difference here is that here we are using simple assignment, rather than installing a method. To document the return type is X in this case, make an entry in typicalValues directly.
f = t -> (...)
typicalValues#f = X