1File::Edit::Portable(3)User Contributed Perl DocumentatioFnile::Edit::Portable(3)
2
3
4

NAME

6       File::Edit::Portable - Read and write files while keeping the original
7       line-endings intact, no matter the platform.
8

SYNOPSIS

10           use File::Edit::Portable;
11
12           my $rw = File::Edit::Portable->new;
13
14           # read a file, replacing original file's line endings with
15           # that of the local platform's default
16
17           my $fh = $rw->read('file.txt');
18
19           # edit file in a loop, and re-write it with its original line endings
20
21           my $fh = $rw->read('file.txt');
22           my $wfh = $rw->tempfile;
23
24           while (<$fh>){
25               ...
26               print $wfh $_;
27           }
28
29           $rw->write(contents => $wfh);
30
31           # get an array of the file's contents, with line endings stripped off
32
33           my @contents = $rw->read('file.txt');
34
35           # write out a file using original file's record separator, into a new file,
36           # preserving the original
37
38           $rw->write(contents => \@contents, copy => 'file2.txt');
39
40           # replace original file's record separator with a new (custom) one
41
42           $rw->write(recsep => "\r\n", contents => \@contents);
43
44           # rewrite all files in a directory recursively with local
45           # platform's default record separator
46
47           $rw->dir(dir => '/path/to/files');
48
49           # insert new data into a file after a specified line number
50
51           $rw->splice(file => 'file.txt', line => $num, insert => \@contents);
52
53           # insert new data into a file after a found search term
54
55           $rw->splice(file => 'file.txt', find => 'term', insert => \@contents);
56
57           # get a file's record separator
58
59           $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

DESCRIPTION

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
69       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
78       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

EXPORT

86       None by default. See EXPORT_OK
87

EXPORT_OK

89       "recsep()", "platform_recsep()"
90

METHODS

92   "new"
93       Returns a new "File::Edit::Portable" object.
94
95   "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
100       In list context, will return an array, where each element is a line
101       from the file, with all line endings stripped off.
102
103       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
106   "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
112       Parameters:
113
114       "file => 'file.txt'"
115
116       Not needed if you've used "read()" to open the file. However, if you
117       have multiple "read()"s open, "write()" will die without the 'file'
118       param, as it won't know which file you're wanting to write.
119
120       "copy => 'file2.txt'"
121
122       Set this if you want to write to an alternate (new) file, rather than
123       the original.
124
125       "contents => $filehandle" or "contents => \@contents"
126
127       Mandatory - either an array with one line per element, or a file handle
128       (file handle is far less memory-intensive).
129
130       "recsep => "\r\n""
131
132       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,
135       "\n" for Unix and "\r" for Mac. Use a call to "platform_recsep()" as
136       the value to use the local platforms default separator.
137
138   "splice"
139       Inserts new data into a file after a specified line number or search
140       term.
141
142       Parameters:
143
144       "file => 'file.txt'"
145
146       Mandatory.
147
148       "insert => \@contents"
149
150       Mandatory - an array reference containing the contents to merge into
151       the file.
152
153       "copy => 'file2.txt'"
154
155       Optional - we'll read from "file", but we'll write to this new file.
156
157       "line => Integer"
158
159       Optional - Merge the contents on the line following the one specified
160       here.
161
162       "find => 'search term'"
163
164       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
170       "limit => Integer"
171
172       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
176       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
180       Returns an array of the modified file contents.
181
182   "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
188       Parameters:
189
190       "dir => '/path/to/files'"
191
192       Mandatory.
193
194       "types => ['*.txt', '*.dat']"
195
196       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
200       "maxdepth => Integer"
201
202       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
206       "recsep => "\r\n""
207
208       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
212       "list => 1"
213
214       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
217       Default is disabled.
218
219   "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
223       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
228       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
231   "platform_recsep($want)"
232       Returns the the current platform's (OS) record separator in string
233       form.
234
235       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
240       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
243   "tempfile"
244       Returns a file handle in write mode to an empty temp file.
245

AUTHOR

247       Steve Bertrand, "<steveb at cpan.org>"
248

BUGS

250       Please report any bugs or feature requests to
251       <https://github.com/stevieb9/file-edit-portable/issues>
252

REPOSITORY

254       <https://github.com/stevieb9/file-edit-portable>
255

BUILD RESULTS (THIS VERSION)

257       CPAN Testers: <http://matrix.cpantesters.org/?dist=File-Edit-Portable>
258

SUPPORT

260       You can find documentation for this module with the perldoc command.
261
262           perldoc File::Edit::Portable
263
265       Copyright 2022 Steve Bertrand.
266
267       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
271       See <http://dev.perl.org/licenses/> for more information.
272
273
274
275perl v5.36.0                      2022-11-30           File::Edit::Portable(3)
Impressum