=encoding utf8 =head1 TITLE DRAFT: Synopsis 32: Setting Library - Basics =head1 AUTHORS Rod Adams Larry Wall Aaron Sherman Mark Stosberg Carl Mäsak Moritz Lenz Tim Nelson =head1 VERSION Created: 19 Mar 2009 extracted from S29-functions.pod Last Modified: 30 Apr 2009 Version: 2 The document is a draft. If you read the HTML version, it is generated from the pod in the pugs repository under /docs/Perl6/Spec/S32-setting-library/Basics.pod so edit it there in the SVN repository if you would like to make changes. =head1 Roles =head2 Object The following are defined in the C role: role Object { 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 true() {...} } =item defined our Bool multi method defined ( $self: ) is export our Bool multi method defined ( $self: ::role ) is export C returns true if the parameter has a value and that value is not the undefined value (per C), 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 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 C on a variable should place the object in the same state as if it was just declared. =item not method not() {...} =item true method true() {...} XXX Copied from S02 -- should it be deleted from there? The definition of C<.Bool> for the most ancestral type (that is, the C type) is equivalent to C<.defined>. Since type objects are considered undefined, all type objects (including C 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 an C it would be considered defined, and thus true. (It is not clear that this is allowed, however.) =head2 Any The following are defined in the C role: role Any does Object does Pattern { our Bool multi sub eqv (Ordering @by, $a, $b) {...} our Bool multi sub eqv (Ordering $by = &infix:, $a, $b) {...} our multi method clone (::T $self --> T) {...} our multi method clone (::T $self, *%attributes --> T) {...} our Order multi sub cmp (Ordering @by, $a, $b) {...} our Order multi sub cmp (Ordering $by = &infix:, $a, $b) {...} 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 ( Object $o: ) is export {...} our multi method warn ( Object $o: ) is export {...} } =over =item eqv our Bool multi sub eqv (Ordering @by, $a, $b) our Bool multi sub eqv (Ordering $by = &infix:, $a, $b) Returns a Bool indicating if the parameters are equivalent, using criteria C<$by> or C<@by> for comparisons. C<@by> differs from C<$by> in that each criterion is applied, in order, until a non-zero (equivalent) result is achieved. =item can our Callable multi method can ($self:, Str $method) 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 our multi method clone (::T $self --> T) our multi method clone (::T $self, *%attributes --> T) 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 cmp our Order multi sub cmp (Ordering @by, $a, $b) our Order multi sub cmp (Ordering $by = &infix:, $a, $b) Returns C, or C, or C (which numify to -1, 0, +1 respectively) indicating if paramater C<$a> should be ordered before/tied with/after parameter C<$b>, using criteria C<$by> or C<@by> for comparisons. C<@by> differs from C<$by> in that each criterion is applied, in order, until a non-zero (tie) result is achieved. If the values are not comparable, returns a proto C object that is undefined. =item does our Bool multi method does ($self:, $type) Returns C if and only if C<$self> conforms to type C<$type>. =item isa our Bool multi method isa ($self:, $type) Returns C 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 our Str multi method perl ( Object $o: ) is export Returns a perlish representation of the object, so that calling C on the returned string reproduces the object as accurately as possible. =item warn our multi method warn ( Object $o: ) is export Prints a warning to C<$*ERR>, which is usually finds C<$PROCESS::ERR>. See C for details. =back =head2 Pattern role Pattern { method ACCEPTS($self:, $other) {...} method REJECTS($self:, $other) {...} } =item ACCEPTS Used in smartmatching; see S03. =item REJECTS Used in smartmatching; see S03. =head2 Scalar B: L C provides the basic tools for operating on undifferentiated scalar variables. All of the following are exported by default. =over =item undef constant Scalar Scalar::undef Returns the undefined scalar object. C has no value at all, but for historical compatibility, it will numify to C<0> and stringify to the empty string, potentially generating a warning in doing so. There are two ways to determine if a value equal to undef: the C function (or method) can be called or the C (or C) operator can be used. C is also considered to be false in a boolean context. Such a conversion does not generate a warning. Perl 5's unary C function is renamed C to avoid confusion with the value C (which is always 0-ary now). =item VAR This is not really a method, but some kind of macro. See L for details. =back =head1 Additions Please post errors and feedback to perl6-language. If you are making a general laundry list, please separate messages by topic.