NAME

Lingua::Abbreviate::Hierarchy - Shorten verbose namespaces

VERSION

This document describes Lingua::Abbreviate::Hierarchy version 0.03

SYNOPSIS

use Lingua::Abbreviate::Hierarchy;
my $abr = Lingua::Abbreviate::Hierarchy->new( keep => 1 );

$abr->add_namespace(qw(
  comp.lang.perl.misc
  comp.lang.perl.advocacy
));

# gets 'c.l.p.misc'
my $clpm = $abr->ab('comp.lang.perl.misc');

# abbreviate an array
my @ab = $abr->ab(qw(
  comp.lang.perl.misc
  comp.lang.perl.advocacy
));

DESCRIPTION

It's a common practice to abbreviate the elements of namespaces like this:

comp.lang.perl.misc     -> c.l.p.misc
comp.lang.perl.advocacy -> c.l.p.advocacy

This module performs such abbreviation. It guarantees that generated abbreviations are long enough to be unique within the current namespace.

INTERFACE

To abbreviate names within a namespace use the module:

use Lingua::Ab::H;   # use abbreviated name

Create a new abbreviator:

my $abr = Lingua::Ab::H->new( keep => 1 );

Set up the namespace:

$abr->add_namespace(qw(
  comp.lang.perl.misc
  comp.lang.perl.advocacy
));

Get your abbreviations:

# gets 'c.l.p.misc'
my $clpm = $abr->ab('comp.lang.perl.misc');

# abbreviate an array
my @ab = $abr->ab(qw(
  comp.lang.perl.misc
  comp.lang.perl.advocacy
));

Often the namespace will be larger; for example if you wanted to generate abbreviations that would be unique within the entire comp.lang.* hierarchy you would add all the terms in that space to the abbreviator.

new

Create a new abbreviator. Options may be passed as key, value pairs:

my $abr = Lingua::Ab::H->new(
  keep => 1,
  sep => '::'
);

The following options are recognised:

sep => string

The string that separates components in the namespace. For example '.' for domain names or '::' for Perl package names;

only => number

Abbreviate only the initial N elements in the name.

keep => number

Leave N elements at the end of the name unabbreviated.

max => number

Abbreviate from the left until the generated abbreviation contains N or fewer characters. If only is specified then at least that many elements will be abbreviated. If keep is specified that many trailing elements will be unabbreviated.

May return more than N characters if the fully abbreviated name is still too long.

trunc => string

A truncation string (which may be empty). When trunc is supplied the generated abbreviation will always be <= max characters and will be prefixed by the truncation string.

flip => bool

Normally we consider the namespace to be rooted at the left (like a filename or package name). Set flip to true to process right-rooted namespaces (like domain names).

ns => array ref

Supply a reference to an array containing namespace terms. See add_namespace for more details.

add_namespace

Add terms to the abbreviator's namespace:

$abr->add_namespace( 'foo.com', 'bar.com' );

When abbreviating a term only those elements of the term that fall within the namespace will be abbreviated. Elements outside the namespace will be untouched.

ab

Abbreviate one or more terms:

my $short = $abr->ab( 'this.is.a.long.name' );

Or with an array:

my @short = $abr->ab( @long );

ex

Expand an abbreviation created by calling ab. When applied to abbreviations created in the current namespace ex will reliably expand arbitrary abbreviated terms. It will also pass through non-abbreviated terms unmolested.

If the namespace for expansion is not identical to the namespace for abbreviation then the results are unpredictable.

my @ab = $abr->ab( @terms );      # Abbreviate terms...
my @ex = $abr->ex( @ab );         # ...and get them back

DEPENDENCIES

None.

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-lingua-abbreviate-hierarchy@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Andy Armstrong <andy@hexten.net>

LICENCE AND COPYRIGHT

Copyright (c) 2009, Andy Armstrong <andy@hexten.net>.

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