NAME
Business::AU::ABN - Format and validate ABNs ( Australian Business Number )
SYNOPSIS
# Create a new ABN object
use Business::AU::ABN;
my $ABN = new Business::AU::ABN( '12 004 044 937' );
# Validate the ABN
$ABN->validate;
# Validate in a single method call
Business::AU::ABN->validate( '12 004 044 937' );
# Validate in a single function call
Business::AU::ABN::validate( '12 004 044 937' );
# The validate function is also importable
use Business::AU:ABN 'validate';
validate( '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 is specifically designed to catch situations in which you get two digits the wrong way around, or worse.
Business::AU::ABN implements an object form of an ABN number. It has the ability to validate, and automatically reformates the number into the common and most prefered 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 sub can be accessed in ANY form, and will just "do what you mean". See the method details for more information.
METHODS
new $string
The new method creates a new Business::AU::ABN object. It expects as argument a defined string containing at least one non-whitespace character, or it will immediately return undef.
The method does not reformat or check the string provided in any way.
to_string
The to_string method returns the ABN as a string. This is the method called by the stringification overload. Providing that the ABN has been validated, this method will return the ABN in the correct '01 234 567 890' format.
$ABN->validate
When called as a method on an object, validate does a number of simple format checks on the string originally provided, cleaning up and reformatting whitespace as needed. It then runs a checksum validation on the value.
Returns true if the ABN is valid, or false if not
Business::AU::ABN->validate $string
When called as a static method, validate takes a string as an argument and attempts to validate it. When called in this form, the method is a little more flexible, and should tolerate just about any crap as an argument, returning false.
Returns the correctly formatted ABN (which is also 'true' in boolean context) if the ABN is valid. Returns false otherwise.
Business::AU::ABN::validate $string
When called directly as a fully referenced function, validate 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 $string
The validate function can also be imported to your package and used directly, as in the following example.
use Business::AU::ABN 'validate';
my $abn = '01 234 567 890';
print "Your ABN is " . validate($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 DO
Add the method acn to derive the older Australian Company Number
SUPPORT
Bugs should be reported via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Business%3A%3AAU%3A%3AABNFor 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.