|
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.
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.
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.
(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 is actually
executed.
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``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``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``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``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.
Given a category C, return the valid attribute field names for
structures belonging to category C as a sorted sequence of strings.
(Procedure.) Given a category C, list the valid attribute field names for
structures belonging to category C.
[Next][Prev] [Right] [Left] [Up] [Index] [Root]
|