File Coverage

blib/lib/Text/BibTeX/BibSort.pm

Criterion	Covered	Total	%
statement	55	65	84.6
branch	10	16	62.5
condition	5	9	55.5
subroutine	9	11	81.8
pod	1	6	16.6
total	80	107	74.7

# ----------------------------------------------------------------------
# NAME       : BibSort.pm
# CLASSES    : Text::BibTeX::BibSort
# RELATIONS  : sub-class of StructuredEntry
#              super-class of BibEntry
# DESCRIPTION: Provides methods for generating sort keys of entries
#              in a BibTeX-style bibliographic database.
# CREATED    : 1997/11/24, GPW (taken from Bib.pm)
# MODIFIED   :
# VERSION    : $Id$
# COPYRIGHT  : Copyright (c) 1997-2000 by Gregory P. Ward.  All rights
#              reserved.
#
#              This file is part of the Text::BibTeX library.  This is free
#              software; you can redistribute it and/or modify it under the
#              same terms as Perl itself.
# ----------------------------------------------------------------------

package Text::BibTeX::BibSort;
use strict;
use vars qw(@ISA $VERSION);

use Text::BibTeX::Structure;

@ISA = qw(Text::BibTeX::StructuredEntry);
$VERSION = 0.87;

use Text::BibTeX qw(purify_string change_case);

use Carp;

=head1 NAME

Text::BibTeX::BibSort - generate sort keys for bibliographic entries

=head1 SYNOPSIS

   # Assuming $entry comes from a database of the 'Bib' structure
   # (i.e., that it's blessed into the BibEntry class, which inherits
   # the sort_key method from BibSort):
   $sort_key = $entry->sort_key;

=head1 DESCRIPTION

C is a base class of C
for generating sort keys from bibliography entries.  It could in
principle (and, someday, might) offer a wide range of highly
customizable sort-key generators.  Currently, though, it provides only a
single method (C) for public use, and that method only pays
attention to one structure option, C.

=head1 METHODS

=over 4

=item sort_key ()

Generates a sort key for a single bibliographic entry.  Assumes this
entry conforms to the C database structure.  The nature of this
sort key is controlled by the C option, which can be either
C<"name"> or C<"year">.  (The C also has a role, in
determining how author/editor names are formatted for inclusion in the
sort key.)

For by-name sorting (which is how BibTeX's standard styles work), the sort
key consists of one of the C, C, C, or C
fields (depending on the entry type and which fields are actually present),
followed by the year and the title.  All fields are drastically simplified
to produce the sort key: non-English letters are mercilessly anglicized,
non-alphabetic characters are stripped, and everything is forced to
lowercase.  (The first two steps are done by the C routine;
see L for a brief
description, and the description of the C function C in
L for all the gory details.)

=cut

# methods for sorting -- everything here is geared towards generating
# a sort key; it's up to external code to actually order entries (since,
# of course, a single entry doesn't know anything about any other
# entries!)

# also, we assume that an entry has been checked and coerced into
# shape -- that way we don't need to check for defined-ness of
# strings, or check the type, or anything.

sub sort_key
{
   my $self = shift;
   my ($sortby, $type, $nkey, $skey);

   $sortby = $self->structure->get_options ('sortby');
   croak ("BibSort::sort_key: sortby option is 'none'")
      if $sortby eq 'none';
   croak ("BibSort::sort_key: unknown sortby option '$sortby'")
      unless $sortby eq 'name' || $sortby eq 'year';

   $type = $self->type;

   if ($type eq 'book' || $type eq 'inbook')
   {
      $nkey = $self->format_alt_fields ('author' => 'sort_format_names',
                                        'editor' => 'sort_format_names',
                                        'key'    => 'sortify');
   }
   elsif ($type eq 'proceedings')
   {
      $nkey = $self->format_alt_fields ('editor' => 'sort_format_names',
                                        'organization' => 'sort_format_org',
                                        'key'    => 'sortify');
   }
   elsif ($type eq 'manual')
   {
      $nkey = $self->format_alt_fields ('author' => 'sort_format_names',
                                        'organization' => 'sort_format_org',
                                        'key'    => 'sortify');
   }
   else
   {
      $nkey = $self->format_alt_fields ('author' => 'sort_format_names',
                                        'key'    => 'sortify');
   }

   my $ykey = change_case ('l', (purify_string ($self->get ('year'))));
   $skey = ($sortby eq 'name')
      ? $nkey . '    ' . $ykey
      : $ykey . '    ' . $nkey;
   $skey .= '    ' . $self->sort_format_title ('title');
   return $skey;

}  # sort_key


sub sortify
{
   my ($self, $field) = @_;
   return lc (purify_string ($self->get ($field)));
}


sub sort_format_names
{
   require Text::BibTeX::Name;
   require Text::BibTeX::NameFormat;

   my ($self, $field) = @_;
   my ($abbrev, $format, $name);

   $abbrev = ! ($self->structure->get_options ('namestyle') eq 'full');
   $format =  Text::BibTeX::NameFormat->new ("vljf", $abbrev);
   $name   = Text::BibTeX::Name->new;

   my (@snames, $i, $sname);
   @snames = $self->split ($field);
   for $i (0 .. $#snames)
   {
      $sname = $snames[$i];
      if ($sname eq 'others')           # hmmm... should we only do this on
      {                                 # the final name?
         $sname = 'et al';              # purified version of "et. al."
      }
      else
      {
         # A spot of ugliness here:
         #   - lc (purify_string (x)) ought to be sortify (x), but I have
         #     already made sortify a method that only operates on a field,
         #     rather than a generic function (as it is in BibTeX)

         $name->split ($sname, $self->filename, $self->line ($field), $i+1);
         $sname = $name->format ($format);
#         print "s_f_n: about to purify >$sname<\n";
         $snames[$i] = lc (purify_string ($sname));
      }
   }
   return join ('   ', @snames);
}



# sort_format_org and sort_format_title are suspiciously similar...
# could probably have one method to handle both tasks...

sub sort_format_org
{
   my ($self, $field) = @_;

   my $value = $self->get ($field);
   $value =~ s/^the\b\s*//i;
   return lc (purify_string ($value));
}


sub sort_format_title
{
   my ($self, $field) = @_;

   my $value = $self->get ($field);
   $value =~ s/^(the|an?)\b\s*//i;
   return lc (purify_string ($value));
}


# Hmm, I suspect format_alt_fields is a little more general purpose --
# probably belongs outside of the "generate sort key" methods.
# (Or.... does it maybe belong in one of the base classes, StructuredEntry
# or even Entry?)

sub format_alt_fields
{
   my $self = shift;
   my ($field, $method);

   while (@_)
   {
      ($field, $method) = (shift, shift);
      if ($self->exists ($field))
      {
         $method = $self->can ($method)
            || croak ("unknown method in class " . (ref $self));
         return &$method ($self, $field);
      }
   }

   return undef;                        # whoops, none of the alternate fields
                                        # were present
}

1;

=back

=head1 SEE ALSO

L, L,
L

=head1 AUTHOR

Greg Ward

=head1 COPYRIGHT

Copyright (c) 1997-2000 by Gregory P. Ward.  All rights reserved.  This file
is part of the Text::BibTeX library.  This library is free software; you
may redistribute it and/or modify it under the same terms as Perl itself.