=pod

=head1 NAME

Data::Range::Compare::Stream::Iterator::File - Simple File Iterator

=head1 SYNOPSIS

  use Data::Range::Compare::Stream;
  use Data::Range::Compare::Stream::Iterator::File;

  my $iterator=Data::Range::Compare::Stream::Iterator::File->new(
    filename=>'some_file.csv',
  );

  while($iterator->has_next) {
    my $next_range=$iterator->get_next;
    print $next_range,"\n";
  }

=head1 DESCRIPTION

This module implements a very simple file iterator interface.  This iterator interface assumes that the data is pre-sorted.  The result objects returned are ranges: The class the objects are constructed from is determined by $iterator->NEW_FROM.  Parsing is handled by $iterator->parse_line.

=head2 OO Methods

=over 3

=item * my $iterator=new Data::Range::Compare::Stream::Iterator::File;

Instance Constructor, all arguments are optional
  
One of the following arguments is mandatory:

  filename=>'source_file.csv'  
    # the file is assumed to be an absolute or relative path to the file location.

  fh=>\*GLOB|IO::File->new('somefile')
    # The object itself is assumed to be an open file handle
    # filename will be set to the object ref of the fh=>xxx object

Optional arguments:

   factory_instance =>$obj
     # defines the object that implements the $obj->factory($start,$end,$data).
     # new ranges are constructed from the factory interfcae.  If a factory interface
     # is not created an instance of Data::Range::Compare::Stream is assumed.

   NEW_FROM=>'Data::Range::Compare::Stream',
     # Depricated!
     # sets the object class new ranges will be created from

   parse_line=>undef|code_ref
     # Default: undef, Sets the code ref to be used when parsing a line
     # if not set the default internals will be used

   result_to_line=>undef|code_ref
     # Default: undef, Sets the code ref used to convert a result to a line that can be parsed
     # if not set the default internals will be used

=item * if($iterator->in_error) { ... }

Returns true if there was a problem opening the file.

=item * my $class=$iterator->NEW_FROM;

$class will contain the name of the class new ranges are to be constructed from.  The resulting class is required to extend or implement Data::Range::Compare::Stream.

=item * my $ref=$self->parse_line($line);

Given a $line returns the arguments required to construct an object that extends or implements Data::Range::Compare::Stream.  When overloading or passing in constructor arguments that provide a call back make sure result_to_line produces the expected line parse_line expects.

  sub parse_line {
    my ($self,$line)=@_;
    return $self->{parse_line}->($line) if defined($self->{parse_line});
    chomp $line;
    [split /\s+/,$line];
  }

=item * while($iterator->has_next) { do something }

Returns true when there are more rows to fetch.

=item * my $range=$iterator->get_next;

Returns the next $range from the given source file.

=item * my $line=$iterator->result_to_line($range);

Given a $range from $iterator->get_next, this interface converts the $range object into a line that can be parsed by $iterator->parse_line($line).  Think of this function as a data serializer for range objects generated by an $iterator object.  The code can be described as follows:

  sub result_to_line {
    my ($self,$range)=@_;
    my $line=$range->range_start_to_string.' '.$range->range_end_to_string."\n";
    return $line;
  }

=item * my $size=$iterator->get_size

Returns the number of lines in the source file.

=item * my $pos=$iterator->get_pos;

Returns the current line the iterator is on.

=back

=head1 SEE ALSO

Data::Range::Compare::Stream::Cookbook

=head1 AUTHOR

Michael Shipper

=head1 Source-Forge Project

As of version 0.001 the Project has been moved to Source-Forge.net

L<Data Range Compare|https://sourceforge.net/projects/data-range-comp/>
L<https://sourceforge.net/projects/data-range-comp/>

=head1 COPYRIGHT

Copyright 2011 Michael Shipper.  All rights reserved.

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

=cut