| 1 | package BoutrosLab::TSVStream::IO::Role::Writer::Dyn; | ||
| 2 | |||
| 3 | # safe Perl | ||
| 4 | 1 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | 1 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | 1 | ▶ | use Carp; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | |||
| 8 | 1 | ▶ | use BoutrosLab::TSVStream::IO::Role::Writer::Fixed; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | |||
| 10 | =head1 NAME | ||
| 11 | |||
| 12 | BoutrosLab::TSVStream:Writer | ||
| 13 | |||
| 14 | =cut | ||
| 15 | |||
| 16 | 1 | ▶ | use Moose::Role; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 17 | 1 | ▶ | use Moose::Util::TypeConstraints; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 18 | 1 | ▶ | use namespace::autoclean; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 19 | |||
| 20 | 1 | with 'BoutrosLab::TSVStream::IO::Role::Writer::Fixed' => { -excludes => '_list_headers' }; | |
| 21 | |||
| 22 | 0 | ▶ | sub _list_headers { |
|
Subroutine
_list_headers: not called CC=1 SCAR=6.9
| |||
| 23 | 0 | my $self = shift; | |
| 24 | 0 | return ( [ @{ $self->fields }, @{ $self->dyn_fields } ] ); | |
| 25 | } | ||
| 26 | |||
| 27 | =head1 SYNOPSIS | ||
| 28 | |||
| 29 | $class->writer( ... ); | ||
| 30 | |||
| 31 | # ($class will use the role BoutrosLab::TSVStream which will provide | ||
| 32 | # the writer method, that method will return a Writer object with: | ||
| 33 | # ... | ||
| 34 | # return BoutrosLab::TSVStream::Writer->new( | ||
| 35 | # handle => $fd, # (required) | ||
| 36 | # class => $class, # (required) class | ||
| 37 | # file => $file, # (optional) used (as filename) in error messages | ||
| 38 | # header => $str, # (optional) one of: write skip (default 'write' unless append) | ||
| 39 | # append => 1, # (optional) if true: | ||
| 40 | # # file is opened for append (if stream not provided) | ||
| 41 | # # header defaults to 'skip' | ||
| 42 | # ); | ||
| 43 | |||
| 44 | while (my $record = $writer->read) { | ||
| 45 | # ... $record is a $class object | ||
| 46 | # ... use $record->field1, $record->field2, etc. - all of the methods of $class object | ||
| 47 | } | ||
| 48 | |||
| 49 | =head1 DESCRIPTION | ||
| 50 | |||
| 51 | This object provides an iterator to read through the lines | ||
| 52 | of a data stream (C<$fd>), converting each from a line with | ||
| 53 | tab separated fields into an object of a class (C<$classs>) | ||
| 54 | that has attributes for those fields. | ||
| 55 | |||
| 56 | Usually, the data stream will start with a line that has the | ||
| 57 | fieldnames in a tab separated list, and the rest of the stream | ||
| 58 | has lines that contain the field values in a tab separated list. | ||
| 59 | |||
| 60 | Any error diagnostics will refer to the stream using the | ||
| 61 | C<$file> filename if it is provided. | ||
| 62 | |||
| 63 | The C<$class> class will have a class method named C<_fields> | ||
| 64 | that provides a ref to array of string listing the fields to | ||
| 65 | .be written and their order. | ||
| 66 | |||
| 67 | A class C<$class> object must be provided for each line. | ||
| 68 | The object will be re-formatted into tab separated format | ||
| 69 | and written out. | ||
| 70 | |||
| 71 | If C<header> is provided, it can be 'write', or 'skip'. | ||
| 72 | This controls what is done to the handle initially. | ||
| 73 | |||
| 74 | If 'write' is specified, a header line is written to the stream | ||
| 75 | containing the field names in tab separated format before writing | ||
| 76 | any explicitly provided objects. This is the default. If 'skip' | ||
| 77 | is specified, no header is written. | ||
| 78 | |||
| 79 | If 'skip' is specified, the stream is not checked for a header | ||
| 80 | line. (You would use this option either if the file does not | ||
| 81 | have a header line, or if you are scanning from the middle of | ||
| 82 | a file handle that is no longer at the start of the file.) | ||
| 83 | |||
| 84 | =head1 ATTRIBUTES | ||
| 85 | |||
| 86 | =head2 handle - the filehandle to be read | ||
| 87 | |||
| 88 | =head2 file - the name of the stream, usually a filename, for diagnostic purposes | ||
| 89 | |||
| 90 | =head2 class - the class that records transformed into | ||
| 91 | |||
| 92 | =head2 fields - list of field names, usually provided by class | ||
| 93 | |||
| 94 | handle, file, class and fields are provided by the ...::IO::Role::Base::Fixed role | ||
| 95 | |||
| 96 | =head2 append - (optional) boolean to cause writes to append to the stream, causes header to default to 'skip' | ||
| 97 | |||
| 98 | =head2 header - 'write', or 'skip' (default 'write' normally, 'skip' if 'append' is enabled) | ||
| 99 | |||
| 100 | The C<'write'> setting causes the first line of the stream to be written | ||
| 101 | with a list of field names. This is the default unless the append option | ||
| 102 | is set. | ||
| 103 | |||
| 104 | If the C<'skip'> setting is provided, the stream writing will start with | ||
| 105 | a data value. Use this either for writing a stream that is not supposed | ||
| 106 | to have a header line, or else to append additional values to an existing | ||
| 107 | file (of the same type of course). This must normally be asked for | ||
| 108 | explicitly, but it is the default if the append option is set. | ||
| 109 | |||
| 110 | =head1 BUILDARGS | ||
| 111 | |||
| 112 | The BUILDARGS method opens a handle if only a file is provided. | ||
| 113 | |||
| 114 | =head1 BUILD | ||
| 115 | |||
| 116 | The BUILD method handles any requirements for reading and processing a | ||
| 117 | header line. | ||
| 118 | |||
| 119 | =head1 METHODS | ||
| 120 | |||
| 121 | =head2 write - read a line to the stream from a class element | ||
| 122 | |||
| 123 | ##### | ||
| 124 | |||
| 125 | =head1 AUTHOR | ||
| 126 | |||
| 127 | John Macdonald - Boutros Lab | ||
| 128 | |||
| 129 | =head1 ACKNOWLEDGEMENTS | ||
| 130 | |||
| 131 | Paul Boutros, Phd, PI - Boutros Lab | ||
| 132 | |||
| 133 | The Ontario Institute for Cancer Research | ||
| 134 | |||
| 135 | =cut | ||
| 136 | |||
| 137 | 1 | 1; | |
| 138 | |||