NAME

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

VERSION

Version 0.01

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'

DESCRIPTION

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

Designed to replace the service() helper in the gedcom and 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.

METHODS

new

Purpose

Constructs a new branch detector object.

API Specification

Input

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

Output

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

Arguments

• language - BCP-47 primary subtag e.g. 'en', 'fr', 'de'. If not given, the language is detected from the environment using I18N::LangTags::Detect and the standard locale environment variables, falling back to 'en'. Optional.
• warn_on_error - If true, carp is called when detect() is called and no branch is identified in the supplied text. Optional, defaults to 0.

Returns

A blessed Genealogy::Military::Branch object.

Side Effects

None.

Notes

The language is detected and cached once at construction time.

Example

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

detect

Purpose

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

API Specification

Input

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

Output

{ type => 'string' }

Arguments

• text - The free-text string to scan. Required. May be passed positionally as a single string.

Returns

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

Side Effects

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

Notes

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

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'

AUTHOR

Nigel Horne <njh@nigelhorne.com>

BUGS

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

TODO

• Add Australian, Canadian and other Commonwealth branch patterns
• Add more US-specific patterns (Space Force etc)
• Consider a companion Genealogy::Military::Rank module

SEE ALSO

• Test Dashboard
• Genealogy::Occupation
• Params::Get
• Params::Validate::Strict
• Return::Set

LICENSE AND COPYRIGHT

Copyright 2026 Nigel Horne.

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