File Coverage

blib/lib/Data/Record/Serialize/Role/Sink/Stream.pm
Criterion Covered Total %
statement 30 31 96.7
branch 11 14 78.5
condition 9 18 50.0
subroutine 7 7 100.0
pod 1 1 100.0
total 58 71 81.6


line stmt bran cond sub pod time code
1              
2             # ABSTRACT: output encoded data to a stream.
3              
4             use Scalar::Util;
5 7     7   3115 use Moo::Role;
  7         18  
  7         280  
6 7     7   36  
  7         16  
  7         46  
7             use Data::Record::Serialize::Error { errors => [ '::create', '::parameter', '::internal' ] }, -all;
8 7     7   2553  
  7         16  
  7         92  
9             our $VERSION = '1.03'; # TRIAL
10              
11             use IO::File;
12 7     7   3490  
  7         10571  
  7         849  
13             use namespace::clean;
14 7     7   45  
  7         14  
  7         41  
15              
16              
17              
18              
19              
20              
21              
22              
23              
24              
25              
26              
27              
28              
29              
30              
31              
32              
33              
34              
35              
36              
37              
38              
39              
40              
41              
42              
43              
44             has output => (
45             is => 'ro',
46             default => '-',
47             isa => sub {
48             defined $_[0]
49             or error( '::parameter', "'output' parameter must be defined" );
50             my $ref = ref $_[0];
51             return if $ref eq 'GLOB' or $ref eq 'SCALAR';
52              
53             if ( $ref eq '' ) {
54             $ref = ref( \$_[0] ); # turn plain *STDOUT into \*STDOUT
55             return if $ref eq 'GLOB';
56             return if length $_[0];
57             error( '::parameter', "string 'output' parameter must not be empty" );
58             }
59              
60             return
61             if Scalar::Util::blessed $_[0]
62             and $_[0]->isa( 'IO::Handle' ) || $_[0]->isa( 'FileHandle' );
63             error( '::parameter', "illegal value for 'output' parameter" );
64             },
65             );
66              
67              
68              
69              
70              
71              
72              
73             has fh => (
74             is => 'lazy',
75             init_arg => undef,
76             clearer => 1,
77             predicate => 1,
78             );
79              
80              
81              
82              
83              
84              
85              
86             has _passed_fh => (
87             is => 'rwp',
88             init_arg => undef,
89             default => 1,
90             );
91              
92             my $self = shift;
93              
94 17     17   1000 my $output = $self->output;
95             my $ref = ref $output;
96 17         55  
97 17         35 # filename
98             if ( $ref eq '' ) {
99             return $output if ref( \$output ) eq 'GLOB';
100 17 100       53 return \*STDOUT if $output eq '-';
101 2 100       12  
102 1 50       3 $self->_set__passed_fh( 0 );
103             return (
104 1         4 IO::File->new( $output, 'w' )
105             or error( '::create', "unable to create output file: '$output'" )
106 1   33     8 );
107             }
108              
109             return $output
110             if $ref eq 'GLOB'
111 15 50 33     99 or Scalar::Util::blessed( $output )
      66        
      66        
112             && ( $output->isa( 'IO::Handle' ) || $output->isa( 'FileHandle' ) );
113              
114             $self->_set__passed_fh( 0 );
115             return (
116 12         39 IO::File->new( $output, 'w' )
117             or error( '::create', "unable to open scalar for output" ) ) if $ref eq 'SCALAR';
118 12 50 33     79  
119             error( '::internal', "can't get here" );
120             }
121 0         0  
122              
123              
124              
125              
126              
127              
128              
129              
130              
131              
132              
133              
134              
135              
136              
137              
138              
139              
140              
141              
142              
143              
144              
145              
146              
147             my ( $self, $in_global_destruction ) = @_;
148              
149             # don't bother closing the FH in global destruction (it'll be done
150 20     20 1 375 # on its own) or if we were passed a file handle in the output
151             # attribute.
152             return if $in_global_destruction or $self->_passed_fh;
153              
154             # fh is lazy, so the object may close without every using it, so
155 20 100 66     146 # don't inadvertently create it.
156             $self->fh->close if $self->has_fh;
157             $self->clear_fh;
158             }
159 10 100       180  
160 10         425 1;
161              
162             #
163             # This file is part of Data-Record-Serialize
164             #
165             # This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.
166             #
167             # This is free software, licensed under:
168             #
169             # The GNU General Public License, Version 3, June 2007
170             #
171              
172              
173             =pod
174              
175             =for :stopwords Diab Jerius Smithsonian Astrophysical Observatory
176              
177             =head1 NAME
178              
179             Data::Record::Serialize::Role::Sink::Stream - output encoded data to a stream.
180              
181             =head1 VERSION
182              
183             version 1.03
184              
185             =head1 SYNOPSIS
186              
187             with 'Data::Record::Serialize::Role::Sink::Stream';
188              
189             =head1 DESCRIPTION
190              
191             A L<Moo::Role> which provides the underlying support for stream sinks.
192             B<Data::Record::Serialize::Role::Sink::Stream> outputs encoded data to a
193             file handle.
194              
195             =head1 CLASS METHODS
196              
197             =head2 new
198              
199             This role adds two named arguments to the constructor, L</output> and
200             L</fh>, which mirror the added object attributes.
201              
202             =head1 ATTRIBUTES
203              
204             =head2 output
205              
206             One of the following:
207              
208             =over
209              
210             =item *
211              
212             The name of an output file (which will be created). If it is the
213             string C<->, output will be written to the standard output stream.
214             Must not be the empty string.
215              
216             =item *
217              
218             a reference to a scalar to which the records will be written.
219              
220             =item *
221              
222             a GLOB (i.e. C<\*STDOUT>), or a reference to an object which derives
223             from L<IO::Handle> (e.g. L<IO::File>, L<FileHandle>, etc.). These
224             will I<not> be closed upon destruction of the serializer or when the
225             L</close> method is called.
226              
227             =back
228              
229             =head2 fh
230              
231             The file handle to which the data will be output
232              
233             =head2 _passed_fh
234              
235             Will be true if L</output> was not a file name.
236              
237             =head1 METHODS
238              
239             =head2 close
240              
241             $obj->close( ?$in_global_destruction );
242              
243             Close the object; useful in destructors. Only files created by the
244             serializer will be closed. If a filehandle, GLOB, or similar object
245             is passed via the constructor's L</output> parameter L</close> method
246             is called.
247              
248             =for Pod::Coverage close
249             has_fh
250             clear_fh
251              
252             =head1 SUPPORT
253              
254             =head2 Bugs
255              
256             Please report any bugs or feature requests to bug-data-record-serialize@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=Data-Record-Serialize
257              
258             =head2 Source
259              
260             Source is available at
261              
262             https://gitlab.com/djerius/data-record-serialize
263              
264             and may be cloned from
265              
266             https://gitlab.com/djerius/data-record-serialize.git
267              
268             =head1 SEE ALSO
269              
270             Please see those modules/websites for more information related to this module.
271              
272             =over 4
273              
274             =item *
275              
276             L<Data::Record::Serialize|Data::Record::Serialize>
277              
278             =back
279              
280             =head1 AUTHOR
281              
282             Diab Jerius <djerius@cpan.org>
283              
284             =head1 COPYRIGHT AND LICENSE
285              
286             This software is Copyright (c) 2017 by Smithsonian Astrophysical Observatory.
287              
288             This is free software, licensed under:
289              
290             The GNU General Public License, Version 3, June 2007
291              
292             =cut