File Coverage

blib/lib/stringification.pm
Criterion Covered Total %
statement 13 13 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod n/a
total 18 18 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, 2011-2012 -- leonerd@leonerd.org.uk
5              
6             package stringification;
7              
8 4     4   105600 use strict;
  4         11  
  4         160  
9 4     4   21 use warnings;
  4         11  
  4         139  
10              
11 4     4   74 use Carp;
  4         8  
  4         962  
12              
13             our $VERSION = '0.01_004';
14              
15             require XSLoader;
16             XSLoader::load(__PACKAGE__, $VERSION );
17              
18             =head1 NAME
19              
20             C - allow or forbid implicitly converting references into
21             strings
22              
23             =head1 SYNOPSIS
24            
25             no stringification;
26              
27             my $array = [ 1, 2, 3 ];
28              
29             print "My array is $array\n"; # dies
30              
31             =head1 DESCRIPTION
32              
33             Normally in Perl, a reference may be implicitly converted into a string,
34             usually of a form like C.
35              
36             This module provides a lexically-scoped pragma which alters the behaviour of
37             the following operations:
38              
39             "$ref" # stringify
40             $ref . "foo" # concat
41             lc $ref
42             lcfirst $ref
43             uc $ref
44             ucfirst $ref
45             quotemeta $ref
46             $ref =~ m//
47             split //, $ref
48             join $ref, @strs
49             join "", $ref
50             print $ref
51             say $ref
52              
53             When disabled by C, all of these operations will fail with
54             an exception when invoked on a non-object reference.
55              
56             $ perl -E 'no stringification; my $arr = []; say "Array is $arr"'
57             Attempted to concat a reference at -e line 1.
58              
59             The effects of this module are lexically scoped; to re-enable stringification
60             of references during a lexical scope, C again.
61              
62             =cut
63              
64             sub unimport
65             {
66             # Inform older perls that %^H needs rescoping
67 3     3   21 $^H |= 0x20000;
68              
69             # This is 'no stringification'; i.e. enable
70 3         7504 $^H{stringification} = 1;
71             }
72              
73             sub import
74             {
75             # Inform older perls that %^H needs rescoping
76 4     4   27 $^H |= 0x20000;
77              
78             # This is 'use stringification'; i.e. disable
79 4         558 delete $^H{stringification};
80             }
81              
82             =head1 TODO
83              
84             =over 4
85              
86             =item *
87              
88             More testing, especially around interoperatbility with other op-hooking
89             modules.
90              
91             =item *
92              
93             Hook more ops; including
94              
95             $ref =~ s///;
96             s//$ref/;
97             substr( $ref, 0, 0 )
98             substr( $str, 0, 0, $ref )
99             substr( $str, 0, 0 ) = $ref
100              
101             =item *
102              
103             Consider whether to detect for objects that don't have overload magic, and
104             forbid these too.
105              
106             =item *
107              
108             A mode where string conversions just give warnings, rather than outright
109             failures.
110              
111             no stringification 'warn';
112              
113             =back
114              
115             =head1 AUTHOR
116              
117             Paul Evans
118              
119             =cut
120              
121             0x55AA;