Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

document DeclareCategoryCollections; document constructors; improve reference manual; add NameOfCategoryCollections helper #3469

Merged
merged 6 commits into from
May 28, 2019
Merged

document DeclareCategoryCollections; document constructors; improve reference manual; add NameOfCategoryCollections helper #3469

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
48b0216
doc: document DeclareCategoryCollections
fingolfin May 23, 2019
94b1a25
lib: add NameOfCategoryCollections helper
fingolfin May 23, 2019
f1f12f3
doc: move a bunch of functions to "better" places
fingolfin May 23, 2019
44c85c6
doc: reformat two lists as actual GAPDoc lists
fingolfin May 23, 2019
0378bcd
doc: basic documentation for constructors
stevelinton May 23, 2019
1d0031c
doc: merge parts of chapter 79 to chapters 13 and 78
fingolfin May 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/ref/coll.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@
<#Include Label="IsCollectionFamily">
<#Include Label="ElementsFamily">
<#Include Label="CategoryCollections">
<#Include Label="DeclareCategoryCollections">

</Section>

Expand Down
287 changes: 26 additions & 261 deletions doc/ref/create.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,7 @@
This chapter is divided into three parts.
<P/>
In the first part, it is explained how to create
filters (see&nbsp;<Ref Sect="Creating Categories"/>, <Ref Sect="Creating Representations"/>,
<Ref Sect="Creating Attributes and Properties"/>, <Ref Sect="Creating Other Filters"/>),
operations (see&nbsp;<Ref Sect="Creating Operations"/>),
families (see&nbsp;<Ref Sect="Creating Families"/>),
types (see&nbsp;<Ref Sect="Creating Types"/>),
and objects with given type (see&nbsp;<Ref Sect="Creating Objects"/>).
objects with given type (see&nbsp;<Ref Sect="Creating Objects"/>).
<P/>
In the second part, first a few small examples are given,
for dealing with the usual cases of
Expand All @@ -44,206 +39,6 @@ how the functions from the first part are used,
and why it is useful to have a declaration part and an implementation part.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Categories">
<Heading>Creating Categories</Heading>

<#Include Label="NewCategory">
<#Include Label="CategoryFamily">

<P/>

See also <Ref Func="CategoryCollections"/>.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Representations">
<Heading>Creating Representations</Heading>

<#Include Label="NewRepresentation">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Attributes and Properties">
<Heading>Creating Attributes and Properties</Heading>

Each method that is installed for an attribute or a property
via <Ref Func="InstallMethod"/> must require exactly one argument,
and this must lie in the filter <A>filter</A> that was entered as second
argument of <Ref Func="NewAttribute"/> resp. <Ref Func="NewProperty"/>.
<P/>
As for any operation (see&nbsp;<Ref Sect="Creating Operations"/>),
for attributes and properties one can install a method taking an argument
that does not lie in <A>filt</A> via <Ref Func="InstallOtherMethod"/>,
or a method for more than one argument;
in the latter case,
clearly the result value is <E>not</E> stored in any of the arguments.

<#Include Label="NewAttribute">
<#Include Label="NewProperty">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Other Filters">
<Heading>Creating Other Filters</Heading>

In order to change the value of <A>filt</A> for an object <A>obj</A>,
one can use logical implications
(see&nbsp;<Ref Sect="Logical Implications"/>) or
<Ref Func="SetFilterObj"/>, <Ref Func="ResetFilterObj"/>.

<#Include Label="NewFilter">
<#Include Label="SetFilterObj">
<#Include Label="ResetFilterObj">

<!-- %T Categories and representations should not be operations, -->
<!-- %T the same for filters made by <C>NewFilter</C>! -->
<!-- %AK Now everything is displayed properly -->

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Operations">
<Heading>Creating Operations</Heading>

<#Include Label="NewOperation">

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Constructors">
<Heading>Creating Constructors</Heading>

<#Include Label="NewConstructor">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Families">
<Heading>Creating Families</Heading>

Families are probably the least obvious part of the &GAP; type system,
so some remarks about the role of families are necessary.
When one uses &GAP; as it is, one will (better: should) not meet
families at all.
The two situations where families come into play are the following.
<P/>
First, since families are used to describe relations between arguments of
operations in the method selection mechanism
(see Chapter&nbsp;<Ref Chap="Method Selection"/>,
and also Chapter&nbsp;<Ref Chap="Types of Objects"/>),
one has to prescribe such a relation in each method installation
(see&nbsp;<Ref Sect="Method Installation"/>);
usual relations are <Ref Func="ReturnTrue"/>
(which means that any relation of the actual arguments is admissible),
<Ref Func="IsIdenticalObj"/> (which means that
there are two arguments that lie in the same family),
and <C>IsCollsElms</C>
(which means that there are two arguments,
the first being a collection of elements that lie in the same family
as the second argument).
<P/>
Second &ndash;and this is the more complicated situation&ndash;
whenever one creates a new kind of objects,
one has to decide what its family shall be.
If the new object shall be equal to existing objects,
for example if it is just represented in a different way,
there is no choice:
The new object must lie in the same family as all objects
that shall be equal to it.
So only if the new object is different
(w.r.t.&nbsp;the equality <Q><C>=</C></Q>)
from all other &GAP; objects, we are likely to create a new family
for it.
Note that enlarging an existing family by such new objects
may be problematic because of implications that have been
installed for all objects of the family in question.
The choice of families depends on the applications one has in mind.
For example, if the new objects in question are not likely to be
arguments of operations for which family relations are relevant
(for example binary arithmetic operations),
one could create one family for all such objects,
and regard it as <Q>the family of all those &GAP; objects that would
in fact not need a family</Q>.
On the other extreme, if one wants to create domains of the new objects
then one has to choose the family in such a way that all intended
elements of a domain do in fact lie in the same family.
(Remember that a domain is a collection,
see Chapter&nbsp;<Ref Sect="Domains"/>,
and that a collection consists of elements in the same family,
see Chapter&nbsp;<Ref Chap="Collections"/>
and Section&nbsp;<Ref Sect="Families"/>.)
<P/>
Let us look at an example.
Suppose that no permutations are available in &GAP;,
and that we want to implement permutations.
Clearly we want to support permutation groups,
but it is not a priori clear how to distribute the new permutations
into families.
We can put all permutations into one family;
this is how in fact permutations are implemented in &GAP;.
But it would also be possible to put all permutations of a given degree
into a family of their own;
this would for example mean that for each degree,
there would be distinguished trivial permutations,
and that the stabilizer of the point <C>5</C> in the symmetric group on the
points <C>1</C>, <C>2</C>, <M>\ldots</M>, <C>5</C> is not regarded as equal to the
symmetric group on <C>1</C>, <C>2</C>, <C>3</C>, <C>4</C>.
Note that the latter approach would have the advantage that it is
no problem to construct permutations and permutation groups acting on
arbitrary (finite) sets,
for example by constructing first the symmetric group on the set
and then generating any desired permutation group as a subgroup of this
symmetric group.
<P/>
So one aspect concerning a reasonable choice of families is
to make the families large enough for being able to form interesting
domains of elements in the family.
But on the other hand,
it is useful to choose the families small enough for admitting
meaningful relations between objects.
For example, the elements of different free groups in &GAP;
lie in different families;
the multiplication of free group elements is installed only for the
case that the two operands lie in the same family,
with the effect that one cannot erroneously form the product of
elements from different free groups.
In this case, families appear as a tool for providing useful
restrictions.
<P/>
As another example, note that an element and a collection containing
this element never lie in the same family,
by the general implementation of collections;
namely, the family of a collection of elements in the family <A>Fam</A>
is the collections family of <A>Fam</A> (see&nbsp;<Ref Attr="CollectionsFamily"/>).
This means that for a collection, we need not (because we cannot)
decide about its family.
<P/>
A few functions in &GAP; return families,
see <Ref Attr="CollectionsFamily"/> and <Ref Attr="ElementsFamily"/>.

<#Include Label="NewFamily">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Types">
<Heading>Creating Types</Heading>

<#Include Label="NewType">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Objects">
<Heading>Creating Objects</Heading>
Expand Down Expand Up @@ -300,7 +95,7 @@ in order to keep the information stored in <A>cobj</A> consistent.
<P/>
First of all, in the access or assignment to a component as shown above,
<A>name</A> must be among the admissible component names
for the representation of <A>cobj</A>, see&nbsp;<Ref Sect="Creating Representations"/>.
for the representation of <A>cobj</A>, see&nbsp;<Ref Func="NewRepresentation"/>.
Second, preferably only few low level functions should use <C>!.</C>,
whereas this operator should not occur in <Q>user interactions</Q>.
<P/>
Expand Down Expand Up @@ -408,7 +203,7 @@ in order to keep the information stored in <A>pobj</A> consistent.
<P/>
First of all, in the access or assignment to a position as shown above,
<A>pos</A> must be among the admissible positions
for the representation of <A>pobj</A>, see&nbsp;<Ref Sect="Creating Representations"/>.
for the representation of <A>pobj</A>, see&nbsp;<Ref Func="NewRepresentation"/>.
Second, preferably only few low level functions should use <C>![]</C>,
whereas this operator should not occur in <Q>user interactions</Q>.
<P/>
Expand Down Expand Up @@ -1176,26 +971,11 @@ avoid their being overwritten accidentally.

See also Section <Ref Sect="More About Global Variables"/>.

<#Include Label="DeclareCategory">
<#Include Label="TypeOfOperation">
<#Include Label="IsCategory">
<#Include Label="IsRepresentation">
<#Include Label="IsProperty">
<#Include Label="IsAttribute">
<#Include Label="CategoryByName">
<#Include Label="DeclareRepresentation">
<#Include Label="DeclareAttribute">
<#Include Label="DeclareProperty">
<#Include Label="DeclareFilter">
<#Include Label="DeclareOperation">
<#Include Label="DeclareConstructor">
<#Include Label="DeclareGlobalFunction">
<#Include Label="DeclareGlobalVariable">
<#Include Label="InstallValue">
<#Include Label="DeclareSynonym">
<#Include Label="FlushCaches">
<#Include Label="FilterByName">
<#Include Label="ShowDeclarationsOfOperation">
<#Include Label="DeclareGlobalFunction">
<#Include Label="DeclareSynonym">

</Section>

Expand All @@ -1220,43 +1000,28 @@ Values for these functions can be installed in the implementation part
via <Ref Func="InstallGlobalFunction"/>.
<P/>
Calls to the following functions belong to the declaration part.
<P/>
<Ref Func="DeclareAttribute"/>,
<P/>
<Ref Func="DeclareCategory"/>,
<P/>
<Ref Func="DeclareFilter"/>,
<P/>
<Ref Func="DeclareOperation"/>,
<P/>
<Ref Func="DeclareGlobalFunction"/>,
<P/>
<Ref Func="DeclareSynonym"/>,
<P/>
<Ref Func="DeclareSynonymAttr"/>,
<P/>
<Ref Func="DeclareProperty"/>,
<P/>
<Ref Func="InstallTrueMethod"/>.
<P/>
<List>
<Item><Ref Func="DeclareAttribute"/>,</Item>
<Item><Ref Func="DeclareCategory"/>,</Item>
<Item><Ref Func="DeclareFilter"/>,</Item>
<Item><Ref Func="DeclareOperation"/>,</Item>
<Item><Ref Func="DeclareGlobalFunction"/>,</Item>
<Item><Ref Func="DeclareSynonym"/>,</Item>
<Item><Ref Func="DeclareSynonymAttr"/>,</Item>
<Item><Ref Func="DeclareProperty"/>,</Item>
<Item><Ref Func="InstallTrueMethod"/>.</Item>
</List>
Calls to the following functions belong to the implementation part.
<P/>
<Ref Func="DeclareRepresentation"/>,
<P/>
<Ref Func="InstallGlobalFunction"/>,
<P/>
<Ref Func="InstallMethod"/>,
<P/>
<Ref Func="InstallImmediateMethod"/>,
<P/>
<Ref Func="InstallOtherMethod"/>,
<P/>
<Ref Func="NewFamily"/>,
<P/>
<Ref Func="NewType"/>,
<P/>
<Ref Func="Objectify"/>.
<P/>
<List>
<Item><Ref Func="DeclareRepresentation"/>,</Item>
<Item><Ref Func="InstallGlobalFunction"/>,</Item>
<Item><Ref Func="InstallMethod"/>,</Item>
<Item><Ref Func="InstallImmediateMethod"/>,</Item>
<Item><Ref Func="InstallOtherMethod"/>,</Item>
<Item><Ref Func="NewFamily"/>,</Item>
<Item><Ref Func="NewType"/>,</Item>
<Item><Ref Func="Objectify"/>.</Item>
</List>
<Index Key="DeclareRepresentation" Subkey="belongs to implementation part">
<C>DeclareRepresentation</C></Index>
Whenever both a <C>New</C><A>Something</A> and a
Expand Down
7 changes: 3 additions & 4 deletions doc/ref/domain.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -605,8 +605,8 @@ The functions <Ref Func="InstallSubsetMaintenance"/>,
<Ref Func="InstallFactorMaintenance"/> are used to tell &GAP;
under what conditions an attribute is maintained under taking subsets,
or forming factor structures or isomorphic domains.
This is used only when a new attribute is created,
see&nbsp;<Ref Sect="Creating Attributes and Properties"/>.
This is used only when a new attribute or property is created,
see&nbsp;<Ref Func="NewAttribute"/> and <Ref Func="NewProperty"/>.
For the attributes already available,
such as <Ref Prop="IsFinite"/> and <Ref Prop="IsCommutative"/>,
the maintenances are already notified.
Expand Down Expand Up @@ -680,8 +680,7 @@ and <Ref Filt="IsLieMatrix"/>.

The following categories of elements are to be understood mainly as
categories for all objects in a family,
they are usually used as third argument of <C>NewFamily</C>
(see&nbsp;<Ref Sect="Creating Families"/>).
they are usually used as third argument of <Ref Func="NewFamily"/>.
fingolfin marked this conversation as resolved.
Show resolved Hide resolved
The purpose of each of the following categories is then to guarantee that
each collection of its elements automatically lies in its collections
category (see&nbsp;<Ref Func="CategoryCollections"/>).
Expand Down
1 change: 0 additions & 1 deletion doc/ref/function.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,6 @@ So <Ref Func="ReturnTrue"/> is often used as family predicate in
Functions are &GAP; objects and thus have categories and a family.

<#Include Label="IsFunction">
<#Include Label="IsOperation">
<#Include Label="FunctionsFamily">

</Section>
Expand Down
Loading