NAME ^

src/pmc/role.pmc - Role - defines a role

DESCRIPTION ^

This class implements the Role PMC, a unit of class composition as outlined in docs/pdds/pdd15_objects.pod.

Role is not derived from any other PMC.

Structure ^

The Role PMC structure (Parrot_Role) consists of five items:

name

The name of the role -- a STRING. An empty STRING is allocated during initialization.

namespace

The namespace the role is associated with, if any. A Null PMC is allocated during initialization.

roles

The list of roles from which this role is composed, if any. An empty ResizablePMCArray is allocated during initialization.

methods

The directory of method names and methods this role implements. An empty Hash PMC is allocated during initialization.

attrib_metadata

The directory of attribute names and attribute metadata this role contains. An empty Hash PMC is allocated during initialization.

Functions ^

void init()

Initializes a Role PMC.

void init_pmc(PMC *init_data)

Creates a Role and initializes it using the settings from the Hash passed in init_data.

void destroy()

Free the memory associated with the object's underlying struct.

void mark()

Mark referenced strings and PMCs in the structure as live.

void add_attribute(STRING *name, PMC *type)

Adds the given attribute with an optional type. Enters the attribute in the attributes array.

void add_method(STRING *name, PMC *sub)

Adds the given sub PMC as a method with the given name.

void add_role(PMC *role)

Composes the supplied Role PMC into this role, provided there are no conflicts.

PMC *inspect_str(STRING *what)

Provides introspection of a specific piece of information about the role. The available information is:

name - String PMC containing the name of the role

namespce - NameSpace PMC of the the namespace attached to the role

attributes - Hash keyed on attribute name, value is hash describing it

methods - Hash keyed on method name, value is an invokable PMC. Includes methods composed in from roles.

roles - Array of Role PMCs. Includes roles done by the roles that were composed into this role.

PMC *inspect()

Returns a Hash describing the role, with key/value pairs as described in inspect_str.

STRING *get_string()

Return the name of the role (without the HLL namespace).

INTVAL does(STRING *rolename)

Returns whether the class does the role with the given *rolename.

INTVAL does_pmc(PMC *role)

Returns whether the class does the givne *role.

Methods ^

METHOD name(STRING *name :optional, int got_name :opt_flag)

Sets the name of the role, and updates the namespace accoringly.

METHOD get_namespace()

Gets the namespace associated with this role, if any.

METHOD attributes()

Return a hash where the keys are attribute names and the values are hashes providing a set of key/value pairs describing the attribute.

METHOD add_attribute(STRING *attribute_name, PMC *attribute_type :optional, int got_type :opt_flag)

Add an attribute to the role. Requires a name and, optionally, a type.

METHOD methods()

Return a hash where the keys are method names and the values are methods.

METHOD add_method(STRING *name, PMC *sub)

Adds the given sub PMC as a method with the given name.

METHOD roles()

Return the roles array PMC.

METHOD add_role(PMC *role, PMC *exclude_method :optional :named("exclude_method"), int got_exclude_method :opt_flag, PMC *alias_method :optional :named("alias_method"), int got_alias_method :opt_flag)

Compose the given role into this one, using the given exclusions and aliases.

void inspect(STRING *what :optional)

Gets all introspection data for the role or, if the optional string parameter is supplied, a particular item of introspection data.

void does(STRING *role)

Returns true if this role (or any role composed into this one) performs the named role. This will recurse through all roles as far back as it can.

STABILITY ^

Unstable. This PMC is under active development; major portions of the interface have not yet been completed.

SEE ALSO ^

docs/pdds/pdd15_objects.pod.


parrot