NAME

File::Butler - Handy collection of file manipulation tools

SYNOPSIS

  # Functional Interface

  use File::Butler;
  Butler( "somefile.txt", "read", \@lines );
  $single_line = Butler( "somefile.txt", "read" );
  Butler( "somefile.txt", "write", \@lines );
  Butler( "somefile.txt", "write", \$line );
  Butler( "somefile.txt", "append", \@data );
  Butler( "somefile.txt", "append", \$data );
  Butler( "somefile.txt", "prepend", \@data );
  Butler( "somefile.txt", "prepend", \$data );
  Butler( "/home/kurt", "dir", \@files );
  Butler( "somefile.txt", "srm" [, $passes] );
  ( $lines, $words, $characters ) = Butler( "somefile.txt", "wc" );

  # OO Interface

  use File::Butler;
  $ref = File::Butler->new();
  @lines = $ref->read( $file );
  $single_line = $ref->read( $file );
  $ref->write( $file, \@lines );
  $ref->write( $file, \$line );
  $ref->append( $file, \@lines );
  $ref->append( $file, \$line );
  $ref->prepend( $file, \@lines );
  $ref->prepend( $file, \$line );
  @files = $ref->dir( $directory );
  $ref->srm( $file [, $passes] );
  ( $lines, $words, $characters ) = $ref->wc( $file );

DESCRIPTION

This module is a handy collection of file manipulation tools, and was really designed as more of a convenience than anything else. All of the various functions are fairly self-explanatory.

Please note that starting with v3.00, an Object Oriented interface was added to File::Butler. For backwards compatability, the previous functional style will always be supported.

EXAMPLES

Butler( $file, ``read'', \@lines )

Reads the contents of $file and stores the contents in the array passed as a reference.

$single_line = Butler( $file, ``read'' )

Reads the contents of $file and returns the contents as a scalar.

Butler( $file, ``write'', \@lines )

No surprises here. Writes the contents of @lines into $file, clobbering the previous contents of $file.

Butler( $file, ``append'', \@lines )

Again, no surprises. Appends the contents of @lines to $file.

Butler( $file, ``prepend'', \@lines )

Prepends the contents of @lines to $file.

Butler( $directory, ``dir'', \@files )

Returns a list of the files in $directory, ignoring files that start with ``.'' (i.e., .htaccess)

Butler( $file, ``srm'' [, passes])

Writes over the contents of $file with a series of 0's and 1's the specified number of times, and then unlinks the file. If passes is not specified, it writes over the file once before unlinking. A total of 10 different overwrite methods are used. If more than 10 passes are specified, the cycle repeats. The cycle is as follows:

Pass 1: Random 0's and 1's; Pass 2: Same as #1; Pass 3: Same as #1; Pass 4: Same as #1; Pass 5: 010101; Pass 6: 101010; Pass 7: 100100; Pass 8: 010010; Pass 9: 000000; Pass 10: 111111

( $lines, $words, $characters ) = Butler( $file, ``wc'' )

Returns the number of lines, words, and characters in $file. This may or may not exactly match the Linux tool ``wc''. The number of words in this case is the number of word items matching the regular expression m/(\w+)/g;

AUTHOR

Kurt Kincaid, sifukurt@yahoo.com