TITLE

SUBTITLE

I<Warning>: this role is part of the Rakudo implementation, and is not
a part of the language specification.


Type declarations may include declarator blocks (C<#|> and C<#=>), which allow
you to set the type's documentation. This can then be accessed through the
C<WHY> method on objects of that type:


code

=begin code
#|[Documented is an example class for Metamodel::Documenting's documentation.]
class Documented { }
#=[Take a look at my WHY!]

say Documented.WHY;
# OUTPUT:
# Documented is an example class for Metamodel::Documenting's documentation.
# Take a look at my WHY!
=end code


C<Metamodel::Documenting> is what implements this behavior for types.
This example can be rewritten to use its methods explicitly like so:


=begin code
BEGIN {
    our Mu constant Documented = Metamodel::ClassHOW.new_type: :name<Documented>;
    Documented.HOW.compose: Documented;
    Documented.HOW.set_why: do {
        my Pod::Block::Declarator:D $pod .= new;
        $pod._add_leading:  "Documented is an example class for Metamodel::Documenting's documentation.";
        $pod._add_trailing: "Take a look at my WHY!";
        $pod
    };
}

say Documented.HOW.WHY;
# OUTPUT:
# Documented is an example class for Metamodel::Documenting's documentation.
# Take a look at my WHY!
=end code


It typically isn't necessary to handle documentation for types directly
through their HOW like this, as C<Metamodel::Documenting>'s methods are
exposed through L<C<Mu>|/type/Mu> via its C<WHY> and C<set_why> methods,
which are usable on types in most cases.


head

Sets the documentation for a type to C<$why>.


root

Metaobject that can hold attributes


role Metamodel::AttributeContainer


Metaobject that supports the C3 method resolution order


role Metamodel::C3MRO


Metaobject supporting object finalization


role Metamodel::Finalization


Metaobject that supports storing and introspecting methods


role Metamodel::MethodContainer


Metaobject for generating mixins


role Metamodel::Mixins


Metaobject that supports resolving inherited methods


role Metamodel::MROBasedMethodDispatch


Metaobject that supports multiple inheritance


role Metamodel::MultipleInheritance


Metaobject that supports named types


role Metamodel::Naming


Represents a group of roles with different parameterizations


role Metamodel::ParametricRoleGroupHOW


Represents a non-instantiated, parameterized, role.


role Metamodel::ParametricRoleHOW


Metaobject that supports private methods


role Metamodel::PrivateMethodContainer


Metaobject that supports holding/containing roles


role Metamodel::RoleContainer


Metaobject that supports punning of roles.


role Metamodel::RolePunning


Metarole for type stashes


role Metamodel::Stashing


Metaobject that supports trust relations between types


role Metamodel::Trusting


Metaobjects that support versioning


role Metamodel::Versioning


Metarole for documenting types.


para

L<Examples| file:../examples/index.podlite>


L<Download |file:../download/index.podlite>


React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


HEADER

FOOTER

role Metamodel::Documenting


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


C<Metamodel::EnumHOW> is the metaclass behind the C<enum> keyword.


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


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


Is roughly equivalent to this code using C<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;
}


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


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


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


method set_export_callback($obj, $callback)


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


Returns the export callback set by C<.set_export_callback>.


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
C<.add_enum_value>.


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


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


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


Returns the composalizer set by C<.set_composalizer>.


Adds a value to this enum. C<$value> should be an instance of the enum itself,
as type L<C<Enumeration>|/type/Enumeration>.


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


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


Metaobject representing a Raku class.


class Metamodel::ClassHOW


Provides an implementation of a concrete instance of a role


role Metamodel::ConcreteRoleHOW


Support for parameterized roles that have not been instantiated


role Metamodel::CurriedRoleHOW


Metaobject for type definiteness


class Metamodel::DefiniteHOW


Metaobject representing a Raku package.


class Metamodel::PackageHOW


Metaobject that supports low-level type operations


class Metamodel::Primitives


Metaobject representing a Raku enum.


class Metamodel::EnumHOW


Type objects may be given a I<type smiley>, which is a suffix that
denotes their definiteness:


=begin code
say Any:D.^name; # OUTPUT: «Any:D␤»
say Any:U.^name; # OUTPUT: «Any:U␤»
say Any:_.^name; # OUTPUT: «Any␤»
=end code


Despite sharing a type with L<C<Any>|/type/Any>, C<Any:U> and C<Any:D> in particular
have different type-checking behaviors from it:


=begin code
say Any ~~ Any:D;     # OUTPUT: «False␤»
say Any ~~ Any:U;     # OUTPUT: «True␤»
say Any ~~ Any:_;     # OUTPUT: «True␤»
say Any.new ~~ Any:D; # OUTPUT: «True␤»
say Any.new ~~ Any:U; # OUTPUT: «False␤»
say Any.new ~~ Any:_; # OUTPUT: «True␤»
=end code


This happens because C<Any:D> and C<Any:U> are not created with
L<C<Metamodel::ClassHOW>|/type/Metamodel::ClassHOW> like you might expect
L<C<Any>|/type/Any> type objects to be, but C<Metamodel::DefiniteHOW> instead. This
HOW defines the behavior for definite type objects such as these.


Is roughly equivalent to this code using the methods of
C<Metamodel::DefiniteHOW>:


method new_type(:$base_type!, :$definite!)


Creates a new definite type given a base type and definiteness.
C<$definite> should either be C<1> for C<:D> types or C<0> for C<:U>
types.


Returns the shortname of a definite type.


Returns the base type for a definite type:


Returns C<1> if the definite type given is a C<:D> type or C<0> if it is
a C<:U> type.


Produces a nominal type object for a definite type. This is its base
type, which may also get nominalized if it has the C<nominalizable>
archetype.


method find_method($definite_type, $name)


Looks up a method on the base type of a definite type.


method type_check($definite_type, $checkee)


Performs a type-check of a definite type against C<$checkee>. This will
check if C<$checkee> is of its base type, returning C<True> if they
match or C<False> otherwise. This metamethod can get called when a
definite type is on the left-hand side of a smartmatch, for instance.


method accepts_type($definite_type, $checkee)


Performs a type-check of C<$checkee> against a definite type. This will
check if C<$checkee> is of its base type and matches its definiteness,
returning C<True> if they match or C<False> otherwise.  This metamethod
can get called when the definite type is on the right-hand side of a
smartmatch, for instance.


The Raku Knowledge Base


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


role Metamodel::Documenting

Methods

method set_why

method WHY

See Also