NAME
    Business::AU::ABN - Validate and format Australian Business Numbers

SYNOPSIS
      # Create a new validated ABN object
      use Business::AU::ABN;
      my $ABN = new Business::AU::ABN( '12 004 044 937' );
  
      # Validate in a single method call
      Business::AU::ABN->validate_abn( '12 004 044 937' );
  
      # Validate in a single function call
      Business::AU::ABN::validate_abn( '12 004 044 937' );
  
      # The validate_abn function is also importable
      use Business::AU::ABN 'validate_abn';
      validate_abn( '12 004 044 937' );

DESCRIPTION
    The Australian Business Number ( ABN ) is a government allocated number
    required by all businesses in order to trade in Australia. It is
    intented to provide a central, universal, and unique identifier for all
    businesses.

    It's also rather neat, in that it is capable of self-validating. Much
    like a credit card number does, a simple algorithm applied to the digits
    can confirm that the number is valid. ( Although the business may not
    actually exist ). The checksum algorithm was specifically designed to
    catch situations in which you get two digits the wrong way around, or
    something of that nature.

    Business::AU::ABN provides a validation/formatting mechanism, and an
    object form of an ABN number. ABNs are reformatted into the most
    preferred format, '01 234 567 890'.

    The object itself automatically stringifies to the it's formatted
    number, so you can do things like "print "Your ABN $ABN looks OK"" and
    other things of that nature.

  Highly flexible validation
    Apart from the algorithm itself, most of this module is aimed at making
    the validation mechanism as flexible and easy to use as possible.

    With this in mind, the "validate_abn" sub can be accessed in ANY form,
    and will just "do what you mean". See the method details for more
    information.

    Also, all validation will take just about any crap as an argument, and
    not die or throw a warning. It will just return false.

  "Group" ABNs as yet unsupported
    For some bizarre reason I've not yet managed to work out, there exists a
    SECOND type of ABN not documented in the ATO mod 89 document, known as a
    "group" ABN, and designed for one member of a group of companies.
    Frankly, I only found out this exists because my accountany has one, and
    I couldn't put the number into Quick Books.

    The Group ABN has an additional 3 numbers ( at the end I believe ). I
    have no idea how to validate it, and if anyone knows more, drop me an
    email at the address provided below.

METHODS
  new $string
    The "new" method creates a new "Business::AU::ABN" object. Takes as
    argument a value, and validates that it is correct before creating the
    object. As such if an object is provided that passes
    "$ABN->isa('Business::AU::ABN')", it IS a valid ABN and does not need to
    be checked.

    Returns a new "Business::AU::ABN" on success, or sets the error string
    and returns false if the string is not an ABN.

  $ABN->validate_abn
    When called as a method on an object, "validate_abn" isn't really that
    useful, as ABN objects are already assumed to be correct, but the method
    is included for completeness sake.

    Returns the correctly formatted ABN (which is also 'true' in boolean
    context) if the ABN is valid, or false if not.

  Business::AU::ABN->validate_abn $string
    When called as a static method, "validate_abn" takes a string as an
    argument and attempts to validate it as an ABN.

    Returns the correctly formatted ABN (which is also 'true' in boolean
    context) if the ABN is valid. Returns false otherwise.

  Business::AU::ABN::validate_abn $string
    When called directly as a fully referenced function, "validate_abn"
    responds in exactly the same was as for the static method above.

    Returns the correctly formatted ABN (which is also 'true' in boolean
    context) if the ABN is valid. Returns false otherwise.

  validate_abn $string
    The "validate_abn" function can also be imported to your package and
    used directly, as in the following example.

      use Business::AU::ABN 'validate_abn';
      my $abn = '01 234 567 890';
      print "Your ABN is " . validate_abn($abn) ? 'valid' : 'invalid';

    The imported function reponds identically to the fully referenced
    function and the static method.

    Returns the correctly formatted ABN (which is also 'true' in boolean
    context) if the ABN is valid. Returns false otherwise.

  to_string
    The "to_string" method returns the ABN as a string. This is also the
    method called by the stringification overload.

  errstr
    When "validate_abn" or "new" return false, a message describing the
    problem can be accessed via any of the following.

      # Global variable
      $Business::AU::ABN::errstr
  
      # Class method
      Business::AU::ABN->errstr
  
      # Function
      Business::AU::ABN::errstr()

TO DO
    Add the method "ACN" to get the older Australian Company Number from the
    ABN, which is a superset of it.

SUPPORT
    Bugs should be reported via the CPAN bug tracker at

      http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Business%3A%3AAU%3A%3AABN

    For other issues, contact the author

AUTHORS
            Adam Kennedy ( maintainer )
            cpan@ali.as
            http://ali.as/

COPYRIGHT
    Copyright (c) 2003-2004 Adam Kennedy. All rights reserved. This program
    is free software; you can redistribute it and/or modify it under the
    same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

