File Coverage

blib/lib/Crypt/HSXKPasswd.pm

Criterion	Covered	Total	%
statement	671	974	68.8
branch	163	326	50.0
condition	24	61	39.3
subroutine	69	85	81.1
pod	32	35	91.4
total	959	1481	64.7

package Crypt::HSXKPasswd;

# import required modules
use strict;
use warnings;
use Carp; # for nicer 'exception' handling for users of the module
use Fatal qw( :void open close binmode ); # make builtins throw exceptions on failure
use English qw( -no_match_vars ); # for more readable code
use Scalar::Util qw( blessed ); # for checking if a reference is blessed
use Math::Round; # for round()
use Math::BigInt; # for the massive numbers needed to store the permutations
use Clone qw( clone ); # for cloning nested data structures - exports clone()
use Readonly; # for truly constant constants
use JSON; # for dealing with JSON strings
use List::MoreUtils qw( uniq ); # for array deduplication
use Type::Tiny; # for generating anonymous type constraints when needed
use Type::Params qw( compile multisig ); # for parameter validation with Type::Tiny objects
use Types::Standard qw( slurpy :types ); # for basic type checking (Int Str etc.)
use Crypt::HSXKPasswd::Types qw( :types ); # for custom type checking
use Crypt::HSXKPasswd::Helper; # exports utility functions like _error & _warn
use Crypt::HSXKPasswd::Dictionary::Basic;
use Crypt::HSXKPasswd::RNG::Math_Random_Secure;
use Crypt::HSXKPasswd::RNG::Data_Entropy;
use Crypt::HSXKPasswd::RNG::DevUrandom;
use Crypt::HSXKPasswd::RNG::Basic;

# set things up for using UTF-8
use 5.016; # min Perl for good UTF-8 support, implies feature 'unicode_strings'
use Encode qw( encode decode );
use Text::Unidecode; # for stripping accents from accented characters
use utf8;
binmode STDOUT, ':encoding(UTF-8)';

# import (or not) optional modules
eval{
    # the default dicrionary may not have been geneated using the Util module
    require Crypt::HSXKPasswd::Dictionary::EN;
}or do{
    carp('WARNING - failed to load Crypt::HSXKPasswd::Dictionary::EN');
};

## no critic (ProhibitAutomaticExportation);
use base qw( Exporter );
our @EXPORT = qw( hsxkpasswd );
## use critic

# Copyright (c) 2015, Bart Busschots T/A Bartificer Web Solutions All rights
# reserved.
#
# Code released under the FreeBSD license (included in the POD at the bottom of
# this file)

#==============================================================================
# Code
#==============================================================================

#
# === Constants and Package Variables =========================================#
#

# version info
use version; our $VERSION = qv('3.6');

# entropy control variables
my $_ENTROPY_MIN_BLIND = 78; # 78 bits - equivalent to 12 alpha numeric characters with mixed case and symbols
my $_ENTROPY_MIN_SEEN = 52; # 52 bits - equivalent to 8 alpha numeric characters with mixed case and symbols
my $_ENTROPY_WARNINGS = 'ALL'; # valid values are 'ALL', 'BLIND', or 'NONE' (invalid values treated like 'ALL')

# utility constants
Readonly my $_CLASS => __PACKAGE__;
Readonly my $_TYPES_CLASS => 'Crypt::HSXKPasswd::Types';
Readonly my $_DICTIONARY_BASE_CLASS => 'Crypt::HSXKPasswd::Dictionary';
Readonly my $_RNG_BASE_CLASS => 'Crypt::HSXKPasswd::RNG';

#
# Constructor -----------------------------------------------------------------
#

#####-SUB-######################################################################
# Type       : CONSTRUCTOR (CLASS)
# Purpose    : Instantiate an object of type XKPasswd
# Returns    : An object of type XKPasswd
# Arguments  : This function accepts the following named arguments - all
#              optional:
#              dictionary - an object that inherits from
#                  Crypt::HSXKPasswd::Dictionary
#              dictionary_list - an array ref of words to use as a dictionary.
#              dictionary_file - the path to a dictionary file.
#              dictionary_file_encoding - the encoding to use when loading the
#                  dictionary file, defaults to UTF-8.
#              preset - the preset to use
#              preset_overrides - a hashref of config options to override.
#                  Ignored unless preset is set, and in use.
#              config - a config hashref.
#              config_json - a config as a JSON string (requires that the JSON
#                  module be installed)
#              rng - an object that inherits from Crypt::HSXKPasswd::RNG
# Throws     : Croaks if the function is called in an invalid way, called with
#              invalid args, or called with a JSON string when JSON is not
#              installed.
# Notes      : The order of preference for word sources is dictionary, then
#              dictionary_list, then dictionary_file. If none are specified,
#              then an instance of Crypt::HSXKPasswd::Dictionary::EN will be
#              used.
#              The order of preference for the configuration source is config
#              then config_json, then preset. If no configuration source is
#              specified, then the preset 'DEFAULT' is used.
#              If no RNG is passed, _best_available_rng() will be used to
#              instantiate and instance of the most secure RNG usable on the
#              system.
# See Also   : For valid configuarion options see POD documentation below
sub new{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(slurpy Dict[
        dictionary => Optional[InstanceOf[$_DICTIONARY_BASE_CLASS]],
        dictionary_list => Optional[ArrayRef[Str]],
        dictionary_file => Optional[Str],
        dictionary_file_encoding => Optional[Str],
        config => Optional[Config],
        config_json => Optional[Str],
        preset => Optional[PresetName],
        preset_overrides => Optional[ConfigOverride],
        rng => Optional[InstanceOf[$_RNG_BASE_CLASS]],
    ]);
    my ($options) = $args_check->(@args);

    # set defaults
    $options->{dictionary_file_encoding} = 'UTF-8' unless $options->{dictionary_file_encoding};


    # before going any further, check the presets and key definitions if debugging (doing later may cause an error before we test)
    if($_CLASS->module_config('DEBUG')){
        $_CLASS->_check_config_key_definitions();
        $_CLASS->_check_preset_definitions();
    }

    # process the word source
    my $dictionary;
    if($options->{dictionary}){
        $dictionary = $options->{dictionary};
    }elsif($options->{dictionary_list}){
        $dictionary = Crypt::HSXKPasswd::Dictionary::Basic->new($options->{dictionary_list});
    }elsif($options->{dictionary_file}){
        $dictionary = Crypt::HSXKPasswd::Dictionary::Basic->new($options->{dictionary_file}, $options->{dictionary_file_encoding});
    }else{
        $dictionary = Crypt::HSXKPasswd::Dictionary::EN->new();
    }

    # process the config source
    my $config = {};
    if($options->{config}){
        $config = $options->{config};
    }elsif($options->{config_json}){
        $config = $options->{config_json}; # pass the string on, config() will deal with it
    }elsif($options->{preset}){
        $config = $_CLASS->preset_config($options->{preset}, $options->{preset_overrides});
    }else{
        $config = $_CLASS->default_config();
    }

    # process the random number source
    my $rng = {};
    if($options->{rng}){
        $rng = $options->{rng};
    }else{
        $rng = $_CLASS->_best_available_rng();
    }

    # initialise the object
    my $instance = {
        # 'public' instance variables (none so far)
        # 'PRIVATE' internal variables
        _CONFIG => {},
        _DICTIONARY_SOURCE => {}, # the dictionary object to source words from
        _RNG => {}, # the random number generator
        _CACHE_DICTIONARY_FULL => [], # a cache of all words found in the dictionary file
        _CACHE_DICTIONARY_LIMITED => [], # a cache of all the words found in the dictionary file that meet the length criteria
        _CACHE_CONTAINS_ACCENTS => 0, # a cache of whether or not the filtered word list contains words with accented letters
        _CACHE_ENTROPYSTATS => {}, # a cache of the entropy stats for the current combination of dictionary and config
        _CACHE_RANDOM => [], # a cache of random numbers (as floating points between 0 and 1)
        _PASSWORD_COUNTER => 0, # the number of passwords this instance has generated
    };
    bless $instance, $class;

    # load the config - will croak on invalid config
    $instance->config($config);

    # load the dictionary (can't be done until the config is loaded)
    $instance->dictionary($dictionary);

    # load the rng
    $instance->rng($rng);

    # if debugging, print status
    _debug("instantiated $_CLASS object with the following details:\n".$instance->status());

    # return the initialised object
    return $instance;
}

#
# Public Class (Static) functions ---------------------------------------------
#

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Return or update a module config variable
# Returns    : The value of the specified module config variable
# Arguments  : 1) the name of the module config variable
#              2) OPTIONAL - a new value for the module config variable
# Throws     : Croaks on invalid invocation, or invalid args
# Notes      :
# See Also   :
sub module_config{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(
        NonEmptyString->plus_coercions(Str, q{uc $_}), ## no critic (RequireInterpolationOfMetachars)
        Optional[Maybe[Value]],
    );
    my ($config_key, $new_value) = $args_check->(@args);


    # figure out which variable we are accessing
    ## no critic (ProhibitCascadingIfElse);
    if($config_key eq 'LOG_STREAM'){
        # check if we are a setter
        if(defined $new_value){
            # make sure the new value is valid
            FileHandle->check($new_value) || _error(FileHandle->get_message($new_value));

            # save the new value
            $Crypt::HSXKPasswd::Helper::_LOG_STREAM = $new_value; ## no critic (ProtectPrivateVars)
        }

        #return the value
        return $Crypt::HSXKPasswd::Helper::_LOG_STREAM; ## no critic (ProtectPrivateVars)
    }
    elsif($config_key eq 'LOG_ERRORS'){
        # check if we are a setter
        if(defined $new_value){
            # make sure the new value is valid
            TrueFalse->check($new_value) || _error(TrueFalse->get_message($new_value));

            # save the new value
            $Crypt::HSXKPasswd::Helper::_LOG_ERRORS = $new_value; ## no critic (ProtectPrivateVars)
        }

        #return the value
        return $Crypt::HSXKPasswd::Helper::_LOG_ERRORS; ## no critic (ProtectPrivateVars)
    }
    elsif($config_key eq 'DEBUG'){
        # check if we are a setter
        if(defined $new_value){
            # make sure the new value is valid
            TrueFalse->check($new_value) || _error(TrueFalse->get_message($new_value));

            # save the new value
            $Crypt::HSXKPasswd::Helper::_DEBUG = $new_value; ## no critic (ProtectPrivateVars)
        }

        #return the value
        return $Crypt::HSXKPasswd::Helper::_DEBUG; ## no critic (ProtectPrivateVars)
    }elsif($config_key eq 'ENTROPY_MIN_BLIND'){
        # check if we are a setter
        if(defined $new_value){
            # make sure the new value is valid
            PositiveInteger->check($new_value) || _error(PositiveInteger->get_message($new_value));

            # save the new value
            $_ENTROPY_MIN_BLIND = $new_value;
        }

        #return the value
        return $_ENTROPY_MIN_BLIND;
    }elsif($config_key eq 'ENTROPY_MIN_SEEN'){
        # check if we are a setter
        if(defined $new_value){
            # make sure the new value is valid
            PositiveInteger->check($new_value) || _error(PositiveInteger->get_message($new_value));

            # save the new value
            $_ENTROPY_MIN_SEEN = $new_value;
        }

        #return the value
        return $_ENTROPY_MIN_SEEN;
    }elsif($config_key eq 'ENTROPY_WARNINGS'){
        # check if we are a setter
        if(defined $new_value){
            # make sure the new value is valid
            EntropyWarningLevel->check($new_value) || _error(EntropyWarningLevel->get_message($new_value));

            # save the new value
            $_ENTROPY_WARNINGS = $new_value;
        }

        #return the value
        return $_ENTROPY_WARNINGS;
    }else{
        # the config key was invalid
        _error(qq{no package variable '$config_key'});
    }
    ## use critic

    # It's not possible to get here, so return 1 to keep PerlCritic happy
    return 1;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Get a list of defined config keys.
# Returns    : An array of strings.
# Arguments  : NONE
# Throws     : NOTHING
# Notes      :
# See Also   :
sub defined_config_keys{
    # gather and return the list of config key names
    return (sort keys %{$_TYPES_CLASS->_config_keys()});
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Return the specification for a given config key.
# Returns    : A hash indexed by 'required', 'type', and 'expects'.
# Arguments  : 1) a valid config key name
# Throws     : Croaks on invalid invocation and args
# Notes      :
# See Also   :
sub config_key_definition{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(ConfigKeyName);
    my ($key) = $args_check->(@args);

    # get a referece to the keys hashref from the Types class
    my $defined_keys = $_TYPES_CLASS->_config_keys();

    # assemble the hash
    my %definition = (
        required => $defined_keys->{$key}->{required},
        type => $defined_keys->{$key}->{type},
        expects => $defined_keys->{$key}->{expects},
    );

    # return the hash
    return %definition;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Return a hash of all key definitions indexed by key name.
# Returns    : A hash of key defintions as returned by config_key_definition().
# Arguments  : NONE
# Throws     : NOTHING
# Notes      :
# See Also   : config_key_definition()
sub config_key_definitions{
    # gather the definitions
    my %definitions = ();
    foreach my $key ($_CLASS->defined_config_keys()){
        $definitions{$key} = $_CLASS->config_key_definition($key);
    }

    # return the definitions
    return %definitions;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : generate a config hashref populated with the default values
# Returns    : a hashref
# Arguments  : 1. OPTIONAL - a hashref with config keys to over-ride when
#                 assembling the config
# Throws     : Croaks if invoked in an invalid way. If passed overrides also
#              Croaks if the resulting config is invalid, and Carps if passed
#              on each invalid key passed in the overrides hashref.
# Notes      :
# See Also   :
sub default_config{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Optional[ConfigOverride]);
    my ($overrides) = $args_check->(@args);

    # build and return a default config
    return $_CLASS->preset_config('DEFAULT', $overrides);
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Return the specification for a given preset.
# Returns    : A hash indexed by 'description', and 'config'.
# Arguments  : 1) OPTIONAL - a valid preset name, defaults to 'DEFAULT'
# Throws     : Croaks on invalid invocation and args
# Notes      :
# See Also   :
sub preset_definition{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Optional[Maybe[PresetName]]);
    my ($preset_name) = $args_check->(@args);

    # set defaults
    $preset_name = 'DEFAULT' unless $preset_name;

    # get a referece to the presets hashref from the Types class
    my $preset_defs = $_TYPES_CLASS->_presets();

    # assemble the hash
    my %definition = (
        description => $preset_defs->{$preset_name}->{description},
        config => $preset_defs->{$preset_name}->{config},
    );

    # return the hash
    return %definition;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Return a hash of all preset definitions indexed by name.
# Returns    : A hash of preset defintions as returned by preset_definition().
# Arguments  : NONE
# Throws     : NOTHING
# Notes      :
# See Also   : preset_definition()
sub preset_definitions{
    # gather the definitions
    my %definitions = ();
    foreach my $name ($_CLASS->defined_presets()){
        $definitions{$name} = $_CLASS->preset_definition($name);
    }

    # return the definitions
    return %definitions;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : generate a config hashref populated using a preset
# Returns    : a hashref
# Arguments  : 1. OPTIONAL - The name of the preset to assemble the config for
#                 as a scalar. If no name is passed, the preset 'DEFAULT' is
#                 used
#              2. OPTIONAL - a hashref with config keys to over-ride when
#                 assembling the config
# Throws     : Croaks if invoked in an invalid way. If passed overrides also
#              Croaks if the resulting config is invalid, and Carps if passed
#              on each invalid key passed in the overrides hashref.
# Notes      :
# See Also   :
sub preset_config{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Optional[PresetName], Optional[Maybe[ConfigOverride]]);
    my ($preset_name, $overrides) = $args_check->(@args);

    # default the preset name to 'DEFAULT'
    $preset_name = 'DEFAULT' unless $preset_name;

    # get a reference to the Presets hashref from the Types class
    my $preset_defs = $_TYPES_CLASS->_presets();

    # start by loading the preset
    my $config = $_CLASS->clone_config($preset_defs->{$preset_name}->{config});

    # if overrides were passed, apply them and validate
    if(defined $overrides){
        # save the keys into the config
        foreach my $key (keys %{$overrides}){
            $config->{$key} = $overrides->{$key};
        }
        # validate the resulting config
        unless(Config->check($config)){
            _error('The preset combined with the specified overrides produces an invalid config: '.Config->get_message($config));
        }
    }

    # return the config
    return $config;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Resturn the presets defined in the Crypt::HSXKPasswd module as a
#              JSON string
# Returns    : A JSON String as a scalar. The JSON string represets a hashref
#              with three keys  - 'defined_keys' contains an array of preset
#              identifiers, 'presets' contains the preset configs indexed by
#              preset identifier, and 'preset_descriptions' contains the a
#              hashref of descriptions indexed by preset identifiers
# Arguments  : NONE
# Throws     : If there is a problem converting the objects to JSON.
# Notes      :
# See Also   :
sub presets_json{
    # assemble an object containing the presets with any keys that can't be
    #  converted to JSON removed
    my @defined_presets = $_CLASS->defined_presets();
    my $sanitised_presets = {};
    my $preset_descriptions = {};
    foreach my $preset_name (@defined_presets){
        $sanitised_presets->{$preset_name} = $_CLASS->preset_config($preset_name);
        $preset_descriptions->{$preset_name} = $_CLASS->preset_description($preset_name);
    }
    my $return_object = {
        defined_presets => [@defined_presets],
        presets => $sanitised_presets,
        preset_descriptions => $preset_descriptions,
    };

    # try convert the object to a JSON string
    my $json_string = q{};
    eval{
        $json_string = JSON->new()->encode($return_object);
        1; # ensure truthy evaluation on succesful execution
    }or do{
        _error("failed to render presets as JSON string with error: $EVAL_ERROR");
    };

    # return the JSON string
    return $json_string;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Clone a config hashref
# Returns    : a hashref
# Arguments  : 1. the config hashref to clone
# Throws     : Croaks if called in an invalid way, or with an invalid config.
# Notes      : This function needs to be updated each time a new non-scalar
#              valid config key is added to the library.
# See Also   :
sub clone_config{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Config);
    my ($config) = $args_check->(@args);

    return clone($config);
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Remove all keys from a hashref that are not valid config keys
# Returns    : A reference to a hashref
# Arguments  : 1) a hashref
#              2) OPTIONAL - a list of named arguments:
#                 'warn_invalid_key_names' - must be either 1 or 0. If 1,
#                     warnings will be issued for any keys containined in the
#                     test hash that are not valid config keys.
#                     'suppress_warnings' takes precedence over this argument.
#                 'suppress_warnings' - must be either 1 or 0. If 1, no warnings
#                     will be printed when dropping valid keys with invalid
#                     values, or invalid keys.
# Throws     : Croaks on invalid args. Unless configured not to, will warn if
#              a valid key with an invalid value is encountered.
# Notes      :
# See Also   :
sub distil_to_config_keys{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(HashRef,
        slurpy Dict[
            suppress_warnings => Optional[TrueFalse],
            warn_invalid_key_names => Optional[TrueFalse],
        ],
    );
    my ($hashref, $options) = $args_check->(@args);

    # get a list of all the defined keys
    my @defined_keys = $_CLASS->defined_config_keys();

    # if warnings are not suppressed, and if extra warnings are asked for, check for invalid keys
    if(!$options->{suppress_warnings} && $options->{warn_invalid_key_names}){
        # build a lookup table to quickly test if a key exists
        my %defined_keys_lookup = ();
        foreach my $key (@defined_keys){
            $defined_keys_lookup{$key} = 1;
        }

        # check each key in the test hash against the lookup table
        foreach my $test_key (sort keys %{$hashref}){
            unless($defined_keys_lookup{$test_key}){
                _warn(qq{distilling out undefined config key '$test_key'});
            }
        }
    }

    # start with a new blank hashref, and copy across only the valid keys
    my $distilled = {};
    foreach my $key (@defined_keys){
        if(defined $hashref->{$key}){
            if(ConfigKeyAssignment->check({$key => $hashref->{$key}})){
                $distilled->{$key} = clone($hashref->{$key});
            }else{
                _warn("distilling out valid config key '$key' because of invalid value: ".ConfigKeyAssignment->get_message({$key => $hashref->{$key}})) unless $options->{suppress_warnings};
            }
        }
    }
    _debug('hashref distilled down from '.(scalar keys %{$hashref}).' to '.(scalar keys %{$distilled}).' keys');

    # return the distilled hashref
    return $distilled;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Distil an array of strings down to a de-duplicated array of only
#              symbols.
# Returns    : An array of strings
# Arguments  : 1) A reference to an array of strings
#              2) OPTIONAL - a named argument warn with a value of 0 or 1. If 1
#                 is passed, warnings will be issued each time an invalid string
#                 is skipped over.
# Throws     : Croaks on invalid invocation or args, and warns on request when
#              skipping words.
# Notes      :
# See Also   :
sub distil_to_symbol_alphabet{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(ArrayRef[Str], slurpy Dict[warn => Optional[TrueFalse]]);
    my ($array_ref, $options) = $args_check->(@args);
    my $warn = $options->{warn} || 0;

    # loop through the array and copy all valid synbols to a new array
    my @valid_symbols = ();
    foreach my $potential_symbol (@{$array_ref}){
        if(Symbol->check($potential_symbol)){
            push @valid_symbols, $potential_symbol;
        }else{
            if($warn || _do_debug()){
                my $msg = 'skipping invalid symbol: '.Symbol->get_message($potential_symbol);
                if($warn){
                    _warn($msg);
                }else{
                    _debug($msg);
                }
            }
        }
    }

    # de-dupe the valid symbols
    my @final_alphabet = uniq(@valid_symbols);

    # return the valid symbols
    return @final_alphabet;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Distil an array of strings down to a de-duplicated array of only
#              the valid words.
# Returns    : An array of words
# Arguments  : 1) A reference to an array of strings
#              2) OPTIONAL - a named argument warn with a value of 0 or 1. If 1
#                 is passed, warnings will be issued each time an invalid string
#                 is skipped over.
# Throws     : Croaks on invalid invocation or args, and warns on request when
#              skipping words.
# Notes      :
# See Also   :
sub distil_to_words{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # just pass everything through to the dictionary class
    return $_DICTIONARY_BASE_CLASS->distil_to_words(@args);
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : validate a config hashref
# Returns    : 1 if the config is valid, 0 otherwise
# Arguments  : 1. a hashref to validate
#              2. OPTIONAL - a named argument croak with a value of 1 or 1
# Throws     : Croaks on invalid args, or on error if second arg is truthy
# Notes      : This function needs to be updated each time a new valid config
#              key is added to the library.
# See Also   :
sub is_valid_config{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Item, slurpy Dict[croak => Optional[TrueFalse]]);
    my ($config, $options) = $args_check->(@args);

    # validate the config
    my $is_valid = Config->check($config) || 0;

    # croak if appropriate
    if(!$is_valid && $options->{croak}){
        _error(Config->get_message($config));
    }

    # return the result of the validation
    return $is_valid;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Convert a config hashref to a JSON String
# Returns    : A scalar
# Arguments  : 1. A config hashref
# Throws     : Croaks on invalid invocation, invalid args, or if the JSON module
#              is not available
# Notes      :
# See Also   :
sub config_to_json{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Config);
    my ($config) = $args_check->(@args);

    # try render the config to a JSON string
    my $ans = q{};
    eval{
        $ans = encode_json($config);
        1; # ensure a thurthy evaluation on successful execution
    }or do{
        _error("Failed to convert config to JSON stirng with error: $EVAL_ERROR");
    };

    # return the string
    return $ans;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Convert a config hashref to a String
# Returns    : A scalar
# Arguments  : 1. A config hashref
# Throws     : Croaks on invalid invocation or with invalid args. Carps if there
#              are problems with the config hashref.
# Notes      :
# See Also   :
sub config_to_string{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Config);
    my ($config) = $args_check->(@args);

    # get a reference to the key definitions from the types class
    my $defined_keys = $_TYPES_CLASS->_config_keys();

    # assemble the string to return
    my $ans = q{};
    CONFIG_KEY:
    foreach my $key (sort keys %{$defined_keys}){
        # skip undefined keys
        next CONFIG_KEY unless defined $config->{$key};

        # process the key
        if(ref $config->{$key} eq q{}){
            # the key is a scalar
            $ans .= $key.q{: '}.$config->{$key}.qq{'\n};
        }elsif(ref $config->{$key} eq 'ARRAY'){
            # the key is an array ref
            $ans .= "$key: [";
            my @parts = ();
            foreach my $subval (sort @{$config->{$key}}){
                push @parts, "'$subval'";
            }
            $ans .= join q{, }, @parts;
            $ans .= "]\n";
        }elsif(ref $config->{$key} eq 'HASH'){
            $ans .= "$key: {";
            my @parts = ();
            foreach my $subkey (sort keys %{$config->{$key}}){
                push @parts, "$subkey: '$config->{$key}->{$subkey}'";
            }
            $ans .= join q{, }, @parts;
            $ans .= "}\n";
        }else{
            # this should never happen, but just in case, throw a warning
            _warn("the data for the key '$key' is of an un-expected type (".(ref $config->{$key}).') - skipping key');
        }
    }

    # return the string
    return $ans;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Return the description for a given preset
# Returns    : A scalar string
# Arguments  : 1. OPTIONAL - the name of the preset to get the description for,
#                 if no name is passed 'DEFAULT' is assumed
# Throws     : Croaks on invalid invocation or invalid args
# Notes      :
# See Also   :
sub preset_description{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Optional[Maybe[PresetName]]);
    my ($preset) = $args_check->(@args);

    # set defaults
    $preset = 'DEFAULT' unless $preset;

    # get a reference to the preset definitions from the Types class
    my $preset_defs = $_TYPES_CLASS->_presets();

    # return the description by loading the preset
    return $preset_defs->{$preset}->{description};
}


#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Return a list of all valid preset names
# Returns    : An array of preset names as scalars
# Arguments  : NONE
# Throws     : NOTHING
# Notes      :
# See Also   :
sub defined_presets{
    # return the preset names
    my @preset_names = sort keys %{$_TYPES_CLASS->_presets()};
    return @preset_names;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Render the defined presets as a string
# Returns    : A scalar
# Arguments  : NONE
# Throws     : NOTHING
# Notes      :
# See Also   :
sub presets_to_string{
    # get a reference to the preset definitions from th Types class
    my $preset_defs = $_TYPES_CLASS->_presets();

    # loop through each preset and assemble the result
    my $ans = q{};
    my @preset_names = $_CLASS->defined_presets();
    foreach my $preset (@preset_names){
        $ans .= $preset."\n===\n";
        $ans .= $preset_defs->{$preset}->{description}."\n";
        $ans .= "\nConfig:\n---\n";
        $ans .= $_CLASS->config_to_string($preset_defs->{$preset}->{config});
        $ans .= "\nStatistics:\n---\n";
        my %stats = $_CLASS->config_stats($preset_defs->{$preset}->{config});
        if($stats{length_min} == $stats{length_max}){
            $ans .= "Length (fixed): $stats{length_min} characters\n";
        }else{
            $ans .= "Length (variable): between $stats{length_min} & $stats{length_max} characters\n";
        }
        $ans .= "Random Numbers Needed Per-Password: $stats{random_numbers_required}\n";
        $ans .= "\n";
    }

    # return the string
    return $ans;
}

#####-SUB-#####################################################################
# Type       : CLASS
# Purpose    : Calculate the number of random numbers needed to genereate a
#              single password with a given config.
# Returns    : An integer
# Arguments  : 1) a valid config hashref
# Throws     : Croaks in invalid invocation, or invalid args
# Notes      :
# See Also   :
sub config_random_numbers_required{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Config);
    my ($config) = $args_check->(@args);

    # calculate the number of random numbers needed to generate the password
    my $num_rand = 0;
    $num_rand += $config->{num_words};
    if($config->{case_transform} eq 'RANDOM'){
        $num_rand += $config->{num_words};
    }
    if($config->{separator_character} eq 'RANDOM'){
        $num_rand++;
    }
    if(defined $config->{padding_character} && $config->{padding_character} eq 'RANDOM'){
        $num_rand++;
    }
    $num_rand += $config->{padding_digits_before};
    $num_rand += $config->{padding_digits_after};

    # return the number
    return $num_rand;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Calculate statistics for a given configutration hashref.
# Returns    : A hash of statistics indexed by the following keys:
#              * 'length_min' - the minimum possible length of a password
#                generated by the given config
#              * 'length_max' - the maximum possible length of a password
#                generated by the given config
#              * 'random_numbers_required' - the number of random numbers needed
#                to generate a single password using the given config
# Arguments  : 1. A valid config hashref
#              2. OPTONAL - a named argument 'suppress_warnings' to indicate that
#                 no warnings should be issued if the config is such that there
#                 are uncertainties in the calculation.
# Throws     : Croaks on invalid invocation or args, carps if multi-character
#              substitutions are in use when not using adapive padding
# Notes      : This function ignores character replacements, if one or more
#              multi-character replacements are used when padding is not set
#              to adaptive, this function will return an invalid max length.
# See Also   :
sub config_stats{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Config, slurpy Dict[suppress_warnings => Optional[TrueFalse]]);
    my ($config, $options) = $args_check->(@args);
    my $suppres_warnings = $options->{suppress_warnings} || 0;

    # calculate the lengths
    my $len_min = 0;
    my $len_max = 0;
    if($config->{padding_type} eq 'ADAPTIVE'){
        $len_min = $len_max = $config->{pad_to_length};
    }else{
        # calcualte the length of everything but the words themselves
        my $len_base = 0;
        if($config->{padding_type} eq 'FIXED'){
            $len_base += $config->{padding_characters_before};
            $len_base += $config->{padding_characters_after};
        }
        if($config->{padding_digits_before} > 0){
            $len_base += $config->{padding_digits_before};
            if($config->{separator_character} ne 'NONE'){
                $len_base++;
            }
        }
        if($config->{padding_digits_after} > 0){
            $len_base += $config->{padding_digits_after};
            if($config->{separator_character} ne 'NONE'){
                $len_base++;
            }
        }
        if($config->{separator_character} ne 'NONE'){
            $len_base += $config->{num_words} - 1;
        }

        # maximise and minimise the word lengths to calculate the final answers
        $len_min = $len_base + ($config->{num_words} * $config->{word_length_min});
        $len_max = $len_base + ($config->{num_words} * $config->{word_length_max});
    }

    # calculate the number of random numbers needed to generate the password
    my $num_rand = $_CLASS->config_random_numbers_required($config);

    # detect whether or not we need to carp about multi-character replacements
    if($config->{padding_type} ne 'ADAPTIVE' && !$suppres_warnings){
        if(defined $config->{character_substitutions}){
            CHAR_SUB:
            foreach my $char (keys %{$config->{character_substitutions}}){
                if(length $config->{character_substitutions}->{$char} > 1){
                    _warn('maximum length may be underestimated. The loaded config contains at least one character substitution which replaces a single character with multiple characters.');
                    last CHAR_SUB;
                }
            }
        }
    }

    # assemble the result and return
    my $stats = {
        length_min => $len_min,
        length_max => $len_max,
        random_numbers_required => $num_rand,
    };
    return %{$stats};
}

#
# --- Public Instance functions -----------------------------------------------
#

#####-SUB-#####################################################################
# Type       : INSTANCE
# Purpose    : Get the currently loaded dictionary object, or, load a new
#              dictionary
# Returns    : An clone of the loaded dictionary object, or, a reference to the
#              instance (to enable function chaining) if called as a setter
# Arguments  : 1. OPTIONAL - the source for the dictionary, can be:
#                 The path to a dictionary file
#                     -OR-
#                 A reference to an array of words
#                     -OR-
#                 An instance of a sub-class of Crypt::HSXKPasswd::Dictionary
#              2. OPTIONAL - the encoding to import the file with. The default
#                 is UTF-8 (ignored if the first argument is not a file path).
# Throws     : Croaks on invalid invocation, or, if there is a problem loading
#              a dictionary file. While debugging, also warns when skipping
#              invalid words.
# Notes      :
# See Also   : For description of dictionary file format, see POD documentation
#              below
sub dictionary{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = multisig(
        [],
        [NonEmptyString, Optional[Maybe[NonEmptyString]]],
        [InstanceOf[$_DICTIONARY_BASE_CLASS]],
        [ArrayRef[Str]],
    );
    my ($dictionary_source, $encoding) = $args_check->(@args);

    # set defaults
    $encoding = 'UTF-8' unless $encoding;

    # if we're a getter, just get and return
    unless(defined $dictionary_source){
        return $self->{_DICTIONARY_SOURCE}->clone();
    }

    # OK, so we're a setter - carry on!

    # croak if we are called before the config has been loaded into the instance
    unless(defined $self->{_CONFIG}->{word_length_min} && $self->{_CONFIG}->{word_length_max}){
        _error('failed to load word source - config has not been loaded yet');
    }

    # get a dictionary instance
    my $new_dict;
    if(blessed($dictionary_source) && $dictionary_source->isa($_DICTIONARY_BASE_CLASS)){
        $new_dict = $dictionary_source;
    }elsif(ref $dictionary_source eq q{} || ref $dictionary_source eq 'ARRAY'){
        $new_dict = Crypt::HSXKPasswd::Dictionary::Basic->new($dictionary_source, $encoding); # could throw an error
    }else{
        _error('invalid word source - must be a dictionary object, hashref, or file path');
    }

    # load and sanitise the words from the word source
    my @cache_full = $_CLASS->distil_to_words(\@{$new_dict->word_list()});

    # generate the cache of appropriate-length words - croaks if too few words left after filtering
    my @cache_limited = $_CLASS->_filter_word_list(
        \@cache_full,
        $self->{_CONFIG}->{word_length_min},
        $self->{_CONFIG}->{word_length_max},
        allow_accents => $self->{_CONFIG}->{allow_accents},
    );

    # if we got here all is well, so save the new path and caches into the object
    $self->{_DICTIONARY_SOURCE} = $new_dict;
    $self->{_CACHE_DICTIONARY_FULL} = [@cache_full];
    $self->{_CACHE_DICTIONARY_LIMITED} = [@cache_limited];
    if($self->{_CONFIG}->{allow_accents}){
        $self->{_CACHE_CONTAINS_ACCENTS} = $_CLASS->_contains_accented_letters(\@cache_limited);
    }else{
        $self->{_CACHE_CONTAINS_ACCENTS} = 0;
    }

    # update the instance's entropy cache
    $self->_update_entropystats_cache();

    # return a reference to self
    return $self;
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Get a clone of the current config from an instance, or load a
#              new config into the instance.
# Returns    : A config hashref if called with no arguments, or, the instance
#              if called with a hashref (to facilitate function chaining)
# Arguments  : 1. OPTIONAL - a configuration to load as:
#                 A config hashref
#                     -OR-
#                 A JSON string representing a config hashref
# Throws     : Croaks if the function is called in an invalid way, with invalid
#              arguments, or with an invalid config.
# Notes      : Passing a JSON string will cause the function to croak if perl's
#              JSON module is not installed.
# See Also   : For valid configuarion options see POD documentation below
sub config{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = multisig(
        [],
        [Config],
        [NonEmptyString],
    );
    my ($config_raw) = $args_check->(@args);

    # if we're a getter, just get and return
    unless(defined $config_raw){
        return $self->_clone_config();
    }

    # OK - so we're a setter - carry on!

    # see what kind of argument we were passed, and behave appropriately
    my $config = {};
    if(ref $config_raw eq 'HASH'){
        # we  received a hashref, so just and pass it on
        $config = $config_raw;
    }elsif(ref $config_raw eq q{}){
        # we received as string, so treat it as JSON

        # try parse the received string as JSON
        my $config_from_json = {};
        eval{
            $config_from_json = decode_json($config_raw);
            1; # ensure truthy evaluation on successful execution
        }or do{
            _error("Failed to parse JSON config string with error: $EVAL_ERROR");
        };

        # strip out any extraneous keys found
        $config = $_CLASS->distil_to_config_keys($config_from_json);

        # validate the generated config
        unless(Config->check($config)){
            _error('Config extracted from JSON string is not valid: '.Config->get_message($config));
        }
    }else{
        _error('the config passed must be a hashref or a JSON string');
    }

    # distil the alphabets in the new config
    $_CLASS->_distil_alphabets_inplace($config);

    # save a clone of the passed config into the instance
    $self->{_CONFIG} = $_CLASS->clone_config($config);

    # update the instance's entropy cache
    $self->_update_entropystats_cache();

    # return a reference to self to facilitate function chaining
    return $self;
}

#####-SUB-#####################################################################
# Type       : INSTANCE
# Purpose    : Return the config of the currently running instance as a JSON
#              string.
# Returns    : A scalar.
# Arguments  : NONE
# Throws     : Croaks if invoked in an invalid way. Carps if it meets a key of a
#              type not accounted for in the code.
# Notes      : This function will carp if the JSON module is not available
# See Also   :
sub config_as_json{
    my $self = shift;
    _force_instance($self);

    # assemble and return the JSON string
    return $_CLASS->config_to_json($self->{_CONFIG}); # will croak without JSON
}

#####-SUB-#####################################################################
# Type       : INSTANCE
# Purpose    : Return the config of the currently running instance as a string.
# Returns    : A scalar.
# Arguments  : NONE
# Throws     : Croaks if invoked in an invalid way. Carps if it meets a key of a
#              type not accounted for in the code.
# Notes      :
# See Also   :
sub config_as_string{
    my $self = shift;
    _force_instance($self);

    # assemble and return the string
    return $_CLASS->config_to_string($self->{_CONFIG});
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Alter the running config with new values.
# Returns    : A reference to the instalce itself to enable function chaining.
# Arguments  : 1. a hashref containing config keys and values.
# Throws     : Croaks on invalid invocaiton, invalid args, and, if the resulting
#              new config is in some way invalid.
# Notes      : Invalid keys in the new keys hashref will be silently ignored.
# See Also   :
sub update_config{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = compile(ConfigOverride);
    my ($new_keys) = $args_check->(@args);

    # clone the current config as a starting point for the new config
    my $new_config = $self->_clone_config();

    # get a reference to the key definitions from the types class
    my $defined_keys = $_TYPES_CLASS->_config_keys();

    # merge the new values into the config
    my $num_keys_updated = 0;
    CONFIG_KEY:
    foreach my $key ($_CLASS->defined_config_keys()){
        # skip the key if it's not present in the list of new keys
        next CONFIG_KEY unless defined $new_keys->{$key};

        # update the key in the new config
        $new_config->{$key} = $new_keys->{$key};
        $num_keys_updated++;
        _debug("updated $key to new value");
    }
    _debug("updated $num_keys_updated keys");

    # distil the alphabets in the merged config
    $_CLASS->_distil_alphabets_inplace($new_config);

    # validate the merged config
    unless(Config->check($new_config)){
        _error('the updated config is not valid: '.Config->get_message($new_config));
    }

    # re-calculate the dictionary cache if needed
    my @cache_all = @{$self->{_CACHE_DICTIONARY_FULL}};
    my @cache_limited = @{$self->{_CACHE_DICTIONARY_LIMITED}};
    if($new_config->{word_length_min} ne $self->{_CONFIG}->{word_length_min} || $new_config->{word_length_max} ne $self->{_CONFIG}->{word_length_max}){
        # re-build the cache of valid words - throws an error if too few words are returned
        @cache_limited = $_CLASS->_filter_word_list(\@cache_all, $new_config->{word_length_min}, $new_config->{word_length_max}, $new_config->{allow_accents});
    }

    # if we got here, all is well with the new config, so add it and the caches to the instance
    $self->{_CONFIG} = $new_config;
    $self->{_CACHE_DICTIONARY_LIMITED} = [@cache_limited];

    # update the instance's entropy cache
    $self->_update_entropystats_cache();

    # return a reference to self
    return $self;
}

#####-SUB-#####################################################################
# Type       : INSTANCE
# Purpose    : Get the currently loaded RNG object, or, load a new RNG
# Returns    : An instance to the loaded RNG object, or, a reference to the
#              instance (to enable function chaining) if called as a setter
# Arguments  : 1. OPTIONAL - an object that is a Crypt::HSXKPasswd::RNG
# Throws     : Croaks on invalid invocation, or invalid args
# Notes      :
# See Also   :
sub rng{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = multisig(
        [],
        [InstanceOf[$_RNG_BASE_CLASS]],
    );
    my ($rng) = $args_check->(@args);

    # if we're a getter, just get and return
    unless(defined $rng){
        return $self->{_RNG};
    }

    # OK - so we're a getter - carry on!

    # set the RNG
    $self->{_RNG} = $rng;

    # empty the random cache
    $self->{_CACHE_RANDOM} = [];

    # return a reference to self
    return $self;
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Return the status of the internal caches within the instnace.
# Returns    : A string
# Arguments  : NONE
# Throws     : Croaks in invalid invocation
# Notes      :
# See Also   :
sub caches_state{
    my $self = shift;
    _force_instance($self);

    # generate the string
    my $ans = q{};
    $ans .= 'Loaded Words: '.(scalar @{$self->{_CACHE_DICTIONARY_LIMITED}}).' (out of '.(scalar @{$self->{_CACHE_DICTIONARY_FULL}}).' loaded from the file)'.qq{\n};
    $ans .= 'Cached Random Numbers: '.(scalar @{$self->{_CACHE_RANDOM}}).qq{\n};

    # return it
    return $ans;
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Generaete a random password based on the object's loaded config
# Returns    : a passowrd as a scalar
# Arguments  : NONE
# Throws     : Croaks on invalid invocation or on error generating the password
# Notes      :
# See Also   :
sub password{
    my $self = shift;
    _force_instance($self);

    #
    # Generate the password
    #
    my $password = q{};
    eval{
        #
        # start by generating the needed parts of the password
        #
        _debug('starting to generate random words');
        my @words = $self->_random_words();
        _debug('got random words='.(join q{, }, @words));
        $self->_transform_case(\@words);
        $self->_substitute_characters(\@words); # TO DO
        my $separator = $self->_separator();
        _debug("got separator=$separator");
        my $pad_char = $self->_padding_char($separator);
        _debug("got pad_char=$pad_char");

        #
        # Then assemble the finished password
        #

        # start with the words and the separator
        $password = join $separator, @words;
        _debug("assembled base password: $password");

        # next add the numbers front and back
        if($self->{_CONFIG}->{padding_digits_before} > 0){
            $password = $self->_random_digits($self->{_CONFIG}->{padding_digits_before}).$separator.$password;
        }
        if($self->{_CONFIG}->{padding_digits_after} > 0){
            $password = $password.$separator.$self->_random_digits($self->{_CONFIG}->{padding_digits_after});
        }
        _debug("added random digits (as configured): $password");


        # then finally add the padding characters
        if($self->{_CONFIG}->{padding_type} eq 'FIXED'){
            # simple fixed padding
            if($self->{_CONFIG}->{padding_characters_before} > 0){
                foreach my $c (1..$self->{_CONFIG}->{padding_characters_before}){
                    $password = $pad_char.$password;
                }
            }
            if($self->{_CONFIG}->{padding_characters_after} > 0){
                foreach my $c (1..$self->{_CONFIG}->{padding_characters_after}){
                    $password .= $pad_char;
                }
            }
        }elsif($self->{_CONFIG}->{padding_type} eq 'ADAPTIVE'){
            # adaptive padding
            my $pwlen = length $password;
            if($pwlen < $self->{_CONFIG}->{pad_to_length}){
                # if the password is shorter than the target length, padd it out
                while((length $password) < $self->{_CONFIG}->{pad_to_length}){
                    $password .= $pad_char;
                }
            }elsif($pwlen > $self->{_CONFIG}->{pad_to_length}){
                # if the password is too long, trim it
                $password = substr $password, 0, $self->{_CONFIG}->{pad_to_length};
            }
        }
        _debug("added padding (as configured): $password");
        1; # ensure true evaluation on successful execution
    }or do{
        _error("Failed to generate password with the following error: $EVAL_ERROR");
    };

    # increment the passwords generated counter
    $self->{_PASSWORD_COUNTER}++;

    # return the finished password
    return $password;
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Generate multiple passwords
# Returns    : An array of passwords as scalars
# Arguments  : 1. the number of passwords to generate as a scalar
# Throws     : Croaks on invalid invocation or invalid args
# Notes      :
# See Also   :
sub passwords{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = compile(NonZeroPositiveInteger);
    my ($num_pws) = $args_check->(@args);

    # generate the needed passwords
    my @passwords = ();
    my $num_to_do = $num_pws;
    while($num_to_do > 0){
        push @passwords, $self->password(); # could croak
        $num_to_do--;
    }

    # return the passwords
    return @passwords;
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Generate n passwords and return them, and the entropy stats as a
#              JSON string.
# Returns    : A JSON string as a scalar representing a hashref contianing an
#              array of passwords indexed by 'passwords', and a hashref of
#              entropy stats indexed by 'stats'. The stats hashref itself is
#              indexed by: 'password_entropy_blind',
#              'password_permutations_blind', 'password_entropy_blind_min',
#              'password_entropy_blind_max', 'password_permutations_blind_max',
#              'password_entropy_seen' & 'password_permutations_seen'
# Arguments  : 1. the number of passwords to generate
# Throws     : Croaks on invalid invocation, invalid args, if there is a
#              problem generating the passwords, statistics, or converting the
#              results to a JSON string, or if the JSON module is not
#              available.
# Notes      :
# See Also   :
sub passwords_json{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = compile(NonZeroPositiveInteger);
    my ($num_pws) = $args_check->(@args);

    # try generate the passwords and stats - could croak
    my @passwords = $self->passwords($num_pws);
    my %stats = $self->stats();

    # generate the hashref containing the results
    my $response_obj = {
        passwords => [@passwords],
        stats => {
            password_entropy_blind => $stats{password_entropy_blind},
            password_permutations_blind => $_CLASS->_render_bigint($stats{password_permutations_blind}),
            password_entropy_blind_min => $stats{password_entropy_blind_min},
            password_permutations_blind_min => $_CLASS->_render_bigint($stats{password_permutations_blind_min}),
            password_entropy_blind_max => $stats{password_entropy_blind_max},
            password_permutations_blind_max => $_CLASS->_render_bigint($stats{password_permutations_blind_max}),
            password_entropy_seen => $stats{password_entropy_seen},
            password_permutations_seen => $_CLASS->_render_bigint($stats{password_permutations_seen}),
        },
    };

    # try generate the JSON string to return
    my $json_string = q{};
    eval{
        $json_string = JSON->new()->encode($response_obj);
        1; # ensure truthy evaluation on succesful execution
    }or do{
        _error("Failed to render hashref as JSON string with error: $EVAL_ERROR");
    };

    # return the JSON string
    return $json_string;
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Return statistics about the instance
# Returns    : A hash of statistics indexed by the following keys:
#              * 'dictionary_source' - the source of the word list
#              * 'dictionary_words_total' - the total number of words loaded
#                from the dictionary file
#              * 'dictionary_words_filtered' - the number of words loaded from
#                the dictionary file that meet the lenght criteria set in the
#                loaded config
#              * 'dictionary_words_percent_available' - the percentage of the
#                total dictionary that is avialable for use with the loaded
#                config
#              * 'dictionary_filter_length_min' - the minimum length world
#                permitted by the filter
#              * 'dictionary_filter_length_max' - the maximum length world
#                permitted by the filter
#              * 'dictionary_contains_accents' - whether or not the filtered
#                list contains accented letters
#              * 'password_entropy_blind_min' - the entropy of the shortest
#                password this config can generate from the point of view of a
#                brute-force attacker in bits
#              * 'password_entropy_blind_max' - the entropy of the longest
#                password this config can generate from the point of view of a
#                brute-force attacker in bits
#              * 'password_entropy_blind' - the entropy of the average length
#                of password generated by this configuration from the point of
#                view of a brute-force attacker in bits
#              * 'password_entropy_seen' - the true entropy of passwords
#                generated by this instance assuming the dictionary and config
#                are known to the attacker in bits
#              * 'password_length_min' - the minimum length of passwords
#                generated with this instance's config
#              * 'password_length_max' - the maximum length of passwords
#                generated with this instance's config
#              * 'password_permutations_blind_min' - the number of permutations
#                a brute-froce attacker would have to try to be sure of success
#                on the shortest possible passwords geneated by this instance
#                as a Math::BigInt object
#              * 'password_permutations_blind_max' - the number of permutations
#                a brute-froce attacker would have to try to be sure of success
#                on the longest possible passwords geneated by this instance as
#                a Math::BigInt object
#              * 'password_permutations_blind' - the number of permutations
#                a brute-froce attacker would have to try to be sure of success
#                on the average length password geneated by this instance as a
#                Math::BigInt object
#              * 'password_permutations_seen' - the number of permutations an
#                attacker with a copy of the dictionary and config would need to
#                try to be sure of cracking a password generated by this
#                instance as a Math::BigInt object
#              * 'password_random_numbers_required' - the number of random
#                numbers needed to generate a single password using the loaded
#                config
#              * 'passwords_generated' - the number of passwords this instance
#                has generated
#              * 'randomnumbers_cached' - the number of random numbers
#                currently cached within the instance
#              * 'randomnumbers_cache_increment' - the number of random numbers
#                generated at once to re-plenish the cache when it's empty
#              * 'randomnumbers_source' - the name of the class used to
#                generate random numbers
# Arguments  : NONE
# Throws     : Croaks on invalid invocation
# Notes      :
# See Also   :
sub stats{
    my $self = shift;
    _force_instance($self);

    # create a hash to assemble all the stats into
    my %stats = ();

    # deal with the config-specific stats
    my %config_stats = $_CLASS->config_stats($self->{_CONFIG});
    $stats{password_length_min} = $config_stats{length_min};
    $stats{password_length_max} = $config_stats{length_max};
    $stats{password_random_numbers_required} = $config_stats{random_numbers_required};

    # deal with the dictionary file
    my %dict_stats = $self->_calcualte_dictionary_stats();
    $stats{dictionary_source} = $dict_stats{source};
    $stats{dictionary_words_total} = $dict_stats{num_words_total};
    $stats{dictionary_words_filtered} = $dict_stats{num_words_filtered};
    $stats{dictionary_words_percent_available} = $dict_stats{percent_words_available};
    $stats{dictionary_filter_length_min} = $dict_stats{filter_length_min};
    $stats{dictionary_filter_length_max} = $dict_stats{filter_length_max};
    $stats{dictionary_contains_accents} = $dict_stats{contains_accents};

    # deal with the entropy stats
    $stats{password_entropy_blind_min} = $self->{_CACHE_ENTROPYSTATS}->{entropy_blind_min};
    $stats{password_entropy_blind_max} = $self->{_CACHE_ENTROPYSTATS}->{entropy_blind_max};
    $stats{password_entropy_blind} = $self->{_CACHE_ENTROPYSTATS}->{entropy_blind};
    $stats{password_entropy_seen} = $self->{_CACHE_ENTROPYSTATS}->{entropy_seen};
    $stats{password_permutations_blind_min} = $self->{_CACHE_ENTROPYSTATS}->{permutations_blind_min};
    $stats{password_permutations_blind_max} = $self->{_CACHE_ENTROPYSTATS}->{permutations_blind_max};
    $stats{password_permutations_blind} = $self->{_CACHE_ENTROPYSTATS}->{permutations_blind};
    $stats{password_permutations_seen} = $self->{_CACHE_ENTROPYSTATS}->{permutations_seen};

    # deal with password counter
    $stats{passwords_generated} = $self->{_PASSWORD_COUNTER};

    # deal with the random number generator
    $stats{randomnumbers_cached} = scalar @{$self->{_CACHE_RANDOM}};
    $stats{randomnumbers_source} = blessed($self->{_RNG});

    # return the stats
    return %stats;
}

#####-SUB-######################################################################
# Type       : INSTANCE
# Purpose    : Represent the current state of the instance as a string.
# Returns    : Returns a multi-line string as as scalar containing details of the
#              loaded dictionary file, config, and caches
# Arguments  : NONE
# Throws     : Croaks on invalid invocation
# Notes      :
# See Also   :
sub status{
    my $self = shift;
    _force_instance($self);

    # assemble the response
    my %stats = $self->stats();
    my $status = q{};

    # the dictionary
    $status .= "*DICTIONARY*\n";
    $status .= "Source: $stats{dictionary_source}\n";
    $status .= "# words: $stats{dictionary_words_total}\n";
    $status .= "# words of valid length: $stats{dictionary_words_filtered} ($stats{dictionary_words_percent_available}%)\n";
    $status .= 'Contains Accented Characters: '.($stats{dictionary_contains_accents} ? 'YES' : 'NO')."\n";

    # the config
    $status .= "\n*CONFIG*\n";
    $status .= $self->config_as_string();

    # the random number cache
    $status .= "\n*RANDOM NUMBER CACHE*\n";
    $status .= "Random Number Generator: $stats{randomnumbers_source}\n";
    $status .= "# in cache: $stats{randomnumbers_cached}\n";

    # password statistics
    $status .= "\n*PASSWORD STATISTICS*\n";
    if($stats{password_length_min} == $stats{password_length_max}){
        $status .= "Password length: $stats{password_length_max}\n";
        $status .= 'Permutations (brute-force): '.$_CLASS->_render_bigint($stats{password_permutations_blind_max})."\n";
    }else{
        $status .= "Password length: between $stats{password_length_min} & $stats{password_length_max}\n";
        $status .= 'Permutations (brute-force): between '.$_CLASS->_render_bigint($stats{password_permutations_blind_min}).q{ & }.$_CLASS->_render_bigint($stats{password_permutations_blind_max}).q{ (average }.$_CLASS->_render_bigint($stats{password_permutations_blind}).")\n";
    }
    $status .= 'Permutations (given dictionary & config): '.$_CLASS->_render_bigint($stats{password_permutations_seen})."\n";
    if($stats{password_length_min} == $stats{password_length_max}){
        $status .= "Entropy (brute-force): $stats{password_entropy_blind_max}bits\n";
    }else{
        $status .= "Entropy (Brute-Force): between $stats{password_entropy_blind_min}bits and $stats{password_entropy_blind_max}bits (average $stats{password_entropy_blind}bits)\n";
    }
    $status .= "Entropy (given dictionary & config): $stats{password_entropy_seen}bits\n";
    $status .= "# Random Numbers needed per-password: $stats{password_random_numbers_required}\n";
    $status .= "Passwords Generated: $stats{passwords_generated}\n";

    # debug-only
    if($_Types_CLASS::_DEBUG){ ## no critic (ProtectPrivateVars)
        $status .= "\n*DEBUG INFO*\n";
        if($_Types_CLASS::_CAN_STACK_TRACE){ ## no critic (ProtectPrivateVars)
            $status .= "Devel::StackTrace IS installed\n";
        }else{
            $status .= "Devel::StackTrace is NOT installed\n";
        }
    }

    # return the status
    return $status;
}

#
# Regular Subs-----------------------------------------------------------------
#

#####-SUB-######################################################################
# Type       : SUBROUTINE
# Purpose    : A functional interface to this library (exported)
# Returns    : A random password as a scalar
# Arguments  : See the constructor
# Throws     : Croaks on error
# Notes      : See the Constructor
# See Also   : For valid configuarion options see POD documentation below
sub hsxkpasswd{
    my @constructor_args = @_;

    # try initialise an xkpasswd object
    my $hsxkpasswd;
    eval{
        $hsxkpasswd = $_CLASS->new(@constructor_args);
        1; # ensure truthy evaliation on successful execution
    } or do {
        _error("Failed to generate password with the following error: $EVAL_ERROR");
    };

    # genereate and return a password - could croak
    return $hsxkpasswd->password();
}

#
# 'Private' functions ---------------------------------------------------------
#

#####-SUB-######################################################################
# Type       : INSTANCE ('PRIVATE')
# Purpose    : Clone the instance's config hashref
# Returns    : a hashref
# Arguments  : NONE
# Throws     : Croaks if called in an invalid way
# Notes      :
# See Also   :
sub _clone_config{
    my $self = shift;
    _force_instance($self);

    # build the clone
    my $clone = $_CLASS->clone_config($self->{_CONFIG});

    # if, and only if, debugging, validate the cloned config so errors in the
    # cloning code will trigger an exception
    if($self->{debug}){
        Config->check($clone) || _error('cloning error - clone is invalid: '.Config->get_message($clone));
    }

    # return the clone
    return $clone;
}

#####-SUB-######################################################################
# Type       : CLASS
# Purpose    : Distil all alphabets in a config hashref
# Returns    : always returns 1 (to keep perlcritic happy)
# Arguments  : 1) a config hashref
# Throws     : Croaks on invalid invocation or args
# Notes      :
# See Also   :
sub _distil_alphabets_inplace{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Config);
    my ($config) = $args_check->(@args);

    # distil all three possible alphabet keys, if pressent
    if($config->{symbol_alphabet}){
        $config->{symbol_alphabet} = [$_CLASS->distil_to_symbol_alphabet($config->{symbol_alphabet})];
    }
    if($config->{padding_alphabet}){
        $config->{padding_alphabet} = [$_CLASS->distil_to_symbol_alphabet($config->{padding_alphabet})];
    }
    if($config->{separator_alphabet}){
        $config->{separator_alphabet} = [$_CLASS->distil_to_symbol_alphabet($config->{separator_alphabet})];
    }

    # an explicit return
    return 1;
}

#####-SUB-######################################################################
# Type       : CLASS (PRIVATE)
# Purpose    : Filter a word list based on word length
# Returns    : An array of words as scalars.
# Arguments  : 1. a reference to the array of words to filter.
#              2. the minimum allowed word length
#              3. the maximum allowed word length
#              4. OPTIONAL - named argument allow_accents with a value of 0 or
#                 1. If 1 is passed, accents will not be stripped from words,
#                 otherwise they will.
# Throws     : Croaks on invalid invocation, or if too few matching words found.
# Notes      : Unless the fourth argument is a truthy value, accents will be
#              stripped from the words.
# See Also   :
sub _filter_word_list{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(
        ArrayRef[Str],
        WordLength,
        WordLength,
        slurpy Dict[allow_accents => Optional[TrueFalse]]
    );
    my ($word_list_ref, $min_len, $max_len, $options) = $args_check->(@args);
    my $allow_accents = $options->{allow_accents} || 0;
    unless($max_len >= $min_len){
        _error("minimum length (recived $min_len) cannot be greater than maximum length (received $max_len)");
    }

    #build the array of words of appropriate length
    my @ans = ();
    WORD:
    foreach my $word (@{$word_list_ref}){
        # calcualte the grapheme length
        my $grapheme_length = $_CLASS->_grapheme_length($word);

        # skip words shorter than the minimum
        next WORD if $grapheme_length < $min_len;

        # skip words longer than the maximum
        next WORD if $grapheme_length > $max_len;

        # strip accents unless they are explicitly allowed by the config
        unless($allow_accents){
            $word = unidecode($word);
        }

        # store the word in the filtered list
        push @ans, $word;
    }

    # return the list
    return @ans;
}

#####-SUB-######################################################################
# Type       : CLASS (PRIVATE)
# Purpose    : Determine whether a word list contains accented characters
# Returns    : 1 if the word list does contain accented characters, and 0 if it
#              does not.
# Arguments  : 1. A reference to an array of words to test
# Throws     : NOTHING
# Notes      :
# See Also   :
sub _contains_accented_letters{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(ArrayRef[Str]);
    my ($word_list_ref) = $args_check->(@args);

    # assume no accented characters, test until 1 is found
    my $accent_found = 0;
    WORD:
    foreach my $word (@{$word_list_ref}){
        # check for accents by stripping accents and comparing to original
        my $word_accents_stripped = unidecode($word);
        unless($word eq $word_accents_stripped){
            $accent_found = 1;
            last WORD;
        }
    }

    # return the list
    return $accent_found;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Generate a random integer greater than 0 and less than a given
#              maximum value.
# Returns    : A random integer as a scalar.
# Arguments  : 1. the min value for the random number (as a positive integer)
# Throws     : Croaks if invoked in an invalid way, with invalid args, of if
#              there is a problem generating random numbers (should the cache)
#              be empty.
# Notes      : The random cache is used as the source for the randomness. If the
#              random pool is empty, this function will replenish it.
# See Also   :
sub _random_int{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = compile(NonZeroPositiveInteger);
    my ($max) = $args_check->(@args);

    # calculate the random number
    my $ans = ($self->_rand() * 1_000_000) % $max;

    # return it
    _debug("returning $ans (max=$max)");
    return $ans;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Generate a number of random integers.
# Returns    : A scalar containing a number of random integers.
# Arguments  : 1. The number of random integers to generate
# Throws     : Croaks on invalid invocation, or if there is a problem generating
#              the needed randomness.
# Notes      :
# See Also   :
sub _random_digits{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = compile(NonZeroPositiveInteger);
    my ($num) = $args_check->(@args);

    # assemble the response
    my $ans = q{};
    foreach my $n (1..$num){
        $ans .= $self->_random_int(10);
    }

    # return the response
    return $ans;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Return the next random number in the cache, and if needed,
#              replenish it.
# Returns    : A decimal number between 0 and 1
# Arguments  : NONE
# Throws     : Croaks if invoked in an invalid way, or if there is problem
#              replenishing the random cache.
# Notes      :
# See Also   :
sub _rand{
    my $self = shift;
    _force_instance($self);

    # get the next random number from the cache
    my $num = shift @{$self->{_CACHE_RANDOM}};
    if(!defined $num){
        # the cache was empty - so try top up the random cache - could croak
        _debug('random cache empty - attempting to replenish');
        $self->_increment_random_cache();

        # try shift again
        $num = shift @{$self->{_CACHE_RANDOM}};
    }

    # make sure we got a valid random number
    unless(defined $num && $num =~ m/^\d+([.]\d+)?$/sx && $num >= 0 && $num <= 1){
        _error('found invalid entry in random cache');
    }

    # return the random number
    _debug("returning $num (".(scalar @{$self->{_CACHE_RANDOM}}).' remaining in cache)');
    return $num;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Append random numbers to the cache.
# Returns    : Always returns 1.
# Arguments  : NONE
# Throws     : Croaks if incorrectly invoked or if the random generating
#              function fails to produce random numbers.
# Notes      :
# See Also   :
sub _increment_random_cache{
    my $self = shift;
    _force_instance($self);

    # genereate the random numbers
    my @random_numbers = $self->{_RNG}->random_numbers($_CLASS->config_random_numbers_required($self->{_CONFIG}));
    _debug('generated '.(scalar @random_numbers).' random numbers ('.(join q{, }, @random_numbers).')');

    # validate them
    unless(scalar @random_numbers){
        _error('random function did not return any random numbers');
    }
    foreach my $num (@random_numbers){
        unless($num =~ m/^1|(0([.]\d+)?)$/sx){
            _error("random function returned and invalid value ($num)");
        }
    }

    # add them to the cache
    foreach my $num (@random_numbers){
        push @{$self->{_CACHE_RANDOM}}, $num;
    }

    # always return 1 (to keep PerlCritic happy)
    return 1;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Get the required number of random words from the loaded words
#              file
# Returns    : An array of words
# Arguments  : NONE
# Throws     : Croaks on invalid invocation or error generating random numbers
# Notes      : The number of words generated is determined by the num_words
#              config key.
# See Also   :
sub _random_words{
    my $self = shift;
    _force_instance($self);

    # get the random words
    my @ans = ();
    _debug('about to generate '.$self->{_CONFIG}->{num_words}.' words');
    while ((scalar @ans) < $self->{_CONFIG}->{num_words}){
        my $word = $self->{_CACHE_DICTIONARY_LIMITED}->[$self->_random_int(scalar @{$self->{_CACHE_DICTIONARY_LIMITED}})];
        _debug("generate word=$word");
        push @ans, $word;
    }

    # return the list of random words
    _debug('returning '.(scalar @ans).' words');
    return @ans;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Get the separator character to use based on the loaded config.
# Returns    : A scalar containing the separator, which could be an empty string.
# Arguments  : NONE
# Throws     : Croaks on invalid invocation, or if there is a problem generating
#              any needed random numbers.
# Notes      : The character returned is controlled by the config variable
#              separator_character
# See Also   :
sub _separator{
    my $self = shift;
    _force_instance($self);

    # figure out the separator character
    my $sep = $self->{_CONFIG}->{separator_character};
    if ($sep eq 'NONE'){
        $sep = q{};
    }elsif($sep eq 'RANDOM'){
        if(defined $self->{_CONFIG}->{separator_alphabet}){
            $sep = $self->{_CONFIG}->{separator_alphabet}->[$self->_random_int(scalar @{$self->{_CONFIG}->{separator_alphabet}})];
        }else{
            $sep = $self->{_CONFIG}->{symbol_alphabet}->[$self->_random_int(scalar @{$self->{_CONFIG}->{symbol_alphabet}})];
        }
    }

    # return the separator character
    return $sep
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Return the padding character based on the loaded config.
# Returns    : A scalar containing the padding character, which could be an
#              empty string.
# Arguments  : 1. the separator character being used to generate the password
# Throws     : Croaks on invalid invocation, or if there is a problem geneating
#              any needed random numbers.
# Notes      : The character returned is determined by a combination of the
#              padding_type & padding_character config variables.
# See Also   :
sub _padding_char{
    my $self = shift;
    my $sep = shift;


    # validate args - doing it the old-fassioned way because the separator will
    # be an empty string if the separator is set to 'NONE'
    _force_instance($self);
    if($sep){
        unless(Symbol->check($sep)){
            _error('first argument must be an empty string or a valid Symbol');
        }
    }

    # if there is no padding character needed, return an empty string
    if($self->{_CONFIG}->{padding_type} eq 'NONE'){
        return q{};
    }

    # if we got here we do need a character, so generate one as appropriate
    my $padc = $self->{_CONFIG}->{padding_character};
    if($padc eq 'SEPARATOR'){
        $padc = $sep;
    }elsif($padc eq 'RANDOM'){
        if(defined $self->{_CONFIG}->{padding_alphabet}){
            $padc = $self->{_CONFIG}->{padding_alphabet}->[$self->_random_int(scalar @{$self->{_CONFIG}->{padding_alphabet}})];
        }else{
            $padc = $self->{_CONFIG}->{symbol_alphabet}->[$self->_random_int(scalar @{$self->{_CONFIG}->{symbol_alphabet}})];
        }
    }

    # return the padding character
    return $padc;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Apply the case transform (if any) specified in the loaded config.
# Returns    : Always returns 1 (to keep PerlCritic happy)
# Arguments  : 1. A reference to the array contianing the words to be
#                 transformed.
# Throws     : Croaks on invalid invocation or if there is a problem generating
#              any needed random numbers.
# Notes      : The transformations applied are controlled by the case_transform
#              config variable.
# See Also   :
sub _transform_case{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = compile(ArrayRef[Str]);
    my ($words_ref) = $args_check->(@args);

    # if the transform is set to nothing, then just return
    if($self->{_CONFIG}->{case_transform} eq 'NONE'){
        return 1;
    }

    # apply the appropriate transform
    ## no critic (ProhibitCascadingIfElse);
    if($self->{_CONFIG}->{case_transform} eq 'UPPER'){
        foreach my $i (0..((scalar @{$words_ref}) - 1)){
            $words_ref->[$i] = uc $words_ref->[$i];
        }
    }elsif($self->{_CONFIG}->{case_transform} eq 'LOWER'){
        foreach my $i (0..((scalar @{$words_ref}) - 1)){
            $words_ref->[$i] = lc $words_ref->[$i];
        }
    }elsif($self->{_CONFIG}->{case_transform} eq 'CAPITALISE'){
        foreach my $i (0..((scalar @{$words_ref}) - 1)){
            $words_ref->[$i] = ucfirst lc $words_ref->[$i];
        }
    }elsif($self->{_CONFIG}->{case_transform} eq 'INVERT'){
        foreach my $i (0..((scalar @{$words_ref}) - 1)){
            $words_ref->[$i] = lcfirst uc $words_ref->[$i];
        }
    }elsif($self->{_CONFIG}->{case_transform} eq 'ALTERNATE'){
        # randomly decide whether to capitalise on odd or even
        my $rand_bias = ($self->_random_int(2) % 2 == 0) ? 1 : 0;
        foreach my $i (0..((scalar @{$words_ref}) - 1)){
            my $word = $words_ref->[$i];
            if(($i + $rand_bias) % 2 == 0){
                $word = lc $word;
            }else{
                $word = uc $word;
            }
            $words_ref->[$i] = $word;
        }
    }elsif($self->{_CONFIG}->{case_transform} eq 'RANDOM'){
        foreach my $i (0..((scalar @{$words_ref}) - 1)){
            my $word = $words_ref->[$i];
            if($self->_random_int(2) % 2 == 0){
                $word = uc $word;
            }else{
                $word = lc $word;
            }
            $words_ref->[$i] = $word;
        }
    }
    ## use critic

    return 1; # just to to keep PerlCritic happy
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Apply any case transforms specified in the loaded config.
# Returns    : Always returns 1 (to keep PerlCritic happy)
# Arguments  : 1. a reference to an array containing the words that will make up
#                 the password.
# Throws     : Croaks on invalid invocation or invalid args.
# Notes      : The substitutions that will be applied are specified in the
#              character_substitutions config variable.
# See Also   :
sub _substitute_characters{
    my @args = @_;
    my $self = shift @args;
    _force_instance($self);

    # validate args
    state $args_check = compile(ArrayRef[Str]);
    my ($words_ref) = $args_check->(@args);

    # if no substitutions are defined, do nothing
    unless(defined $self->{_CONFIG}->{character_substitutions} && (scalar keys %{$self->{_CONFIG}->{character_substitutions}})){
        return 1;
    }

    # If we got here, go ahead and apply the substitutions
    foreach my $i (0..((scalar @{$words_ref}) - 1)){
        my $word = $words_ref->[$i];
        foreach my $char (keys %{$self->{_CONFIG}->{character_substitutions}}){
            my $sub = $self->{_CONFIG}->{character_substitutions}->{$char};
            $word =~ s/$char/$sub/sxg;
        }
        $words_ref->[$i] = $word;
    }

    # always return 1 to keep PerlCritic happy
    return 1;
}

#####-SUB-######################################################################
# Type       : CLASS (PRIVATE)
# Purpose    : Perform sanity checks on all the config key definitions
# Returns    : Always returns 1 (to keep PerlCritic happy)
# Arguments  : NONE
# Throws     : Croaks if there is a problem with a key definition.
# Notes      : The function is designed to be called from the constructor when
#              in debug mode, so it prints information on what it's doing
#              to STDERR.
# See Also   :
sub _check_config_key_definitions{
    # get a reference to the config key definitions form the Types class
    my $key_definitions = $_TYPES_CLASS->_config_keys();

    # loop through each key definition and do some sanity checks
    my $num_problems = 0;
    foreach my $key_name ($_CLASS->defined_config_keys()){
        _debug("checking config key '$key_name'");
        unless(ConfigKeyDefinition->check($key_definitions->{$key_name})){
            _warn(ConfigKeyDefinition->get_message($key_definitions->{$key_name}));
            $num_problems++;
        }
    }
    if($num_problems == 0){
        _debug('all config key definitions OK');
    }else{
        _error("there are errors in $num_problems config key definitions - fix these before continuing");
    }

    # to keep perlcritic happy
    return 1;
}

#####-SUB-######################################################################
# Type       : CLASS (PRIVATE)
# Purpose    : Perform sanity checks on all defined presets
# Returns    : Always returns 1 (to keep perlcritic happy)
# Arguments  : NONE
# Throws     : Croaks if there is a problem with a preset.
# Notes      : The function is designed to be called from the constructor when
#              in debug mode, so it prints information on what it's doing
#              to STDERR.
# See Also   :
sub _check_preset_definitions{
    # get a reference to the preset definitions from the types class
    my $preset_defs = $_TYPES_CLASS->_presets();

    # loop through all presets and perform sanity checks
    my $num_problems = 0;
    foreach my $preset_name (sort keys %{$preset_defs}){
        _debug("checking preset '$preset_name'");
        unless(PresetDefinition->check($preset_defs->{$preset_name})){
            _warn(PresetDefinition->get_message($preset_defs->{$preset_name}));
            $num_problems++;
        }
    }
    if($num_problems == 0){
        _debug('all presets OK');
    }else{
        _error("there are errors in $num_problems presets - fix these before continuing");
    }

    # to keep perlcritic happy
    return 1;
}

#####-SUB-######################################################################
# Type       : CLASS (PRIVATE)
# Purpose    : Create an RNG object that is as secure as possible.
# Returns    : An instance of a class that extends Crypt::HSXKPasswd::RNG.
# Arguments  : NONE
# Throws     : This function issues a warning if it has to fall back to
#              Crypt::HSXKPasswd::RNG::Basic.
# Notes      : This function works its way through the constructurs for the
#              following RNG classes in the following order, returing the first
#              successfully instantiate object:
#              1) Crypt::HSXKPasswd::RNG::Math_Random_Secure (using
#                 Math::Random::Secure)
#              2) Crypt::HSXKPasswd::RNG::Data_Entropy (using
#                 Data::Entropy::Algorithms)
#              3) Crypt::HSXKPasswd::RNG::DevUrandom (reads from /dev/urandom)
#              4) Crypt::HSXKPasswd::RNG::Basic (using Perl's built-in rand())
#              This ordering is based on security and speed - all but Basic are
#              good from a secutrity point of view, but Math::Random::Secure is
#              over six times faster than Data::Entropy::Algorithms, so it is
#              reduced to second place. Speed tested wth the commands:
#              time perl -MMath::Random::Secure -e "foreach my \$n (0..1000000){Math::Random::Secure::rand();}"
#              time perl -MData::Entropy::Algorithms -e "foreach my \$n (0..1000000){Data::Entropy::Algorithms::rand();}"
# See Also   :
sub _best_available_rng{
    # try the good entropy sources in order
    my $rng;
    eval{
        $rng = Crypt::HSXKPasswd::RNG::Math_Random_Secure->new(); # will return a truthy value on success
    }or do{
        _debug("Failed to instantiate a Crypt::HSXKPasswd::RNG::Math_Random_Secure object with error: $EVAL_ERROR");
    };
    return $rng if $rng;
    eval{
        $rng = Crypt::HSXKPasswd::RNG::Data_Entropy->new(); # will return a truthy value on success
    }or do{
        _debug("Failed to instantiate a Crypt::HSXKPasswd::RNG::Data_Entropy object with error: $EVAL_ERROR");
    };
    return $rng if $rng;
    eval{
        $rng = Crypt::HSXKPasswd::RNG::DevUrandom->new(); # will return a truthy value on success
    }or do{
        _debug("Failed to instantiate a Crypt::HSXKPasswd::RNG::DevUrandom object with error: $EVAL_ERROR");
    };
    return $rng if $rng;

    # if we got here, no secure RNGs were avaialable, so warn, then return an instance of the basic RNG
    _warn(q{using Perl's built-in rand() function for random number generation. This is secure enough for most users, but you can get more secure random numbers by installing Math::Random::Secure or Data::Entropy::Algorithms});
    return Crypt::HSXKPasswd::RNG::Basic->new();
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Gather entropy stats for the combination of the loaded config
#              and dictionary.
# Returns    : A hash of stats indexed by:
#              * 'permutations_blind_min' - the number of permutations to be
#                tested by an attacker with no knowledge of the dictionary file
#                used, or the config used, assuming the minimum possible
#                password length from the given config (as BigInt)
#              * 'permutations_blind_max' - the number of permutations to be
#                tested by an attacker with no knowledge of the dictionary file
#                used, or the cofig file used, assuming the maximum possible
#                password length fom the given config (as BigInt)
#              * 'permutations_blind' - the number of permutations for the
#                average password length for the given config (as BigInt)
#              * 'permutations_seen' - the number of permutations to be tested
#                by an attacker with full knowledge of the dictionary file and
#                configuration used (as BigInt)
#              * 'entropy_blind_min' - permutations_blind_min converted to bits
#              * 'entropy_blind_max' - permutations_blind_max converted to bits
#              * 'entropy_blind' - permutations_blind converted to bits
#              * 'entropy_seen' - permutations_seen converted to bits
# Arguments  : NONE
# Throws     : Croaks on invalid invocation
# Notes      : This function uses config_stats() to determined the longest and
#              shortest password lengths, so the caveat that function has
#              when it comes to multi-character substitutions applies here too.
#              This function assumes no accented characters (at least for now).
#              For the blind calculations, if any single symbol is present, a
#              search-space of 33 symbols is assumed (same as password
#              haystacks page)
# See Also   : config_stats()
sub _calculate_entropy_stats{
    my $self = shift;
    _force_instance($self);

    my %ans = ();

    # get the password length details for the config
    my %config_stats = $_CLASS->config_stats($self->{_CONFIG}, suppress_warnings => 1);
    my $b_length_min = Math::BigInt->new($config_stats{length_min});
    my $b_length_max = Math::BigInt->new($config_stats{length_max});

    # calculate the blind permutations - (based purely on length and alphabet)
    my $alphabet_count = 26; # all passwords have at least one case of letters
    if($self->{_CONFIG}->{case_transform} =~ m/^(ALTERNATE)|(CAPITALISE)|(INVERT)|(RANDOM)$/sx){
        $alphabet_count += 26; # these configs guarantee a mix of cases
    }
    if($self->{_CONFIG}->{padding_digits_before} > 0 || $self->{_CONFIG}->{padding_digits_after} > 0){
        $alphabet_count += 10; # these configs guarantee digits in the mix
    }
    if($self->_passwords_will_contain_symbol() || $self->{_CACHE_CONTAINS_ACCENTS}){
        $alphabet_count += 33; # the config almost certainly includes a symbol, so add 33 to the alphabet (like password haystacks does)
    }
    my $b_alphabet_count = Math::BigInt->new($alphabet_count);
    my $length_avg = round(($config_stats{length_min} + $config_stats{length_max})/2);
    $ans{permutations_blind_min} = $b_alphabet_count->copy()->bpow($b_length_min); #$alphabet_count ** $length_min;
    _debug('got permutations_blind_min='.$ans{permutations_blind_min});
    $ans{permutations_blind_max} = $b_alphabet_count->copy()->bpow($b_length_max); #$alphabet_count ** $length_max;
    _debug('got permutations_blind_max='.$ans{permutations_blind_max});
    $ans{permutations_blind} = $b_alphabet_count->copy()->bpow(Math::BigInt->new($length_avg)); #$alphabet_count ** $length_avg;
    _debug('got permutations_blind='.$ans{permutations_blind});

    # calculate the seen permutations
    my $num_words = scalar @{$self->{_CACHE_DICTIONARY_LIMITED}};
    my $b_num_words = Math::BigInt->new($num_words);
    my $b_seen_perms = Math::BigInt->new('0');
    # start with the permutations from the chosen words
    $b_seen_perms->badd($b_num_words->copy()->bpow(Math::BigInt->new($self->{_CONFIG}->{num_words}))); # += $num_words ** $self->{_CONFIG}->{num_words};
    # then add the extra randomness from the case transformations (if any)
    if($self->{_CONFIG}->{case_transform} eq 'RANDOM'){
        # multiply by two for each word
        for my $n (1..$self->{_CONFIG}->{num_words}){
            $b_seen_perms->bmul(Math::BigInt->new(2));
        }
    }elsif($self->{_CONFIG}->{case_transform} eq 'ALTERNATE'){
        # multiply by two for the one random decision about whether or capitalise the odd or even words
        $b_seen_perms->bmul(Math::BigInt->new(2));
    }
    # multiply in the permutations from the separator (if any - i.e. if it's randomly chosen)
    if($self->{_CONFIG}->{separator_character} eq 'RANDOM'){
        if(defined $self->{_CONFIG}->{separator_alphabet}){
            $b_seen_perms->bmul(Math::BigInt->new(scalar @{$self->{_CONFIG}->{separator_alphabet}}));
        }else{
            $b_seen_perms->bmul(Math::BigInt->new(scalar @{$self->{_CONFIG}->{symbol_alphabet}}));
        }
    }
    # multiply in the permutations from the padding character (if any - i.e. if it's randomly chosen)
    if($self->{_CONFIG}->{padding_type} ne 'NONE' && $self->{_CONFIG}->{padding_character} eq 'RANDOM'){
        if(defined $self->{_CONFIG}->{padding_alphabet}){
            $b_seen_perms->bmul(Math::BigInt->new(scalar @{$self->{_CONFIG}->{padding_alphabet}}));
        }else{
            $b_seen_perms->bmul(Math::BigInt->new(scalar @{$self->{_CONFIG}->{symbol_alphabet}}));
        }
    }
    # multiply in the permutations from the padding digits (if any)
    my $num_padding_digits = $self->{_CONFIG}->{padding_digits_before} + $self->{_CONFIG}->{padding_digits_after};
    while($num_padding_digits > 0){
        $b_seen_perms->bmul(Math::BigInt->new('10'));
        $num_padding_digits--;
    }
    $ans{permutations_seen} = $b_seen_perms;
    _debug('got permutations_seen='.$ans{permutations_seen});

    # calculate the entropy values based on the permutations
    $ans{entropy_blind_min} = $ans{permutations_blind_min}->copy()->blog(2)->numify();
    _debug('got entropy_blind_min='.$ans{entropy_blind_min});
    $ans{entropy_blind_max} = $ans{permutations_blind_max}->copy()->blog(2)->numify();
    _debug('got entropy_blind_max='.$ans{entropy_blind_max});
    $ans{entropy_blind} = $ans{permutations_blind}->copy()->blog(2)->numify();
    _debug('got entropy_blind='.$ans{entropy_blind});
    $ans{entropy_seen} = $ans{permutations_seen}->copy()->blog(2)->numify();
    _debug('got entropy_seen='.$ans{entropy_seen});

    # return the stats
    return %ans;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Calculate statistics on the loaded dictionary file
# Returns    : A hash of statistics indexed by:
#              * 'source' - the source for the word list
#              * 'filter_length_min' - the minimum allowed word length
#              * 'filter_length_max' - the maximum allowed word length
#              * 'num_words_total' - the number of words in the un-filtered
#                dictionary file
#              * 'num_words_filtered' - the number of words after filtering on
#                size limitations
#              * 'percent_words_available' - the percentage of the un-filtered
#                words remaining in the filtered words list
#              * 'contains_accents' - whether or not the filtered word list
#                contains accented letter
# Arguments  : NONE
# Throws     : Croaks on invalid invocation
# Notes      :
# See Also   :
sub _calcualte_dictionary_stats{
    my $self = shift;
    _force_instance($self);

    # create a hash to aggregate the stats into
    my %ans = ();

    # deal with agregate numbers first
    $ans{source} = $self->{_DICTIONARY_SOURCE}->source();
    $ans{num_words_total} = scalar @{$self->{_CACHE_DICTIONARY_FULL}};
    $ans{num_words_filtered} = scalar @{$self->{_CACHE_DICTIONARY_LIMITED}};
    $ans{percent_words_available} = round(($ans{num_words_filtered}/$ans{num_words_total}) * 100);
    $ans{filter_length_min} = $self->{_CONFIG}->{word_length_min};
    $ans{filter_length_max} = $self->{_CONFIG}->{word_length_max};
    $ans{contains_accents} = $self->{_CACHE_CONTAINS_ACCENTS};

    # return the stats
    return %ans;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : A function to check if passwords genereated with the loaded
#              config would contian a symbol
# Returns    : 1 if the config will produce passwords with a symbol, or 0
#              otherwise
# Arguments  : NONE
# Throws     : Croaks on invalid invocation
# Notes      : This function is used by _calculate_entropy_stats() to figure out
#              whether or not there are symbols in the alphabet when calculating
#              the brute-force entropy.
# See Also   : _calculate_entropy_stats()
sub _passwords_will_contain_symbol{
    my $self = shift;
    _force_instance($self);

    # assume no symbol, if we find one, set to 1
    my $symbol_used = 0;

    ## no critic (ProhibitEnumeratedClasses);
    # first check the padding
    if($self->{_CONFIG}->{padding_type} ne 'NONE'){
        if($self->{_CONFIG}->{padding_character} eq 'RANDOM'){
            if(defined $self->{_CONFIG}->{padding_alphabet}){
                my $all_pad_chars = join q{}, @{$self->{_CONFIG}->{padding_alphabet}};
                if($all_pad_chars =~ m/[^0-9a-zA-Z]/sx){ # if we have just one non-word character
                    $symbol_used = 1;
                }
            }else{
                my $all_pad_chars = join q{}, @{$self->{_CONFIG}->{symbol_alphabet}};
                if($all_pad_chars =~ m/[^0-9a-zA-Z]/sx){ # if we have just one non-word character
                    $symbol_used = 1;
                }
            }
        }else{
            if($self->{_CONFIG}->{padding_character} =~ m/[^0-9a-zA-Z]/sx){ # the padding character is not a word character
                $symbol_used = 1;
            }
        }
    }

    # then check the separator
    if($self->{_CONFIG}->{separator_character} ne 'NONE'){
        if($self->{_CONFIG}->{separator_character} eq 'RANDOM'){
            if(defined $self->{_CONFIG}->{separator_alphabet}){
                my $all_sep_chars = join q{}, @{$self->{_CONFIG}->{separator_alphabet}};
                if($all_sep_chars =~ m/[^0-9a-zA-Z]/sx){ # if we have just one non-word character
                    $symbol_used = 1;
                }
            }else{
                my $all_sep_chars = join q{}, @{$self->{_CONFIG}->{symbol_alphabet}};
                if($all_sep_chars =~ m/[^0-9a-zA-Z]/sx){ # if we have just one non-word character
                    $symbol_used = 1;
                }
            }
        }else{
            if($self->{_CONFIG}->{separator_character} =~ m/[^0-9a-zA-Z]/sx){ # the separator is not a word character
                $symbol_used = 1;
            }
        }
    }
    ## use critic

    # return
    return $symbol_used;
}

#####-SUB-######################################################################
# Type       : INSTANCE (PRIVATE)
# Purpose    : Update the entropy stats cache (and warn of low entropy if
#              appropriate)
# Returns    : always returns 1 (to keep perlcritic happy)
# Arguments  : NONE
# Throws     : Croaks on invalid invocation
# Notes      : This function should only be called from config() or dictionary().
#              The entropy is calculated with _calculate_entropy_stats(), and a
#              reference to the hash returned from that function is stored in
#              $self->{_CACHE_ENTROPYSTATS}.
# See Also   : _calculate_entropy_stats(), config() & dictionary()
sub _update_entropystats_cache{
    my $self = shift;
    _force_instance($self);

    # do nothing if the dictionary has not been loaded yet (should only happen while the constructor is building an instance)
    return 1 unless($self->{_DICTIONARY_SOURCE} && blessed($self->{_DICTIONARY_SOURCE}) && $self->{_DICTIONARY_SOURCE}->isa($_DICTIONARY_BASE_CLASS));

    # calculate and store the entropy stats
    my %stats = $self->_calculate_entropy_stats();
    $self->{_CACHE_ENTROPYSTATS} = \%stats;

    # warn if we need to
    unless(uc $_ENTROPY_WARNINGS eq 'NONE'){
        # blind warnings are always needed if the level is not 'NONE'
        if($self->{_CACHE_ENTROPYSTATS}->{entropy_blind_min} < $_ENTROPY_MIN_BLIND){
            _warn('for brute force attacks, the combination of the loaded config and dictionary produces an entropy of '.$self->{_CACHE_ENTROPYSTATS}->{entropy_blind_min}.'bits, below the minimum recommended '.$_ENTROPY_MIN_BLIND.'bits');
        }

        # seen warnings if the cut-off is not 'BLIND'
        unless(uc $_ENTROPY_WARNINGS eq 'BLIND'){
            if($self->{_CACHE_ENTROPYSTATS}->{entropy_seen} < $_ENTROPY_MIN_SEEN){
                _warn('for attacks assuming full knowledge, the combination of the loaded config and dictionary produces an entropy of '.$self->{_CACHE_ENTROPYSTATS}->{entropy_seen}.'bits, below the minimum recommended '.$_ENTROPY_MIN_SEEN.'bits');
            }
        }
    }

    # to keep perl critic happy
    return 1;
}

#####-SUB-######################################################################
# Type       : CLASS (PRIVATE)
# Purpose    : To nicely print a Math::BigInt object
# Returns    : a string representing the object's value in scientific notation
#              with 1 digit before the decimal and 2 after
# Arguments  : 1. a Math::BigInt object
# Throws     : Croaks on invalid invocation or args
# Notes      :
# See Also   :
sub _render_bigint{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(InstanceOf['Math::BigInt']);
    my ($bigint) = $args_check->(@args);

    # convert the bigint to an array of characters
    my @chars = split //sx, "$bigint";

    # render nicely
    if(scalar @chars < 3){
        return q{}.join q{}, @chars;
    }
    # start with the three most signifficant digits (as a decimal)
    my $ans = q{}.$chars[0].q{.}.$chars[1].$chars[2];
    # then add the scientific notation bit
    $ans .= 'x10^'.(scalar @chars - 1);

    # return the result
    return $ans;
}

#####-SUB-######################################################################
# Type       : CLASS (PRIVATE)
# Purpose    : Get the so-called 'grapheme length' of a unicode string, that is
#              to say, the length of a word where a letter with an accent counts
#              as a single letter.
# Returns    : An integer
# Arguments  : 1) the string to get the length of
# Throws     : Croaks on invalid invocation and invalid args
# Notes      : Perl, by default, will consider accented letters as having a
#              length of two. This function uses a very common algorythm
#              recommended all over the internet, including in the Perl Unicode
#              cookbook: http://search.cpan.org/~shay/perl-5.20.2/pod/perlunicook.pod
#              Before resorting to this technique, I tried to use the
#              grapheme_length function from Unicode::Util, but it proved
#              unacceptably slow.
# See Also   :
sub _grapheme_length{
    my @args = @_;
    my $class = shift @args;
    _force_class($class);

    # validate args
    state $args_check = compile(Str);
    my ($string) = $args_check->(@args);

    # do the calculation
    my $grapheme_length = 0;
    while($string =~ /\X/gsx){$grapheme_length++};

    # return the result
    return $grapheme_length;
}

1; # because Perl is just a little bit odd :)
__END__