TITLE

DRAFT: Synopsis 32: Setting Library - Basics

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>

VERSION

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

Last Modified: 17 Dec 2009
Version: 4

The document is a draft.

If you read the HTML version, it is generated from the Pod in the specs repository under https://github.com/perl6/specs/blob/master/S32-setting-library/Basics.pod so edit it there in the git repository if you would like to make changes.

Roles

Mu

The following are defined in the Mu role:

role Mu {
    our Bool multi method defined ($self:) is export {...}
    our Bool multi method defined ($self: ::role ) is export {...}

    our multi method undefine( $self: ) is export {...}

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

defined

our Bool multi method defined ( $self: ) is export
our Bool multi method defined ( $self: ::role ) is export

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.

undefine

our multi undefine( Any $thing )
our multi method undefine( Any $self )

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 undefine on a variable should place the object in the same state as if it was just declared.

not

method not() {...}

so

method so() {...}

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

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

Any

The following are defined in the Any role:

role Any does Mu does Pattern {
    our multi method clone (::T $self --> T) {...}
    our multi method clone (::T $self, *%attributes --> T) {...}

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

can

our Callable multi method can ($self:, Str $method)

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

Otherwise an undefined value is returned.

clone

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

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

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

does

our Bool multi method does ($self:, $type)

Returns True if and only if $self conforms to type $type.

isa

our Bool multi method isa ($self:, $type)

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

perl

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

Returns a perlish representation of the object, so that calling eval on the returned string reproduces the object as accurately as possible.

warn

our multi method warn ( Mu $o: ) 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 $*ERR (which usually finds $PROCESS::ERR; see 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 $*ERR, please use note instead. warn should be reserved for use in threatening situations when you don't quite want to throw an exception.

Pattern

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

ACCEPTS

Used in smartmatching; see S03.

Scalar

API document: Scalar

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

VAR

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

Additions

Please post errors and feedback to perl6-language. If you are making a general laundry list, please separate messages by topic.