File Coverage

blib/lib/Syntax/Keyword/PhaserExpression.pm
Criterion Covered Total %
statement 8 8 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 11 11 100.0


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, 2024-- leonerd@leonerd.org.uk
5              
6             package Syntax::Keyword::PhaserExpression 0.01;
7              
8 2     2   623476 use v5.18;
  2         8  
9 2     2   12 use warnings;
  2         9  
  2         130  
10              
11 2     2   10 use Carp;
  2         3  
  2         243  
12              
13             require XSLoader;
14             XSLoader::load( __PACKAGE__, our $VERSION );
15              
16             =head1 NAME
17              
18             C - phasers as arbitrary expressions rather than blocks
19              
20             =head1 SYNOPSIS
21              
22             =for highlighter language=perl
23              
24             use Syntax::Keyword::PhaserExpression;
25              
26             if( BEGIN $ENV{DEBUG} ) {
27             printf STDERR "Here's a debugging message> %s\n", gen_debug();
28             }
29              
30             =head1 DESCRIPTION
31              
32             This module provides a syntax plugin that alters the behaviour of perl's
33             C keyword. This allows hoisting an expression to be evaluated at
34             compile-time, and replace its result into the compiled code. This may be
35             useful for performance, to avoid otherwise-expensive calls whose value won't
36             change, or to inline constants for other performance-related benefits.
37              
38             There may also be situations where it is useful to have expressions evaluated
39             early enough in compiletime so that their effects can influence the
40             compilation of later code.
41              
42             =cut
43              
44             =head1 KEYWORDS
45              
46             =cut
47              
48             =head2 BEGIN
49              
50             BEGIN expr...
51              
52             An expression prefixed with the C keyword is evaluated as soon as it is
53             compiled. The scalar result is then captured and inlined, as a constant, into
54             the surrounding code.
55              
56             As the expression is not a full block, it does not create a surrounding scope
57             that hides lexical variables inside it. This can be useful for assigning a
58             value to a variable at compiletime so that later compiletime expressions can
59             see its value.
60              
61             BEGIN my $arg = "the value";
62             use Some::Module arg => $arg;
63              
64             Note that the expression may not start with an open brace (C<{>) character, as
65             that is used by regular Perl's C block. This module does not replace
66             that syntax.
67              
68             =cut
69              
70             =head1 TODO
71              
72             =over 4
73              
74             =item *
75              
76             Implement some other phaser keywords. C and C might be useful.
77             Not C for obvious reasons. ;)
78              
79             =back
80              
81             =cut
82              
83             =head1 AUTHOR
84              
85             Paul Evans
86              
87             =cut
88              
89             0x55AA;