Documentation

Attributes

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.

Predefined System Attributes

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 still 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;

is completely equivalent to the code:

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

(note that the function AssertAttribute takes a string for its second argument so the name must be enclosed in double quotes). Similarly, the code:

> if assigned S`Name then
> x := S`Name;
> // do something with x...
> end if;

is completely equivalent to the code:

> l, x := HasAttribute(S, "Name");
> if l then
> // do something with x...
> end if;

(note again that the function HasAttribute takes a string for its second argument so the name must be enclosed in double quotes).

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.

declare attributes C: F₁, ..., F_n;

Given a category C, and a comma-separated list of identifiers F₁, ..., F_n 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 is actually executed.

Accessing Attributes

Attributes of structures are accessed in the same way that records are: using the backquote (`) operator. The double backquote operator (") can also be used if the field name is a string.

S`fieldname : Str, Fieldname -> Elt

S"N : Str, Str -> 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. In the S"N form, N is a string giving the field name.

assigned S`fieldname : Str, Fieldname -> BoolElt

assigned S"N : Str, Str -> BoolElt

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. In the S"N form, N is a string giving the field name.

S`fieldname := expression;

S"N := expression;

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. In the S"N form, N is a string giving the field name.

delete S`fieldname;

delete S"N;

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 the S"N form, N is a string giving the field name.

GetAttributes(C) : Cat -> [ MonStgElt ]

Given a category C, return the valid attribute field names for structures belonging to category C as a sorted sequence of strings.

ListAttributes(C) : Cat ->

(Procedure.) Given a category C, list the valid attribute field names for structures belonging to category C.

V2.28, 13 July 2023

Contents

S"N : Str, Str -> Elt

assigned S"N : Str, Str -> BoolElt

S"N := expression;

delete S"N;