LICENSE

Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

CONTACT

Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.

Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.

NAME

Bio::EnsEMBL::Utils::IO

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

METHODS

See subroutines.

MAINTAINER

$Author$

VERSION

$Revision$

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

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

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

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

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

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

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

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

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

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
              L<process_to_array>.
Returntype  : ArrayRef
Example     : my $contents_array = fh_to_array($fh);
Exceptions  : None
Status      : Stable

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

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

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

work_with_file

Arg [1]     : string $file
Arg [2]     : string; $mode
              Supports all modes specified by the C<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

gz_work_with_file

Arg [1]     : string $file
Arg [2]     : string; $mode
              Supports modes like C<r>, C<w>, C<\>> and C<\<>
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

bz_work_with_file

Arg [1]     : string $file
Arg [2]     : string; $mode
              Supports modes like C<r>, C<w>, C<\>> and C<\<>
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

zip_work_with_file

Arg [1]     : string $file
Arg [2]     : string; $mode
              Supports modes like C<r>, C<w>, C<\>> and C<\<>
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

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;

                # 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

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

cpanm Bio::EnsEMBL

perl -MCPAN -e shell
install Bio::EnsEMBL