NAME

Sort::Key::Merger - Perl extension for merging sorted things

SYNOPSIS

  use Sort::Key::Merger qw(keymerger);

  sub line_key_value {

      # $_[0] is available as a scratchpad that persist
      # between calls for the same $_;
      unless (defined $_[0]) {
          # so we use it to cache the file handle when we
	  # open a file on the first read
	  open $_[0], "<", $_
	      or croak "unable to open $_";
      }

      # don't get confused by this while loop, it's only
      # used to ignore empty lines
      my $fh = $_[0];
      local $_; # break $_ aliasing;
      while (<$fh>) {
	  next if /^\s*$/;
	  chomp;
	  if (my ($key, $value) = /^(\S+)\s+(.*)$/) {
	      return ($key, $value)
	  }
	  warn "bad line $_"
      }

      # signals the end of the data by returning an
      # empty list
      ()
  }

  # create a merger object:
  my $merger = keymerger { line_key_value } @ARGV;

  # sort and write the values:
  my $value;
  while (defined($value=$merger->())) {
      print "value: $value\n"
  }

DESCRIPTION

Sort::Key::Merger allows to merge presorted collections of things based on some (calculated) key.

EXPORT

None by default.

The functions described below can be exported requesting so explicitly, i.e.:

use Sort::Key::Merger qw(keymerger);

FUNCTIONS

keymerger { generate_key_value_pair } @sources;

merges the (presorted) generated values sorted by their keys lexicographically.

Every item in @source is aliased by $_ and then the user defined subroutine generate_key_value_pair called. The result from that subroutine call should be a (key, value) pair. Keys are used to determine the order in which the values are sorted and returned.

generate_key_value_pair can return an empty list to indicate that a source has become exhausted.

The result from keymerger is another subroutine that works as a generator. It can be called as:

my $next = &$merger;

or

my $next = $merger->();

In scalar context it returns the next value or undef if all the sources have been exhausted. In list context it returns all the values remaining from the sources merged in a sorted list.

NOTE: an additional argument is passed to the generate_key_value_pair callback in $_[0]. It is to be used as a scrachpad, its value is associated to the current source and will perdure between calls from the same generator, i.e.:

  my $merger = keymerger {

      # use $_[0] to cache an open file handler:
      $_[0] or open $_[0], '<', $_
	  or croak "unable to open $_";

      my $fh = $_[0];
      local $_;
      while (<$fh>) {
	  chomp;
	  return $_ => $_;
      }
      ();
  } ('/tmp/foo', '/tmp/bar');

This function honours the use locale pragma.

nkeymerger { generate_key_value_pair } @sources

is like keymerger but compares the keys numerically.

This function honours the use integer pragma.

filekeymerger { generate_key } @files;

returns a merger subroutine that returns lines read from @files sorted by the keys that generate_key generates.

@files can contain file names or handles for already open files.

generate_key is called with the line just read on $_ and has to return the sorting key for it. If its return value is undef the line is ignored.

The line can be modified inside generate_key changing $_, i.e.:

my $merger = filekeymerger {
    chomp($_); #             <-- here
    return undef if /^\s*$/;
    substr($_, -1, 10)
} @ARGV;

Finally, $/ can be changed from its default value to read the files in chunks other than lines.

The return value from this function is a subroutine reference that on successive calls returns the sorted elements; or all elements in one go when called in list context, i.e.:

my $merger = filekeymerger { (split)[0] } @ARGV;
my @sorted = $merger->();

This function honours the use locale pragma.

nfilekeymerger { generate_key } @files;

is like filekeymerger but the keys are compared numerically.

This function honours the use integer pragma.

SEE ALSO

Sort::Key, locale, integer, perl core sort function.

AUTHOR

Salvador Fandiño, <sfandino@yahoo.com>

COPYRIGHT AND LICENSE

Copyright (C) 2005 by Salvador Fandiño.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.