1File::Edit::Portable(3)User Contributed Perl DocumentatioFnile::Edit::Portable(3)
2
6 File::Edit::Portable - Read and write files while keeping the original
7 line-endings intact, no matter the platform.
8
10 use File::Edit::Portable;
11 my $rw = File::Edit::Portable->new;
13 # read a file, replacing original file's line endings with
15 # that of the local platform's default
16 my $fh = $rw->read('file.txt');
18 # edit file in a loop, and re-write it with its original line endings
20 my $fh = $rw->read('file.txt');
22 my $wfh = $rw->tempfile;
23 while (<$fh>){
25 ...
26 print $wfh $_;
27 }
28 $rw->write(contents => $wfh);
30 # get an array of the file's contents, with line endings stripped off
32 my @contents = $rw->read('file.txt');
34 # write out a file using original file's record separator, into a new file,
36 # preserving the original
37 $rw->write(contents => \@contents, copy => 'file2.txt');
39 # replace original file's record separator with a new (custom) one
41 $rw->write(recsep => "\r\n", contents => \@contents);
43 # rewrite all files in a directory recursively with local
45 # platform's default record separator
46 $rw->dir(dir => '/path/to/files');
48 # insert new data into a file after a specified line number
50 $rw->splice(file => 'file.txt', line => $num, insert => \@contents);
52 # insert new data into a file after a found search term
54 $rw->splice(file => 'file.txt', find => 'term', insert => \@contents);
56 # get a file's record separator
58 $rw->recsep('file.txt'); # string form
60 $rw->recsep('file.txt', 'hex'); # hex form
61 $rw->recsep('file.txt', 'type'); # line ending type (nix, win, mac, etc)
62
64 The default behaviour of "perl" is to read and write files using the
65 Operating System's (OS) default record separator (line ending). If you
66 open a file on an OS where the record separators are that of another
67 OS, things can and do break.
68 This module will read in a file, keep track of the file's current
70 record separators regardless of the OS, and save them for later
71 writing. It can return either a file handle (in scalar context) that
72 has had its line endings replaced with that of the local OS platform,
73 or an array of the file's contents (in list context) with line endings
74 stripped off. You can then modify this array and send it back in for
75 writing to the same file or a new file, where the original file's line
76 endings will be re-appended (or a custom ending if you so choose).
77 Uses are for dynamically reading/writing files while on one Operating
79 System, but you don't know whether the record separators are platform-
80 standard. Shared storage between multpile platforms are a good use
81 case. This module affords you the ability to not have to check each
82 file, and is very useful in looping over a directory where various
83 files may have been written by different platforms.
84
86 None by default. See EXPORT_OK
87
89 recsep(), platform_recsep()
90
92 "new"
93 Returns a new "File::Edit::Portable" object.
94 read('file.txt')
96 In scalar context, will return a read-only file handle to a copy of the
97 file that has had its line endings replaced with those of the local OS
98 platform's record separator.
99 In list context, will return an array, where each element is a line
101 from the file, with all line endings stripped off.
102 In both cases, we save the line endings that were found in the original
104 file (which is used when write() is called, by default).
105 "write"
107 Writes the data back to the original file, or alternately a new file.
108 Returns 1 on success. If you inadvertantly append newlines to the new
109 elements of the contents array, we'll strip them off before appending
110 the real newlines.
111 Parameters:
113 "file => 'file.txt'"
115 Not needed if you've used read() to open the file. However, if you have
117 multiple read()s open, write() will die without the 'file' param, as it
118 won't know which file you're wanting to write.
119 "copy => 'file2.txt'"
121 Set this if you want to write to an alternate (new) file, rather than
123 the original.
124 "contents => $filehandle" or "contents => \@contents"
126 Mandatory - either an array with one line per element, or a file handle
128 (file handle is far less memory-intensive).
129 "recsep => "\r\n""
131 Optional - a double-quoted string of any characters you want to write
133 as the line ending (record separator). This value will override what
134 was found in the read() call. Common ones are "\r\n" for Windows, "\n"
135 for Unix and "\r" for Mac. Use a call to platform_recsep() as the value
136 to use the local platforms default separator.
137 "splice"
139 Inserts new data into a file after a specified line number or search
140 term.
141 Parameters:
143 "file => 'file.txt'"
145 Mandatory.
147 "insert => \@contents"
149 Mandatory - an array reference containing the contents to merge into
151 the file.
152 "copy => 'file2.txt'"
154 Optional - we'll read from "file", but we'll write to this new file.
156 "line => Integer"
158 Optional - Merge the contents on the line following the one specified
160 here.
161 "find => 'search term'"
163 Optional - Merge the contents into the file on the line following the
165 first find of the search term. The search term is put into "qr", so
166 single quotes are recommended, and all regex patterns are honoured.
167 Note that we also accept a pre-created "qr//" Regexp object directly
168 (as opposed to a string).
169 "limit => Integer"
171 Optional - When splicing with the 'find' param, set this to the number
173 of finds to insert after. Default is stop after the first find. Set to
174 0 will insert after all finds.
175 NOTE: Although both are optional, at least one of "line" or "find" must
177 be sent in. If both are sent in, we'll warn, and operate on the line
178 number and skip the find parameter.
179 Returns an array of the modified file contents.
181 "dir"
183 Rewrites the line endings in some or all files within a directory
184 structure recursively. By default, rewrites all files with the current
185 platform's default line ending. Returns an array of the names of the
186 files found.
187 Parameters:
189 "dir => '/path/to/files'"
191 Mandatory.
193 "types => ['*.txt', '*.dat']"
195 Optional - Specify wildcard combinations for files to work on. We'll
197 accept anything that File::Find::Rule::name() method does. If not
198 supplied, we work on all files.
199 "maxdepth => Integer"
201 Optional - Specify how many levels of recursion to do after entering
203 the directory. We'll do a full recurse through all sub-directories if
204 this parameter is not set.
205 "recsep => "\r\n""
207 Optional - If this parameter is not sent in, we'll replace the line
209 endings with that of the current platform we're operating on.
210 Otherwise, we'll use the double-quoted value sent in.
211 "list => 1"
213 Optional - If set to any true value, we'll return an array of the names
215 of the files found, but won't take any editing action on them.
216 Default is disabled.
218 "recsep('file.txt', $want)"
220 Returns the record separator found within the file. If the file is
221 empty, we'll return the local platform's default record separator.
222 The optional $want parameter can contain either 'hex' or 'type'. If
224 'hex' is sent in, the record separator will be returned in hex form
225 (eg: "\0d\0a" for Windows). If 'type' is sent in, we'll return a short-
226 form of the line-ending type (eg: win, nix, mac, etc).
227 Note that this method can be imported into your namespace on demand if
229 you don't need the object functionality of the module.
230 platform_recsep($want)
232 Returns the the current platform's (OS) record separator in string
233 form.
234 The optional $want parameter can contain either 'hex' or 'type'. If
236 'hex' is sent in, the record separator will be returned in hex form
237 (eg: "\0d\0a" for Windows). If 'type' is sent in, we'll return a short-
238 from of the line-ending type (eg: win, nix, mac, etc).
239 Note that this method can be imported into your namespace on demand if
241 you don't need the object functionality of the module.
242 "tempfile"
244 Returns a file handle in write mode to an empty temp file.
245
247 Steve Bertrand, "<steveb at cpan.org>"
248
250 Please report any bugs or feature requests to
251 <https://github.com/stevieb9/file-edit-portable/issues>
252
254 <https://github.com/stevieb9/file-edit-portable>
255
257 CPAN Testers: <http://matrix.cpantesters.org/?dist=File-Edit-Portable>
258
260 You can find documentation for this module with the perldoc command.
261 perldoc File::Edit::Portable
263
265 Copyright 2022 Steve Bertrand.
266 This program is free software; you can redistribute it and/or modify it
268 under the terms of either: the GNU General Public License as published
269 by the Free Software Foundation; or the Artistic License.
270 See <http://dev.perl.org/licenses/> for more information.
272perl v5.38.0 2023-07-20 File::Edit::Portable(3)