.\" -*- 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 "true 3pm"
.TH true 3pm 2024-01-11 "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
true \- automatically return a true value when a file is required
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  package Contemporary::Perl;
\&
\&  use strict;
\&  use warnings;
\&  use true;
\&
\&  sub import {
\&      strict\->import();
\&      warnings\->import();
\&      true\->import();
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Perl's \f(CW\*(C`require\*(C'\fR builtin (and its \f(CW\*(C`use\*(C'\fR wrapper) requires the files it loads
to return a true value. This is usually accomplished by placing a single
.PP
.Vb 1
\&    1;
.Ve
.PP
statement at the end of included scripts or modules. It's not onerous to add
but it's a speed bump on the Perl novice's road to enlightenment. In addition,
it appears to be a \fInon-sequitur\fR to the uninitiated, leading some to attempt
to mitigate its appearance with a comment:
.PP
.Vb 1
\&    1; # keep require happy
.Ve
.PP
or:
.PP
.Vb 1
\&    1; # Do not remove this line
.Ve
.PP
or even:
.PP
.Vb 1
\&    1; # Must end with this, because Perl is bogus.
.Ve
.PP
This module packages this "return true" behaviour so that it doesn't need to be
written explicitly. It can be used directly, but it is intended to be invoked
from the \f(CW\*(C`import\*(C'\fR method of a Modern::Perl\-style module that
enables modern Perl features and conveniences and cleans up legacy Perl warts.
.SS METHODS
.IX Subsection "METHODS"
\&\f(CW\*(C`true\*(C'\fR is file-scoped rather than lexically-scoped. Importing it anywhere in a
file (e.g. at the top-level or in a nested scope) causes that file to return true,
and unimporting it anywhere in a file restores the default behaviour. Redundant
imports/unimports are ignored.
.PP
\fIimport\fR
.IX Subsection "import"
.PP
Enable the "automatically return true" behaviour for the currently-compiling
file. This should typically be invoked from the \f(CW\*(C`import\*(C'\fR method of a module
that loads \f(CW\*(C`true\*(C'\fR. Code that uses this module solely on behalf of its callers
can load \f(CW\*(C`true\*(C'\fR without importing it e.g.
.PP
.Vb 1
\&    use true (); # don\*(Aqt import
\&
\&    sub import {
\&        true\->import();
\&    }
\&
\&    1;
.Ve
.PP
But there's nothing stopping a wrapper module also importing \f(CW\*(C`true\*(C'\fR to obviate
its own need to explicitly return a true value:
.PP
.Vb 1
\&    use true; # both load and import it
\&
\&    sub import {
\&        true\->import();
\&    }
\&
\&    # no need to return true
.Ve
.PP
\fIunimport\fR
.IX Subsection "unimport"
.PP
Disable the "automatically return true" behaviour for the currently-compiling file.
.SS EXPORTS
.IX Subsection "EXPORTS"
None by default.
.SH NOTES
.IX Header "NOTES"
Because the unquoted name \f(CW\*(C`true\*(C'\fR represents the boolean value \f(CW\*(C`true\*(C'\fR in YAML,
the module name must be quoted when written as a dependency in META.yml. In cases
where this can't easily be done, a dependency can be declared on the package
true::VERSION, which has the same version as \f(CW\*(C`true.pm\*(C'\fR.
.SH VERSION
.IX Header "VERSION"
1.0.2
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
latest
.IP \(bu 4
Modern::Perl
.IP \(bu 4
nonsense
.IP \(bu 4
perl5i
.IP \(bu 4
Toolkit
.SH AUTHOR
.IX Header "AUTHOR"
chocolateboy <chocolate@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2010\-2020 by chocolateboy.
.PP
This library is free software; you can redistribute it and/or modify it under the
terms of the Artistic License 2.0 <https://www.opensource.org/licenses/artistic-license-2.0.php>.