<?xml version="1.0" encoding="utf-8" ?> <!-- for emacs: -*- coding: utf-8 -*- -->
<!-- Apache may like this line in the file .htaccess: AddCharset utf-8 .html -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0 plus SVG 1.1//EN" "http://www.w3.org/2002/04/xhtml-math-svg/xhtml-math-svg-flat.dtd" >
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>specifying typical values</title>
<link rel="stylesheet" type="text/css" href="../../../../Macaulay2/Style/doc.css"/>
</head>
<body>
<table class="buttons">
<tr>
<td><div><a href="_splice.html">next</a> | <a href="___Spec_lp__Ring_rp.html">previous</a> | <a href="_splice.html">forward</a> | <a href="___Spec_lp__Ring_rp.html">backward</a> | up | <a href="index.html">top</a> | <a href="master.html">index</a> | <a href="toc.html">toc</a> | <a href="http://www.math.uiuc.edu/Macaulay2/">Macaulay2 web site</a></div>
</td>
</tr>
</table>
<hr/>
<div><h1>specifying typical values</h1>
<div>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 <a href="_is__Module.html" title="whether something is a module">isModule</a> returns a boolean value, and this is specified when creating the method function with the option <a href="_method.html" title="make a new method function">TypicalValue</a> as follows.<pre>isModule = method(TypicalValue => Boolean)</pre>
<p/>
Other functions, such as <a href="_prune.html" title="prune, e.g., compute a minimal presentation">prune</a>, return values of various types, depending on the type of the arguments provided. To install a function <tt>f</tt> as the handler for <tt>prune</tt> applied to a matrix, we would normally use the following statement.<pre>prune Matrix := f</pre>
To specify that the value typically returned is a matrix (of class <tt>Matrix</tt>), we replace <tt>f</tt> by <tt>Matrix => f</tt>, as follows.<pre>prune Matrix := Matrix => f</pre>
Here is the way our code looks.<table class="examples"><tr><td><pre>i1 : code(prune, Matrix)
o1 = -- code for method: prune(Matrix)
/builddir/build/BUILD/Macaulay2-1.3.1-r10737/Macaulay2/m2/modules2.m2:444:64-449: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;
m)</pre>
</td></tr>
</table>
The information is stored in the hash table <a href="_typical__Values.html" title="types of values returned by functions">typicalValues</a>, and can be recovered like this.<table class="examples"><tr><td><pre>i2 : typicalValues#(prune,Matrix)
o2 = Matrix
o2 : Type</pre>
</td></tr>
</table>
<p/>
Warning: don't imagine that a definition of the form <pre>f = t -> (...)</pre>
can be replaced with a declaration of the following form.<pre>f = X => t -> (...)</pre>
The difference here is that here we are using simple assignment, rather than installing a method. To document the return type is <tt>X</tt> in this case, make an entry in <tt>typicalValues</tt> directly.<pre>f = t -> (...)
typicalValues#f = X</pre>
</div>
</div>
</body>
</html>
