class Metamodel::EnumHOW
    does Metamodel::Naming
    does Metamodel::Documenting
    does Metamodel::Stashing
    does Metamodel::AttributeContainer
    does Metamodel::MethodContainer
    does Metamodel::MultiMethodContainer
    does Metamodel::RoleContainer
    does Metamodel::BaseType
    does Metamodel::MROBasedMethodDispatch
    does Metamodel::MROBasedTypeChecking
    does Metamodel::BUILDPLAN
    does Metamodel::BoolificationProtocol
    does Metamodel::REPRComposeProtocol
    does Metamodel::InvocationProtocol
    does Metamodel::Mixins
        { }

Warning: this class is part of the Rakudo implementation, and is not a part of the language specification.

Metamodel::EnumHOW is the metaclass behind the enum keyword.

enum Numbers <1 2>;
say Numbers.HOW ~~ Metamodel::EnumHOW; # OUTPUT: «True␤»

The following enum declaration:

our Int enum Error <Warning Failure Exception Sorrow Panic>;

Is roughly equivalent to this code using Metamodel::EnumHOW's methods:

BEGIN {
    my constant Error = Metamodel::EnumHOW.new_type: :name<Error>, :base_type(Int);
    Error.^add_role: Enumeration;
    Error.^add_role: NumericEnumeration;
    Error.^compose;
    for <Warning Failure Exception Sorrow Panic>.kv -> Int $v, Str $k {
        # Note: Enumeration.pred and .succ will not work when adding enum 
        # values as pairs. They should be instances of the enum itself, but 
        # this isn't possible to do without nqp. 
        Error.^add_enum_value: $k => $v;
        OUR::{$k} := Error.^enum_from_value: $v;
    }
    Error.^compose_values;
    OUR::<Error> := Error;
}

Methods

method new_type

method new_type(:$name!, :$base_type?, :$repr = 'P6opaque', :$is_mixin)

Creates a new type object for an enum. $name is the enum name, $base_type is the type given when the enum is declared using a scoped declaration (if any), and $repr is the type representation passed to the enum using the repr trait. $is_mixin is unused.

method add_parent

method add_parent($obj, $parent)

Sets the base type of an enum. This can only be used if no base type was passed to .new_type.

method set_export_callback

method set_export_callback($obj, $callback)

Sets the enum's export callback, which is invoked when calling .compose_values. This is called when applying the export trait to an enum. $callback should be a routine of some sort, taking no arguments, that handles exporting the enum's values.

method export_callback

method export_callback($obj)

Returns the export callback set by .set_export_callback.

method compose

method compose($obj, :$compiler_services)

Completes a type object for an enum. This is when any roles done by the enum are mixed in. This needs to be called before any enum values can be added using .add_enum_value.

method is_composed

method is_composed($obj)

Returns 1 if the enum is composed, otherwise returns 0.

method compose_values

method compose_values($obj)

Calls the export callback set by .set_export_callback and removes it from state. This should be called after adding the enum's values using .add_enum_value.

method set_composalizer

method set_composalizer($c)

Sets the composalizer for an enum, which produces a type that can be mixed in with another. $c should be a routine of some that has the following signature:

:($type, $name, @enum_values)

method composalizer

method composalizer($obj)

Returns the composalizer set by .set_composalizer.

method add_enum_value

method add_enum_value($obj, $value)

Adds a value to this enum. $value should be an instance of the enum itself, as type Enumeration.

method enum_values

method enum_values($obj)

Returns the values for the enum.

enum Numbers <10 20>;
say Numbers.^enum_values;                   # OUTPUT: {10 => 0, 20 => 1}

method elems

method elems($obj)

Returns the number of values.

enum Numbers <10 20>;
say Numbers.^elems;                         # OUTPUT: 2

method enum_from_value

method enum_from_value($obj, $value)

Given a value of the enum's base type, return the corresponding enum.

enum Numbers <10 20>;
say Numbers.^enum_from_value(0);            # OUTPUT: 10

method enum_value_list

method enum_value_list($obj)

Returns a list of the enum values.

enum Numbers <10 20>;
say Numbers.^enum_value_list;               # OUTPUT: (10 20)

Type Graph

Routines supplied by role Metamodel::Naming

Metamodel::EnumHOW does role Metamodel::Naming, which provides the following routines:

(Metamodel::Naming) method name

method name($type)

Returns the name of the metaobject, if any.

say 42.^name;       # OUTPUT: «Int␤»

(Metamodel::Naming) method set_name

method set_name($type, $new_name)

Sets the new name of the metaobject.

Routines supplied by role Metamodel::Stashing

Metamodel::EnumHOW does role Metamodel::Stashing, which provides the following routines:

(Metamodel::Stashing) method add_stash

method add_stash($type_obj)

Creates and sets a stash for a type, returning $type_obj.

This method is typically called as the last step of creating a new type. For example, this is how it would be used in a minimal HOW that only supports naming and stashing:

class WithStashHOW
    does Metamodel::Naming
    does Metamodel::Stashing
{
    method new_type(WithStashHOW:_: Str:D :$name! --> Mu) {
        my WithStashHOW:D $meta := self.new;
        my Mu             $type := Metamodel::Primitives.create_type: $meta, 'Uninstantiable';
        $meta.set_name: $type, $name;
        self.add_stash: $type
    }
}
 
my Mu constant WithStash = WithStashHOW.new_type: :name<WithStash>;
say WithStash.WHO; # OUTPUT: «WithStash␤» 

Routines supplied by role Metamodel::AttributeContainer

Metamodel::EnumHOW does role Metamodel::AttributeContainer, which provides the following routines:

(Metamodel::AttributeContainer) method add_attribute

method add_attribute($obj, $attribute)

Adds an attribute. $attribute must be an object that supports the methods name, type and package, which are called without arguments. It can for example be of type Attribute.

(Metamodel::AttributeContainer) method attributes

method attributes($obj)

Returns a list of attributes. For most Raku types, these will be objects of type Attribute.

(Metamodel::AttributeContainer) method set_rw

method set_rw($obj)

Marks a type whose attributes default to having a write accessor. For example in

class Point is rw {
    has $.x;
    has $.y;
}

The is rw trait on the class calls the set_rw method on the metaclass, making all the attributes implicitly writable, so that you can write;

my $p = Point.new(x => 1, y => 2);
$p.x = 42;

(Metamodel::AttributeContainer) method rw

method rw($obj)

Returns a true value if method set_rw has been called on this object, that is, if new public attributes are writable by default.

Routines supplied by role Metamodel::MethodContainer

Metamodel::EnumHOW does role Metamodel::MethodContainer, which provides the following routines:

(Metamodel::MethodContainer) method add_method

method add_method($obj, $name, $code)

Adds a method to the metaclass, to be called with name $name. This should only be done before a type is composed.

(Metamodel::MethodContainer) method methods

method methods($obj, :$all, :$local)

Returns a list of public methods available on the class (which includes methods from superclasses and roles). By default this stops at the classes Cool, Any or Mu; to really get all methods, use the :all adverb. If :local is set, only methods declared directly in the class are returned.

class A {
    method x() { };
}
 
say A.^methods();                   # x 
say A.^methods(:all);               # x infinite defined ...

The returned list contains objects of type Method, which you can use to introspect their signatures and call them.

Some introspection method-look-alikes like WHAT will not show up, although they are present in any Raku object. They are handled at the grammar level and will likely remain so for bootstrap reasons.

(Metamodel::MethodContainer) method method_table

method method_table($obj --> Hash:D)

Returns a hash where the keys are method names, and the values are methods. Note that the keys are the names by which the methods can be called, not necessarily the names by which the methods know themselves.

(Metamodel::MethodContainer) method lookup

method lookup($obj, $name --> Method)

Returns the first matching method object of the provided $name or (Mu) if no method object was found. The search for a matching method object is done by following the mro of $obj. Note that lookup is supposed to be used for introspection, if you're after something which can be invoked you probably want to use find_method instead.

say 2.5.^lookup("sqrt").raku;      # OUTPUT: «method sqrt (Rat $: *%_) ...␤» 
say Str.^lookup("BUILD").raku;     # OUTPUT: «submethod BUILD (Str $: :$value = "", *%_ --> Nil) ...␤» 
say Int.^lookup("does-not-exist"); # OUTPUT: «(Mu)␤»

The difference between find_method and lookup are that find_method will use a default candidate for parametric roles, whereas lookup throws an exception in this case, and that find_method honors FALLBACK methods, which lookup does not.

Routines supplied by role Metamodel::RoleContainer

Metamodel::EnumHOW does role Metamodel::RoleContainer, which provides the following routines:

(Metamodel::RoleContainer) method add_role

method add_role($obj, Mu $role)

Adds the $role to the list of roles to be composed.

(Metamodel::RoleContainer) method roles_to_compose

method roles_to_compose($obj --> List:D)

returns a list of roles added with add_role, which are to be composed at type composition time.

Routines supplied by role Metamodel::MROBasedMethodDispatch

Metamodel::EnumHOW does role Metamodel::MROBasedMethodDispatch, which provides the following routines:

(Metamodel::MROBasedMethodDispatch) method find_method

method find_method($obj, $name, :$no_fallback, *%adverbs)

Given a method name, it returns the method object of that name which is closest in the method resolution order (MRO). If no method can be found, it returns a VM-specific sentinel value (typically a low-level NULL value) that can be tested for with a test for definedness:

for <upper-case  uc> {
    Str.^find_method: $^meth andthen .("foo").say
        orelse "method `$meth` not found".say
}
# OUTPUT: 
# method `upper-case` not found 
# FOO 

If :no_fallback is supplied, fallback methods are not considered.

(Metamodel::MROBasedMethodDispatch) method find_method_qualified

method find_method_qualified($obj, $type, $name)

Given a method name and a type, returns the method from that type. This is used in calls like

self.SomeParentClass::the_method();

(Metamodel::MROBasedMethodDispatch) method can

method can($obj, $name)

Returns the list of methods of that name the object can do.

(Metamodel::MROBasedMethodDispatch) method publish_method_cache

Defined as:

method publish_method_cache($obj)

Walk MRO and add methods to cache, unless another method lower in the class hierarchy "shadowed" it.

Routines supplied by role Metamodel::Mixins

Metamodel::EnumHOW does role Metamodel::Mixins, which provides the following routines:

(Metamodel::Mixins) method set_is_mixin

method set_is_mixin($obj)

Marks $obj as being a mixin.

(Metamodel::Mixins) method is_mixin

method is_mixin($obj)

Returns 1 If $obj has been marked as being a mixin with set_is_mixin, otherwise returns 0.

(Metamodel::Mixins) method set_mixin_attribute

method set_mixin_attribute($obj, $attr)

Sets the mixin attribute for $obj to $attr (which should be an Attribute instance).

(Metamodel::Mixins) method mixin_attribute

method mixin_attribute($obj)

Returns the mixin attribute for $obj set with set_mixin_attribute.

(Metamodel::Mixins) method setup_mixin_cache

method setup_mixin_cache($obj)

Sets up caching of mixins for $obj. After this metamethod has been called, calls to mixin will not create a new type for mixins of $obj given the same list of roles more than once. This should be called at some point before composition.

(Metamodel::Mixins) method flush_cache

method flush_cache($obj)

No-op.

(Metamodel::Mixins) method generate_mixin

method generate_mixin($obj, @roles)

Creates a new mixin metaobject that inherits from $obj and does each of the roles in @roles. This is then composed and has its mixin attribute set (if any exists) before getting returned.

While this generates a new mixin type, this doesn't actually mix it into $obj; if that is what you intend to do, use the mixin metamethod instead.

(Metamodel::Mixins) method mixin

method mixin($obj, *@roles, :$needs-mixin-attribute)

Generates a new mixin type by calling generate_mixin with $obj and @roles. If $obj is composed, the mixin cache of $obj will be checked for any existing mixin for these beforehand. If $obj is an instance of a type, this will return $obj reblessed with the mixin generated, otherwise this will return the mixin itself.

If $needs-mixin-attribute is True, this will throw an exception if no mixin attribute exists on the mixin generated before returning.