File Coverage

=head1 NAME

Genealogy::Military::Branch - Extract military branch from free-text genealogy notes

=head1 VERSION

Version 0.01

=head1 SYNOPSIS

    use Genealogy::Military::Branch;

    my $detector = Genealogy::Military::Branch->new();

    my $branch = $detector->detect(
        text => 'He served in the Royal Navy from 1914 to 1918',
    );
    # Returns 'navy'

    my $branch = $detector->detect(
        text => 'Served with the RAF in Bomber Command',
    );
    # Returns 'RAF'

    my $branch = $detector->detect(
        text => 'Some unrelated text',
    );
    # Returns 'military'

=head1 DESCRIPTION

Scans free-text military service notes from genealogy records and returns
the name of the military branch mentioned.  Returns C<'military'> (localised)
when no specific branch is recognised.

Designed to replace the C<service()> helper in the C<gedcom> and C<ged2site>
distributions, which contain duplicate implementations of the same logic.

Detection patterns cover British, US and Commonwealth branches.  The returned
string is localised to the system locale, which is detected from the
environment at construction time.

=head1 METHODS

=head2 new

=head3 Purpose

Constructs a new branch detector object.

=head3 API Specification

=head4 Input

    {
        language => {
            type     => 'string',
            optional => 1,
        },
        warn_on_error => {
            type     => 'boolean',
            optional => 1,
            default  => 0,
        },
    }

=head4 Output

    { type => 'object', isa => 'Genealogy::Military::Branch' }

=head3 Arguments

=over 4

=item * C<language> - BCP-47 primary subtag e.g. C<'en'>, C<'fr'>, C<'de'>.
If not given, the language is detected from the environment using
C<I18N::LangTags::Detect> and the standard locale environment variables,
falling back to C<'en'>.  Optional.

=item * C<warn_on_error> - If true, C<carp> is called when C<detect()> is
called and no branch is identified in the supplied text.  Optional, defaults
to 0.

=back

=head3 Returns

A blessed C<Genealogy::Military::Branch> object.

=head3 Notes

The language is detected and cached once at construction time.

=head3 Example

    my $detector = Genealogy::Military::Branch->new({
        language      => 'fr',
        warn_on_error => 1,
    });

=cut

=head2 detect

Scans a free-text string for references to military branches and returns
the localised branch name.

=head3 API Specification

=head4 Input

    {
        text => {
            type => 'string',
        },
    }

=head4 Output

    { type => 'string' }

=head3 Arguments

=over 4

=item * C<text> - The free-text string to scan.  Required.  May be passed
positionally as a single string.

=back

=head3 Returns

A string containing the detected branch name, localised to the language
supplied at construction.  Returns C<'military'> (or its localised
equivalent) when no branch is detected.  Never returns C<undef>.

=head3 Side Effects

If C<warn_on_error> was set true at construction and no branch is detected,
emits a warning via C<carp>.

=head3 Notes

Detection patterns are tried in order of specificity.  The first pattern
to match wins, so C<'Merchant Navy'> is correctly identified as
C<'Merchant Navy'> rather than C<'navy'>.

=head3 Example

    # Named argument form
    my $branch = $detector->detect(
        text => 'He served in the Royal Engineers during the Great War',
    );
    # Returns 'Royal Engineers'

    # Positional form
    my $branch = $detector->detect('Private in the Infantry');
    # Returns 'army'

=cut

=head1 AUTHOR

Nigel Horne C<< <njh@nigelhorne.com> >>

=head1 BUGS

Please report bugs via the GitHub issue tracker:
L<https://github.com/nigelhorne/Genealogy-Military-Branch/issues>

=head1 TODO

=over 4

=item * Add Australian, Canadian and other Commonwealth branch patterns

=item * Add more US-specific patterns (Space Force etc)

=item * Consider a companion C<Genealogy::Military::Rank> module

=back

=head1 SEE ALSO

=over 4

=item * L<Test Dashboard|https://nigelhorne.github.io/Genealogy-Military-Branch/coverage/>

=item * L<Genealogy::Occupation>

=item * L<Params::Get>

=item * L<Params::Validate::Strict>

=item * L<Return::Set>

=back

=head1 LICENSE AND COPYRIGHT

Copyright 2026 Nigel Horne.

This program is released under the following licence: GPL2
If you use it, please let me know.

=cut