File Coverage

blib/lib/Text/Widont.pm

Criterion	Covered	Total	%
statement	30	30	100.0
branch	9	14	64.2
condition	5	9	55.5
subroutine	7	7	100.0
pod	2	2	100.0
total	53	62	85.4

package Text::Widont;

use strict;
use warnings;

use Carp qw( croak );

our $VERSION = '0.01';


# By default export the 'widont' function and 'nbsp' constant.
use base qw/ Exporter /;
our @EXPORT = qw( widont nbsp );


=head1 NAME

Text::Widont - Suppress typographic widows

=head1 SYNOPSIS

    use Text::Widont;

    # For a single string...
    my $string = 'Look behind you, a Three-Headed Monkey!';
    print widont($string, nbsp->{html});  # "...a Three-Headed Monkey!"

    # For a number of strings...
    my $strings = [
        'You fight like a dairy farmer.',
        'How appropriate. You fight like a cow.',
    ];
    print join "\n", @{ widont( $strings, nbsp->{html} ) };

Or the L way:

    use Text::Widont qw( nbsp );

    my $tw = Text::Widont->new( nbsp => nbsp->{html} );

    my $string = "I'm selling these fine leather jackets.";
    print $tw->widont($string);  # "...fine leather jackets."


=head1 DESCRIPTION

Collins English Dictionary defines a "widow" in typesetting as:

    A short line at the end of a paragraph, especially one that occurs as the
    top line of a page or column.

For example, in the text...

    How much wood could a woodchuck
    chuck if a woodchuck could chuck
    wood?

...the word "wood" at the end is considered a widow. Using C,
that sentence would instead appear as...

    How much wood could a woodchuck
    chuck if a woodchuck could
    chuck wood?


=head1 NON-BREAKING SPACE TYPES

C exports a hash ref, C, that contains the following
representations of a non-breaking space to be used with the widont function:

=over

=item html

The C< > HTML character entity.

=item html_hex

The C< > HTML character entity.

=item html_dec

The C< > HTML character entity.

=item unicode

Unicode's "No-Break Space" character.

=back


=cut


use constant nbsp => {
    html     => ' ',
    html_dec => ' ',
    html_hex => ' ',
    unicode  => pack( 'U', 0x00A0 ),
};


=head1 FUNCTIONS

=head2 widont( $string, $nbsp )

The C function takes a string and returns a copy with the space
between the final two words replaced with the given C<$nbsp>. C<$string> can
optionally be a reference to an array of strings to transform. In this case
strings will be modified in place as well as a copy returned.

In the absence of an explicit C<$nbsp>, Unicode's No-Break Space character
will be used.


=cut


# This function also acts as an object method as described in the next POD
# section.
sub widont {
    my ( $self, $string, $nbsp );
    $string = shift;

    # Check to see if the subroutine has been called as an object method...
    if ( ref $string eq 'Text::Widont' ) {
        $self   = $string;
        $string = shift;

        $nbsp = $self->{nbsp} eq 'html'     ? nbsp->{html}
              : $self->{nbsp} eq 'html_dec' ? nbsp->{html_dec}
              : $self->{nbsp} eq 'html_hex' ? nbsp->{html_hex}
              : $self->{nbsp} eq 'unicode'  ? nbsp->{unicode}
              : $self->{nbsp};
    }

    # Make sure a $string was passed...
    croak 'widont requires a string' if !defined $string;

    # $nbsp defaults to unicode...
    $nbsp ||= shift || nbsp->{unicode};


    # Iterate over the string(s) to perform the transformation...
    foreach ( ref $string eq 'ARRAY' ? @$string : $string ) {
        s/([^\s])\s+([^\s]+\s*)$/$1$nbsp$2/;
    }

    return $string;
}


=head1 METHODS

C also provides an object oriented interface.

=head2 -Enew( nbsp => $nbsp )

Instantiates a new C object. C is an optional argument
that will be used when performing the substitution. It defaults to Unicode's
No-Break Space character.


=cut


sub new {
    my $class = shift;
    my $self  = bless { @_ }, $class;

    # Default to No-Break Space.
    $self->{nbsp} ||= nbsp->{unicode};

    return $self;
}


=head2 -Ewidont( $string )

Performs the substitution described L, using the object's
C property and the given string.


=cut


# sub widont {} already defined above.



1;  # End of the module code; everything from here is documentation...
__END__