path: root/upstream/debian-unstable/man1/perlclass.1

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PERLCLASS 1"
.TH PERLCLASS 1 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
perlclass \- Perl class syntax reference
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    use v5.38;
\&    use feature \*(Aqclass\*(Aq;
\&
\&    class My::Example 1.234 {
\&        field $x;
\&
\&        ADJUST {
\&            $x = "Hello, world";
\&        }
\&
\&        method print_message {
\&            say $x;
\&        }
\&    }
\&
\&    My::Example\->new\->print_message;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This document describes the syntax of the Perl's \f(CW\*(C`class\*(C'\fR feature, which
provides native keywords supporting object-oriented programming paradigm.
.SS History
.IX Subsection "History"
Since Perl 5, support for objects revolved around the concept of \fIblessing\fR
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.
.PP
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 \f(CW\*(C`bless\*(C'\fR
wrapper, but a completely new system built right into the perl interpreter.
.SH KEYWORDS
.IX Header "KEYWORDS"
Enabling the \f(CW\*(C`class\*(C'\fR feature allows the usage of the following new keywords in
the scope of current package:
.SS class
.IX Subsection "class"
.Vb 1
\&    class NAME BLOCK
\&
\&    class NAME VERSION BLOCK
\&
\&    class NAME;
\&
\&    class NAME VERSION;
.Ve
.PP
The \f(CW\*(C`class\*(C'\fR keyword declares a new package which is intended to be a class.
All other keywords from the \f(CW\*(C`class\*(C'\fR feature should be used in scope of this
declaration.
.PP
.Vb 3
\&    class WithVersion 1.000 {
\&        # class definition goes here
\&    }
.Ve
.PP
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
\&\f(CW\*(C`class\*(C'\fR or \f(CW\*(C`package\*(C'\fR statement.
.PP
\&\f(CW\*(C`class\*(C'\fR and \f(CW\*(C`package\*(C'\fR declarations are similar, but classes automatically get
a constructor named \f(CW\*(C`new\*(C'\fR \- You don't have to (and should not) write one.
Additionally, in the class BLOCK you are allowed to declare fields and methods.
.SS field
.IX Subsection "field"
.Vb 1
\&    field VARIABLE_NAME;
\&
\&    field VARIABLE_NAME = EXPR;
\&
\&    field VARIABLE_NAME : ATTRIBUTES;
\&
\&    field VARIABLE_NAME : ATTRIBUTES = EXPR;
.Ve
.PP
Fields are variables which are visible in the scope of the class \- more
specifically within "method" and \f(CW\*(C`ADJUST\*(C'\fR blocks. Each class instance get
their own storage of fields, independent of each other.
.PP
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.
.PP
.Vb 5
\&    class WithFields {
\&        field $scalar = 42;
\&        field @array  = qw(this is just an array);
\&        field %hash   = (species => \*(AqMartian\*(Aq, planet => \*(AqMars\*(Aq);
\&    }
.Ve
.PP
Fields may optionally have initializing expressions. If present, the expression
will be evaluated within the constructor of each object instance. During each
evaluation, the expression can use the value of any previously-set field, as
well as see any other variables in scope.
.PP
.Vb 4
\&    class WithACounter {
\&        my $next_count = 1;
\&        field $count = $next_count++;
\&    }
.Ve
.PP
When combined with the \f(CW\*(C`:param\*(C'\fR field attribute, the defaulting expression can
use any of the \f(CW\*(C`=\*(C'\fR, \f(CW\*(C`//=\*(C'\fR or \f(CW\*(C`||=\*(C'\fR operators. Expressions using \f(CW\*(C`=\*(C'\fR will
apply whenever the caller did not pass the corresponding parameter to the
constructor at all. Expressions using \f(CW\*(C`//=\*(C'\fR will also apply if the caller did
pass the parameter but the value was undefined, and expressions using \f(CW\*(C`||=\*(C'\fR
will apply if the value was false.
.SS method
.IX Subsection "method"
.Vb 1
\&    method METHOD_NAME SIGNATURE BLOCK
\&
\&    method METHOD_NAME BLOCK
\&
\&    method SIGNATURE BLOCK
\&
\&    method BLOCK
.Ve
.PP
Methods are subroutines intended to be called in the context of class objects.
.PP
A variable named \f(CW$self\fR populated with the current object instance will
automatically be created in the lexical scope of \f(CW\*(C`method\*(C'\fR.
.PP
Methods always act as if \f(CW\*(C`use feature \*(Aqsignatures\*(Aq\*(C'\fR is in effect, but \f(CW$self\fR
will not appear in the arguments list as far as the signature is concerned.
.PP
.Vb 2
\&    class WithMethods {
\&        field $greetings;
\&
\&        ADJUST {
\&            $greetings = "Hello";
\&        }
\&
\&        method greet($name = "someone") {
\&            say "$greetings, $name";
\&        }
\&    }
.Ve
.PP
Just like regular subroutines, methods \fIcan\fR be anonymous:
.PP
.Vb 1
\&    class AnonMethodFactory {
\&
\&        method get_anon_method {
\&            return method {
\&                return \*(Aqthis is an anonymous method\*(Aq;
\&            };
\&        }
\&    }
.Ve
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
Specific aspects of the keywords mentioned above are managed using
\&\fIattributes\fR. Attributes all start with a colon, and one or more of them can
be appended after the item's name, separated by a space.
.SS "Class attributes"
.IX Subsection "Class attributes"
\fI:isa\fR
.IX Subsection ":isa"
.PP
Classes may inherit from \fBone\fR superclass, by using the \f(CW\*(C`:isa\*(C'\fR class
attribute.
.PP
.Vb 1
\&    class Example::Base { ... }
\&
\&    class Example::Subclass :isa(Example::Base) { ... }
.Ve
.PP
Inherited methods are visible and may be invoked. Fields are always lexical
and therefore not visible by inheritance.
.PP
The \f(CW\*(C`:isa\*(C'\fR attribute may request a minimum version of the base class; it is
applied similar to \f(CW\*(C`use\*(C'\fR \- if the provided version is too low it will fail at
compile time.
.PP
.Vb 1
\&    class Example::Subclass :isa(Example::Base 2.345) { ... }
.Ve
.PP
The \f(CW\*(C`:isa\*(C'\fR attribute will attempt to \f(CW\*(C`require\*(C'\fR the named module if it is not
already loaded.
.SS "Field attributes"
.IX Subsection "Field attributes"
\fI:param\fR
.IX Subsection ":param"
.PP
A scalar field with a \f(CW\*(C`:param\*(C'\fR attribute will take its value from a named
parameter passed to the constructor. By default the parameter will have the
same name as the field (minus its leading \f(CW\*(C`$\*(C'\fR sigil), but a different name
can be specified in the attribute.
.PP
.Vb 2
\&    field $x :param;
\&    field $y :param(the_y_value);
.Ve
.PP
If there is no defaulting expression then the parameter is required by the
constructor; the caller must pass it or an exception is thrown. With a
defaulting expression this becomes optional.
.SS "Method attributes"
.IX Subsection "Method attributes"
None yet.
.SH "OBJECT LIFECYCLE"
.IX Header "OBJECT LIFECYCLE"
.SS Construction
.IX Subsection "Construction"
Each object begins its life with a constructor call. The constructor is always
named \f(CW\*(C`new\*(C'\fR and is invoked like a method call on the class name:
.PP
.Vb 1
\&    my $object = My::Class\->new(%arguments);
.Ve
.PP
During the construction, class fields are compared to \f(CW%arguments\fR hash and
populated where possible.
.SS Adjustment
.IX Subsection "Adjustment"
Object adjustment can be performed during the construction to run user-defined
code. It is done with the help of \f(CW\*(C`ADJUST\*(C'\fR blocks, which are called in order
of declaration.
.PP
They are similar to \f(CW\*(C`BEGIN\*(C'\fR blocks, which run during the compilation of a
package. However, they also have access to \f(CW$self\fR lexical (object instance)
and all object fields created up to that point.
.SS Lifetime
.IX Subsection "Lifetime"
After the construction phase, object is ready to be used.
.PP
Using \f(CW\*(C`blessed\*(C'\fR (\f(CW\*(C`Scalar::Util::blessed\*(C'\fR or \f(CW\*(C`builtin::blessed\*(C'\fR) on the
object will return the name of the class, while \f(CW\*(C`reftype\*(C'\fR
(\f(CW\*(C`Scalar::Util::reftype\*(C'\fR or \f(CW\*(C`builtin::reftype\*(C'\fR) will return the string
\&\f(CW\*(AqOBJECT\*(Aq\fR.
.SS Destruction
.IX Subsection "Destruction"
Just like with other references, when object reference count reaches zero it
will automatically be destroyed.
.SH TODO
.IX Header "TODO"
This feature is still experimental and very incomplete. The following list
gives some overview of the kinds of work still to be added or changed:
.IP \(bu 4
Roles
.Sp
Some syntax for declaring a role (likely a \f(CW\*(C`role\*(C'\fR keyword), and for consuming
a role into a class (likely a \f(CW:does()\fR attribute).
.IP \(bu 4
Parameters to ADJUST blocks
.Sp
Some syntax for declaring that an \f(CW\*(C`ADJUST\*(C'\fR block can consume named
parameters, which become part of the class constructor's API. This might be
inspired by a similar plan to add named arguments to subroutine signatures.
.Sp
.Vb 5
\&    class X {
\&        ADJUST (:$alpha, :$beta = 123) {
\&           ...
\&        }
\&    }
\&
\&    my $obj = X\->new(alpha => 456);
.Ve
.IP \(bu 4
ADJUST blocks as true blocks
.Sp
Currently, every ADJUST block is wrapped in its own CV that gets invoked with
the full ENTERSUB overhead. It should be possible to use the same mechanism
that makes all field initializer expressions appear within the same CV on
ADJUST blocks as well, merging them all into a single CV per class. This will
make it faster to invoke if a class has more than one of them.
.IP \(bu 4
Accessor generator attributes
.Sp
Attributes to request that accessor methods be generated for fields. Likely
\&\f(CW\*(C`:reader\*(C'\fR and \f(CW\*(C`:writer\*(C'\fR.
.Sp
.Vb 3
\&    class X {
\&        field $name :reader;
\&    }
.Ve
.Sp
Equivalent to
.Sp
.Vb 4
\&    class X {
\&        field $name;
\&        method name { return $name; }
\&    }
.Ve
.IP \(bu 4
Metaprogramming
.Sp
An extension of the metaprogramming API (currently proposed by
RFC0022 <https://github.com/Perl/RFCs/pull/25>) which adds knowledge of
classes, methods, fields, ADJUST blocks, and other such class-related details.
.IP \(bu 4
Extension Customisation
.Sp
Ways in which out-of-core modules can interact with the class system,
including an ability for them to provide new class or field attributes.
.SH AUTHORS
.IX Header "AUTHORS"
Paul Evans
.PP
Bartosz Jarzyna