To declare subroutines:
- sub NAME; # A "forward" declaration.
- sub NAME(PROTO); # ditto, but with prototypes
+ sub NAME; # A "forward" declaration.
+ sub NAME(PROTO); # ditto, but with prototypes
+ sub NAME : ATTRS; # with attributes
+ sub NAME(PROTO) : ATTRS; # with attributes and prototypes
- sub NAME BLOCK # A declaration and a definition.
- sub NAME(PROTO) BLOCK # ditto, but with prototypes
+ sub NAME BLOCK # A declaration and a definition.
+ sub NAME(PROTO) BLOCK # ditto, but with prototypes
+ sub NAME : ATTRS BLOCK # with attributes
+ sub NAME(PROTO) : ATTRS BLOCK # with prototypes and attributes
To define an anonymous subroutine at runtime:
- $subref = sub BLOCK; # no proto
- $subref = sub (PROTO) BLOCK; # with proto
+ $subref = sub BLOCK; # no proto
+ $subref = sub (PROTO) BLOCK; # with proto
+ $subref = sub : ATTRS BLOCK; # with attributes
+ $subref = sub (PROTO) : ATTRS BLOCK; # with proto and attributes
To import subroutines:
...
}
-Asisng to a list of private variables to name your arguments:
+Assigning to a list of private variables to name your arguments:
sub maybeset {
my($key, $value) = @_;
}
Notice how this (unprototyped) function doesn't care whether it was
-passed real scalars or arrays. Perl sees all arugments as one big,
+passed real scalars or arrays. Perl sees all arguments as one big,
long, flat parameter list in C<@_>. This is one area where
Perl's simple argument-passing style shines. The C<upcase()>
function would work perfectly well without changing the C<upcase()>
an argument to defined() or undef(). Nor is it optional when you
want to do an indirect subroutine call with a subroutine name or
reference using the C<&$subref()> or C<&{$subref}()> constructs,
-although the C<$subref-E<gt>()> notation solves that problem.
+although the C<< $subref->() >> notation solves that problem.
See L<perlref> for more about all that.
Subroutines may be called recursively. If a subroutine is called
is partly for historical reasons, and partly for having a convenient way
to cheat if you know what you're doing. See L<Prototypes> below.
-Function whose names are in all upper case are reserved to the Perl
+Functions whose names are in all upper case are reserved to the Perl
core, as are modules whose names are in all lower case. A
function in all capitals is a loosely-held convention meaning it
will be called indirectly by the run-time system itself, usually
due to a triggered event. Functions that do special, pre-defined
-things include C<BEGIN>, C<END>, C<AUTOLOAD>, and C<DESTROY>--plus
-all functions mentioned in L<perltie>. The 5.005 release adds
-C<INIT> to this list.
+things include C<BEGIN>, C<CHECK>, C<INIT>, C<END>, C<AUTOLOAD>, and
+C<DESTROY>--plus all functions mentioned in L<perltie>.
=head2 Private Variables via my()
my (@wid, %get); # declare list of variables local
my $foo = "flurp"; # declare $foo lexical, and init it
my @oof = @bar; # declare @oof lexical, and init it
+ my $x : Foo = $y; # similar, with an attribute applied
+
+B<WARNING>: The use of attribute lists on C<my> declarations is
+experimental. This feature should not be relied upon. It may
+change or disappear in future releases of Perl. See L<attributes>.
The C<my> operator declares the listed variables to be lexically
confined to the enclosing block, conditional (C<if/unless/elsif/else>),
or C<do/require/use>'d file. If more than one value is listed, the
list must be placed in parentheses. All listed elements must be
legal lvalues. Only alphanumeric identifiers may be lexically
-scoped--magical built-in like C<$/> must currently be C<local>ize
+scoped--magical built-ins like C<$/> must currently be C<local>ize
with C<local> instead.
Unlike dynamic variables created by the C<local> operator, lexical
then any variable mentioned from there to the end of the enclosing
block must either refer to a lexical variable, be predeclared via
-C<use vars>, or else must be fully qualified with the package name.
+C<our> or C<use vars>, or else must be fully qualified with the package name.
A compilation error results otherwise. An inner block may countermand
this with C<no strict 'vars'>.
}
See L<perlmod/"Package Constructors and Destructors"> about the
-special triggered functions, C<BEGIN> and C<INIT>.
+special triggered functions, C<BEGIN>, C<CHECK>, C<INIT> and C<END>.
If declared at the outermost scope (the file scope), then lexicals
work somewhat like C's file statics. They are available to all
The behavior of local() on non-existent members of composite
types is subject to change in future.
+=head2 Lvalue subroutines
+
+B<WARNING>: Lvalue subroutines are still experimental and the implementation
+may change in future versions of Perl.
+
+It is possible to return a modifiable value from a subroutine.
+To do this, you have to declare the subroutine to return an lvalue.
+
+ my $val;
+ sub canmod : lvalue {
+ $val;
+ }
+ sub nomod {
+ $val;
+ }
+
+ canmod() = 5; # assigns to $val
+ nomod() = 5; # ERROR
+
+The scalar/list context for the subroutine and for the right-hand
+side of assignment is determined as if the subroutine call is replaced
+by a scalar. For example, consider:
+
+ data(2,3) = get_data(3,4);
+
+Both subroutines here are called in a scalar context, while in:
+
+ (data(2,3)) = get_data(3,4);
+
+and in:
+
+ (data(2),data(3)) = get_data(3,4);
+
+all the subroutines are called in a list context.
+
+The current implementation does not allow arrays and hashes to be
+returned from lvalue subroutines directly. You may return a
+reference instead. This restriction may be lifted in future.
+
=head2 Passing Symbol Table Entries (typeglobs)
B<WARNING>: The mechanism described in this section was originally
=item 2. You need to create a local file or directory handle or a local function.
-A function that needs a filehandle of its own must use C<local()> uses
-C<local()> on complete typeglob. This can be used to create new symbol
+A function that needs a filehandle of its own must use
+C<local()> on a complete typeglob. This can be used to create new symbol
table entries:
sub ioqueue {
Here we're using the typeglobs to do symbol table aliasing. It's
a tad subtle, though, and also won't work if you're using C<my>
-variables, because only globals (even in disguised as C<local>s)
+variables, because only globals (even in disguise as C<local>s)
are in the symbol table.
If you're passing around filehandles, you could usually just use the bare
subroutine, then it behaves like an old-fashioned subroutine. It
naturally falls out from this rule that prototypes have no influence
on subroutine references like C<\&foo> or on indirect subroutine
-calls like C<&{$subref}> or C<$subref-E<gt>()>.
+calls like C<&{$subref}> or C<< $subref->() >>.
Method calls are not influenced by prototypes either, because the
function to be called is indeterminate at compile time, since
unbackslashed C<@> or C<%> eats all remaining arguments, and forces
list context. An argument represented by C<$> forces scalar context. An
C<&> requires an anonymous subroutine, which, if passed as the first
-argument, does not require the C<sub> keyword or a subsequent comma. A
-C<*> allows the subroutine to accept a bareword, constant, scalar expression,
+argument, does not require the C<sub> keyword or a subsequent comma.
+
+A C<*> allows the subroutine to accept a bareword, constant, scalar expression,
typeglob, or a reference to a typeglob in that slot. The value will be
available to the subroutine either as a simple scalar, or (in the latter
-two cases) as a reference to the typeglob.
+two cases) as a reference to the typeglob. If you wish to always convert
+such arguments to a typeglob reference, use Symbol::qualify_to_ref() as
+follows:
+
+ use Symbol 'qualify_to_ref';
+
+ sub foo (*) {
+ my $fh = qualify_to_ref(shift, caller);
+ ...
+ }
A semicolon separates mandatory arguments from optional arguments.
It is redundant before C<@> or C<%>, which gobble up everything else.
saying C<CORE::open()> always refers to the built-in C<open()>, even
if the current package has imported some other subroutine called
C<&open()> from elsewhere. Even though it looks like a regular
-function calls, it isn't: you can't take a reference to it, such as
+function call, it isn't: you can't take a reference to it, such as
the incorrect C<\&CORE::open> might appear to produce.
Library modules should not in general export built-in names like C<open>
SelfLoader modules in L<SelfLoader>, and the document on adding C
functions to Perl code in L<perlxs>.
+=head2 Subroutine Attributes
+
+A subroutine declaration or definition may have a list of attributes
+associated with it. If such an attribute list is present, it is
+broken up at space or colon boundaries and treated as though a
+C<use attributes> had been seen. See L<attributes> for details
+about what attributes are currently supported.
+Unlike the limitation with the obsolescent C<use attrs>, the
+C<sub : ATTRLIST> syntax works to associate the attributes with
+a pre-declaration, and not just with a subroutine definition.
+
+The attributes must be valid as simple identifier names (without any
+punctuation other than the '_' character). They may have a parameter
+list appended, which is only checked for whether its parentheses ('(',')')
+nest properly.
+
+Examples of valid syntax (even though the attributes are unknown):
+
+ sub fnord (&\%) : switch(10,foo(7,3)) : expensive ;
+ sub plugh () : Ugly('\(") :Bad ;
+ sub xyzzy : _5x5 { ... }
+
+Examples of invalid syntax:
+
+ sub fnord : switch(10,foo() ; # ()-string not balanced
+ sub snoid : Ugly('(') ; # ()-string not balanced
+ sub xyzzy : 5x5 ; # "5x5" not a valid identifier
+ sub plugh : Y2::north ; # "Y2::north" not a simple identifier
+ sub snurt : foo + bar ; # "+" not a colon or space
+
+The attribute list is passed as a list of constant strings to the code
+which associates them with the subroutine. In particular, the second example
+of valid syntax above currently looks like this in terms of how it's
+parsed and invoked:
+
+ use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad';
+
+For further details on attribute lists and their manipulation,
+see L<attributes>.
+
=head1 SEE ALSO
See L<perlref/"Function Templates"> for more about references and closures.
See L<perlxs> if you'd like to learn about calling C subroutines from Perl.
-See L<perlembed> if you'd like to learn about calling PErl subroutines from C.
+See L<perlembed> if you'd like to learn about calling Perl subroutines from C.
See L<perlmod> to learn about bundling up your functions in separate files.
See L<perlmodlib> to learn what library modules come standard on your system.
See L<perltoot> to learn how to make object method calls.