File::Flat(3pm)

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

NAME

6       File::Flat - Implements a flat filesystem
7

SYNOPSIS

DESCRIPTION

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

METHODS

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

TO DO

291       Function interface to be written, like File::Spec::Functions, to pro‐
292       vide importable functions.
293
294       There's something bigger here too, I'm not exactly sure what it is, but
295       I think there might be the beginings of a unified filesystem interface
296       here... FSI.pm
297

SUPPORT

299       Bugs should be filed at via the CPAN bug tracker at:
300
301       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Flat>
302
303       For other issues or comments, contact the author
304

AUTHORS

306       Adam Kennedy <adamk@cpan.org>
307

COPYRIGHT

312       Copyright (c) 2002 - 2006 Adam Kennedy. All rights reserved.  This pro‐
313       gram is free software; you can redistribute it and/or modify it under
314       the same terms as Perl itself.
315
316       The full text of the license can be found in the LICENSE file included
317       with this module.
318
319
320
321perl v5.8.8                       2007-01-13                     File::Flat(3)