This section is placed beside the section on packages because the use of attributes is most common within packages.

For any structure within Magma, it is possible to have attributes associated with it. These are simply values stored within the structure and are referred to by named fields in exactly the same manner as Magma records.

There are two kinds of structure attributes: predefined system attributes and user-defined attributes. Both kinds are discussed in the following subsections. A description of how attributes are accessed and assigned then follows.

Subsections

• Predefined System Attributes
• User-defined Attributes
• Accessing Attributes
• Examples

The valid fields of predefined system attributes are automatically defined at the startup of Magma. These fields now replace the old method of using the procedure AssertAttribute and the function HasAttribute (which will stay work for some time to preserve backwards compatibility). For each name which is a valid first argument for AssertAttribute and HasAttribute, that name is a valid attribute field for structures of the appropriate category. Thus the backquote method for accessing attributes described in detail below should now be used instead of the old method. For such attributes, the code:

> S`Name := x;

> AssertAttribute(S, "Name", x);

> if assigned S`Name then

> x := S`Name;

> // do something with x...

> end if;

> l, x := HasAttribute(S, "Name");

> if l then

> // do something with x...

> end if;

Note also that if a system attribute is not set, referring to it in an expression (using the backquote operator) will not trigger the calculation of it (while the corresponding intrinsic function will if it exists); rather an error will ensue. Use the assigned operator to test whether an attribute is actually set.

User-defined Attributes

For any category C, the user can stipulate valid attribute fields for structures of C. After this is done, any structure of category C may have attributes assigned to it and accessed from it.

There are two ways of adding new valid attributes to a category C: by the procedure AddAttribute or by the declare attributes package declaration. The former should be used outside of packages (e.g. in interactive usage), while the latter must be used within packages to declare attribute fields used by the package and related packages.

AddAttribute(C, F) : Cat, MonStgElt -> ;

(Procedure.) Given a category C, and a string F, append the field name F to the list of valid attribute field names for structures belonging to category C. This procedure should not be used within packages but during interactive use. Previous fields for C are still valid -- this just adds another valid one.

Given a category C, and a comma-separated list of identifiers F1, ..., Fn append the field names specified by the identifiers to the list of valid attribute field names for structures belonging to category C. This declaration directive must be used within (and only within) packages to declare attribute fields used by the package and packages related to it which use the same fields. It is not a statement but a directive which is stored with the other information of the package when it is compiled and subsequently attached -- not when any code in is actually executed.

Attributes of structures are accessed in the same way that records are: using the backquote (`) operator.

S`fieldname : Str, Fieldname -> Elt

Given a structure S and a field name, return the current value for the given field in S. If the value is not assigned, an error results. The field name must be valid for the category of S.

Given a structure S and a field name, return whether the given field in S currently has a value. The field name must be valid for the category of S.

Given a structure S and a field name, assign the given field of S to be the value of the expression (any old value is first discarded). The field name must be valid for the category of S.

Given a structure S and a field name, delete the given field of S. The field then becomes unassigned in S. The field name must be valid for the category of S and the field must be currently assigned in S. This statement is not allowed for predefined system attributes.

In this subsection we give examples which illustrate all of the above features.

> // Create group G.
> G := PSL(3, 2);
> // Check whether order known.
> assigned G`Order;
false

> // Attempt to access order -- error since not assigned.

> G`Order;

>> G`Order;
    ^
Runtime error in `: Attribute 'Order' for this structure
is valid but not assigned
> // Force computation of order by intrinsic Order.
> Order(G);
168
> // Check Order field again.
> assigned G`Order; 
true
> G`Order;
168
> // Create code C and set its minimum weight.
> C := QRCode(GF(2), 31);
> C`MinimumWeight := 7;                                                        
> C;
[31, 16, 7] Quadratic Residue code over GF(2)
...

> // Add attribute field MyStuff for matrix groups.
> AddAttribute(GrpMat, "MyStuff");
> // Create group G.
> G := GL(2, 3);
> // Try illegal field.

> G`silly;

>> G`silly;
    ^
Runtime error in `: Invalid attribute 'silly' for this structure
> // Try legal but unassigned field.

> G`MyStuff;

>> G`MyStuff;
    ^
Runtime error in `: Attribute 'MyStuff' for this structure is valid but not 
assigned
> // Assign field and notice value.
> G`MyStuff := [1, 2];
> G`MyStuff;
[ 1, 2 ]

declare attributes GrpMat: PermRep, PermRepMap;

intrinsic PermutationRepresentation(G::GrpMat) -> GrpPerm
{A permutation group representation P of G, with homomorphism f: G -> P};
    // Only compute rep if not already stored.
    if not assigned G`PermRep then
        G`PermRepMap, G`PermRep := CosetAction(G, sub<G|>);
    end if;
    return G`PermRep, G`PermRepMap;
end intrinsic;

> Attach("permrep.m");

> G := GL(2, 2);

> P, f := PermutationRepresentation(G);

> P;
Permutation group P acting on a set of cardinality 6
    (1, 2)(3, 5)(4, 6)
    (1, 3)(2, 4)(5, 6)

> f;
Mapping from: GrpMat: G to GrpPerm: P