File Coverage

blib/lib/Sublike/Extended.pm
Criterion Covered Total %
statement 6 7 85.7
branch n/a
condition n/a
subroutine 3 4 75.0
pod n/a
total 9 11 81.8


line stmt bran cond sub pod time code
1             # You may distribute under the terms of either the GNU General Public License
2             # or the Artistic License (the same terms as Perl itself)
3             #
4             # (C) Paul Evans, 2023 -- leonerd@leonerd.org.uk
5              
6             package Sublike::Extended 0.19;
7              
8 1     1   235928 use v5.14;
  1         11  
9 1     1   6 use warnings;
  1         6  
  1         122  
10              
11             require XSLoader;
12             XSLoader::load( __PACKAGE__, our $VERSION );
13              
14             =head1 NAME
15              
16             C - enable extended features when parsing C-like syntax
17              
18             =head1 SYNOPSIS
19              
20             use v5.26;
21             use Sublike::Extended;
22             use experimental 'signatures';
23              
24             extended sub greet (:$name = "world") {
25             say "Hello, $name";
26             }
27              
28             greet( name => $ENV{USER} );
29              
30             =head1 DESCRIPTION
31              
32             This module extends the syntax for declaring named or anonymous subroutines
33             using Perl's builtin C keyword, or other similar keywords provided by
34             third-party modules, to enable parsing of extra features.
35              
36             Currently, the only extended features that are provided are related to the
37             parsing of a subroutine signature. Since signatures are only available on Perl
38             version 5.26 or later, this module is unlikely to be useful in earlier
39             versions of Perl.
40              
41             =head2 Named parameters
42              
43             Extended subroutines can be declare named parameters in the signature, after
44             any positional ones. These take the form of a name prefixed by a colon
45             character. The caller of such a function should pass values for these
46             parameters by the usual name-value pair syntax that would be used for passing
47             into a regular hash. Within the body of the subroutine the values passed into
48             these are unpacked into regular lexical variables.
49              
50             extended sub colour (:$red, :$green, :$blue) {
51             ... # $red, $green and $blue are available as regular lexicals
52             }
53              
54             # argument order at the caller site is not important
55             colour(green => 1, blue => 2, red => 3);
56              
57             As with positional parameters, they are normally mandatory, but can be made
58             optional by supplying a defaulting expression. If the caller fails to pass a
59             value corresponding to the parameter, the default expression is evaluated and
60             used instead.
61              
62             extended sub f (:$x0, :$x1, :$x2 = 0) { ... }
63             # The caller must provide x0 and x1, but x2 is optional
64              
65             An optional slurpy hash is also permitted after all of these. It will contain
66             the values of any other name-value pairs given by the caller, after those
67             corresponding to named parameters have already been extracted.
68              
69             extended sub g (:$alpha, :$beta, %rest) { ... }
70              
71             =head2 Parameter Attributes
72              
73             Parameters to extended subroutines can use attribute syntax to apply extra
74             attributes to individual parameters.
75              
76             extended sub info ($x :Attribute) { ... }
77              
78             Any attributes that are available are ones that have been previously
79             registered with L using its XS-level API. The particular
80             behaviour of such an attribute would be defined by whatever module provided
81             the attribute.
82              
83             =head1 KEYWORDS
84              
85             =head2 extended
86              
87             extended sub NAME (SIGNATURE...) { BODY... }
88              
89             extended sub (SIGNATURE...) { BODY... };
90              
91             This prefix keyword enables extra parsing features when handling a C (or
92             other sub-like function keyword).
93              
94             This keyword can be freely mixed with other C-prefix keywords, such as
95             C from L
96              
97             async extended sub f (:$param) { ... }
98              
99             This can also be used with other keywords that provide C-like syntax,
100             such as C from L or the core C.
101              
102             extended method f (:$param) { ... }
103              
104             =cut
105              
106             sub import
107             {
108 1     1   364 $^H{"Sublike::Extended/extended"}++;
109             }
110              
111             sub unimport
112             {
113 0     0     delete $^H{"Sublike::Extended/extended"};
114             }
115              
116             =head1 AUTHOR
117              
118             Paul Evans
119              
120             =cut
121              
122             0x55AA;