=over

=item our VARLIST
X<our> X<global>

=item our TYPE VARLIST

=item our VARLIST : ATTRS

=item our TYPE VARLIST : ATTRS

L<C<our>|/our VARLIST> makes a lexical alias to a package (i.e. global)
variable of the same name in the current package for use within the
current lexical scope.

L<C<our>|/our VARLIST> has the same scoping rules as
L<C<my>|/my VARLIST> or L<C<state>|/state VARLIST>, meaning that it is
only valid within a lexical scope.  Unlike L<C<my>|/my VARLIST> and
L<C<state>|/state VARLIST>, which both declare new (lexical) variables,
L<C<our>|/our VARLIST> only creates an alias to an existing variable: a
package variable of the same name.

This means that when C<use strict 'vars'> is in effect, L<C<our>|/our
VARLIST> lets you use a package variable without qualifying it with the
package name, but only within the lexical scope of the
L<C<our>|/our VARLIST> declaration.  This applies immediately--even
within the same statement.

    package Foo;
    use v5.36;  # which implies "use strict;"

    $Foo::foo = 23;

    {
        our $foo;   # alias to $Foo::foo
        print $foo; # prints 23
    }

    print $Foo::foo; # prints 23

    print $foo; # ERROR: requires explicit package name

This works even if the package variable has not been used before, as
package variables spring into existence when first used.

    package Foo;
    use v5.36;

    our $foo = 23;   # just like $Foo::foo = 23

    print $Foo::foo; # prints 23

Because the variable becomes legal immediately under C<use strict 'vars'>, so
long as there is no variable with that name already in scope, you can then
reference the package variable again even within the same statement.

    package Foo;
    use v5.36;

    my  $foo = $foo; # error, undeclared $foo on right-hand side
    our $foo = $foo; # no errors

If more than one variable is listed, the list must be placed
in parentheses.

    our($bar, $baz);

Like L<C<my>|/my VARLIST>, L<C<state>|/state VARLIST>, and
L<C<local>|/local EXPR>, L<C<our>|/our VARLIST> can operate on a variable
anywhere it appears in an expression (aside from interpolation in strings).
The declaration will not apply to additional uses of the same variable until
the next statement. This means additional uses of that variable within the
same statement will act as they would have before that declaration occurred,
with the exception that it will still satisfy strict 'vars' and interpret that
variable as the newly aliased package variable if it was not yet declared in
that scope.

    package main;
    my $x = 2;
    foo($x, our $x = $x + 1, $x); # foo() receives (2, 3, 2)
    foo($x, our $z = 5, $z);      # foo() receives (3, 5, 5)

An L<C<our>|/our VARLIST> declaration declares an alias for a package
variable that will be visible
across its entire lexical scope, even across package boundaries.  The
package in which the variable is entered is determined at the point
of the declaration, not at the point of use.  This means the following
behavior holds:

    package Foo;
    our $bar;      # declares $Foo::bar for rest of lexical scope
    $bar = 20;

    package Bar;
    print $bar;    # prints 20, as it refers to $Foo::bar

Multiple L<C<our>|/our VARLIST> declarations with the same name in the
same lexical
scope are allowed if they are in different packages.  If they happen
to be in the same package, Perl will emit warnings if you have asked
for them, just like multiple L<C<my>|/my VARLIST> declarations.  Unlike
a second L<C<my>|/my VARLIST> declaration, which will bind the name to a
fresh variable, a second L<C<our>|/our VARLIST> declaration in the same
package, in the same scope, is merely redundant.

    use warnings;
    package Foo;
    our $bar;      # declares $Foo::bar for rest of lexical scope
    $bar = 20;

    package Bar;
    our $bar = 30; # declares $Bar::bar for rest of lexical scope
    print $bar;    # prints 30

    our $bar;      # emits warning but has no other effect
    print $bar;    # still prints 30

An L<C<our>|/our VARLIST> declaration may also have a list of attributes
associated with it.

The exact semantics and interface of TYPE and ATTRS are still
evolving.  TYPE is currently bound to the use of the L<fields> pragma,
and attributes are handled using the L<attributes> pragma, or, starting
from Perl 5.8.0, also via the L<Attribute::Handlers> module.  See
L<perlsub/"Private Variables via my()"> for details.

Note that with a parenthesised list, L<C<undef>|/undef EXPR> can be used
as a dummy placeholder, for example to skip assignment of initial
values:

    our ( undef, $min, $hour ) = localtime;

L<C<our>|/our VARLIST> creates a lexically scoped alias to the package
variable of the same name, and as such differs from L<C<use vars>|vars>,
which allows use of an unqualified name I<only> within the affected
package, without consideration for scopes.

=back