=begin pod

=TITLE class Mu

=SUBTITLE The root of the Perl 6 type hierarchy.

    class Mu { ... }

The root of the Perl 6 type hierarchy. For the origin of the name, see
L<http://en.wikipedia.org/wiki/Mu_%28negative%29>. One can also say that
there are many undefined values in Perl 6, and C<Mu> is the I<most undefined>
value.

Note that most classes do not derive from C<Mu> directly, but rather from
L<Any|/type/Any>.

=head1 Methods

=head2 routine defined

    multi sub    defined(Mu) returns Bool:D
    multi method defined()   returns Bool:D

Returns C<False> on the type object, and C<True> otherwise.

    say Int.defined;                # False
    say 42.defined;                 # True

Very few types (like L<Failure|/type/Failure>) override C<defined> to return
C<False> even for instances:

    sub fails() { fail 'oh noe' };
    say fails().defined;            # False

=head2 routine Bool

    multi sub    Bool(Mu) returns Bool:D
    multi method Bool()   returns Bool:D

Returns C<False> on the type object, and C<True> otherwise.

Many built-in types override this to be C<False> for empty collections, the
empty L<string|/type/Str> or numerical zeros

    say Mu.Bool;                    # False
    say Mu.new.Bool;                # True
    say [1, 2, 3].Bool;             # True
    say [].Bool;                    # False
    say { 'hash' => 'full'}.Bool;   # True
    say {}.Bool;                    # False

=head2 method Str

    multi method Str()   returns Str

Returns a string representation of the invocant, intended to be machine
readable. Method C<Str> warns on type objects, and produces the empty string.

    say Mu.Str;                     #!> use of uninitialized value of type Mu in string context

=head2 routine gist

    multi sub    gist(Mu) returns Str
    multi method gist()   returns Str

Returns a string representation of the invocant, optimized for
fast recognition by humans.

The default C<gist> method in C<Mu> re-dispatches to the L<perl> method for
defined invocants, and returns the type name in parenthesis for type object
invocants. Many built-in classes override the case of instances to something 
more specific that may truncate output.

C<gist> is the method that L<say> calls implicitly, so C<say $something> and
C<say $something.gist> generally produce the same output.

    say Mu.gist;        # (Mu)
    say Mu.new.gist;    # Mu.new()

=head2 routine perl

    multi sub    perl(Mu) returns Str
    multi method perl()   returns Str

Returns a Perlish representation of the object (i.e., can usually
be re-evaluated with L<EVAL> to regenerate the object). The exact output of
C<perl> is implementation specific, since there are generally many ways to
write a Perl expression that produces a particular value

=head2 method clone

    method clone(*%twiddles)

Creates a shallow clone of the invocant. If named arguments are passed
to it, their values are used in every place where an attribute name matches
the name of a named argument.

=begin code
class Point2D {
    has ($.x, $.y);
    multi method gist(Point2D:D:) {
        "Point($.x, $.y)";
    }
}

my $p = Point2D.new(x => 2, y => 3);

say $p;                     # Point(2, 3)
say $p.clone(y => -5);      # Point(2, -5)
=end code

=head2 method new

    multi method new(*%attrinit)

Default method for constructing (create + initialize) new objects
of a class. This method expects only named arguments which are then
used to initialize attributes with accessors of the same name.

Classes may provide their own C<new> method to override this default.

C<new> triggers an object construction mechanism that calls submethods named
C<BUILD> in each class of an inheritance hierarchy, if they exist. See
L<the documentation on object construction|/language/objects#Object
Construction> for more information.

=head2 method bless

    method bless(*%attrinit) returns Mu:D

Lower-level object construction method than C<new>.

Creates a new object of the same type as the invocant, uses
the named arguments to initialize attributes, and returns the
created object.

You can use this method when writing custom constructors:

    class Point {
        has $.x;
        has $.y;
        multi method new($x, $y) {
            self.bless(:$x, :$y);
        }
    }
    my $p = Point.new(-1, 1);

(Though each time you write a custom constructor, remember that it makes
subclassing harder).

=head2 method CREATE

    method CREATE() returns Mu:D

Allocates a new object of the same type as the invocant, without
initializing any attributes.

    say Mu.CREATE.defined;  # True

=head2 method print

    multi method print() returns Bool:D

Prints value to C<$*OUT> after stringification using C<.Str> method without
adding a newline at end.

    "abc\n".print;          # abc␤

=head2 method put

    multi method put() returns Bool:D

Prints value to C<$*OUT> after stringification using C<.Str> method adding a
newline at end.

    "abc".put;              # abc␤

=head2 method say

    multi method say() returns Bool:D

Prints value to C<$*OUT> after stringification using C<.gist> method with
newline at end. To produce machine readable output use C<.put>.

    say 42;                 # 42␤

=head2 method ACCEPTS

    multi method ACCEPTS(Mu:U: $other)

C<ACCEPTS> is the method that smart matching with the L<infix ~~|routine:~~>
operator and given/when invokes on the right-hand side (the matcher).

The C<Mu:U> multi performs a type check. Returns C<True> if C<$other> conforms to the invocant
(which is always a type object or failure).

    say 42 ~~ Mu;           # True
    say 42 ~~ Int;          # True
    say 42 ~~ Str;          # False

Note that there is no multi for defined invocants; this is to allow
autothreading of L<junctions|/type/Junction>, which happens as a fallback
mechanism when no direct candidate is available to dispatch to.

=head2 method WHICH

    multi method WHICH() returns ObjAt:D

Returns an object of type L<ObjAt> which uniquely identifies the object.
Value types override this method which makes sure that two equivalent objects
return the same return value from C<WHICH>.

    say 42.WHICH eq 42.WHICH;       # True

=head2 method WHERE

    method WHERE() returns Int

Returns an C<Int> representing the memory address of the object.

=head2 method WHY

    multi method WHY()

Returns the attached Pod value.  For instance,

=for code
    sub cast(Spell $s)
    #= Initiate a specified spell normally
    #= (do not use for class 7 spells)
    {
	do-raw-magic($s);
    }
    say &cast.WHY;

prints

    Initiate a specified spell normally (do not use for class 7 spells)

See the L<documentation specification|http://design.perl6.org/S26.html> for
details about attaching Pod to variables, classes, functions, methods, etc.

=head2 trait is export

    multi sub trait_mod:<is>(Mu:U \type, :$export!)

Marks a type as being exported, that is, available to external users.

    my class SomeClass is export { }

A user of a module or class automatically gets all the symbols imported that
are marked as C<is export>.

See L</language/modules#Exporting and Selective Importing> for more details.

=head2 method take

    method take()

Takes the given item and passes it to the enclosing C<gather> block.

    #| randomly select numbers for lotto
    my $num-selected-numbers = 6;
    my $max-lotto-numbers = 49;
    gather for ^$num-selected-numbers {
        take (1 .. $max-lotto-numbers).pick(1);
    }.say;    #-> 32 22 1 17 32 9  (for example)

=head2 method so

    method so()

Returns a C<Bool> value representing the logical non-negation of an
expression.  One can use this method similarly to the English sentence: "If
that is B<so>, then do this thing".  For instance,

    my @args = <-a -e -b -v>;
    my $verbose-selected = any(@args) eq '-v' | '-V';
    if $verbose-selected.so {
        say "Verbose option detected in arguments";
    } #-> Verbose option detected in arguments

=head2 method not

    method not()

Returns a C<Bool> value representing the logical negation of an expression.
Thus it is the opposite of C<so>.

    my @args = <-a -e -b>;
    my $verbose-selected = any(@args) eq '-v' | '-V';
    if $verbose-selected.not {
        say "Verbose option not present in arguments";
    } #-> Verbose option not present in arguments

Since there is also a prefix version of C<not>, the above code reads better
like so:

    my @args = <-a -e -b>;
    my $verbose-selected = any(@args) eq '-v' | '-V';
    if not $verbose-selected {
        say "Verbose option not present in arguments";
    } #-> Verbose option not present in arguments

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
