Bio::EnsEMBL::Utils::IO Class Reference

Public Member Functions
public Scalar	slurp ()
public void	spurt ()
public Scalar	gz_slurp ()
public Scalar	bz_slurp ()
public Scalar	zip_slurp ()
public ArrayRef	slurp_to_array ()
public ArrayRef	gz_slurp_to_array ()
public ArrayRef	bz_slurp_to_array ()
public ArrayRef	zip_slurp_to_array ()
public ArrayRef	fh_to_array ()
public ArrayRef	process_to_array ()
public void	iterate_lines ()
public void	iterate_file ()
public void	work_with_file ()
public void	gz_work_with_file ()
public void	bz_work_with_file ()
public void	zip_work_with_file ()
public Arrayref	filter_dir ()
public void	move_data ()

Detailed Description

Synopsis

  use Bio::EnsEMBL::Utils::IO qw/slurp work_with_file slurp_to_array fh_to_array/;
  #or
  # use Bio::EnsEMBL::Utils::IO qw/:slurp/; # brings in any method starting with slurp
  # use Bio::EnsEMBL::Utils::IO qw/:array/; # brings in any method which ends with _array
  # use Bio::EnsEMBL::Utils::IO qw/:gz/;    # brings all methods which start with gz_
  # use Bio::EnsEMBL::Utils::IO qw/:bz/;    # brings all methods which start with bz_
  # use Bio::EnsEMBL::Utils::IO qw/:zip/;   # brings all methods which start with zip_
  # use Bio::EnsEMBL::Utils::IO qw/:all/;   # brings all methods in
 
# As a scalar
my $file_contents = slurp('/my/file/location.txt');
print length($file_contents);
 
# As a ref
my $file_contents_ref = slurp('/my/file/location.txt', 1);
print length($$file_contents_ref);
 
# Sending it to an array
my $array = slurp_to_array('/my/location');
work_with_file('/my/location', 'r', sub {
  $array = process_to_array($_[0], sub {
    #Gives us input line by line
    return "INPUT: $_";
  });
});
 
# Simplified vesion but without the post processing
$array = fh_to_array($fh);
 
# Sending this back out to another file
work_with_file('/my/file/newlocation.txt', 'w', sub {
  my ($fh) = @_;
  print $fh $$file_contents_ref;
  return;
});
 
# Gzipping the data to another file
gz_work_with_file('/my/file.gz', 'w', sub {
  my ($fh) = @_;
  print $fh $$file_contents_ref;
  return;
});
 
# Working with a set of lines manually
work_with_file('/my/file', 'r', sub {
  my ($fh) = @_;
  iterate_lines($fh, sub {
    my ($line) = @_;
    print $line; #Send the line in the file back out
    return;
  });
  return;
});
 
# Doing the same in one go
iterate_file('/my/file', sub {
  my ($line) = @_;
  print $line; #Send the line in the file back out
  return;
});
 
# Move all data from one file handle to another. Bit like a copy
move_data($src_fh, $trg_fh);

Description

A collection of subroutines aimed to helping IO based operations

Definition at line 80 of file IO.pm.

Member Function Documentation

bz_slurp()

public Scalar Bio::EnsEMBL::Utils::IO::bz_slurp

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean; $want_ref Indicates if we want to return a scalar reference
  Arg [3]     : boolean; $binary
  Arg [4]     : HashRef arguments to pass into IO compression layers
  Description : Forces the contents of a file into a scalar. This is the
                fastest way to get a file into memory in Perl. You can also
                get a scalar reference back to avoid copying the file contents
                in Scalar references. If the input file is binary then specify
                with the binary flag
  Returntype  : Scalar or reference of the file contents depending on arg 2
  Example     :

my $contents = slurp('/tmp/file.txt.bz2');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

bz_slurp_to_array()

public ArrayRef Bio::EnsEMBL::Utils::IO::bz_slurp_to_array

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean $chomp
  Arg [3]     : HashRef arguments to pass into IO compression layers
  Description : Sends the contents of the given bzipped file into an ArrayRef
  Returntype  : ArrayRef
  Example     :

my $contents_array = bz_slurp_to_array('/tmp/file.txt.bz2');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

bz_work_with_file()

public void Bio::EnsEMBL::Utils::IO::bz_work_with_file

(

)

  Arg [1]     : string $file
  Arg [2]     : string; $mode
                Supports modes like r, w, > and <
  Arg [3]     : CodeRef the callback which is given the open file handle as
                its only argument
  Arg [4]     : HashRef used to pass options into the IO
                compression/uncompression modules
  Description : Performs the nitty gritty of checking if a file handle is open
                and closing the resulting filehandle down.
  Returntype  : None
  Example     :

bz_work_with_file('/tmp/out.txt.bz2', 'w', sub {
                 my ($fh) = @_;
                 print $fh 'hello';
                 return;
               });

  Exceptions  : If we could not work with the file due to permissions
  Status      : Stable

Code:

fh_to_array()

public ArrayRef Bio::EnsEMBL::Utils::IO::fh_to_array

(

)

  Arg [1]     : Glob/IO::Handle $fh
  Arg [2]     : boolean $chomp
  Description : Sends the contents of the given filehandle into an ArrayRef.
                Will perform chomp on each line if specified. If you require
                any more advanced line based processing then see
                process_to_array.
  Returntype  : ArrayRef
  Example     :

my $contents_array = fh_to_array($fh);

  Exceptions  : None
  Status      : Stable

Code:

filter_dir()

public Arrayref Bio::EnsEMBL::Utils::IO::filter_dir

(

)

  Arg [1]     : String; directory
  Arg [2]     : CodeRef; the callback which is given a file in the
                directory as its only argument
  Description : Return the lexicographically sorted content of a directory.
                The callback allows to specify the criteria an entry in
                the directory must satisfy in order to appear in the content.
  Returntype  : Arrayref; list with the filtered files/directory
  Example     :

 filter_dir('/tmp', sub {
                  my $file = shift;
 
@section autotoc_md32 select perl scripts in the directory
                  return $file if $file =~ /\.pl$/;
                });

  Exceptions  : If the directory cannot be opened or its handle
                cannot be closed
  Status      : Stable

Code:

gz_slurp()

public Scalar Bio::EnsEMBL::Utils::IO::gz_slurp

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean; $want_ref Indicates if we want to return a scalar reference
  Arg [3]     : boolean; $binary
  Arg [4]     : HashRef arguments to pass into IO compression layers
  Description : Forces the contents of a file into a scalar. This is the
                fastest way to get a file into memory in Perl. You can also
                get a scalar reference back to avoid copying the file contents
                in Scalar references. If the input file is binary then specify
                with the binary flag
  Returntype  : Scalar or reference of the file contents depending on arg 2
  Example     :

my $contents = slurp('/tmp/file.txt.gz');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

gz_slurp_to_array()

public ArrayRef Bio::EnsEMBL::Utils::IO::gz_slurp_to_array

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean $chomp
  Arg [3]     : HashRef arguments to pass into IO compression layers
  Description : Sends the contents of the given gzipped file into an ArrayRef
  Returntype  : ArrayRef
  Example     :

my $contents_array = gz_slurp_to_array('/tmp/file.txt.gz');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

gz_work_with_file()

public void Bio::EnsEMBL::Utils::IO::gz_work_with_file

(

)

  Arg [1]     : string $file
  Arg [2]     : string; $mode
                Supports modes like r, w, > and <
  Arg [3]     : CodeRef the callback which is given the open file handle as
                its only argument
  Arg [4]     : HashRef used to pass options into the IO
                compression/uncompression modules
  Description : Performs the nitty gritty of checking if a file handle is open
                and closing the resulting filehandle down.
  Returntype  : None
  Example     :

gz_work_with_file('/tmp/out.txt.gz', 'w', sub {
                 my ($fh) = @_;
                 print $fh 'hello';
                 return;
               });

  Exceptions  : If we could not work with the file due to permissions
  Status      : Stable

Code:

iterate_file()

public void Bio::EnsEMBL::Utils::IO::iterate_file

(

)

  Arg [1]     : string $file
  Arg [3]     : CodeRef the callback which is used to iterate the lines in
                the file
  Description : Iterates through each line from the given file and
                hands them to the callback one by one
  Returntype  : None
  Example     :

iterate_file('/my/file', sub { print "INPUT: $_"; });

  Exceptions  : If the file did not exist or if a callback was not given.
  Status      : Stable

Code:

iterate_lines()

public void Bio::EnsEMBL::Utils::IO::iterate_lines

(

)

  Arg [1]     : Glob/IO::Handle $fh
  Arg [2]     : CodeRef $callback
  Description : Iterates through each line from the given file handle and
                hands them to the callback one by one
  Returntype  : None
  Example     :

iterate_lines($fh, sub { print "INPUT: $_"; });

  Exceptions  : If the fh did not exist or if a callback was not given.
  Status      : Stable

Code:

move_data()

public void Bio::EnsEMBL::Utils::IO::move_data

(

)

  Arg [1]     : FileHandle $src_fh
  Arg [2]     : FileHandle $trg_fh
  Arg [3]     : int $buffer. Defaults to 8KB
  Description : Moves data from the given source filehandle to the target one
                using a 8KB buffer or user specified buffer
  Returntype  : None
  Example     :

move_data($src_fh, $trg_fh, 16*1024); # copy in 16KB chunks

  Exceptions  : If inputs were not as expected

Code:

process_to_array()

public ArrayRef Bio::EnsEMBL::Utils::IO::process_to_array

(

)

  Arg [1]     : Glob/IO::Handle $fh
  Arg [2]     : CodeRef $callback
  Description : Sends the contents of the given file handle into an ArrayRef
                via the processing callback. Assumes line based input.
  Returntype  : ArrayRef
  Example     :

my $array = process_to_array($fh, sub { return "INPUT: $_"; });

  Exceptions  : If the fh did not exist or if a callback was not given.
  Status      : Stable

Code:

slurp()

public Scalar Bio::EnsEMBL::Utils::IO::slurp

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean; $want_ref
  Arg [3]     : boolean; $binary
                Indicates if we want to return a scalar reference
  Description : Forces the contents of a file into a scalar. This is the
                fastest way to get a file into memory in Perl. You can also
                get a scalar reference back to avoid copying the file contents
                in Scalar references. If the input file is binary then specify
                with the binary flag
  Returntype  : Scalar or reference of the file contents depending on arg 2
  Example     :

my $contents = slurp('/tmp/file.txt');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

slurp_to_array()

public ArrayRef Bio::EnsEMBL::Utils::IO::slurp_to_array

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean $chomp
  Description : Sends the contents of the given file into an ArrayRef
  Returntype  : ArrayRef
  Example     :

my $contents_array = slurp_to_array('/tmp/file.txt');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

spurt()

public void Bio::EnsEMBL::Utils::IO::spurt

(

)

  Arg [1]     : string $file
  Arg [2]     : string $contents
  Arg [3]     : boolean; $append
  Arg [4]     : boolean; $binary
  Description : Convenient method to safely open a file and dump some content into it.
                $append can be set to append to the file instead of resetting it first.
                $binary can be set if the content you are printing is not plain-text.
  Returntype  : None
  Example     :

spurt('/tmp/file.txt', $contents);

  Exceptions  : If the file could not be created or was not writable
  Status      : Stable

Code:

work_with_file()

public void Bio::EnsEMBL::Utils::IO::work_with_file

(

)

  Arg [1]     : string $file
  Arg [2]     : string; $mode
                Supports all modes specified by the open() function as well as those
                supported by IO::File
  Arg [3]     : CodeRef the callback which is given the open file handle as
                its only argument
  Description : Performs the nitty gritty of checking if a file handle is open
                and closing the resulting filehandle down.
  Returntype  : None
  Example     :

work_with_file('/tmp/out.txt', 'w', sub {
                 my ($fh) = @_;
                 print $fh 'hello';
                 return;
               });

  Exceptions  : If we could not work with the file due to permissions
  Status      : Stable

Code:

zip_slurp()

public Scalar Bio::EnsEMBL::Utils::IO::zip_slurp

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean; $want_ref Indicates if we want to return a scalar reference
  Arg [3]     : boolean; $binary
  Arg [4]     : HashRef arguments to pass into IO compression layers
  Description : Forces the contents of a file into a scalar. This is the
                fastest way to get a file into memory in Perl. You can also
                get a scalar reference back to avoid copying the file contents
                in Scalar references. If the input file is binary then specify
                with the binary flag
  Returntype  : Scalar or reference of the file contents depending on arg 2
  Example     :

my $contents = slurp('/tmp/file.txt.zip');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

zip_slurp_to_array()

public ArrayRef Bio::EnsEMBL::Utils::IO::zip_slurp_to_array

(

)

  Arg [1]     : string $file
  Arg [2]     : boolean $chomp
  Arg [3]     : HashRef arguments to pass into IO compression layers
  Description : Sends the contents of the given zipped file into an ArrayRef
  Returntype  : ArrayRef
  Example     :

my $contents_array = zip_slurp_to_array('/tmp/file.txt.zip');

  Exceptions  : If the file did not exist or was not readable
  Status      : Stable

Code:

zip_work_with_file()

public void Bio::EnsEMBL::Utils::IO::zip_work_with_file

(

)

  Arg [1]     : string $file
  Arg [2]     : string; $mode
                Supports modes like r, w, > and <
  Arg [3]     : CodeRef the callback which is given the open file handle as
                its only argument
  Arg [4]     : HashRef used to pass options into the IO
                compression/uncompression modules
  Description : Performs the nitty gritty of checking if a file handle is open
                and closing the resulting filehandle down.
  Returntype  : None
  Example     :

zip_work_with_file('/tmp/out.txt.zip', 'w', sub {
                 my ($fh) = @_;
                 print $fh 'hello';
                 return;
               });

  Exceptions  : If we could not work with the file due to permissions
  Status      : Stable

Code:

---

The documentation for this class was generated from the following file:

• ensembl/modules/Bio/EnsEMBL/Utils/IO.pm