NAME
    Business::DK::PO - danish postal order code generator/validator

VERSION
    This documentation describes version 0.07

SYNOPSIS
        use Business::DK::PO qw(validate);

        my $rv;
        eval {
            $rv = validate(1234563891234562);
        };

        if ($@) {
            die "Code is not of the expected format - $@";
        }

        if ($rv) {
            print "Code is valid";
        } else {
            print "Code is not valid";
        }


        use Business::DK::PO qw(calculate);

        my $code = calculate(1234);


        #Using with Params::Validate

        use Params::Validate qw(:all);
        use Business::DK::PO qw(validatePO);

        sub check_cpr {
            validate( @_,
            { po =>
                { callbacks =>
                    { 'validate_po' => sub { validatePO($_[0]); } } } } );

            print $_[1]." is a valid PO\n";

        }

DESCRIPTION
    The postal orders and postal order codes are used by the danish postal
    service PostDanmark.

FUNCTIONS
  validate
    The function takes a single argument, a 16 digit postal order code.

    The function returns 1 (true) in case of a valid postal order code
    argument and 0 (false) in case of an invalid postal order code argument.

    The validation function goes through the following steps.

    Validation of the argument is done using the functions (all described
    below in detail):

    *   _argument

    *   _content

    *   _length

    If the argument is a valid argument the sum is calculated by
    _calculate_sum based on the argument and the controlcifers array.

    The sum returned is checked using a modulus caluculation and based on
    its validity either 1 or 0 is returned.

  validatePO
    A wrapper for "validate" with a name more suitable for importing, it is
    less common and therefor less intrusive.

    See "validate" for details.

  calculate
    The function takes a single argument, an integer indicating a unique
    reference number you can use to identify an order. Suggestions are
    invoice number, order number or similar.

    The number provided must be between 1 and 15 digits long, meaning a
    number between 1 and 999 trillions.

    The function returns a postal order code consisting of the number given
    as argument appended with a control cifer to make the code valid (See:
    b<validate>

    The calculation function goes through the following steps.

    Validation of the argument is done using the functions (all described
    below in detail):

    *   _argument

    *   _content

    *   _length

    If the argument is a valid argument the sum is calculated by
    _calculate_sum based on the argument and the controlcifers array.

    Based on the sum the argument the controlcifer is calculated and
    appended so that the argument becomes a valid postal order code.

    The calculated and valid code is then returned, left-padded with zeroes
    to make it 16 digits long (SEE: validate).

PRIVATE FUNCTIONS
  _argument
    This function is called from either validate or calculate if an argument
    is not provided.

    It dies with an error message indicating the exceptional situation and
    attempts to guide the user to providing a sensible input.

    The _argument function takes two arguments:

    *   minimum length required of number (mandatory)

    *   maximum length required of number (optional)

    The arguments are used in the error message issued with die, since this
    method always dies.

  _content
    This function validates the content of the argument, it croaks if the
    argument is not an integer (consisting of digits only).

  _length
    This function validates the length of the argument, it dies if the
    argument does not fit wihtin the boundaries specified by the arguments
    provided:

    The _length function takes the following arguments:

    *   number (mandatory), the number to be validated

    *   minimum length required of number (mandatory)

    *   maximum length required of number (optional)

  _calculate_sum
    This function takes an integer and calculates the sum bases on the the
    controlcifer array.

EXPORTS
    Business::DK::PO exports on request:

    *   "validate"

    *   "validatePO"

    *   "calculate"

    *   "_argument"

    *   "_content"

    *   "_length"

    *   "_calculate_sum"

TESTS
    Coverage of the test suite is at 100%

        ---------------------------- ------ ------ ------ ------ ------ ------ ------
        File                           stmt   bran   cond    sub    pod   time  total
        ---------------------------- ------ ------ ------ ------ ------ ------ ------
        blib/lib/Business/DK/PO.pm    100.0  100.0    n/a  100.0  100.0  100.0  100.0
        Total                         100.0  100.0    n/a  100.0  100.0  100.0  100.0
        ---------------------------- ------ ------ ------ ------ ------ ------ ------

    Test::Kwalitee passes

    Test::Perl::Critic passes at severity 1, brutal, with many policies
    disabled though, see /perlcriticrc.

BUGS
    Please report issues via CPAN RT:

      http://rt.cpan.org/NoAuth/Bugs.html?Dist=Business-DK-PO

    or by sending mail to

      bug-Business-DK-PO@rt.cpan.org

SEE ALSO
    <http://www.bgbank.dk/bfBlankethaandbog>
    bin/calculate_po.pl
    bin/validate_po.pl

AUTHOR
    Jonas B. Nielsen, (jonasbn) - "<jonasbn@cpan.org>"

COPYRIGHT
    Business-DK-PO is (C) by Jonas B. Nielsen, (jonasbn) 2006-2014

    Business-DK-PO is released under the artistic license

    The distribution is licensed under the Artistic License, as specified by
    the Artistic file in the standard perl distribution
    (http://www.perl.com/language/misc/Artistic.html).