File Coverage

=head1 NAME

Text::Names::Abbreviate - Create abbreviated name formats from full names

=head2 VERSION

Version 0.03

=cut

=head1 SYNOPSIS

  use Text::Names::Abbreviate qw(abbreviate);

  say abbreviate('John Quincy Adams');                            # J. Q. Adams
  say abbreviate('Adams, John Quincy');                          # J. Q. Adams
  say abbreviate('George R R Martin', { format => 'initials' }); # G.R.R.M.

=head1 DESCRIPTION

This module provides simple abbreviation logic for full personal names with
multiple formatting options and styles.  Input is expected to be a personal
name consisting of one or more whitespace-separated components interpreted as:

  First [Middle ...] Last

Names consisting of a single component are returned unchanged.

=head1 SUBROUTINES/METHODS

=head2 abbreviate

Produce an abbreviated form of a personal name.

=head3 Purpose

Accept a full name in either C<First Middle Last> or C<Last, First Middle>
form and return a formatted abbreviated string according to the requested
C<format>, C<style>, and C<separator>.

=head3 Args

=over 4

=item name (required)

Non-empty string.  Accepted in two forms:

=over 4

=item C<First [Middle ...] Last>

=item C<Last, First [Middle ...]>

=back

A leading comma (C<", John">) signals that no last name is present; only
initials are produced.

=item format (optional, default C<default>)

One of C<default>, C<initials>, C<compact>, C<shortlast>.

=over 4

=item C<default>   -- C<J. Q. Adams>

=item C<initials>  -- C<J.Q.A.>

=item C<compact>   -- C<JQA>

=item C<shortlast> -- initials then full last name; honours C<last_first> style
(e.g. C<Adams, J. Q.>).

=back

=item style (optional, default C<first_last>)

One of C<first_last>, C<last_first>.  All formats honour this option.

=item separator (optional, default C<.>)

String appended after each initial.  Empty string removes all punctuation.

=back

=head3 Returns

A plain string.  Returns C<''> for inputs that normalise to nothing (e.g. a
bare comma).

=head3 Side Effects

None.  The function is purely functional with no persistent state.

=head3 Usage

  # Positional
  my $abbrev = abbreviate('John Quincy Adams');

  # Options hashref
  my $abbrev = abbreviate('John Quincy Adams', {
      format    => 'initials',
      style     => 'last_first',
      separator => '-',
  });

=head3 API SPECIFICATION

  INPUT
  {
    name      => { type => 'string', min => 1, optional => 0 },
    format    => { type => 'string',
                   memberof => [qw(default initials compact shortlast)],
                   optional => 1 },
    style     => { type => 'string',
                   memberof => [qw(first_last last_first)],
                   optional => 1 },
    separator => { type => 'string', optional => 1 },
  }

  OUTPUT
  { type => 'string' }    # croaks on argument error

=head3 MESSAGES

  Error                                    Meaning / Resolution
  ---------------------------------------  -----------------------------------------------
  name parameter missing or undefined      Called without a name argument; supply one.
  name must be a non-empty string          Passed '' or undef; supply a non-empty string.
  format must be one of: ...               Invalid format constant; see API SPECIFICATION.
  style must be one of: ...               Invalid style constant; see API SPECIFICATION.

=head3 PSEUDOCODE

  FUNCTION abbreviate(name, options):
     Validate parameters via %PARAM_SCHEMA       (croak on violation)
     Assign defaults: format=default, style=first_last, sep="."
     _normalize_name(name):
         - collapse consecutive commas
         - detect and reorder "Last, First" form
         - track $had_leading_comma (input had no last-name component)
         - collapse internal whitespace; trim
     Return '' if normalized name is empty
     _extract_parts(name, had_leading_comma, format, style):
         - tokenize on whitespace
         - pop last token as $last_name (unless leading-comma form)
         - build @initials from remaining tokens (first char each)
         - if style=last_first and format!=default: unshift last initial, clear $last_name
         - filter empty initials
     Format result:
         compact   -> join('', @initials, first($last_name))
         initials  -> join($sep, @all_letters) . $sep
         shortlast -> join(' ', map {"$_$sep"} @initials) . " $last_name"
         default   -> joined initials; prepend/append $last_name per $style

=cut