1File::Flat(3) User Contributed Perl Documentation File::Flat(3)
2
6 File::Flat - Implements a flat filesystem
7
9 version 1.07
10
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 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 All methods are statically called, for example, to write some stuff to
26 a file.
27 use File::Flat;
29 File::Flat->write( 'filename', 'file contents' );
30 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 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 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 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 #!/usr/bin/perl
51 use strict;
53 use File::Flat;
54 delete_files(@ARGV);
56 exit();
57 # 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 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
71 exists $filename
72 Tests for the existence of the file. This is an exact duplicate of the
73 -e function.
74 isaFile $filename
76 Tests whether "filename" is a file. This is an exact duplicate of the
77 -f function.
78 isaDirectory $filename
80 Test whether "filename" is a directory. This is an exact duplicate of
81 the -d function.
82 canRead $filename
84 Does the file or directory exist, and can we read from it.
85 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 canReadWrite $filename
91 Does a file or directory exist, and can we both read and write it.
92 canExecute $filename
94 Does a file or directory exist, and can we execute it.
95 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 canRemove $filename
101 Can we remove the file or directory.
102 isaText $filename
104 Does the file "filename" exist, and is it a text file.
105 isaBinary $filename
107 Does the file "filename" exist, and is it a binary file.
108 fileSize $filename
110 If the file exists, returns its size in bytes. Returns undef if the
111 file does not exist.
112 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 In the single argument form, it takes modes in the form [mode]filename.
119 For example, all the following are valid.
120 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 In the two argument form, it takes the following
128 File::Flat->open( '<', 'filename' );
130 File::Flat->open( '>', 'filename' );
131 File::Flat->open( '>>', 'filename' );
132 File::Flat->open( '+<', 'filename' );
133 It does not support the more esoteric forms of open, such us opening to
135 a pipe or other such things.
136 On successfully opening the file, it returns it as an IO::File object.
138 Returns undef on error.
139 getReadHandle $filename
141 The same as File::Flat->open( '<', 'filename' )
142 getWriteHandle $filename
144 The same as File::Flat->open( '>', 'filename' )
145 getAppendHandle $filename
147 The same as File::Flat->open( '>>', 'filename' )
148 getReadWriteHandle $filename
150 The same as File::Flat->open( '+<', 'filename' )
151 read $filename
153 Opens and reads in an entire file, chomping as needed.
154 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 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 On success, returns a reference to a scalar, containing the entire
165 file. Returns undef on error.
166 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 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 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 Returns true on success, and undef on error.
186 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 This is the method you should be using to write to log files, etc.
192 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 This method otherwise acts the same as "write".
201 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 For example "<File::Flat-"( './this', './a/b/c/d/that' );>> will create
208 the directory structure required as needed.
209 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 "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 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 remove $filename [, $prune ]
226 The "remove" method will remove a file, or recursively remove a
227 directory.
228 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 Returns true if the deletion (and pruning if requested) was a success,
235 or "undef" otherwise.
236 prune $filename
238 For a file that has already been delete, "prune" will work upwards,
239 removing any empty directories it finds.
240 For anyone familiar with CVS, it is similar to the "update -P" flag.
242 Returns true, or "undef" on error.
244 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 Returns true on success, or undef on error.
252 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 An optional file mode ( default 0755 ) can be provided.
258 Returns true on success, returns undef on error.
260
262 Function interface to be written, like File::Spec::Functions, to
263 provide importable functions.
264 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
270 File::Spec, <http://ali.as/>
271
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
278 Adam Kennedy <adamk@cpan.org>
279
281 • Adam Kennedy <adam@ali.as>
282 • Karen Etheridge <ether@cpan.org>
284
286 This software is copyright (c) 2002 by Adam Kennedy.
287 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.
290perl v5.38.0 2023-07-20 File::Flat(3)