specifying typical values

specifying typical values

For the purpose of construction 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 = -- ../../../../../Macaulay2/m2/modules2.m2:440-445

     prune(Matrix) := Matrix => (m) -> (

          M := source m;

          if not M.?pruningMap then m = m * (prune M).pruningMap;

          N := target m;

          if not N.?pruningMap then m = (prune N).pruningMap^-1 * m;

          m)

The information is stored in the hash table typicalValues, and can be recovered like this.

i2 : typicalValues#(prune,Matrix)



o2 = Matrix



o2 : Type



  --  the class of all matrices

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