role.pmc

/*
Copyright (C) 2001-2007, The Perl Foundation.
$Id$

=head1 NAME

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

=head1 DESCRIPTION

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

Role is not derived from any other PMC.

=head2 Structure

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

=over 4

=item C<name>

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

=item C<namespace>

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

=item C<roles>

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

=item C<methods>

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

=item C<attrib_metadata>

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

=cut

*/

#include "parrot/parrot.h"
#define PARROT_ROLE(o) ((Parrot_Role *) PMC_data(o))

/* This is the underlying structure of this PMC. */
typedef struct Parrot_Role {
    STRING *name;         /* The name of the role. */
    PMC *namespace;       /* The namespace it's linked to, if any. */
    PMC *roles;           /* Any roles that this role is composed from. */
    PMC *methods;         /* Hash of method names to methods in this role. */
    PMC *attrib_metadata; /* Hash of attributes in this role to hashes of metadata. */
} Parrot_Role;


/* Takes a hash and initializes the role based on it. */
static void init_role_from_hash(Parrot_Interp interp, PMC *self, PMC *info)
{
    Parrot_Role *role = PARROT_ROLE(self);
    int have_name, have_ns;
    PMC *old_ns;
    int i;

    /* Ensure we actually have some initialization info. */
    if (PMC_IS_NULL(info))
        return;

    /* Check if we have a name and/or a namespace. */
    have_name = VTABLE_exists_keyed_str(interp, info,
        string_from_const_cstring(interp, "name", 0));
    have_ns = VTABLE_exists_keyed_str(interp, info,
        string_from_const_cstring(interp, "namespace", 0));

    /* Take a copy of the current namespace the role is attached to. */
    old_ns = role->namespace;

    /* Let's roll (no pun intended!) If we have a namespace and a name,
     * set both. */
    if (have_name && have_ns) {
        /* If we weren't passed a NameSpace PMC, assume it's something we have
         * to look one up with and do so. */
        PMC *namespace = VTABLE_get_pmc_keyed_str(interp, info,
            string_from_const_cstring(interp, "namespace", 0));
        if (!VTABLE_isa(interp, namespace, string_from_const_cstring(interp, "NameSpace", 0)))
            namespace = Parrot_make_namespace_autobase(interp, namespace);

        /* If we get something null back it's an error; otherwise, store it. */
        if (!PMC_IS_NULL(namespace))
            role->namespace = namespace;
        else
            real_exception(interp, NULL, E_NameError, "Namespace not found");

        /* Set a (string) name. */
        role->name = VTABLE_get_string_keyed_str(interp, info,
            string_from_const_cstring(interp, "name", 0));
    }

    /* Otherwise, we may just have a name. */
    else if (have_name) {
        /* Set the name. */
        role->name = VTABLE_get_string_keyed_str(interp, info,
            string_from_const_cstring(interp, "name", 0));

        /* Namespace is nested in the current namespace and with the name of
         * the role. */
        role->namespace = Parrot_make_namespace_keyed_str(interp,
            CONTEXT(interp->ctx)->current_namespace, role->name);
    }

    /* Otherwise, we may just have a namespace. */
    else if (have_ns) {
        /* If we weren't passed a NameSpace PMC, assume it's something we have
         * to look one up with and do so. */
        PMC *namespace = VTABLE_get_pmc_keyed_str(interp, info,
            string_from_const_cstring(interp, "namespace", 0));
        if (!VTABLE_isa(interp, namespace, string_from_const_cstring(interp, "NameSpace", 0)))
            namespace = Parrot_make_namespace_autobase(interp, namespace);

        /* If we get something null back it's an error; otherwise, store it. */
        if (!PMC_IS_NULL(namespace))
            role->namespace = namespace;
        else
            real_exception(interp, NULL, E_NameError, "Namespace not found");

        /* Name is that of the most nested part of the namespace. */
        role->name = VTABLE_get_string(interp, namespace);
    }

    /* If we were attached to a namespce and are now attached to a new one,
     * need to unset ourselves in the old namespace. */
    if (!PMC_IS_NULL(old_ns) && role->namespace != old_ns)
        Parrot_PCCINVOKE(interp, old_ns,
            string_from_const_cstring(interp, "set_class", 0),
            "P->", PMCNULL);

    /* Link namespace to this role, if there is one. */
    if (!PMC_IS_NULL(role->namespace))
        Parrot_PCCINVOKE(interp, role->namespace,
            string_from_const_cstring(interp, "set_class", 0),
            "P->", self);

    /* Initialize roles, if we have any. */
    if (VTABLE_exists_keyed_str(interp, info,
        string_from_const_cstring(interp, "roles", 0))) {
        /* Loop over roles array and compose them. */
        PMC *role_list = VTABLE_get_pmc_keyed_str(interp, info,
            string_from_const_cstring(interp, "roles", 0));
        int role_count = VTABLE_elements(interp, role_list);
        for (i = 0; i < role_count; i++) {
            PMC *cur_role = VTABLE_get_pmc_keyed_int(interp, role_list, i);
            VTABLE_add_role(interp, self, cur_role);
        }
    }

    /* Initialize attributes, if we have any. */
    if (VTABLE_exists_keyed_str(interp, info,
        string_from_const_cstring(interp, "attributes", 0))) {
        /* Loop over attributes array and add them. */
        PMC *attrib_name_list = VTABLE_get_pmc_keyed_str(interp, info,
            string_from_const_cstring(interp, "attributes", 0));
        int attrib_count = VTABLE_elements(interp, attrib_name_list);
        for (i = 0; i < attrib_count; i++) {
            STRING *attrib_name = VTABLE_get_string_keyed_int(interp,
                attrib_name_list, i);
            VTABLE_add_attribute(interp, self, attrib_name, PMCNULL);
        }
    }

    /* Initialize methods, if we have any. */
    if (VTABLE_exists_keyed_str(interp, info,
        string_from_const_cstring(interp, "methods", 0))) {
        /* Get the methods hash. */
        PMC *methods = VTABLE_get_pmc_keyed_str(interp, info,
            string_from_const_cstring(interp, "methods", 0));

        /* Iterate over the list of methods. */
        PMC *iter = VTABLE_get_iter(interp, methods);
        while (VTABLE_get_bool(interp, iter)) {
            /* Add the method. */
            STRING *method_name = VTABLE_shift_string(interp, iter);
            PMC *method_pmc = VTABLE_get_pmc_keyed_str(interp, methods, method_name);
            VTABLE_add_method(interp, self, method_name, method_pmc);
        }
    }
}


/*

=back

=head2 Functions

=over 4

=cut

*/

pmclass Role
    need_ext {


/*

=item C<void init()>

Initializes a Role PMC.

=item C<void init_pmc(PMC *init_data)>

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

=cut

*/

    void init() {
        Parrot_Role *role = NULL;

        /* Set flags for custom DOD mark and destroy. */
        PObj_custom_mark_SET(SELF);
        PObj_active_destroy_SET(SELF);

        /* Set up the object. */
        role                  = mem_sys_allocate_zeroed(sizeof (Parrot_Role));
        role->name            = CONST_STRING(interp, "");
        role->namespace       = PMCNULL;
        role->roles           = pmc_new(interp, enum_class_ResizablePMCArray);
        role->methods         = pmc_new(interp, enum_class_Hash);
        role->attrib_metadata = pmc_new(interp, enum_class_Hash);
        PMC_data(SELF)        = role;
    }

    void init_pmc(PMC* init_data) {
        /* Create the role. */
        SELF.init();

        /* Initialize the role with the supplied data. */
        init_role_from_hash(interp, SELF, init_data);
    }


/*

=item C<void destroy()>

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

=cut

*/

    void destroy() {
            mem_sys_free(PMC_data(SELF));
    }


/*

=item C<void mark()>

Mark referenced strings and PMCs in the structure as live.

=cut

*/

    void mark() {
        Parrot_Role *role = PARROT_ROLE(SELF);
        if (role->name)
            pobject_lives(interp, (PObj*)role->name);
        if (role->namespace)
            pobject_lives(interp, (PObj*)role->namespace);
        if (role->roles)
            pobject_lives(interp, (PObj*)role->roles);
        if (role->methods)
            pobject_lives(interp, (PObj*)role->methods);
        if (role->attrib_metadata)
            pobject_lives(interp, (PObj*)role->attrib_metadata);
    }


/*

=item C<void add_attribute(STRING *name, PMC *type)>

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

=cut

*/

    void add_attribute(STRING *name, PMC *type) {
        Parrot_Role *role = PARROT_ROLE(SELF);
        PMC *new_attribute = pmc_new(interp, enum_class_Hash);

        /* Set name and type. */
        VTABLE_set_string_keyed_str(interp, new_attribute,
            CONST_STRING(interp, "name"), name);
        if (!PMC_IS_NULL(type)) {
            VTABLE_set_pmc_keyed_str(interp, new_attribute,
                CONST_STRING(interp, "type"), type);
        }

        /* Enter the attribute in the attributes array. */
        VTABLE_set_pmc_keyed_str(interp, role->attrib_metadata, name, new_attribute);
    }


/*

=item C<void add_method(STRING *name, PMC *sub)>

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

=cut

*/

    void add_method(STRING *name, PMC *sub) {
        Parrot_Role *role = PARROT_ROLE(SELF);

        /* If we have already added a method with this name... */
        if (VTABLE_exists_keyed_str(interp, role->methods, name)) {
            /* XXX Need to handle multi methods here. */
            real_exception(interp, NULL, E_NotImplementedError,
                "Currently, adding multiple methods of the same name is not supported.");
        }
        else {
            /* Enter it into the table. */
            VTABLE_set_pmc_keyed_str(interp, role->methods, name, sub);
        }
    }


/*

=item C<void add_role(PMC *role)>

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

=cut

*/

    void add_role(PMC *role) {
        Parrot_Role *this_role = PARROT_ROLE(SELF);

        /* Do the composition. */
        Parrot_ComposeRole(interp, role, PMCNULL, 0, PMCNULL, 0,
               this_role->methods, this_role->roles);
    }


/*

=item C<PMC *inspect_str(STRING *what)>

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

=over 4

=item name - String PMC containing the name of the role

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

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

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

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

=back

=cut

*/

    PMC* inspect_str(STRING *what) {
        Parrot_Role *role = PARROT_ROLE(SELF);

        /* What should we return? */
        PMC *found;
        if (string_equal(interp, what, CONST_STRING(interp, "name")) == 0) {
            found = pmc_new(interp, enum_class_String);
            VTABLE_set_string_native(interp, found, role->name);
        }
        else if (string_equal(interp, what, CONST_STRING(interp, "namespace")) == 0) {
            /* Don't clone the namespace, as it's not part of our state. */
            return role->namespace;
        }
        else if (string_equal(interp, what, CONST_STRING(interp, "attributes")) == 0) {
            found = role->attrib_metadata;
        }
        else if (string_equal(interp, what, CONST_STRING(interp, "methods")) == 0) {
            found = role->methods;
        }
        else if (string_equal(interp, what, CONST_STRING(interp, "roles")) == 0) {
            found = role->roles;
        }
        else {
            real_exception(interp, NULL, INVALID_OPERATION,
                "Unknown introspection value '%S'", what);
        }

        /* Clone and return. */
        return PMC_IS_NULL(found) ? PMCNULL : VTABLE_clone(interp, found);
    }


/*

=item C<PMC *inspect()>

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

=cut

*/

    PMC* inspect() {
        /* Create a hash, then use inspect_str to get all of the data to
         * fill it up with. */
        PMC *metadata = pmc_new(interp, enum_class_Hash);
        VTABLE_set_pmc_keyed_str(interp, metadata, CONST_STRING(interp, "name"),
            VTABLE_inspect_str(interp, SELF, CONST_STRING(interp, "name")));
        VTABLE_set_pmc_keyed_str(interp, metadata, CONST_STRING(interp, "namespace"),
            VTABLE_inspect_str(interp, SELF, CONST_STRING(interp, "namespace")));
        VTABLE_set_pmc_keyed_str(interp, metadata, CONST_STRING(interp, "attributes"),
            VTABLE_inspect_str(interp, SELF, CONST_STRING(interp, "attributes")));
        VTABLE_set_pmc_keyed_str(interp, metadata, CONST_STRING(interp, "methods"),
            VTABLE_inspect_str(interp, SELF, CONST_STRING(interp, "methods")));
        VTABLE_set_pmc_keyed_str(interp, metadata, CONST_STRING(interp, "roles"),
            VTABLE_inspect_str(interp, SELF, CONST_STRING(interp, "roles")));
        return metadata;
    }

    /*
     * Below here are non-vtable methods that eventually will go in a role
     * that is composed into here to optionally give a nice interface from
     * PIR (ParrotRole isa Role does RoleMethods or something like this).
     */


/*

=back

=head2 Methods

=over 4

=item C<PCCMETHOD void
    name(STRING *name :optional, int got_name :opt_flag)>

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

=cut

*/

    PCCMETHOD void name(STRING *name :optional, int got_name :opt_flag) {
        Parrot_Role *role = PARROT_ROLE(SELF);
        STRING *ret_name = NULL;

        if (got_name) {
            /* We'll build a hash just containing the name, then give this to
             * init_role_from_hash - saves some code duplication. */
            PMC *naming_hash = pmc_new(interp, enum_class_Hash);
            VTABLE_set_string_keyed_str(interp, naming_hash,
                CONST_STRING(interp, "name"), name);
            init_role_from_hash(interp, SELF, naming_hash);
        }

        ret_name = role->name;
        PCCRETURN(STRING *ret_name);
    }


/*

=item C<PCCMETHOD void
    namespace()>

Gets the namespace associated with this role, if any.

=cut

*/

    PCCMETHOD void namespace() {
        Parrot_Role *role = PARROT_ROLE(SELF);
        PMC *ret_namespace = role->namespace;
        PCCRETURN(PMC *ret_namespace);
    }


/*

=item C<PCCMETHOD 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.

=cut

*/
    PCCMETHOD void attributes() {
        PMC *ret_attrib_metadata = VTABLE_inspect_str(interp, SELF,
            CONST_STRING(interp, "attributes"));
        PCCRETURN(PMC *ret_attrib_metadata);
    }


/*

=item C<PCCMETHOD void
    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.

=cut

*/
    PCCMETHOD void add_attribute(STRING *attribute_name,
            PMC* attribute_type :optional, int got_type :opt_flag) {
        VTABLE_add_attribute(interp, SELF, attribute_name,
            got_type ? attribute_type : PMCNULL);
    }


/*

=item C<PCCMETHOD void
    methods()>

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

=cut

*/
    PCCMETHOD void methods() {
        PMC *ret_methods = VTABLE_inspect_str(interp, SELF,
                CONST_STRING(interp, "methods"));
        PCCRETURN(PMC *ret_methods);
    }


/*

=item C<PCCMETHOD void
    add_method(STRING *name, PMC *sub)>

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

=cut

*/
    PCCMETHOD void add_method(STRING *name, PMC *sub) {
        VTABLE_add_method(interp, SELF, name, sub);
    }


/*

=item C<PCCMETHOD void
    roles()>

Return the roles array PMC.

=cut

*/
    PCCMETHOD void roles() {
        PMC *ret_roles = VTABLE_inspect_str(interp, SELF,
            CONST_STRING(interp, "roles"));
        PCCRETURN(PMC *ret_roles);
    }


/*

=item C<PCCMETHOD void
    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.

=cut

*/
    PCCMETHOD void 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) {
        Parrot_Role *role_info = PARROT_ROLE(SELF);
        Parrot_ComposeRole(interp, role, exclude_method, got_exclude_method,
                           alias_method, got_alias_method,
                           role_info->methods, role_info->roles);
    }

/*

=item C<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.

=cut

*/
    PCCMETHOD void inspect(STRING *what :optional, int got_what :opt_flag) {
        PMC *found;

        /* Just delegate to the appropriate vtable method. */
        if (got_what)
            found = VTABLE_inspect_str(interp, SELF, what);
        else
            found = VTABLE_inspect(interp, SELF);

        PCCRETURN(PMC *found);
    }

} /* end pmclass Role */


/*

=back

=head1 STABILITY

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

=head1 SEE ALSO

F<docs/pdds/pdd15_objects.pod>.

=cut

*/

/*
 * Local variables:
 *   c-file-style: "parrot"
 * End:
 * vim: expandtab shiftwidth=4:
 */