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

METHODS

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

TO DO

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

SUPPORT

268       Bugs should be filed at via the CPAN bug tracker at:
269
270       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Flat
271       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Flat>
272
273       For other issues or comments, contact the author
274

AUTHORS

276       Adam Kennedy <adamk@cpan.org>
277

COPYRIGHT

282       Copyright 2002 - 2008 Adam Kennedy.
283
284       This program is free software; you can redistribute it and/or modify it
285       under the same terms as Perl itself.
286
287       The full text of the license can be found in the LICENSE file included
288       with this module.
289
290
291
292perl v5.12.0                      2008-03-24                     File::Flat(3)