Author: wayland Date: 2009-03-06 02:49:52 +0100 (Fri, 06 Mar 2009) New Revision: 25719
Added: docs/Perl6/Spec/S32-setting-library/Basics.pod Removed: docs/Perl6/Spec/S32-setting-library/Any.pod docs/Perl6/Spec/S32-setting-library/Scalar.pod Log: Made Basics contain Object, Any, Pattern, and Scalar Deleted: docs/Perl6/Spec/S32-setting-library/Any.pod =================================================================== --- docs/Perl6/Spec/S32-setting-library/Any.pod 2009-03-05 21:27:55 UTC (rev 25718) +++ docs/Perl6/Spec/S32-setting-library/Any.pod 2009-03-06 01:49:52 UTC (rev 25719) @@ -1,184 +0,0 @@ - -=encoding utf8 - -=head1 Title - -DRAFT: Synopsis 32: Setting Library - Any - -=head1 Version - - Author: Rod Adams <r...@rodadams.net> - Maintainer: Larry Wall <la...@wall.org> - Contributions: Aaron Sherman <a...@ajs.com> - Mark Stosberg <m...@summersault.com> - Carl Mäsak <cma...@gmail.com> - Moritz Lenz <mor...@faui2k3.org> - Tim Nelson <wayl...@wayland.id.au> - Date: 19 Mar 2009 extracted from S29-functions.pod - Last Modified: 19 Feb 2009 - Version: 1 - -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/Any.pod so edit it there in -the SVN repository if you would like to make changes. - -=head1 Any - -The following are defined in the C<Any> role: - - role Any does Object does Pattern { - our Bool multi sub eqv (Ordering @by, $a, $b) {...} - our Bool multi sub eqv (Ordering $by = &infix:<eqv>, $a, $b) {...} - - our Bool multi method defined ( Any $self) {...} - our Bool multi method defined ( Any $self, ::role ) {...} - - our multi method undefine( Any $self ) {...} - - 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:<cmp>, $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 defined - - our Bool multi defined ( Any $thing ) - our Bool multi defined ( Any $thing, ::role ) - our Bool multi method defined ( Any $self) - our Bool multi method defined ( Any $self, ::role ) - -C<defined> returns true if the parameter has a value and that value is -not the undefined value (per C<undef>), 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<undefine> on a variable -should place the object in the same state as if it was just -declared. - -=item eqv - - our Bool multi sub eqv (Ordering @by, $a, $b) - our Bool multi sub eqv (Ordering $by = &infix:<eqv>, $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:<cmp>, $a, $b) - -Returns C<Order::Increase>, or C<Order::Same>, or C<Order::Decrease> -(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<Order> object that is undefined. - -=item does - - our Bool multi method does ($self:, $type) - -Returns C<True> if and only if C<$self> conforms to type C<$type>. - -=item isa - - our Bool multi method isa ($self:, $type) - -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 - - our Str multi method perl ( Object $o: ) 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 - - our multi method warn ( Object $o: ) is export - -Prints a warning to C<$*ERR>, which is usually finds C<$PROCESS::ERR>. See -C<Synopsis 16: IPC / IO / Signals> for details. - -=back - -=head1 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. - -=head1 Additions - -Please post errors and feedback to perl6-language. If you are making -a general laundry list, please separate messages by topic. - - - Copied: docs/Perl6/Spec/S32-setting-library/Basics.pod (from rev 25698, docs/Perl6/Spec/S32-setting-library/Any.pod) =================================================================== --- docs/Perl6/Spec/S32-setting-library/Basics.pod (rev 0) +++ docs/Perl6/Spec/S32-setting-library/Basics.pod 2009-03-06 01:49:52 UTC (rev 25719) @@ -0,0 +1,219 @@ + +=encoding utf8 + +=head1 Title + +DRAFT: Synopsis 32: Setting Library - Basics + +=head1 Version + + Author: Rod Adams <r...@rodadams.net> + Maintainer: Larry Wall <la...@wall.org> + Contributions: Aaron Sherman <a...@ajs.com> + Mark Stosberg <m...@summersault.com> + Carl Mäsak <cma...@gmail.com> + Moritz Lenz <mor...@faui2k3.org> + Tim Nelson <wayl...@wayland.id.au> + Date: 19 Mar 2009 extracted from S29-functions.pod + Last Modified: 19 Feb 2009 + Version: 1 + +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<Object> role: + + role Object { + our Bool multi method defined ($self:) {...} + our Bool multi method defined ($self: ::role ) {...} + + our multi method undefine( $self: ) {...} + } + +=item defined + + our Bool multi method defined ( $self: ) is export + our Bool multi method defined ( $self: ::role ) is export + +C<defined> returns true if the parameter has a value and that value is +not the undefined value (per C<undef>), 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<undefine> on a variable +should place the object in the same state as if it was just +declared. + +=head2 Any + +The following are defined in the C<Any> role: + + role Any does Object does Pattern { + our Bool multi sub eqv (Ordering @by, $a, $b) {...} + our Bool multi sub eqv (Ordering $by = &infix:<eqv>, $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:<cmp>, $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:<eqv>, $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:<cmp>, $a, $b) + +Returns C<Order::Increase>, or C<Order::Same>, or C<Order::Decrease> +(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<Order> object that is undefined. + +=item does + + our Bool multi method does ($self:, $type) + +Returns C<True> if and only if C<$self> conforms to type C<$type>. + +=item isa + + our Bool multi method isa ($self:, $type) + +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 + + our Str multi method perl ( Object $o: ) 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 + + our multi method warn ( Object $o: ) is export + +Prints a warning to C<$*ERR>, which is usually finds C<$PROCESS::ERR>. See +C<Synopsis 16: IPC / IO / Signals> 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<API document>: L<Scalar> + +C<Scalar> 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<undef> 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<defined> function (or method) can +be called or the C<//> (or C<orelse>) operator can be used. + +C<undef> is also considered to be false in a boolean context. +Such a conversion does not generate a warning. + +Perl 5's unary C<undef> function is renamed C<undefine> to avoid +confusion with the value C<undef> (which is always 0-ary now). + +=item VAR + +This is not really a method, but some kind of macro. See L<S12> 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. Property changes on: docs/Perl6/Spec/S32-setting-library/Basics.pod ___________________________________________________________________ Added: svn:mime-type + text/plain; charset=UTF-8 Added: svn:mergeinfo + Added: svn:eol-style + native Deleted: docs/Perl6/Spec/S32-setting-library/Scalar.pod =================================================================== --- docs/Perl6/Spec/S32-setting-library/Scalar.pod 2009-03-05 21:27:55 UTC (rev 25718) +++ docs/Perl6/Spec/S32-setting-library/Scalar.pod 2009-03-06 01:49:52 UTC (rev 25719) @@ -1,65 +0,0 @@ - -=encoding utf8 - -=head1 Title - -DRAFT: Synopsis 32: Setting Library - Scalar - -=head1 Version - - Author: Rod Adams <r...@rodadams.net> - Maintainer: Larry Wall <la...@wall.org> - Contributions: Aaron Sherman <a...@ajs.com> - Mark Stosberg <m...@summersault.com> - Carl Mäsak <cma...@gmail.com> - Moritz Lenz <mor...@faui2k3.org> - Tim Nelson <wayl...@wayland.id.au> - Date: 19 Mar 2009 extracted from S29-functions.pod - Last Modified: 19 Feb 2009 - Version: 1 - -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/Miscellaneous-scalars.pod -so edit it there in the SVN repository if you would like to make changes. - -=head1 Scalar - -B<API document>: L<Scalar> - -C<Scalar> 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<undef> 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<defined> function (or method) can -be called or the C<//> (or C<orelse>) operator can be used. - -C<undef> is also considered to be false in a boolean context. -Such a conversion does not generate a warning. - -Perl 5's unary C<undef> function is renamed C<undefine> to avoid -confusion with the value C<undef> (which is always 0-ary now). - -=item VAR - -This is not really a method, but some kind of macro. See L<S12> 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. - - -