Manually apply PR#3352

"Document Metamodel::TypePretense and Metamodel::MethodDelegation"

RIP Kaiepi++

Author: coke

doc/Type/Metamodel/CurriedRoleHOW.rakudoc

@@ -62,6 +62,10 @@ a single parameter an instantiated role will also be of the same type:
     role Zape[::T] {};
     say Zape[Int].HOW; #: «Perl6::Metamodel::CurriedRoleHOW.new␤»
 
+Curried roles L<pretend to be|/type/Metamodel::TypePretense> of types
+L<C<Mu>|/type/Mu>, L<C<Any>|/type/Any>, and L<C<Cool>|/type/Cool>, and
+L<delegate|/type/Metamodel::MethodDelegation> methods to L<C<Any>|/type/Any>.
+
 I<Note>: As with most of the C<Metamodel> classes, this one is mainly for illustration
 purposes and is not intended for the end user to instantiate.
 

doc/Type/Metamodel/MethodDelegation.rakudoc

@@ -0,0 +1,68 @@
+=begin pod :kind<Type> :subkind<role> :category<metamodel>
+
+=TITLE role Metamodel::MethodDelegation
+
+=SUBTITLE Metarole for delegating method dispatch
+
+    role Metamodel::MethodDelegation { }
+
+I<Warning>: this role is part of the Rakudo implementation, and is not
+a part of the language specification.
+
+Methods of L<C<Any>|/type/Any> and L<C<Mu>|/type/Mu> can be invoked on roles, despite them not
+actually having these types as parents:
+
+=begin code
+role Role { }
+
+say Role.raku;                             # OUTPUT: «Role␤»
+say Role.^pun.^parents(:all).map(*.^name); # OUTPUT: «()␤»
+=end code
+
+C<Metamodel::MethodDelegation> is the metarole responsible for this
+behavior. Using the metamethods this provides, metaobjects can delegate
+method dispatch to another type object. This can be useful when
+implementing types that shouldn't store methods of their own through
+L<C<Metamodel::MethodContainer>|/type/Metamodel::MethodContainer>, but
+should still support method dispatch somehow.
+
+All this metarole does is provide an interface for storing a type object
+to delegate methods to and provide a default C<find_method> method for
+delegating method lookups to that type object if no other method lookup
+behavior for it exists; any other behavior related to methods is left up
+to the metaclasses that do this metarole to implement themselves.
+
+Because method delegation is a property of the metaclass for a HOW, not
+HOWs themselves, the C<delegate_methods_to> and
+C<delegating_methods_to> metamethods this metarole provides must be
+invoked directly through a metaclass or HOW, not with C<.^> syntax:
+
+=for code :preamble<role Role { }>
+say Role.HOW.delegating_methods_to.^name; # OUTPUT: «Any␤»
+
+This metarole is commonly used in combination with
+L<C<Metamodel::TypePretense>|/type/Metamodel::TypePretense>.
+
+=head1 Methods
+
+=head2 method delegate_methods_to
+
+    method delegate_methods_to($type)
+
+Delegates methods to C<$type>. This should be a type object, but may be
+any object with a C<find_method> metamethod technically.
+
+=head2 method delegating_methods_to
+
+    method delegating_methods_to()
+
+Returns the type object a metaobject is delegating methods to.
+
+=head2 method find_method
+
+    method find_method($obj, $name)
+
+Looks up a method on the type object this metaobject is delegating
+method dispatch to.
+
+=end pod

doc/Type/Metamodel/ParametricRoleGroupHOW.rakudoc

@@ -4,6 +4,7 @@
 
 =SUBTITLE Represents a group of roles with different parameterizations
 
+:for code :solo
     class Metamodel::ParametricRoleGroupHOW
         does Metamodel::Naming
         does Metamodel::Documenting
@@ -28,6 +29,10 @@ my \zape := Metamodel::ParametricRoleGroupHOW.new_type( name => "zape");
 my \zipi := Metamodel::ParametricRoleHOW.new_type( name => "zipi", group => zape);
 say zipi.HOW; # OUTPUT: «Perl6::Metamodel::ParametricRoleHOW.new␤»
 
+Role groups L<pretend to be|/type/Metamodel::TypePretense> of types
+L<C<Mu>|/type/Mu>, L<C<Any>|/type/Any>, and L<C<Cool>|/type/Cool>, and
+L<delegate|/type/Metamodel::MethodDelegation> methods to L<C<Any>|/type/Any>.
+
 I<Note>: As with most of the C<Metamodel> classes, this one is mainly for illustration
 purposes and is not intended for the end user to instantiate.
 

doc/Type/Metamodel/ParametricRoleHOW.rakudoc

@@ -5,20 +5,20 @@
 =SUBTITLE Represents a non-instantiated, parameterized, role.
 
 =for code :skip-test<TWEAK>
-    class Metamodel::ParametricRoleHOW
-        does Metamodel::Naming
-        does Metamodel::Documenting
-        does Metamodel::Versioning
-        does Metamodel::MethodContainer
-        does Metamodel::PrivateMethodContainer
-        does Metamodel::MultiMethodContainer
-        does Metamodel::AttributeContainer
-        does Metamodel::RoleContainer
-        does Metamodel::MultipleInheritance
-        does Metamodel::Stashing
-        does Metamodel::TypePretense
-        does Metamodel::RolePunning
-        does Metamodel::ArrayType {}
+class Metamodel::ParametricRoleHOW
+    does Metamodel::Naming
+    does Metamodel::Documenting
+    does Metamodel::Versioning
+    does Metamodel::MethodContainer
+    does Metamodel::PrivateMethodContainer
+    does Metamodel::MultiMethodContainer
+    does Metamodel::AttributeContainer
+    does Metamodel::RoleContainer
+    does Metamodel::MultipleInheritance
+    does Metamodel::Stashing
+    does Metamodel::TypePretense
+    does Metamodel::RolePunning
+    does Metamodel::ArrayType {}
 
 I<Warning>: this class is part of the Rakudo implementation, and is not
 a part of the language specification.
@@ -39,6 +39,10 @@ say zipi.HOW; # OUTPUT: «Perl6::Metamodel::ParametricRoleHOW.new␤»
 The extra C<group> argument will need to be used to integrate it in a parametric
 role group, which will need to be defined in advance.
 
+Roles L<pretend to be|/type/Metamodel::TypePretense> of types L<C<Mu>|/type/Mu>,
+L<C<Any>|/type/Any>, and L<C<Cool>|/type/Cool>, and L<delegate|/type/Metamodel::MethodDelegation>
+methods to L<C<Any>|/type/Any>.
+
 I<Note>: As with most of the C<Metamodel> classes, this one is mainly for illustration
 purposes and is not intended for the end user to instantiate.
 

doc/Type/Metamodel/TypePretense.rakudoc

@@ -0,0 +1,75 @@
+=begin pod :kind<Type> :subkind<role> :category<metamodel>
+
+=TITLE role Metamodel::TypePretense
+
+=SUBTITLE Metarole for type pretenses
+
+    role Metamodel::TypePretense { }
+
+I<Warning>: this role is part of the Rakudo implementation, and is not
+a part of the language specification.
+
+Any role will type-check as L<C<Mu>|/type/Mu>, L<C<Any>|/type/Any>, and L<C<Cool>|/type/Cool>, but don't
+actually have these classes as parents:
+
+=begin code
+class Class { }
+role  Role  { }
+
+say Role ~~ Mu;   # OUTPUT: «True␤»
+say Role ~~ Any;  # OUTPUT: «True␤»
+say Role ~~ Cool; # OUTPUT: «True␤»
+
+say Class.^parents(:all).map(*.^name);     # OUTPUT: «(Any Mu)␤»
+say Role.^pun.^parents(:all).map(*.^name); # OUTPUT: «()␤»
+=end code
+
+C<Metamodel::TypePretense> is the metarole that's responsible for this
+behavior. Using the metamethods this provides, types can C<pretend to
+be> other types, i.e. types can type-check as other types. This can be
+useful when implementing types that should not store parent types
+through
+L<C<Metamodel::MultipleInheritance>|/type/Metamodel::MultipleInheritance>,
+but should still type-check like other types somehow.
+
+All this metarole does is provide an interface for storing type objects
+in a HOW and provide a default C<type_check> method that allows types to
+type-check as the types they're pretending to be if no other
+type-checking behavior for it exists; any other behavior related to type
+pretenses are left up to the metaclasses that do this metarole to
+implement themselves.
+
+Because type pretenses are a property of the metaclass for a HOW, not
+HOWs themselves, the C<pretend_to_be> and C<pretending_to_be>
+metamethods this metarole provides must be invoked directly through a
+metaclass or HOW, not with C<.^> syntax:
+
+=for code :preamble<role Role { }>
+say Role.HOW.pretending_to_be.map(*.^name); # OUTPUT: «(Cool Any Mu)»
+
+This metarole is commonly used in combination with
+L<C<Metamodel::MethodDelegation>|/type/Metamodel::MethodDelegation>.
+
+=head1 Methods
+
+=head2 method pretend_to_be
+
+    method pretend_to_be(@types)
+
+Makes all types for a type of HOW pretend to be any of the type objects
+in C<@types>.
+
+=head2 method pretending_to_be
+
+    method pretending_to_be()
+
+Returns the type objects this type of HOW is pretending to be.
+
+=head2 method type_check
+
+    method type_check($obj, $checkee)
+
+If C<$checkee> is the same object as C<$obj> or is of any of the types
+C<$obj> is pretending to be, returns C<1>, otherwise returns C<0>.
+
+=end pod