Basic documentation for constructors

doc/ref/methsel.xml

@@ -256,6 +256,72 @@ one can install also <E>immediate methods</E>.
 
 </Section>
 
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Constructors">
+<Heading>Constructors</Heading>
+
+Constructors are a special type of operation used to make new
+objects. The key difference is that the first argument in a call to a
+constructor is a filter <Ref Sect="Filters"/> rather than an
+object. This signifies filters in which the constructed object must
+lie and method selection is based on the value of this filter, rather
+than its type.
+
+<Example>
+gap> DeclareConstructor("XCons",[IsMagma,IsInt]);
+gap> InstallMethod(XCons, [IsGroup, IsInt], function(t,x) return CyclicGroup(x); end);
+gap> InstallMethod(XCons, [IsPermGroup, IsInt], function(t,x) return SymmetricGroup(x); end);
+gap> InstallMethod(XCons, [IsSemigroup, IsInt], function(t,x) return FullTransformationMonoid(x); end);
+gap> XCons(IsGroup,3);
+&lt;pc group of size 3 with 1 generators&gt;
+gap> XCons(IsPermGroup,3);
+Sym( [ 1 .. 3 ] )
+gap> XCons(IsSemigroup,4);
+&lt;full transformation monoid of degree 4&gt;
+</Example>
+
+The example above shows sonme basic examples (usually a constructor
+will produce isomorphic objects in different representations, not
+different objects as in this case).
+
+If no method has been installed which guarantees to produce a suitable
+objecty, a "No Method Found" error will be returned. 
+<Example>
+gap> XCons(IsFullTransformationMonoid,4);
+Error, no method found! For debugging hints type ?Recovery from NoMethodFound
+Error, no 1st choice method found for `XCons' on 2 arguments called from
+&lt;function "HANDLE_METHOD_NOT_FOUND"&gt;( &lt;arguments&gt; )
+ called from read-eval loop at line 8 of *stdin*
+you can 'quit;' to quit to outer loop, or
+you can 'return;' to continue
+brk&gt;
+gap&gt; XCons(IsNilpotentGroup,4);
+Error, no method found! For debugging hints type ?Recovery from NoMethodFound
+Error, no 1st choice method found for `XCons' on 2 arguments called from
+&lt;function "HANDLE_METHOD_NOT_FOUND"&gt;( &lt;arguments&gt; )
+ called from read-eval loop at line 9 of *stdin*
+you can 'quit;' to quit to outer loop, or
+you can 'return;' to continue
+brk>
+</Example>
+
+Note that in both these cases there are methods that actually produce
+results of the required types, but they have not been installed with
+this information, so are not selected.
+
+<Example>
+gap> XCons(IsRegularSemigroup,4);
+&lt;pc group of size 4 with 2 generators&gt;
+</Example>
+
+Finally note the possibly unexpected behaviour in this example. Since
+all groups are regular semigroups, the cyclic group constructor is
+applicable.
+
+The exact details of method ranking for constructors are under review
+at this time and may be changed, so do not rely on them.
+
+</Section>
 
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <Section Label="Operations and Mathematical Terms">