.\" -*- 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 "Object::Pad::FieldAttr::LazyInit 3pm"
.TH Object::Pad::FieldAttr::LazyInit 3pm 2024-03-07 "perl v5.38.2" "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
"Object::Pad::FieldAttr::LazyInit" \- lazily initialise "Object::Pad" fields at first read
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&   use Object::Pad;
\&   use Object::Pad::FieldAttr::LazyInit;
\&
\&   class Item {
\&      field $uuid :reader :param :LazyInit(_make_uuid);
\&
\&      method _make_uuid {
\&         require Data::GUID;
\&         return Data::GUID\->new\->as_string;
\&      }
\&   }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides a third-party field attribute for Object::Pad\-based
classes, which declares that the field it is attached to has a lazy
initialisation method, which will be called the first time the field's value
is read from.
.PP
\&\fBWARNING\fR The ability for Object::Pad to take third-party field attributes
is still new and highly experimental, and subject to much API change in
future. As a result, this module should be considered equally experimental.
.SH "FIELD ATTRIBUTES"
.IX Header "FIELD ATTRIBUTES"
.SS :LazyInit
.IX Subsection ":LazyInit"
.Vb 1
\&   field $name :LazyInit(NAME) ...;
.Ve
.PP
Declares that if the field variable is read from before it has been otherwise
initialised, then the named method will be called first to create an initial
value for it. Initialisation by either by a \f(CW\*(C`:param\*(C'\fR declaration, explicit
assignment into it, or the use of a \f(CW\*(C`:writer\*(C'\fR accessor will set the value for
the field and mean the lazy initialiser will not be invoked.
.PP
After it has been invoked, the value is stored by the field and thereafter it
will behave as normal; subsequent reads will return the current value, and the
initialiser method will not be invoked again.
.PP
In order to avoid the possibility of accidental recursion when generating the
value, it is recommended that the logic in the lazy initialisation method be
as self-contained as possible; ideally not invoking any methods on \f(CW$self\fR,
and only making use of other fields already declared before the field being
initialised. By placing the initialiser method immediately after the field
declaration, before any other fields, you can reduce the possibility of
getting stuck in such a manner.
.PP
.Vb 1
\&   field $field_zero :param;
\&
\&   field $field_one :LazyInit(_make_one);
\&   method _make_one {
\&      # we can safely use $field_zero in here
\&   }
\&
\&   field $field_two :LazyInit(_make_two);
\&   method _make_two {
\&      # we can safely use $field_zero and $field_one
\&   }
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>