.\" Automatically generated by Pod::Man 4.14 (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
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Feature::Compat::Class 3pm"
.TH Feature::Compat::Class 3pm "2023-01-13" "perl v5.36.0" "User Contributed Perl Documentation"
.\" 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"
"Feature::Compat::Class" \- make "class" syntax available
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Feature::Compat::Class;
\&
\& class Point {
\& field $x :param = 0;
\& field $y :param = 0;
\&
\& method move_to ($new_x, $new_y) {
\& $x = $new_x;
\& $y = $new_y;
\& }
\&
\& method describe {
\& say "A point at ($x, $y)";
\& }
\& }
\&
\& Point\->new(x => 5, y => 10)\->describe;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides the new \f(CW\*(C`class\*(C'\fR keyword and related others (\f(CW\*(C`method\*(C'\fR,
\&\f(CW\*(C`field\*(C'\fR and \f(CW\*(C`ADJUST\*(C'\fR) in a forward-compatible way.
.PP
There is a branch of Perl development source code which provides this syntax,
under the \f(CW\*(C`class\*(C'\fR named feature. If all goes well, this will become available
in a stable release in due course. On such perls that contain the feature,
this module simple enables it.
.PP
On older versions of perl before such syntax is availble in core, it is
currently provided instead using the Object::Pad module, imported with a
special set of options to configure it to only recognise the same syntax as
the core perl feature, thus ensuring any code using it will still continue to
function on that newer perl.
.ie n .SS "Perl Branch with ""feature \*(Aqclass\*(Aq"""
.el .SS "Perl Branch with \f(CWfeature \*(Aqclass\*(Aq\fP"
.IX Subsection "Perl Branch with feature class"
At time of writing, the \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR syntax is not part of mainline
perl source but is available in a branch. That branch currently resides at
. It is intended this
will be migrated to the main \f(CW\*(C`perl\*(C'\fR repository ahead of actually being merged
once development has progressed further.
.PP
This module is a work-in-progress, because the underlying \f(CW\*(C`feature\-class\*(C'\fR
branch is too. Many of the limitations and inabilities listed below are a
result of the early-access nature of this branch, and are expected to be
lifted as work progresses towards a more featureful and complete
implementation.
.SH "KEYWORDS"
.IX Header "KEYWORDS"
The keywords provided by this module offer a subset of the abilities of those
provided by \f(CW\*(C`Object::Pad\*(C'\fR, restricted to specifically only what is commonly
supported by the core syntax as well. In general, the reader should first
consult the documentation for the corresponding \f(CW\*(C`Object::Pad\*(C'\fR keyword, but
the following notes may be of interest:
.SS "class"
.IX Subsection "class"
.Vb 2
\& class NAME { ... }
\& class NAME VERSION { ... }
\&
\& class NAME; ...
\& class NAME VERSION; ...
.Ve
.PP
See also \*(L"class\*(R" in Object::Pad.
.PP
There is no ability to declare any roles with \f(CW\*(C`:does\*(C'\fR. The legacy subkeywords
for these are equally not supported.
.PP
The \f(CW\*(C`:repr\*(C'\fR attribute is also not supported; the default representation type
will always be selected.
.PP
The \f(CW\*(C`:strict(params)\*(C'\fR attribute is not available, but all constructed classes
will behave as if the attribute had been declared. Every generated constructor
will check its parameters for key names left unhandled by \f(CW\*(C`ADJUST\*(C'\fR blocks,
and throw an exception if any remain.
.PP
The following class attributes are supported:
.PP
\fI:isa\fR
.IX Subsection ":isa"
.PP
.Vb 1
\& :isa(CLASS)
\&
\& :isa(CLASS CLASSVER)
.Ve
.PP
\&\fISince version 0.02.\fR
.PP
Declares a superclass that this class extends. At most one superclass is
supported.
.PP
If the package providing the superclass does not exist, an attempt is made to
load it by code equivalent to
.PP
.Vb 1
\& require CLASS ();
.Ve
.PP
and thus it must either already exist, or be locatable via the usual \f(CW@INC\fR
mechanisms.
.PP
An optional version check can also be supplied; it performs the equivalent of
.PP
.Vb 1
\& BaseClass\->VERSION( $ver )
.Ve
.PP
Note that \f(CW\*(C`class\*(C'\fR blocks \fBdo not\fR implicitly enable the \f(CW\*(C`strict\*(C'\fR and
\&\f(CW\*(C`warnings\*(C'\fR pragmata; either when using the core feature or \f(CW\*(C`Object::Pad\*(C'\fR.
This is to avoid surprises when eventually switching to purely using the core
perl feature, which will not do that. Remember however that a \f(CW\*(C`use VERSION\*(C'\fR
of a version \f(CW\*(C`v5.36\*(C'\fR or above will enable both these pragmata anyway, so that
will be sufficient.
.SS "method"
.IX Subsection "method"
.Vb 2
\& method NAME { ... }
\& method NAME;
.Ve
.PP
See also \*(L"method\*(R" in Object::Pad.
.PP
Attributes are not supported, other than the usual ones provided by perl
itself. Of these, only \f(CW\*(C`:lvalue\*(C'\fR is particularly useful.
.PP
Lexical methods are not supported.
.SS "field"
.IX Subsection "field"
.Vb 3
\& field $NAME;
\& field @NAME;
\& field %NAME;
\&
\& field $NAME = EXPR;
\&
\& field $NAME :ATTRS... = EXPR;
.Ve
.PP
See also \*(L"field\*(R" in Object::Pad.
.PP
Most field attributes are not supported. In particular, rather than using the
accessor-generator attributes you will have to create accessor methods
yourself; such as
.PP
.Vb 3
\& field $var;
\& method var { return $var; }
\& method set_var ($new_var) { $var = $new_var; }
.Ve
.PP
\&\fISince version 0.04\fR fields of any type may take initialising expressions.
Initialiser blocks are not supported.
.PP
.Vb 1
\& field $five = 5;
.Ve
.PP
The following field attributes are supported:
.PP
\fI:param\fR
.IX Subsection ":param"
.PP
.Vb 1
\& field $var :param;
\&
\& field $var :param(name)
.Ve
.PP
\&\fISince version 0.04.\fR
.PP
Declares that the constructor will take a named parameter to set the value for
this field in a new instance.
.PP
.Vb 1
\& field $var :param = EXPR;
.Ve
.PP
Without a defaulting expression, the parameter is mandatory. When combined
with a defaulting expression, the parameter is optional and the default will
only apply if the named parameter was not passed to the constructor.
.PP
.Vb 2
\& field $var :param //= EXPR;
\& field $var :param ||= EXPR;
.Ve
.PP
With both the \f(CW\*(C`:param\*(C'\fR attribute and a defaulting expression, the operator
can also be written as \f(CW\*(C`//=\*(C'\fR or \f(CW\*(C`||=\*(C'\fR. In this case, the defaulting
expression will be used even if the caller passed an undefined value (for
\&\f(CW\*(C`//=\*(C'\fR) or a false value (for \f(CW\*(C`||=\*(C'\fR). This simplifies many situations where
\&\f(CW\*(C`undef\*(C'\fR would not be a valid value for a field parameter.
.PP
.Vb 3
\& class C {
\& field $timeout :param //= 20;
\& }
\&
\& C\->new( timeout => $args{timeout} );
\& # default applies if %args has no \*(Aqtimeout\*(Aq key, or if its value is undef
.Ve
.SS "\s-1ADJUST\s0"
.IX Subsection "ADJUST"
.Vb 1
\& ADJUST { ... }
.Ve
.PP
See also \*(L"\s-1ADJUST\*(R"\s0 in Object::Pad.
.PP
Attributes are not supported; in particular the \f(CW\*(C`:params\*(C'\fR attribute of
\&\f(CW\*(C`Object::Pad\*(C'\fR v0.70.
.SS "Other Keywords"
.IX Subsection "Other Keywords"
The following other keywords provided by \f(CW\*(C`Object::Pad\*(C'\fR are not supported here
at all:
.PP
.Vb 1
\& role
\&
\& BUILD, ADJUSTPARAMS
\&
\& has
\&
\& requires
.Ve
.SH "COMPATIBILITY NOTES"
.IX Header "COMPATIBILITY NOTES"
This module may use either Object::Pad or the perl core \f(CW\*(C`class\*(C'\fR feature to
implement its syntax. While the two behave very similarly and both conform to
the description given above, the following differences should be noted.
.IP "Fields in later field expressions" 4
.IX Item "Fields in later field expressions"
The core perl \f(CW\*(C`class\*(C'\fR feature makes every field variable visible to the
initialising expression of later fields. For example,
.Sp
.Vb 2
\& field $one = 1;
\& field $two = $one + 1;
.Ve
.Sp
This is not currently supported by \f(CW\*(C`Object::Pad\*(C'\fR. As a result, it is possible
to write code that works fine with the core perl feature but older perls
cannot support by using \f(CW\*(C`Object::Pad\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans