sub : attrlist

To: Mailing list Perl5 <perl5-porters@perl.org>
Message-Id: <199908290702.DAA32191@Orb.Nashua.NH.US>

p4raw-id: //depot/cfgperl@4043

5 files changed, 236 insertions, 27 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 0cb375a3e7..353c62d55f 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -193,7 +193,7 @@ extension (not included with the standard Perl distribution) may also
 be of use.
  
 (Large file support is also related to 64-bit support, for obvious reasons)
- 
+
 =head2 Better syntax checks on parenthesized unary operators
 
 Expressions such as:
@@ -269,9 +269,25 @@ As before, lexical variables may not have names beginning with control
 characters.  As before, variables whose names begin with a control
 character are always forced to be in package `main'.  All such variables
 are reserved for future extensions, except those that begin with
-C<^_>, which may be used by user programs and is guaranteed not to
+C<^_>, which may be used by user programs and are guaranteed not to
 acquire special meaning in any future version of Perl.
 
+=head2 C<use attrs> implicit in subroutine attributes
+
+Formerly, if you wanted to mark a subroutine as being a method call or
+as requiring an automatic lock() when it is entered, you had to declare
+that with a C<use attrs> pragma in the body of the subroutine.
+That can now be accomplished with a declaration syntax, like this:
+
+    sub mymethod : locked, method ;
+    ...
+    sub mymethod : locked, method {
+	...
+    }
+
+F<AutoSplit.pm> and F<SelfLoader.pm> have been updated to keep the attributes
+with the stubs they provide.  See L<attributes>.
+
 =head1 Significant bug fixes
 
 =head2 E<lt>HANDLEE<gt> on empty files
@@ -364,26 +380,34 @@ EPOC is is now supported (on Psion 5).
 
 =over 4
 
-=item	op/io_const
+=item	lib/attrs
+
+Compatibility tests for C<sub : attrs> vs the older C<use attrs>.
+
+=item	lib/io_const
 
 IO constants (SEEK_*, _IO*).
 
-=item	op/io_dir
+=item	lib/io_dir
 
 Directory-related IO methods (new, read, close, rewind, tied delete).
 
-=item	op/io_multihomed
+=item	lib/io_multihomed
 
 INET sockets with multi-homed hosts.
 
-=item	op/io_poll
+=item	lib/io_poll
 
 IO poll().
 
-=item	op/io_unix
+=item	lib/io_unix
 
 UNIX sockets.
 
+=item	op/attrs
+
+Regression tests for C<my ($x,@y,%z) : attrs> and <sub : attrs>.
+
 =item	op/filetest
 
 File test operators.
@@ -400,6 +424,12 @@ Verify operations that access pad objects (lexicals and temporaries).
 
 =over 4
 
+=item attributes
+
+While used internally by Perl as a pragma, this module also
+provides a way to fetch subroutine and variable attributes.
+See L<attributes>.
+
 =item ByteLoader
 
 The ByteLoader is a dedication extension to generate and run
@@ -540,6 +570,10 @@ See L<perldbmfilter> for further information.
 
 =head2 Pragmata
 
+C<use attrs> is now obsolescent, and is only provided for
+backward-compatibility.  It's been replaced by the C<sub : attributes>
+syntax.  See L<perlsub/"Subroutine Attributes"> and L<attributes>.
+
 C<use utf8> to enable UTF-8 and Unicode support.
 
 C<use caller 'encoding'> allows modules to inherit pragmatic attributes
@@ -579,6 +613,18 @@ A tutorial on managing class data for object modules.
 
 =head1 New Diagnostics
 
+=item "my sub" not yet implemented
+
+(F) Lexically scoped subroutines are not yet implemented.  Don't try that
+yet.
+
+=item %s package attribute may clash with future reserved word: %s
+
+(W) A lowercase attribute name was used that had a package-specific handler.
+That name might have a meaning to Perl itself some day, even though it
+doesn't yet.  Perhaps you should use a mixed-case attribute name, instead.
+See L<attributes>.
+
 =item /%s/: Unrecognized escape \\%c passed through
 
 (W) You used a backslash-character combination which is not recognized
@@ -593,16 +639,52 @@ intended it to be a read-write filehandle, you needed to open it with
 you intended only to read from the file, use "E<lt>".  See
 L<perlfunc/open>.
 
+=item Invalid %s attribute: %s
+
+The indicated attribute for a subroutine or variable was not recognized
+by Perl or by a user-supplied handler.  See L<attributes>.
+
+=item Invalid %s attributes: %s
+
+The indicated attributes for a subroutine or variable were not recognized
+by Perl or by a user-supplied handler.  See L<attributes>.
+
+=item Invalid separator character %s in attribute list
+
+(F) Something other than a comma or whitespace was seen between the
+elements of an attribute list.  If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.  See L<attributes>.
+
 =item Missing command in piped open
 
 (W) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
 construction, but the command was missing or blank.
 
+=item Missing name in "my sub"
+
+(F) The reserved syntax for lexically scoped subroutines requires that they
+have a name with which they can be found.
+
 =item Unrecognized escape \\%c passed through
 
 (W) You used a backslash-character combination which is not recognized
 by Perl.
 
+=item Unterminated attribute parameter in attribute list
+
+(F) The lexer saw an opening (left) parenthesis character while parsing an
+attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.  See L<attributes>.
+
+=item Unterminated attribute list
+
+(F) The lexer found something other than a simple identifier at the start
+of an attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous attribute
+too soon.  See L<attributes>.
+
 =item defined(@array) is deprecated
 
 (D) defined() is not usually useful on arrays because it checks for an
@@ -615,6 +697,27 @@ just use C<if (@array) { # not empty }> for example.
 undefined I<scalar> value.  If you want to see if the hash is empty,
 just use C<if (%hash) { # not empty }> for example.  
 
+=item Invalid separator character %s in subroutine attribute list
+
+(F) Something other than a comma or whitespace was seen between the
+elements of a subroutine attribute list.  If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.
+
+=item Unterminated attribute parameter in subroutine attribute list
+
+(F) The lexer saw an opening (left) parenthesis character while parsing a
+subroutine attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.
+
+=item Unterminated subroutine attribute list
+
+(F) The lexer found something other than a simple identifier at the start
+of a subroutine attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous attribute
+too soon.
+
 =head1 Obsolete Diagnostics
 
 Todo.
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 7077088b3c..cd9583bc87 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -30,6 +30,11 @@ The symbols C<"%(-?@> sort before the letters, while C<[> and C<\> sort after.
 
 =over 4
 
+=item "my sub" not yet implemented
+
+(F) Lexically scoped subroutines are not yet implemented.  Don't try that
+yet.
+
 =item "my" variable %s can't be in a package
 
 (F) Lexically scoped variables aren't in a package, so it doesn't make sense
@@ -174,6 +179,13 @@ regular expression engine didn't specifically check for that.  See L<perlre>.
 (S) The symbol in question was declared but somehow went out of scope
 before it could possibly have been used.
 
+=item %s package attribute may clash with future reserved word: %s
+
+(W) A lowercase attribute name was used that had a package-specific handler.
+That name might have a meaning to Perl itself some day, even though it
+doesn't yet.  Perhaps you should use a mixed-case attribute name, instead.
+See L<attributes>.
+
 =item %s syntax OK
 
 (F) The final summary message when a C<perl -c> succeeds.
@@ -297,7 +309,8 @@ imported with the C<use subs> pragma).
 
 To silently interpret it as the Perl operator, use the C<CORE::> prefix
 on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine
-to be an object method (see L<attrs>).
+to be an object method (see L<perlsub/"Subroutine Attributes">
+or L<attributes>).
 
 =item Args must match #! line
 
@@ -1530,7 +1543,7 @@ before the illegal character.
 
 (F) The number of bits in vec() (the third argument) must be a power of
 two from 1 to 32 (or 64, if your platform supports that).
- 
+
 =item Illegal switch in PERL5OPT: %s
 
 (X) The PERL5OPT environment variable may only be used to set the
@@ -1614,6 +1627,16 @@ rebuild Perl.
 
 (P) Something went badly awry in the regular expression parser.
 
+=item Invalid %s attribute: %s
+
+The indicated attribute for a subroutine or variable was not recognized
+by Perl or by a user-supplied handler.  See L<attributes>.
+
+=item Invalid %s attributes: %s
+
+The indicated attributes for a subroutine or variable were not recognized
+by Perl or by a user-supplied handler.  See L<attributes>.
+
 =item invalid [] range in regexp
 
 (F) The range specified in a character class had a minimum character
@@ -1625,6 +1648,13 @@ a literal character.  See L<perlre>.
 (W) Perl does not understand the given format conversion.
 See L<perlfunc/sprintf>.
 
+=item Invalid separator character %s in attribute list
+
+(F) Something other than a comma or whitespace was seen between the
+elements of an attribute list.  If the previous attribute
+had a parenthesised parameter list, perhaps that list was terminated
+too soon.  See L<attributes>.
+
 =item Invalid type in pack: '%s'
 
 (F) The given character is not a valid pack type.  See L<perlfunc/pack>.
@@ -1756,6 +1786,11 @@ be created for some peculiar reason.
 (W) Multidimensional arrays aren't written like C<$foo[1,2,3]>.  They're written
 like C<$foo[1][2][3]>, as in C.
 
+=item Missing name in "my sub"
+
+(F) The reserved syntax for lexically scoped subroutines requires that they
+have a name with which they can be found.
+
 =item Name "%s::%s" used only once: possible typo
 
 (W) Typographical errors often show up as unique variable names.
@@ -3048,6 +3083,20 @@ a term, so it's looking for the corresponding right angle bracket, and not
 finding it.  Chances are you left some needed parentheses out earlier in
 the line, and you really meant a "less than".
 
+=item Unterminated attribute parameter in attribute list
+
+(F) The lexer saw an opening (left) parenthesis character while parsing an
+attribute list, but the matching closing (right) parenthesis
+character was not found.  You may need to add (or remove) a backslash
+character to get your parentheses to balance.  See L<attributes>.
+
+=item Unterminated attribute list
+
+(F) The lexer found something other than a simple identifier at the start
+of an attribute, and it wasn't a semicolon or the start of a
+block.  Perhaps you terminated the parameter list of the previous attribute
+too soon.  See L<attributes>.
+
 =item Use of $# is deprecated
 
 (D) This was an ill-advised attempt to emulate a poorly defined B<awk> feature.
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 004c0f47cc..d420059d4c 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2366,6 +2366,8 @@ there is an error.  See also C<IPC::SysV> and C<IPC::SysV::Msg> documentation.
 
 =item my EXPR
 
+=item my EXPR : ATTRIBUTES
+
 A C<my> declares the listed variables to be local (lexically) to the
 enclosing block, file, or C<eval>.  If
 more than one value is listed, the list must be placed in parentheses.  See
@@ -4338,10 +4340,10 @@ out the names of those files that contain a match:
 =item sub NAME BLOCK
 
 This is subroutine definition, not a real function I<per se>.  With just a
-NAME (and possibly prototypes), it's just a forward declaration.  Without
-a NAME, it's an anonymous function declaration, and does actually return a
-value: the CODE ref of the closure you just created.  See L<perlsub> and
-L<perlref> for details.
+NAME (and possibly prototypes or attributes), it's just a forward declaration.
+Without a NAME, it's an anonymous function declaration, and does actually
+return a value: the CODE ref of the closure you just created.  See L<perlsub>
+and L<perlref> for details.
 
 =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
 
diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod
index abfa657f61..bfc5223819 100644
--- a/pod/perlmodlib.pod
+++ b/pod/perlmodlib.pod
@@ -46,9 +46,13 @@ The following pragmas are defined (and have their own documentation).
 
 =over 12
 
+=item attributes
+
+set/get the attributes of a subroutine or variable
+
 =item attrs
 
-set/get attributes of a subroutine
+set/get attributes of a subroutine (obsolescent)
 
 =item autouse
 
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 2bd1cfd1ee..47f507f28d 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -6,16 +6,22 @@ perlsub - Perl subroutines
 
 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:
 
@@ -112,7 +118,7 @@ Example:
 	...
     }
 
-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) = @_;
@@ -196,7 +202,7 @@ disables any prototype checking on arguments you do provide.  This
 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
@@ -213,6 +219,11 @@ Synopsis:
     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>),
@@ -220,7 +231,7 @@ loop (C<for/foreach/while/until/continue>), subroutine, C<eval>,
 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
@@ -669,8 +680,8 @@ to it.  Look out for implicit assignments in C<while> conditionals.
 
 =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 {
@@ -798,7 +809,7 @@ It turns out that you can actually do this also:
 
 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
@@ -1043,7 +1054,7 @@ built-in name with the special package qualifier C<CORE::>.  For example,
 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>
@@ -1167,6 +1178,46 @@ described in L<AutoLoader> and in L<AutoSplit>, the standard
 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 comma 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 comma 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.