File Coverage

blib/lib/Mojo/ByteStream.pm
Criterion Covered Total %
statement 46 46 100.0
branch n/a
condition 8 9 88.8
subroutine 43 43 100.0
pod 12 12 100.0
total 109 110 99.0


line stmt bran cond sub pod time code
1             package Mojo::ByteStream;
2 79     2091   356956 use Mojo::Base -strict;
  79         163  
  79         542  
3 79     79   585 use overload bool => sub {1}, '""' => sub { ${$_[0]} }, fallback => 1;
  79     370   215  
  79         797  
  68         206  
  2517         22519  
  2517         9660  
4              
5 79     79   7145 use Exporter 'import';
  79         190  
  79         2964  
6 79     79   5117 use Mojo::Collection;
  79         200  
  79         3298  
7 79     79   503 use Mojo::Util;
  79         188  
  79         58623  
8              
9             our @EXPORT_OK = ('b');
10              
11             # Turn most functions from Mojo::Util into methods
12             my @UTILS = (
13             qw(b64_decode b64_encode camelize decamelize gunzip gzip hmac_sha1_sum),
14             qw(html_unescape md5_bytes md5_sum punycode_decode punycode_encode quote),
15             qw(sha1_bytes sha1_sum slugify term_escape trim unindent unquote url_escape),
16             qw(url_unescape xml_escape xor_encode)
17             );
18             for my $name (@UTILS) {
19             my $sub = Mojo::Util->can($name);
20             Mojo::Util::monkey_patch __PACKAGE__, $name, sub {
21 50     50   101 my $self = shift;
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
        50      
22 50         287 $$self = $sub->($$self, @_);
23 50         177 return $self;
24             };
25             }
26              
27 66     66 1 3359 sub b { __PACKAGE__->new(@_) }
28              
29 3     3 1 19 sub clone { $_[0]->new(${$_[0]}) }
  3         10  
30              
31 5     5 1 28 sub decode { shift->_delegate(\&Mojo::Util::decode, @_) }
32 8     8 1 44 sub encode { shift->_delegate(\&Mojo::Util::encode, @_) }
33              
34             sub new {
35 2589     2589 1 10584 my $class = shift;
36 2589   66     19827 return bless \(my $dummy = join '', @_), ref $class || $class;
37             }
38              
39             sub say {
40 3     3 1 7 my ($self, $handle) = @_;
41 3   100     11 $handle ||= \*STDOUT;
42 3         8 say $handle $$self;
43 3         7 return $self;
44             }
45              
46 2     2 1 4 sub secure_compare { Mojo::Util::secure_compare ${shift()}, shift }
  2         7  
47              
48 4     4 1 9 sub size { length ${$_[0]} }
  4         13  
49              
50             sub split {
51 10   100 10 1 52 my ($self, $pat, $lim) = (shift, shift, shift // 0);
52 10         97 return Mojo::Collection->new(map { $self->new($_) } split $pat, $$self, $lim);
  34         49  
53             }
54              
55 1     1 1 6 sub tap { shift->Mojo::Base::tap(@_) }
56              
57 20     20 1 44 sub to_string { ${$_[0]} }
  20         72  
58              
59 1     1 1 5 sub with_roles { shift->Mojo::Base::with_roles(@_) }
60              
61             sub _delegate {
62 13     13   36 my ($self, $sub) = (shift, shift);
63 13   100     202 $$self = $sub->(shift || 'UTF-8', $$self);
64 13         10701 return $self;
65             }
66              
67             1;
68              
69             =encoding utf8
70              
71             =head1 NAME
72              
73             Mojo::ByteStream - ByteStream
74              
75             =head1 SYNOPSIS
76              
77             use Mojo::ByteStream;
78              
79             # Manipulate bytestream
80             my $stream = Mojo::ByteStream->new('foo_bar_baz');
81             say $stream->camelize;
82              
83             # Chain methods
84             my $stream = Mojo::ByteStream->new('foo bar baz')->quote;
85             $stream = $stream->unquote->encode('UTF-8')->b64_encode('');
86             say "$stream";
87              
88             # Use the alternative constructor
89             use Mojo::ByteStream 'b';
90             my $stream = b('foobarbaz')->b64_encode('')->say;
91              
92             =head1 DESCRIPTION
93              
94             L is a scalar-based container for bytestreams that provides a
95             more friendly API for many of the functions in L.
96              
97             # Access scalar directly to manipulate bytestream
98             my $stream = Mojo::ByteStream->new('foo');
99             $$stream .= 'bar';
100              
101             =head1 FUNCTIONS
102              
103             L implements the following functions, which can be imported
104             individually.
105              
106             =head2 b
107              
108             my $stream = b('test123');
109              
110             Construct a new scalar-based L object.
111              
112             =head1 METHODS
113              
114             L implements the following methods.
115              
116             =head2 b64_decode
117              
118             $stream = $stream->b64_decode;
119              
120             Base64 decode bytestream with L.
121              
122             =head2 b64_encode
123              
124             $stream = $stream->b64_encode;
125             $stream = $stream->b64_encode("\n");
126              
127             Base64 encode bytestream with L.
128              
129             # "Zm9vIGJhciBiYXo="
130             b('foo bar baz')->b64_encode('');
131              
132             =head2 camelize
133              
134             $stream = $stream->camelize;
135              
136             Camelize bytestream with L.
137              
138             =head2 clone
139              
140             my $stream2 = $stream->clone;
141              
142             Return a new L object cloned from this bytestream.
143              
144             =head2 decamelize
145              
146             $stream = $stream->decamelize;
147              
148             Decamelize bytestream with L.
149              
150             =head2 decode
151              
152             $stream = $stream->decode;
153             $stream = $stream->decode('iso-8859-1');
154              
155             Decode bytestream with L, defaults to using C.
156              
157             # "♥"
158             b('%E2%99%A5')->url_unescape->decode;
159              
160             =head2 encode
161              
162             $stream = $stream->encode;
163             $stream = $stream->encode('iso-8859-1');
164              
165             Encode bytestream with L, defaults to using C.
166              
167             # "%E2%99%A5"
168             b('♥')->encode->url_escape;
169              
170             =head2 gunzip
171              
172             $stream = $stream->gunzip;
173              
174             Uncompress bytestream with L.
175              
176             =head2 gzip
177              
178             stream = $stream->gzip;
179              
180             Compress bytestream with L.
181              
182             =head2 hmac_sha1_sum
183              
184             $stream = $stream->hmac_sha1_sum('passw0rd');
185              
186             Generate HMAC-SHA1 checksum for bytestream with L.
187              
188             # "7fbdc89263974a89210ea71f171c77d3f8c21471"
189             b('foo bar baz')->hmac_sha1_sum('secr3t');
190              
191             =head2 html_unescape
192              
193             $stream = $stream->html_unescape;
194              
195             Unescape all HTML entities in bytestream with L.
196              
197             # "%3Chtml%3E"
198             b('<html>')->html_unescape->url_escape;
199              
200             =head2 md5_bytes
201              
202             $stream = $stream->md5_bytes;
203              
204             Generate binary MD5 checksum for bytestream with L.
205              
206             =head2 md5_sum
207              
208             $stream = $stream->md5_sum;
209              
210             Generate MD5 checksum for bytestream with L.
211              
212             =head2 new
213              
214             my $stream = Mojo::ByteStream->new('test123');
215              
216             Construct a new scalar-based L object.
217              
218             =head2 punycode_decode
219              
220             $stream = $stream->punycode_decode;
221              
222             Punycode decode bytestream with L.
223              
224             =head2 punycode_encode
225              
226             $stream = $stream->punycode_encode;
227              
228             Punycode encode bytestream with L.
229              
230             =head2 quote
231              
232             $stream = $stream->quote;
233              
234             Quote bytestream with L.
235              
236             =head2 say
237              
238             $stream = $stream->say;
239             $stream = $stream->say(*STDERR);
240              
241             Print bytestream to handle and append a newline, defaults to using C.
242              
243             =head2 secure_compare
244              
245             my $bool = $stream->secure_compare($str);
246              
247             Compare bytestream with L.
248              
249             =head2 sha1_bytes
250              
251             $stream = $stream->sha1_bytes;
252              
253             Generate binary SHA1 checksum for bytestream with L.
254              
255             =head2 sha1_sum
256              
257             $stream = $stream->sha1_sum;
258              
259             Generate SHA1 checksum for bytestream with L.
260              
261             =head2 size
262              
263             my $size = $stream->size;
264              
265             Size of bytestream.
266              
267             =head2 slugify
268              
269             $stream = $stream->slugify;
270             $stream = $stream->slugify($bool);
271              
272             Generate URL slug for bytestream with L.
273              
274             =head2 split
275              
276             my $collection = $stream->split(',');
277             my $collection = $stream->split(',', -1);
278              
279             Turn bytestream into L object containing L
280             objects.
281              
282             # "One,Two,Three"
283             b("one,two,three")->split(',')->map('camelize')->join(',');
284              
285             # "One,Two,Three,,,"
286             b("one,two,three,,,")->split(',', -1)->map('camelize')->join(',');
287              
288             =head2 tap
289              
290             $stream = $stream->tap(sub {...});
291              
292             Alias for L.
293              
294             =head2 term_escape
295              
296             $stream = $stream->term_escape;
297              
298             Escape POSIX control characters in bytestream with L.
299              
300             # Print binary checksum to terminal
301             b('foo')->sha1_bytes->term_escape->say;
302              
303             =head2 to_string
304              
305             my $str = $stream->to_string;
306              
307             Stringify bytestream.
308              
309             =head2 trim
310              
311             $stream = $stream->trim;
312              
313             Trim whitespace characters from both ends of bytestream with
314             L.
315              
316             =head2 unindent
317              
318             $stream = $stream->unindent;
319              
320             Unindent bytestream with L.
321              
322             =head2 unquote
323              
324             $stream = $stream->unquote;
325              
326             Unquote bytestream with L.
327              
328             =head2 url_escape
329              
330             $stream = $stream->url_escape;
331             $stream = $stream->url_escape('^A-Za-z0-9\-._~');
332              
333             Percent encode all unsafe characters in bytestream with
334             L.
335              
336             # "%E2%98%83"
337             b('☃')->encode->url_escape;
338              
339             =head2 url_unescape
340              
341             $stream = $stream->url_unescape;
342              
343             Decode percent encoded characters in bytestream with
344             L.
345              
346             # "<html>"
347             b('%3Chtml%3E')->url_unescape->xml_escape;
348              
349             =head2 with_roles
350              
351             my $new_class = Mojo::ByteStream->with_roles('Mojo::ByteStream::Role::One');
352             my $new_class = Mojo::ByteStream->with_roles('+One', '+Two');
353             $stream = $stream->with_roles('+One', '+Two');
354              
355             Alias for L.
356              
357             =head2 xml_escape
358              
359             $stream = $stream->xml_escape;
360              
361             Escape only the characters C<&>, C>, C>, C<"> and C<'> in
362             bytestream with L.
363              
364             =head2 xor_encode
365              
366             $stream = $stream->xor_encode($key);
367              
368             XOR encode bytestream with L.
369              
370             # "%04%0E%15B%03%1B%10"
371             b('foo bar')->xor_encode('baz')->url_escape;
372              
373             =head1 OPERATORS
374              
375             L overloads the following operators.
376              
377             =head2 bool
378              
379             my $bool = !!$bytestream;
380              
381             Always true.
382              
383             =head2 stringify
384              
385             my $str = "$bytestream";
386              
387             Alias for L.
388              
389             =head1 SEE ALSO
390              
391             L, L, L.
392              
393             =cut