Document Metamodel::Trusting

lib/Type/Metamodel/Trusting.pod

@@ -0,0 +1,59 @@
+=begin pod
+
+=TITLE role Metamodel::Trusting
+
+=SUBTITLE Metamodel roles that implements trust relations between types
+
+    role Metamodel::Trusting is SuperClass { ... }
+
+Normally, code in a class or role can only access its own private methods. If
+another type declares that it trusts that first class, then access to private
+methods of that second type is possible. C<Metamodel::Trusting> implements
+that aspect of the Perl 6 object system.
+
+    class A {
+        my class B {
+            trusts A;   # that's where Metamodel::Trusting comes in
+            method !private_method() {
+                say "Private method in B";
+            }
+        }
+        method build-and-poke {
+            # call a private method from B
+            # disallowed if A doesn't trust B
+            B.new()!B::private_method();
+        }
+    }
+
+    A.build-and-poke    # Private method in A
+
+=head1 Methods
+
+=head2 method add_trustee
+
+    method add_trustee(Metamodel::Trusting:D: $type, Mu $trustee)
+
+Trust C<$trustee>.
+
+    class A {
+        BEGIN A.^add_trustee(B);
+        # same as 'trusts B';
+    }
+
+=head2 method trusts
+
+    method trusts(Metamodel::Trusting:D: $type) returns List
+
+Returns a list of types that the invocant trusts.
+
+    class A { trusts Int; };
+    say .^name for A.^trusts;       # Int
+
+=head2 method is_trusted
+
+    method is_trusted(Metamodel::Trusting:D: $type, $claimant)
+
+Returns 1 if C<$type> trusts C<$claimant>, and 0 otherwise.
+Types always trust themselves.
+
+=end pod