=encoding utf8

=head1 TITLE

DRAFT: Synopsis 32: Setting Library - Basics

=head1 VERSION

    Created: 19 Mar 2009 extracted from S29-functions.pod

    Last Modified: 29 June 2012
    Version: 5

The document is a draft.

=head1 Roles

=head2 Mu

The following are defined in the C<Mu> class:

 class Mu {
     multi method defined ($self: --> Bool:D ) is export {...}
     multi method defined ( $self: ::role --> Bool:D ) is export { ... }
     multi method new(*%opts) { ... }

     method not() {...}
     method so() {...}

 }

=over

=item defined

  multi method defined ( $self: --> Bool:D ) is export
  multi method defined ( $self: ::role --> Bool:D ) is export

C<defined> returns true if the parameter has a value and that value is
considered defined by its type, otherwise false is returned.

Same as Perl 5, only takes extra optional argument to ask if value is defined
with respect to a particular role:

  defined($x, SomeRole);

A value may be defined according to one role and undefined according to another.
Without the extra argument, defaults to the definition of defined supplied by
the type of the object.

=item new

  multi method new(*%attrs) { }

Creates a new object of the same type as the object is called on,
setting attributes with public accessors to the values provided
by the named arguments to C<new>.

=item undefine

  multi undefine( Any $thing is rw --> Any )

Takes any variable as a parameter and attempts to "remove" its
definition. For simple scalar variables this means assigning
the undefined value to the variable. For objects, this is equivalent
to invoking their undefine method. For arrays, hashes and other
complex data, this might require emptying the structures associated
with the object.

In all cases, calling C<undefine> on a variable
should place the object in the same state as if it was just
declared.

=item not

     method not() {...}

=item so

     method so() {...}

XXX Copied from S02 -- should it be deleted from there?

The definition of C<.Bool> for the most ancestral type (that is, the
C<Mu> type) is equivalent to C<.defined>.  Since type objects are
considered undefined, all type objects (including C<Mu> itself)
are false unless the type overrides the definition of C<.Bool>
to include undefined values.  Instantiated objects default to true
unless the class overrides the definition.  Note that if you could
instantiate a C<Mu> it would be considered defined, and thus true.
(It is not clear that this is allowed, however.)

=back

=head2 Any

The following are defined in the C<Any> class:

 class Any is Mu {
     multi method clone (::T $self:, *%attributes --> T ) {...}

     multi method can ($self:, Str $method --> Callable ) {...}
     multi method does ($self:, $type --> Bool ) {...}
     multi method isa  ($self:, $type --> Bool ) {...}
     multi method perl ( Mu $o: --> Str ) is export {...}
     multi method warn ( Mu $o: --> Any ) is export {...}
 }

=over

=item can

 multi method can ($self:, Str $method --> Callable )

If there is a multi method of name C<$method> that can be called on
C<$self>, then a closure is return which has C<$self> bound to the position
of the invocant.

Otherwise an undefined value is returned.

=item clone

 multi method clone (::T $self --> T --> Any )
 multi method clone (::T $self, *%attributes --> T --> Any )

The first variant returns  an independent copy of C<$o> that is equivalent
to C<$o>.

The second variant does the same, but any named arguments override an
attribute during the cloning process.

=item does

 multi method does ($self:, $type --> Bool )

Returns C<True> if and only if C<$self> conforms to type C<$type>.

=item isa

 multi method isa ($self:, $type --> Bool )

Returns C<True> if a the invocant an instance of class C<$type>, or
of a subset type or a derived class (through inheritance) of C<$type>.

=item perl

 multi method perl ( Mu $o: --> Str ) is export

Returns a perlish representation of the object, so that calling C<EVAL>
on the returned string reproduces the object as accurately as possible.

=item warn

 multi method warn ( Mu $o: --> Any ) is export

Throws a resumable warning exception, which is considered a control
exception, and hence is invisible to most normal exception handlers.
The outermost control handler will print the warning to C<$*ERR>
(which usually finds C<$PROCESS::ERR>; see C<Synopsis 16: IPC /
IO / Signals> for details).  After printing the warning, the exception
is resumed where it was thrown.  To override this behavior, catch the
exception in a CONTROL block.  A quietly {...} block is the opposite of a
try {...} block in that it will suppress any warnings but pass fatal
exceptions through.

To simply print to C<$*ERR>, please use C<note> instead.  C<warn>
should be reserved for use in threatening situations when you don't
quite want to throw an exception.

=back

=head2 Pattern

 role Pattern {
     method ACCEPTS($self:, $other) {...}
 }

=over

=item ACCEPTS

Used in smartmatching; see S03.

=back

=head2 Scalar

C<Scalar> provides the basic tools for operating on undifferentiated
scalar variables. All of the following are exported by default.

=over

=item VAR

This is not really a method, but some kind of macro.  See L<S12> for details.

=back

=head1 AUTHORS

    Rod Adams <rod@rodadams.net>
    Larry Wall <larry@wall.org>
    Aaron Sherman <ajs@ajs.com>
    Mark Stosberg <mark@summersault.com>
    Carl Mäsak <cmasak@gmail.com>
    Moritz Lenz <moritz@faui2k3.org>
    Tim Nelson <wayland@wayland.id.au>