/ 
Slackware-Slackget-0.17
River stage one • 1 direct dependent • 1 total dependent
/ Slackware::Slackget::File

NAME

Slackware::Slackget::File - A class to manage files.

VERSION

Version 1.0.5

SYNOPSIS

Slackware::Slackget::File is the class which represent a file for slack-get.

Access to hard disk are saved by taking a copy of the file in memory, so if you work on big file it may be a bad idea to use this module. Or maybe you have some interest to close the file while you don't work on it.

use Slackware::Slackget::File;

my $file = Slackware::Slackget::File->new('foo.txt'); # if foo.txt exist the constructor will call the Read() method
$file->add("an example\n");
$file->Write();
$file->Write("bar.txt"); # write foo.txt (plus the addition) into bar.txt
$file->Close(); # Free the memory !
$file->Read(); # But the Slackware::Slackget::File object is not destroy and you can re-load the file content
$file->Read("baz.txt"); # Or changing file (the object will be update with the new file)

The main advantage of this module is that you don't work directly on the file but on a copy. So you can make errors, they won't be wrote until you call the Write() method

** ATTENTION ** this module can fail to load file on non-UNIX system because it rely on the "file" and "awk" command line tools. Be sure to use the 'load-raw' => 1 constructor's option on such operating system (most probably the file type will be blank and no problem will happen... but it's still a possibility).

** ATTENTION 2 ** this module rely on bzip2 and gzip command line tools to uncompress the compressed files. On systems which does not support the `gzip -dc` or `bzip2 -dc`, trying to load compressed files will cause crashs, which can eventually lead to the end of the world...

CONSTRUCTOR

new

Take a filename as argument.

my $file = Slackware::Slackget::File->new('foo.txt'); # if foo.txt exist the constructor will call the Read() method
$file->add("an example\n");
$file->Write();
$file->Write("bar.txt");

This class try to determine the type of the file via the command `file` (so you need `file` in your path). If the type of the file is not in gzip, bzip2, ASCII or XML the constructor die()-ed. You can avoid that, if you need to work with unsupported file, by passing a "load-raw" parameter.

Additionnaly you can pass an file encoding (default is utf8). For example as a European I prefer that files are stored and compile in the iso-8859-1 charset so I use the following :

my $file = Slackware::Slackget::File->new('foo.txt','file-encoding' => 'iso-8859-1');

You can also disabling the auto load of the file by passing a parameter 'no-auto-load' => 1 :

my $file = Slackware::Slackget::File->new('foo.txt','file-encoding' => 'iso-8859-1', 'no-auto-load' => 1);

You can also pass an argument "mode" which take 'append or 'write' as value :

my $file = Slackware::Slackget::File->new('foo.txt','file-encoding' => 'iso-8859-1', 'mode' => 'rewrite');

This will decide how to open the file (> or >>). Default is 'write' ('>').

Note: for backward compatibility mode => "rewrite" is still accepted as a valid mode. It is an alias for "append"

You can also specify if the file must be open as binary or normal text with the "binary" argument. This one is boolean (0 or 1). The default value is 0 :

my $file = Slackware::Slackget::File->new('package.tgz','binary' => 1); # In real usage package.tgz will be read UNCOMPRESSED by Read().
my $file = Slackware::Slackget::File->new('foo.txt','file-encoding' => 'iso-8859-1', 'mode' => 'rewrite', binary => 0);

If you want to load a raw file without uncompressing it you can pass the "load-raw" parameter :

my $file = Slackware::Slackget::File->new('package.tgz','binary' => 1, 'load-raw' => 1);

FUNCTIONS

Read

Take a filename as argument, and load the file in memory.

$file->Read($filename);

You can call this method without passing parameters, if you have give a filename to the constructor.

$file->Read();

This method doesn't return the file, you must call Get_file() to do that.

Supported file formats : gzipped, bzipped and ASCII file are natively supported (for compressed formats you need to have gzip and bzip2 installed in your path).

If you specify load-raw => 1 to the constructor, read will load in memory a file even if the format is not recognize.

Lock_file (deprecated)

Same as lock_file, provided for backward compatibility.

lock_file

This method lock the file for slack-get application (not really for others...) by creating a file with the name of the current open file plus a ".lock". This is not a protection but an information system for slack-getd sub process. This method return undef if the lock can't be made.

my $file = new Slackware::Slackget::File ('test.txt');
$file->lock_file ; # create a file test.txt.lock

ATTENTION: You can only lock the current file of the object. With the previous example you can't do :

$file->Lock_file('toto.txt') ;

ATTENTION 2 : Don't forget to unlock your locked file :)

Unlock_file (deprecated)

Same as unlock_file(), provided for backward compatibility.

unlock_file

Unlock a locked file. Only the locker object can unlock a file ! Return 1 if all goes well, else return undef. Return 2 if the file was not locked. Return 0 (false in scalar context) if the file was locked but by another Slackware::Slackget::File object.

my $status = $file->unlock_file ;

Returned value are :

0 : error -> the file was locked by another instance of this class

1 : ok lock removed

2 : the file was not locked

undef : unable to remove the lock.

is_locked

Return 1 if the file is locked by a Slackware::Slackget::File object, else return undef.

print "File is locked\n" if($file->is_locked);

Write

Take a filename to write data and raw data

$file->Write($filename,@data);

You can call this method with just a filename (in this case the file currently loaded will be wrote in the file you specify)

$file->Write($another_filename) ; # Write the currently loaded file into $another_filename

You also can call this method without any parameter :

$file->Write ;

In this case, the Write() method will wrote data in memory into the last opened file (with Read() or new()).

The default encoding of this method is utf-8, pass an extra argument : file-encoding to the constructor to change that.

Add (deprecated)

Same as add(), provided for backward compatibility.

add

Take a table of lines and add them to the end of file image (in memory). You need to commit your change by calling the Write() method !

$file->add(@data);
or
$file->add($data);
or
$file->add("this is some data\n");

Get_file (deprecated)

Same as get_file(), provided for backward compatibility.

get_file

Return the current file in memory as an array.

@file = $file->get_file();

Get_line (deprecated)

Same as get_line(), provided for backward compatibility.

get_line

Return the $index line of the file (the index start at 0).

@file = $file->get_line($index);

Get_selection (deprecated)

Same as get_selection(), provided for backward compatibility.

get_selection

Same as get file but return only lines between $start and $stop.

my @array = $file->get_selection($start,$stop);

You can ommit the $stop parameter (in this case Get_line() return the lines from $start to the end of file)

Close

Free the memory. This method close the current file memory image. If you don't call the Write() method before closing, the changes you have made on the file are lost !

$file->Close();

Write_and_close (deprecated)

Same as write_and_close(), provided for backward compatibility.

write_and_close

An alias which call Write() and then Close();

$file->write_and_close();
or
$file->write_and_close("foo.txt");

encoding

Without parameter return the current file encoding, with a parameter set the encoding for the current file.

print "The current file encoding is ",$file->encoding,"\n"; # return the current encoding
$file->encoding('utf8'); # set the current file encoding to utf8

filename

Return the filename of the file which is currently process by the Slackware::Slackget::File instance.

print $file->filename

You can also set the filename :

$file->filename('foo.txt');

type (read only)

Return the current file type.

print $file->type

AUTHOR

DUPUIS Arnaud, <a.dupuis@infinityperl.org>

BUGS

Please report any bugs or feature requests to bug-Slackware-Slackget@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Slackware-Slackget. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Slackware::Slackget::File

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Bertrand Dupuis (yes my brother) for his contribution to the documentation.

COPYRIGHT & LICENSE

Copyright 2005 DUPUIS Arnaud, All Rights Reserved.

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