start to talk about introspection and meta objects

lib/objects.pod

@@ -31,7 +31,7 @@ Another method call syntax separates the method name and the argument list
 with a colon:
 
     say @*INC.join: ':';
-    
+
 Many operations that don't look like method calls (for example smart
 matching, interpolating an object into a string) result in method
 calls under the hood.
@@ -416,6 +416,86 @@ TODO:  parameterized roles
 
 =head1 Meta-Object Programming and Introspection
 
-TODO: everything :-)
+Perl 6 has a meta object system, which means that the behavior of objects,
+classes, roles, grammars, enums etc. are themselves controlled by other
+objects; those objects are called I<meta objects>. Meta objects are, like
+ordinary objects, instances of classes, in this case we call them I<meta
+classes>.
+
+For each object or class, you can get the meta object by calling C<.HOW> on
+it. Note that although this looks like a method call, it is actually
+special-cased in the compiler, so it is more like a macro.
+
+So, what can you do with the meta object? For one you can check if two
+objects have the same meta class by comparing them for equality:
+
+    say 1.HOW ===   2.HOW;      # True
+    say 1.HOW === Int.HOW;      # True
+    say 1.HOW === Num.HOW;      # False
+
+Perl 6 uses the word I<HOW>, Higher Order Workings, to refer to the meta
+object system. Thus it should be no surprise that in Rakudo, the class name
+of the meta class that controls class behavior is called
+C<Perl6::Metamodel::ClassHOW>. For each class there is one instance of
+C<Perl6::Metamodel::ClassHOW>.
+
+But of course the meta model does much more for you. For example it allows you
+to introspect objects and classes. The calling convention for methods on meta
+objects is to call the method on the meta object, and pass in the object of
+interest as first argument to the object. So to get the name of the class of
+an object, you could write:
+
+    my $object = 1;
+    my $metaobject = 1.HOW;
+    say $metaobject.name($object);      # Int
+
+    # or shorter:
+    say 1.HOW.name(1);                  # Int
+
+(The motivation is that Perl 6 also wants to allow a more prototype-based
+object system, where it's not necessary to create a new meta object for every
+type).
+
+To get rid of using the same object twice, there is a shortcut:
+
+    say 1.^name;                        # Int
+    # same as
+    say 1.HOW.name(1);                  # Int
+
+=head2 Introspection
+
+Introspection is the process of getting information about an object or class
+at runtime. In Perl 6, all introspection goes through the meta object. The
+standard C<ClassHOW> for class-based objects offers these facilities:
+
+=head3 methods
+
+Returns a list of public methods available on the class (which includes
+methods from superclasses and roles). By default this stops at the classes
+C<Cool>, C<Any> or C<Mu>; to really get all methods, use the C<:all> adverb.
+
+
+    class A {
+        method x() { };
+    }
+
+    say A.^methods();                   # x
+    say A.^methods(:all);               # x infinite defined ...
+
+=head3 mro
+
+Returns the list of the class itself and its superclasses in method resolution
+order. Perl 6 linearizes the graph of superclasses into a single list that
+C<$object.^mro> returns; when a method is called, the class and its parent
+classes are visited in that order. (Only conceptually; actually the list of
+methods is built at class composition time).
+
+    say 1.^mro;                         # (Int) (Cool) (Any) (Mu)
+
+=head3 name
+
+Returns the name of the class:
+
+    say 'a string'.^name;               # Str
 
 =end pod