1File::Flat(3)         User Contributed Perl Documentation        File::Flat(3)
2
3
4

NAME

6       File::Flat - Implements a flat filesystem
7

VERSION

9       version 1.07
10

DESCRIPTION

12       File::Flat implements a flat filesystem. A flat filesystem is a
13       filesystem in which directories do not exist. It provides an
14       abstraction over any normal filesystem which makes it appear as if
15       directories do not exist. In effect, it will automatically create
16       directories as needed. This is create for things like install scripts
17       and such, as you never need to worry about the existence of
18       directories, just write to a file, no matter where it is.
19
20   Comprehensive Implementation
21       The implementation of File::Flat is extremely comprehensive in scope.
22       It has methods for all standard file interaction tasks, the -X series
23       of tests, and some other things, such as slurp.
24
25       All methods are statically called, for example, to write some stuff to
26       a file.
27
28         use File::Flat;
29         File::Flat->write( 'filename', 'file contents' );
30
31   Use of other modules
32       File::Flat tries to use more task orientated modules wherever possible.
33       This includes the use of File::Copy, File::Copy::Recursive,
34       File::Remove and others. These are mostly loaded on-demand.
35
36   Pruning and $AUTO_PRUNE
37       "Pruning" is a technique where empty directories are assumed to be
38       useless, and thus empty removed whenever one is created. Thus, when
39       some other task has the potential to leave an empty directory, it is
40       checked and deleted if it is empty.
41
42       By default File::Flat does not prune, and pruning must be done
43       explicitly, via either the "prune" in File::Flat method, or by setting
44       the second argument to the "remove" in File::Flat method to be true.
45
46       However by setting the global $AUTO_PRUNE variable to true, File::Flat
47       will automatically prune directories at all times. You should generally
48       use this locally, such as in the following example.
49
50         #!/usr/bin/perl
51
52         use strict;
53         use File::Flat;
54
55         delete_files(@ARGV);
56         exit();
57
58         # Recursively delete and prune all files provided on the command line
59         sub delete_files {
60               local $File::Flat::AUTO_PRUNE = 1;
61               foreach my $file ( @_ ) {
62                       File::Flat->remove( $file ) or die "Failed to delete $file";
63               }
64         }
65
66   Non-Unix platforms
67       As of version 0.97 File::Flat should work correctly on Win32. Other
68       platforms (such as VMS) are believed to work, but require confirmation.
69

METHODS

71   exists $filename
72       Tests for the existence of the file.  This is an exact duplicate of the
73       -e function.
74
75   isaFile $filename
76       Tests whether "filename" is a file.  This is an exact duplicate of the
77       -f function.
78
79   isaDirectory $filename
80       Test whether "filename" is a directory.  This is an exact duplicate of
81       the -d function.
82
83   canRead $filename
84       Does the file or directory exist, and can we read from it.
85
86   canWrite $filename
87       Does the file or directory exist, and can we write to it OR can we
88       create the file or directory.
89
90   canReadWrite $filename
91       Does a file or directory exist, and can we both read and write it.
92
93   canExecute $filename
94       Does a file or directory exist, and can we execute it.
95
96   canOpen $filename
97       Is this something we can open a filehandle to. Returns true if filename
98       exists, is a file, and we can read from it.
99
100   canRemove $filename
101       Can we remove the file or directory.
102
103   isaText $filename
104       Does the file "filename" exist, and is it a text file.
105
106   isaBinary $filename
107       Does the file "filename" exist, and is it a binary file.
108
109   fileSize $filename
110       If the file exists, returns its size in bytes.  Returns undef if the
111       file does not exist.
112
113   open [ $mode, ] $filename
114       Rough analogue of the open function, but creates directories on demand
115       as needed. Supports most of the normal options to the normal open
116       function.
117
118       In the single argument form, it takes modes in the form [mode]filename.
119       For example, all the following are valid.
120
121         File::Flat->open( 'filename' );
122         File::Flat->open( '<filename' );
123         File::Flat->open( '>filename' );
124         File::Flat->open( '>>filename' );
125         File::Flat->open( '+<filename' );
126
127       In the two argument form, it takes the following
128
129         File::Flat->open( '<', 'filename' );
130         File::Flat->open( '>', 'filename' );
131         File::Flat->open( '>>', 'filename' );
132         File::Flat->open( '+<', 'filename' );
133
134       It does not support the more esoteric forms of open, such us opening to
135       a pipe or other such things.
136
137       On successfully opening the file, it returns it as an IO::File object.
138       Returns undef on error.
139
140   getReadHandle $filename
141       The same as File::Flat->open( '<', 'filename' )
142
143   getWriteHandle $filename
144       The same as File::Flat->open( '>', 'filename' )
145
146   getAppendHandle $filename
147       The same as File::Flat->open( '>>', 'filename' )
148
149   getReadWriteHandle $filename
150       The same as File::Flat->open( '+<', 'filename' )
151
152   read $filename
153       Opens and reads in an entire file, chomping as needed.
154
155       In array context, it returns an array containing each line of the file.
156       In scalar context, it returns a reference to an array containing each
157       line of the file. It returns undef on error.
158
159   slurp $filename
160       The "slurp" method 'slurps' a file in. That is it attempts to read the
161       entire file into a variable in as quick and memory efficient method as
162       possible.
163
164       On success, returns a reference to a scalar, containing the entire
165       file.  Returns undef on error.
166
167   write $filename, ( $content | \$content | \@content )
168       The "write" method is the main method for writing content to a file.
169       It takes two arguments, the location to write to, and the content to
170       write, in several forms.
171
172       If the file already exists, it will be clobbered before writing starts.
173       If the file doesn't exists, the file and any directories will be
174       created as needed.
175
176       Content can be provided in three forms. The contents of a scalar
177       argument will be written directly to the file. You can optionally pass
178       a reference to the scalar. This is recommended when the file size is
179       bigger than a few thousand characters, is it does not duplicate the
180       file contents in memory.  Alternatively, you can pass the content as a
181       reference to an array containing the contents. To ensure uniformity,
182       "write" will add a newline to each line, replacing any existing newline
183       as needed.
184
185       Returns true on success, and undef on error.
186
187   append $filename, ( $content | \$content | \@content )
188       This method is the same as "write", except that it appends to the end
189       of an existing file ( or creates the file as needed ).
190
191       This is the method you should be using to write to log files, etc.
192
193   overwrite $filename, ( $content | \$content | \@content )
194       Performs an atomic write over a file. It does this by writing to a
195       temporary file, and moving the completed file over the top of the
196       existing file ( or creating a new file as needed ). When writing to a
197       file that is on the same partition as /tmp, this should always be
198       atomic.
199
200       This method otherwise acts the same as "write".
201
202   copy $source, $target
203       The "copy" method attempts to copy a file or directory from the source
204       to the target. New directories to contain the target will be created as
205       needed.
206
207       For example "<File::Flat-"( './this', './a/b/c/d/that' );>> will create
208       the directory structure required as needed.
209
210       In the file copy case, if the target already exists, and is a writable
211       file, we replace the existing file, retaining file mode and owners. If
212       the target is a directory, we do NOT copy into that directory, unlike
213       with the 'cp' unix command. And error is instead returned.
214
215       "copy" will also do limited recursive copying or directories. If source
216       is a directory, and target does not exists, a recursive copy of source
217       will be made to target. If target already exists ( file or directory ),
218       "copy" will returns with an error.
219
220   move $source, $target
221       The "move" method follows the conventions of the 'mv' command, with the
222       exception that the directories containing target will of course be
223       created on demand.
224
225   remove $filename [, $prune ]
226       The "remove" method will remove a file, or recursively remove a
227       directory.
228
229       If a second (true) argument is provided, then once the file or
230       directory has been deleted, the method will the automatically work its
231       way upwards pruning (deleting) empty and thus presumably useless
232       directories.
233
234       Returns true if the deletion (and pruning if requested) was a success,
235       or "undef" otherwise.
236
237   prune $filename
238       For a file that has already been delete, "prune" will work upwards,
239       removing any empty directories it finds.
240
241       For anyone familiar with CVS, it is similar to the "update -P" flag.
242
243       Returns true, or "undef" on error.
244
245   truncate $filename [, $size ]
246       The "truncate" method will truncate an existing file to a particular
247       size.  A size of 0 ( zero ) is used if no size is provided. If the file
248       does not exists, it will be created, and set to 0. Attempting to
249       truncate a directory will fail.
250
251       Returns true on success, or undef on error.
252
253   makeDirectory $directory [, mode ]
254       In the case where you do actually have to create a directory only, the
255       "makeDirectory" method can be used to create a directory or any depth.
256
257       An optional file mode ( default 0755 ) can be provided.
258
259       Returns true on success, returns undef on error.
260

TO DO

262       Function interface to be written, like File::Spec::Functions, to
263       provide importable functions.
264
265       There's something bigger here too, I'm not exactly sure what it is, but
266       I think there might be the beginnings of a unified filesystem interface
267       here... FSI.pm
268

SEE ALSO

270       File::Spec, <http://ali.as/>
271

SUPPORT

273       Bugs may be submitted through the RT bug tracker
274       <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Flat> (or
275       bug-File-Flat@rt.cpan.org <mailto:bug-File-Flat@rt.cpan.org>).
276

AUTHOR

278       Adam Kennedy <adamk@cpan.org>
279

CONTRIBUTORS

281       •   Adam Kennedy <adam@ali.as>
282
283       •   Karen Etheridge <ether@cpan.org>
284
286       This software is copyright (c) 2002 by Adam Kennedy.
287
288       This is free software; you can redistribute it and/or modify it under
289       the same terms as the Perl 5 programming language system itself.
290
291
292
293perl v5.38.0                      2023-07-20                     File::Flat(3)
Impressum