diff --git a/.mailmap b/.mailmap index d74f50d4c0..22d07576c4 100644 --- a/.mailmap +++ b/.mailmap @@ -156,6 +156,7 @@ Bah bah@longitude.com Barrie Slaymaker root Bart Kedryna Bart Kedryna bart@cg681574-a.adubn1.nj.home.com +Bartosz Jarzyna bbrtj Beau Cox beau@beaucox.com Ben Carter Benjamin Carter Ben Morrow mauzo@csv.warwick.ac.uk diff --git a/AUTHORS b/AUTHORS index fbb7dfa18e..4fe8393178 100644 --- a/AUTHORS +++ b/AUTHORS @@ -155,6 +155,7 @@ Barrie Slaymaker Barry Friedman Bart Kedryna Bart Van Assche +Bartosz Jarzyna Bas van Sisseren Beau Cox Ben Carter diff --git a/pod/perlclass.pod b/pod/perlclass.pod index 412237de37..b990f665c4 100644 --- a/pod/perlclass.pod +++ b/pod/perlclass.pod @@ -1,79 +1,218 @@ =head1 NAME -perlclass - Perl class syntax +perlclass - Perl class syntax reference -=head1 DESCRIPTION +=head1 SYNOPSIS use v5.36; use feature 'class'; class My::Example 1.234 { field $x; - ADJUST { $x = "Hello, world"; } - method print_message { say $x; } + ADJUST { + $x = "Hello, world"; + } + + method print_message { + say $x; + } } My::Example->new->print_message; -C is like C. Classes automatically get a C method; you -don't have to (and should not) write one. +=head1 DESCRIPTION -C is like C but automatically gains a C<$self> lexical. +This document describes the syntax of the Perl's C feature, which +provides native keywords supporting object-oriented programming paradigm. -C blocks run during construction and are the way to add code that runs -during the construction time of each instance. They also have a C<$self> -lexical. +=head2 History -C is like C but only visible within C and C -blocks. +Since Perl 5, support for objects resolved around the concept of I +references with a package name. Such reference could then be used to call +subroutines from the package it was blessed with (or any of its parents). This +system, while bare-bones, was flexible enough to allow creation of multiple +more advanced, community-driven systems for object orientation. -Instances get their own value storage for fields +Class feature is a core implementation of class syntax which is familiar to +what one would find in other programming languages. It isn't a C +wrapper, but a completely new system built right into the perl interpreter. - class My::Counter { - field $count; ADJUST { $count = 0; } +=head1 KEYWORDS - method incr { $count++ } - method val { return $count; } +Enabling the C feature allows the usage of the following new keywords in +the scope of current package: + +=head2 class + + class NAME BLOCK + + class NAME VERSION BLOCK + + class NAME; + + class NAME VERSION; + +The C keyword declares a new package which is intended to be a class. +All other keywords from the C feature should be used in scope of this +declaration. + + class WithVersion 1.000 { + # class definition goes here } - my $ca = My::Counter->new; - $ca->incr; $ca->incr; $ca->incr; +Classes can be declared in either block or statement syntax. If a block is +used, the body of the block contains the implementation of the class. If the +statement form is used, the remainder of the file is used up until the next +C or C statement. - my $cb = My::Counter->new; - $cb->incr; +C and C declarations are similar, but classes automatically get +a constructor named C - You don't have to (and should not) write one. +Additionally, in the class BLOCK you are allowed to declare fields and methods. - say "Counter A is at ", $ca->val; - say "Counter B is at ", $cb->val; +=head2 field -C always act as if C is in effect. You do -not need to worry about the C<$self> lexical: it is automatically created and -populated with the object instance, which will not appear in the arguments -list as far as the signature is concerned. + field VARIABLE_NAME; - class Example::WithSignatures { - method greet($name = "someone") { - say "Hello, $name"; +Fields are variables which are visible in the scope of the class - more +specifically within L and C blocks. Each class instance get +their own storage of fields, independent of each other. + +A field behaves like a normal lexically scoped variable. It has a sigil and is +private to the class (though creation of an accessor method will make it +accessible from the outside). The main difference is that different instances +access different values in the same scope. + + class WithFields { + field $scalar; + field @array; + field %hash; + + ADJUST { + $scalar = 42; + @array = qw(this is just an array); + %hash = (species => 'Marsian', planet => 'Mars'); } } +=head2 method + + method METHOD_NAME SIGNATURE BLOCK + + method METHOD_NAME BLOCK + + method SIGNATURE BLOCK + + method BLOCK + +Methods are subroutines intended to be called in the context of class objects. + +A variable named C<$self> populated with the current object instance will +automatically be created in the lexical scope of C. + +Methods always act as if C is in effect, but C<$self> +will not appear in the arguments list as far as the signature is concerned. + + class WithMethods { + field $greetings; + + ADJUST { + $greetings = "Hello"; + } + + method greet($name = "someone") { + say "$greetings, $name"; + } + } + +Just like regular subroutines, methods I be anonymous: + + class AnonMethodFactory { + + method get_anon_method { + return method { + return 'this is an anonymous method'; + }; + } + } + +=head1 ATTRIBUTES + +Specific aspects of the keywords mentioned above are managed using +I. Attributes all start with a colon, and one or more of them can +be appended after the item's name, separated by a space. + +=head2 Class attributes + +=head3 :isa + Classes may inherit from B superclass, by using the C<:isa> class attribute. - class Example::Base { ... } + class Example::Base { ... } - class Example::Subclass :isa(Example::Base) { ... } + class Example::Subclass :isa(Example::Base) { ... } Inherited methods are visible and may be invoked. Fields are always lexical -and therefore not visible by inheritence. +and therefore not visible by inheritance. The C<:isa> attribute may request a minimum version of the base class; it is -applied similar to C; if the provided version is too low it will fail at +applied similar to C - if the provided version is too low it will fail at compile time. - class Example::Subclass :isa(Example::Base 2.345) { ... } + class Example::Subclass :isa(Example::Base 2.345) { ... } The C<:isa> attribute will attempt to C the named module if it is not already loaded. +=head2 Field attributes + +None yet. + +=head2 Method attributes + +None yet. + +=head1 OBJECT LIFECYCLE + +=head2 Construction + +Each object begins its life with a constructor call. The constructor is always +named C and is invoked like a method call on the class name: + + my $object = My::Class->new(%arguments); + +During the construction, class fields are compared to C<%arguments> hash and +populated where possible. + +=head2 Adjustment + +Object adjustment can be performed during the construction to run user-defined +code. It is done with the help of C blocks, which are called in order +of declaration. + +They are similar to C blocks, which run during the compilation of a +package. However, they also have access to C<$self> lexical (object instance) +and all object fields created up to that point. + +=head2 Lifetime + +After the construction phase, object is ready to be used. + +Using C (C or C) on the +object will return the name of the class, while C +(C or C) will return the string +C<'OBJECT'>. + +=head2 Destruction + +Just like with other references, when object reference count reaches zero it +will automatically be destroyed. + +=head1 AUTHORS + +Paul Evans + +Bartosz Jarzyna + =cut