README for Sort::Naturally
                                       Time-stamp: "2001-05-25 21:17:33 MDT"

                           Sort::Naturally

[extracted from the Pod...]

NAME
    Sort::Naturally -- sort lexically, but sort numeral parts
    numerically

SYNOPSIS
      @them = nsort(qw(
       foo12a foo12z foo13a foo 14 9x foo12 fooa foolio Foolio Foo12a
      ));
      print join(' ', @them), "\n";

    Prints:

      9x 14 foo fooa foolio Foolio foo12 foo12a Foo12a foo12z foo13a

    (Or "foo12a" + "Foo12a" and "foolio" + "Foolio" and might be
    switched, depending on your locale.)

DESCRIPTION
    This module exports two functions, nsort and ncmp; they are
    used in implementing my idea of a "natural sorting"
    algorithm.  Under natural sorting, numeric substrings are
    compared numerically, and other word-characters are compared
    lexically.

    This is the way I define natural sorting:

    o    Non-numeric word-character substrings are sorted
         lexically, case-insensitively: "Foo" comes between
         "fish" and "fowl".

    o    Numeric substrings are sorted numerically:  "100" comes
         after "20", not before.

    o    \W substrings (neither words-characters nor digits) are
         ignored.

    o    Our use of \w, \d, \D, and \W is locale-sensitive:
         Sort::Naturally uses a use locale statement.

    o    When comparing two strings, where a numeric substring
         in one place is not up against a numeric substring in
         another, the non-numeric always comes first.  This is
         fudged by reading pretending that the lack of a number
         substring has the value -1, like so:

           foo       =>  "foo",  -1
           foobar    =>  "foo",  -1,  "bar"
           foo13     =>  "foo",  13,
           foo13xyz  =>  "foo",  13,  "xyz"

         That's so that "foo" will come before "foo13", which
         will come before "foobar".

    o    The start of a string is exceptional: leading non-\W
         (non-word, non-digit) components are are ignored, and
         numbers come before letters.

    o    I define "numeric substring" just as sequences matching
         m/\d+/ -- scientific notation, commas, decimals, etc.,
         are not seen.  If your data has thousands separators in
         numbers ("20,000 Leagues Under The Sea" or "20.000
         lieues sous les mers"), consider stripping them before
         feeding them to nsort or ncmp.

[end Pod extract]


INSTALLATION

You install Sort::Naturally, as you would install any perl module
library, by running these commands:

  perl Makefile.PL
  make
  make test
  make install

If you want to install a private copy of Sort::Naturally in your home
directory, then you should try to produce the initial Makefile with
something like this command:

 perl Makefile.PL LIB=~/perl

See perldoc perlmodinstall for more information on installing modules.


DOCUMENTATION

POD-format documentation is included in Naturally.pm.  POD is readable
with the 'perldoc' utility.  See ChangeLog for recent changes.


SUPPORT

Questions, bug reports, useful code bits, and suggestions for
Sort::Naturally should just be sent to me at [email protected]


AVAILABILITY

The latest version of Sort::Naturally is available from the
Comprehensive Perl Archive Network (CPAN).  Visit
<http://www.perl.com/CPAN/> to find a CPAN site near you.


COPYRIGHT

Copyright 2001, Sean M. Burke <[email protected]>, all rights
reserved.

The programs and documentation in this dist are distributed in
the hope that they will be useful, but without any warranty; without
even the implied warranty of merchantability or fitness for a
particular purpose.

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