NAME

src/pmc/class.pmc - defines a class

DESCRIPTION

This class implements the Class PMC, as outlined in docs/pdds/pdd15_objects.pod.

Class is not derived from any other PMC.

Structure

The Class PMC structure (Parrot_Class) consists of twelve items:

id

The type number of the PMC.

name

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

namespace

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

instantiated

A flag denoting whether this class has been instantiated since last modification. A native integer with value zero is allocated during initialization.

parents

An array of immediate parent classes. An empty ResizablePMCArray PMC is allocated during initialization.

all_parents

A cached array of ourself and all parent classes, in method resolution order (MRO). A ResizablePMCArray PMC is allocated during initialization, and is populated with the current class.

roles

An array of the roles this class has been composed from. An empty ResizablePMCArray PMC is allocated during initialization.

methods

A directory of method names and method bodies this class provides. An empty Hash PMC is allocated during initialization.

vtable_overrides

A directory of vtable function names and method bodies this class overrides. An empty Hash PMC is allocated during initialization.

attrib_metadata

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

attrib_index

A lookup table for attributes in this class and parents. A Null PMC is allocated during initialization.

attrib_cache

A cache of visible attribute names to attribute indexes. A Null PMC is allocated during initialization.

resolve_method

A list of method names the class provides used for name conflict resolution. An empty ResizablePMCArray PMC is allocated during initialization.

static int cache_class_attribs(PARROT_INTERP, PMC *cur_class, PMC *attrib_index, PMC *cache, int cur_index)

static void build_attrib_index(PARROT_INTERP, PMC *self)

This function builds the attribute index (table to map class name and attribute name to an index) for the current class.

static void init_class_from_hash(PARROT_INTERP, PMC *self, PMC *info)

Takes a hash and initializes the class based on it.

static void initialize_parents(PARROT_INTERP, PMC *object, PMC *all_parents)

static void initialize_parents_pmc(PARROT_INTERP, PMC *object, PMC *all_parents, PMC *init)

static STRING * make_class_name(PARROT_INTERP, PMC *SELF)

This function makes and caches the name of this class, returning the string directly. VTABLE_isa() uses the name without copying it, for efficiency reasons, as it does not modify the STRING. VTABLE_get_string() makes a copy of the STRING, so its callers are free to modify it.

static void calculate_mro(PARROT_INTERP, PMC *SELF, INTVAL num_parents)

Calculates the C3 method resolution order for this class. C3 is the name of an algorithm used to calculate the method resolution order (MRO) to use in a system with multiple inheritance. For more information see the documentation associated with Parrot_ComputeMRO_C3.

Functions

void init()

Initializes a Class PMC.

void init_pmc(PMC *init_data)

The actual class creation code, called from newclass opcode. The init_data argument may be either the name of the class or a hash of initialization arguments. The class is attached to the current HLL namespace.

STRING *get_string()

Returns the name of the class (without the HLL namespace).

void mark()

Marks any referenced strings and PMCs in the structure as live.

void add_attribute(STRING *name, PMC *type)

Adds the given attribute (name) with an optional type. Throws an exception if the current class has been instantiated. Enters the attribute in the attrib_metadata table. Returns an error if an attribute of name already exists.

void remove_attribute(STRING *name)

Removes the given attribute (name) from the class. Throws an exception if the current class has been instantiated, or if the class has no attribute name.

void add_method(STRING *name, PMC *sub)

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

void remove_method(STRING *name)

Removes the method with the given name.

void add_vtable_override(STRING *name, PMC *sub)

Adds the given sub PMC as a vtable override with the given name.

void add_parent(PMC *parent)

Adds the supplied PMC to the list of parents for the class.

void remove_parent(PMC *parent)

Remove the supplied class object from the list of parents for the class. Throws an exception if parent is null, is not a class, or is not a parent, or if the class has been instantiated.

void add_role(PMC *role)

Adds the supplied PMC to the list of roles for the class, provided there are no conflicts.

PMC *inspect_str(STRING *what)

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

name

String PMC containing the name of the class

namespace

NameSpace PMC of the namespace attached to the class.

attributes

Hash keyed on attribute name, where the value is a 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 class.

parents

Array of Class PMCs representing the direct parents of this class.

PMC *inspect()

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

PMC *clone()

Returns an anonymous copy of the class (with no name and no link to a namespace). Unsets the instantiated flag, allowing modifications.

PMC *clone_pmc(PMC *args)

Makes a copy of the class, then modifies or adds to it based upon the contents of the supplied initialization data. If a new name or namespace is not supplied in args then the cloned class will be anonymous. The instantiated flag is unset to allow further modifications.

PMC *instantiate(PMC *init)

Creates a new PMC object of the type of the class and calls init().

INTVAL isa_pmc(PMC *class)

Returns whether the class is or inherits from *class.

INTVAL isa(STRING *classname)

Returns whether the class is or inherits from *classname.

INTVAL does(STRING *role_name)

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

INTVAL does_pmc(PMC *role)

Returns whether the class does the given *role.

INTVAL type()

Returns the integer type of the class.

void visit(PMC *info)

This is used by freeze/thaw to visit the contents of the class.*info is the visit info, (see include/parrot/pmc_freeze.h).

void freeze(PMC *info)

Used to archive the class.

void thaw(PMC *info)

Used to unarchive the class.

INTVAL get_integer()

This is just a temporary hack. Type ID numbers shouldn't be externally visible to the average PIR user. However, we need this for now to interface with functions like Parrot_pmc_new and pmc_reuse, which take type ID numbers still.

void thawfinish(PMC *info)

Called after the class has been thawed.

void name(STRING *name :optional, int has_name :opt_flag)

Sets the name of the class, and updates the namespace accordingly.

void get_namespace()

Gets the namespace that this class is attached to.

void resolve_method()

Sets the list of method names that the class provides to resolve conflicts in methods from roles. When called with no parameter, returns the list.

void new(PMC *args :slurpy :named)

Creates an instance of the object. Initializes any attributes specified in the parameter list.

void 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.

void add_attribute()

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

void methods()

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

void add_method(STRING *name, PMC *sub)

Adds the given sub PMC as a method with the given name. Delegates to the add_method vtable.

void add_vtable_override(STRING *name, PMC *sub)

Adds the given sub PMC as a vtable override with the given name. Delegates to the add_vtable_override vtable.

void remove_method(STRING *name)

Removes the method with the given name.

PMC *find_method(STRING *name)

Walks the MRO of the class and finds the method with the given name.

void parents()

Returns the parents array PMC.

void add_parent(PMC *parent)

Adds the supplied PMC to the list of parents for the class.

void roles()

Returns the roles array PMC.

void add_role(PMC *role, PMC *exclude :optional :named("exclude"), PMC *alias :optional :named("alias"))

Composes a role into a class with the given exclusions and aliases.

void inspect(STRING *what :optional)

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

void isa(STRING *class_name)

Returns true if this object is or derives from the class named in class_name, false otherwise.

void does(STRING *role_name)

Returns true if this object or one of its parents performs the named role, false otherwise.

SEE ALSO

docs/pdds/pdd15_objects.pod.