Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
File::Flat(3)	      User Contributed Perl Documentation	 File::Flat(3)

NAME
       File::Flat - Implements a flat filesystem

VERSION
       version 1.07

DESCRIPTION
       File::Flat implements a flat filesystem.	A flat filesystem is a
       filesystem in which directories do not exist. It	provides an
       abstraction over	any normal filesystem which makes it appear as if
       directories do not exist. In effect, it will automatically create
       directories as needed. This is create for things	like install scripts
       and such, as you	never need to worry about the existence	of
       directories, just write to a file, no matter where it is.

   Comprehensive Implementation
       The implementation of File::Flat	is extremely comprehensive in scope.
       It has methods for all standard file interaction	tasks, the -X series
       of tests, and some other	things,	such as	slurp.

       All methods are statically called, for example, to write	some stuff to
       a file.

	 use File::Flat;
	 File::Flat->write( 'filename',	'file contents'	);

   Use of other	modules
       File::Flat tries	to use more task orientated modules wherever possible.
       This includes the use of	File::Copy, File::Copy::Recursive,
       File::Remove and	others.	These are mostly loaded	on-demand.

   Pruning and $AUTO_PRUNE
       "Pruning" is a technique	where empty directories	are assumed to be
       useless,	and thus empty removed whenever	one is created.	Thus, when
       some other task has the potential to leave an empty directory, it is
       checked and deleted if it is empty.

       By default File::Flat does not prune, and pruning must be done
       explicitly, via either the "prune" in File::Flat	method,	or by setting
       the second argument to the "remove" in File::Flat method	to be true.

       However by setting the global $AUTO_PRUNE variable to true, File::Flat
       will automatically prune	directories at all times. You should generally
       use this	locally, such as in the	following example.

	 #!/usr/bin/perl

	 use strict;
	 use File::Flat;

	 delete_files(@ARGV);
	 exit();

	 # Recursively delete and prune	all files provided on the command line
	 sub delete_files {
	       local $File::Flat::AUTO_PRUNE = 1;
	       foreach my $file	( @_ ) {
		       File::Flat->remove( $file ) or die "Failed to delete $file";
	       }
	 }

   Non-Unix platforms
       As of version 0.97 File::Flat should work correctly on Win32. Other
       platforms (such as VMS) are believed to work, but require confirmation.

METHODS
   exists $filename
       Tests for the existence of the file.  This is an	exact duplicate	of the
       -e function.

   isaFile $filename
       Tests whether "filename"	is a file.  This is an exact duplicate of the
       -f function.

   isaDirectory	$filename
       Test whether "filename" is a directory.	This is	an exact duplicate of
       the -d function.

   canRead $filename
       Does the	file or	directory exist, and can we read from it.

   canWrite $filename
       Does the	file or	directory exist, and can we write to it	OR can we
       create the file or directory.

   canReadWrite	$filename
       Does a file or directory	exist, and can we both read and	write it.

   canExecute $filename
       Does a file or directory	exist, and can we execute it.

   canOpen $filename
       Is this something we can	open a filehandle to. Returns true if filename
       exists, is a file, and we can read from it.

   canRemove $filename
       Can we remove the file or directory.

   isaText $filename
       Does the	file "filename"	exist, and is it a text	file.

   isaBinary $filename
       Does the	file "filename"	exist, and is it a binary file.

   fileSize $filename
       If the file exists, returns its size in bytes.  Returns undef if	the
       file does not exist.

   open	[ $mode, ] $filename
       Rough analogue of the open function, but	creates	directories on demand
       as needed. Supports most	of the normal options to the normal open
       function.

       In the single argument form, it takes modes in the form [mode]filename.
       For example, all	the following are valid.

	 File::Flat->open( 'filename' );
	 File::Flat->open( '<filename' );
	 File::Flat->open( '>filename' );
	 File::Flat->open( '>>filename'	);
	 File::Flat->open( '+<filename'	);

       In the two argument form, it takes the following

	 File::Flat->open( '<',	'filename' );
	 File::Flat->open( '>',	'filename' );
	 File::Flat->open( '>>', 'filename' );
	 File::Flat->open( '+<', 'filename' );

       It does not support the more esoteric forms of open, such us opening to
       a pipe or other such things.

       On successfully opening the file, it returns it as an IO::File object.
       Returns undef on	error.

   getReadHandle $filename
       The same	as File::Flat->open( '<', 'filename' )

   getWriteHandle $filename
       The same	as File::Flat->open( '>', 'filename' )

   getAppendHandle $filename
       The same	as File::Flat->open( '>>', 'filename' )

   getReadWriteHandle $filename
       The same	as File::Flat->open( '+<', 'filename' )

   read	$filename
       Opens and reads in an entire file, chomping as needed.

       In array	context, it returns an array containing	each line of the file.
       In scalar context, it returns a reference to an array containing	each
       line of the file. It returns undef on error.

   slurp $filename
       The "slurp" method 'slurps' a file in. That is it attempts to read the
       entire file into	a variable in as quick and memory efficient method as
       possible.

       On success, returns a reference to a scalar, containing the entire
       file.  Returns undef on error.

   write $filename, ( $content | \$content | \@content )
       The "write" method is the main method for writing content to a file.
       It takes	two arguments, the location to write to, and the content to
       write, in several forms.

       If the file already exists, it will be clobbered	before writing starts.
       If the file doesn't exists, the file and	any directories	will be
       created as needed.

       Content can be provided in three	forms. The contents of a scalar
       argument	will be	written	directly to the	file. You can optionally pass
       a reference to the scalar. This is recommended when the file size is
       bigger than a few thousand characters, is it does not duplicate the
       file contents in	memory.	 Alternatively,	you can	pass the content as a
       reference to an array containing	the contents. To ensure	uniformity,
       "write" will add	a newline to each line,	replacing any existing newline
       as needed.

       Returns true on success,	and undef on error.

   append $filename, ( $content	| \$content | \@content	)
       This method is the same as "write", except that it appends to the end
       of an existing file ( or	creates	the file as needed ).

       This is the method you should be	using to write to log files, etc.

   overwrite $filename,	( $content | \$content | \@content )
       Performs	an atomic write	over a file. It	does this by writing to	a
       temporary file, and moving the completed	file over the top of the
       existing	file ( or creating a new file as needed	). When	writing	to a
       file that is on the same	partition as /tmp, this	should always be
       atomic.

       This method otherwise acts the same as "write".

   copy	$source, $target
       The "copy" method attempts to copy a file or directory from the source
       to the target. New directories to contain the target will be created as
       needed.

       For example "<File::Flat-"( './this', './a/b/c/d/that' );>> will	create
       the directory structure required	as needed.

       In the file copy	case, if the target already exists, and	is a writable
       file, we	replace	the existing file, retaining file mode and owners. If
       the target is a directory, we do	NOT copy into that directory, unlike
       with the	'cp' unix command. And error is	instead	returned.

       "copy" will also	do limited recursive copying or	directories. If	source
       is a directory, and target does not exists, a recursive copy of source
       will be made to target. If target already exists	( file or directory ),
       "copy" will returns with	an error.

   move	$source, $target
       The "move" method follows the conventions of the	'mv' command, with the
       exception that the directories containing target	will of	course be
       created on demand.

   remove $filename [, $prune ]
       The "remove" method will	remove a file, or recursively remove a
       directory.

       If a second (true) argument is provided,	then once the file or
       directory has been deleted, the method will the automatically work its
       way upwards pruning (deleting) empty and	thus presumably	useless
       directories.

       Returns true if the deletion (and pruning if requested) was a success,
       or "undef" otherwise.

   prune $filename
       For a file that has already been	delete,	"prune"	will work upwards,
       removing	any empty directories it finds.

       For anyone familiar with	CVS, it	is similar to the "update -P" flag.

       Returns true, or	"undef"	on error.

   truncate $filename [, $size ]
       The "truncate" method will truncate an existing file to a particular
       size.  A	size of	0 ( zero ) is used if no size is provided. If the file
       does not	exists,	it will	be created, and	set to 0. Attempting to
       truncate	a directory will fail.

       Returns true on success,	or undef on error.

   makeDirectory $directory [, mode ]
       In the case where you do	actually have to create	a directory only, the
       "makeDirectory" method can be used to create a directory	or any depth.

       An optional file	mode ( default 0755 ) can be provided.

       Returns true on success,	returns	undef on error.

TO DO
       Function	interface to be	written, like File::Spec::Functions, to
       provide importable functions.

       There's something bigger	here too, I'm not exactly sure what it is, but
       I think there might be the beginnings of	a unified filesystem interface
       here... FSI.pm

SEE ALSO
       File::Spec, <http://ali.as/>

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

AUTHOR
       Adam Kennedy <adamk@cpan.org>

CONTRIBUTORS
       o   Adam	Kennedy	<adam@ali.as>

       o   Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2002 by Adam Kennedy.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.0			  2020-08-23			 File::Flat(3)

NAME | VERSION | DESCRIPTION | METHODS | TO DO | SEE ALSO | SUPPORT | AUTHOR | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::Flat&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help