File Coverage

blib/lib/Memoize/Lift.pm
Criterion Covered Total %
statement 18 18 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod n/a
total 24 24 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Memoize::Lift - lift expression evaluation to compile time
4              
5             =head1 SYNOPSIS
6              
7             use Memoize::Lift qw(lift);
8              
9             $value = lift(expensive_computation());
10              
11             =head1 DESCRIPTION
12              
13             This module supplies an operator that causes an expression to be evaluated
14             immediately at compile time, memoising its value for use at runtime.
15              
16             =cut
17              
18             package Memoize::Lift;
19              
20 11     11   287839 { use 5.013008; }
  11         41  
  11         499  
21 11     11   61 use warnings;
  11         25  
  11         390  
22 11     11   81 use strict;
  11         42  
  11         454  
23              
24 11     11   11205 use Devel::CallParser 0.000 ();
  11         49845  
  11         384  
25 11     11   93 use XSLoader;
  11         23  
  11         527  
26              
27             our $VERSION = "0.000";
28              
29 11     11   53 use parent "Exporter";
  11         22  
  11         47  
30             our @EXPORT_OK = qw(lift);
31              
32             XSLoader::load(__PACKAGE__, $VERSION);
33              
34             =head1 OPERATORS
35              
36             =over
37              
38             =item lift(EXPR)
39              
40             Evaluate I at compile time and memoise its value. Whenever a
41             C expression is evaluated at runtime, it yields the value
42             that I yielded at compile time. There is one instance of this
43             memoisation for each instance of the C operator in the source.
44              
45             I is lexically located where the C operator is, and can use
46             static aspects of the lexical environment normally. However, because
47             I is evaluated at compile time, it cannot use any aspects of the
48             dynamic environment as it would exist at runtime of the C operator.
49             Lexical variables visible at the location of the C operator remain
50             visible to I, but referencing them is an error.
51              
52             If evaluation of I results in an exception, that exception will
53             terminate compilation.
54              
55             I is always evaluated in scalar context, regardless of the
56             context in which the C operator appears. To memoise a list,
57             write C<@{lift([...])}>.
58              
59             =back
60              
61             =head1 BUGS
62              
63             L will generate incorrect source when deparsing C
64             expressions. It will show the constant value of the expression as best
65             it can, which is not perfect if the value is non-trivial. It has no
66             chance at all to show the original expression that yielded that value,
67             because the expression is not kept: the value determined at compile time
68             is built into the op tree as a constant item.
69              
70             The custom parsing code required for C to operate is only invoked
71             if C is invoked using an unqualified name. That is, referring
72             to it as C won't work. This limitation should be
73             resolved if L or something similar migrates into the
74             core in a future version of Perl.
75              
76             =head1 SEE ALSO
77              
78             L
79              
80             =head1 AUTHOR
81              
82             Andrew Main (Zefram)
83              
84             =head1 COPYRIGHT
85              
86             Copyright (C) 2011 Andrew Main (Zefram)
87              
88             =head1 LICENSE
89              
90             This module is free software; you can redistribute it and/or modify it
91             under the same terms as Perl itself.
92              
93             =cut
94              
95             1;