NAME Tie::Assert - Enforces restrictions on variables' contents VERSION This document refers to version 0.13 of Tie::Assert, released March 8th 2005. SYNOPSIS # Tie a few scalars... my $dna; tie ($dna, 'Tie::Assert::Scalar', sequenceCheck => Tie::Assert::CheckFactory->regex(qr/^[gatc]*$/i), ); $dna = 'gattaca'; # Fine, it matches the regex. $dna = 'wibble'; # Doesn't match regex, will cause an error. my $percentage_score; tie ($percentage_score, 'Tie::Assert::Scalar', rangeCheck => Tie::Assert::CheckFactory->range(0 => 100), ); $percentage_score = 23; # Fine, well within the range provided. $percentage_score = 201; # An invalid percentage score, more errors. my $positive_integer; tie ($positive_integer, 'Tie::Assert::Scalar', positiveCheck => Tie::Assert::CheckFactory->min(0), integerCheck => Tie::Assert::CheckFactory->integer_ok(), ); $positive_number = 23; # A valid positive number $positive_number = -1; # Invalid, another error. Arrays For usage of Tie::Assert with arrays please refer to the Perldoc for Tie::Assert::Array. DESCRIPTION Tie::Assert is designed to fill the niche when Perl developers need to guarantee that a variable obeys certain rules at all times, times when users of others languages would rely on assert() and type-checking. This module is intended to be as flexible as possible, allowing the developer to use it to do things as basic as ensuring a variable is numeric and dying with an error message if not, up to ensuring a string contains a valid and existing account number, and mailing a support account if it's ever invalid. Flexibility is the primary goal here, this module's useful for working out where a program's setting it's variables to invalid values, to providing a certain added level of security by ensuring variables cannot be changed to out-of-range values. Anywhere a value has to remain within a particular range this module could potentially be useful. BASIC USAGE To use Tie::Assert in it's most common way you create a series of checks with the methods of Tie::Assert::CheckFactory, and tie them do a variable via the Tie::Assert::* family of modules. For example, suppose we're going to ensure a variable is a positive number, we can start by using the is_number() and min() functions of CheckFactory to produce the following two checks: my $number_check = Tie::Assert::CheckFactory->is_number(); my $positive_check = Tie::Assert::CheckFactory->min(0); Now we can create our variable and tie it to these two checks, giving them meaningful names in the control hash for tie(). The variable's a scalar so we'll be using Tie::Assert::Scalar as the checker. my $positive_number; # We're tying $positive_number to a 'Tie::Assert::Scalar' checker.. tie ($positive_number, 'Tie::Assert::Scalar', # .. call the number check is_number, this'll be displayed in # the error if an assignment tries to set it to something # not a number.. is_number => $number_check, # .. similarly call the positive number check is_positive. is_positive => $positive_number, ); That's all there is to it. Now if we try and assign a value to the $positive_number variable which isn't a positive number it'll draw our attention to the problem by quitting the program with a nice meaningful error message. ADVANCED TOPICS Obtaining the tied object When Perl ties a variable it creates an object which methods are called on behind the scenes, it's this object that other methods can be called upon to change the way the Tie::Assert class affects it. There's a keyword named tied() which returns the object behind a given tied variable, so we can obtain the object behind $positive_number by: my $positive_number_object = tied($positive_number); If we want we can skip storing the tied object in a variable itself and simply call methods directly on it, it's this format that'll be used below. Adding and removing checks on the fly Sometimes it's convenient to be able to change the checks on a variable at run time, and here's where you want to be able to add and remove checks from the variable yourself rather than just relying on those configured by the tie(). To add a check call add_check() on the tied object, providing it with a check name and check as you did in the constructor. tied($variable)->add_check( oneToTen => Tie::Assert::CheckFactory->range(1=>10), ); If there was already a check assigned to the variable with the given name then it will be replaced by the new one. To remove a check call remove_check() providing it with the check name only. tied($variable)->remove_check('oneToTen'); A final removal method remove_all_checks() will destroy all of the checks on a given variable. tied($variable)->remove_all_checks(); Obtaining information on the current checks There's a couple of methods to query the filters assigned to a given variable, the first is a simple count of the number of filters currently attached to a variable: print "Currently ",tied($variable)->count_filters," filters\n"; A complete list of filters can be obtained by calling the filter_names() method: for my $filter_name (tied($variable)->filter_names) { print "Got filter $filter_name\n"; } Changing the error handler Often the developer doesn't want the entire program to die when it's given an invalid value, they simply want it to log it, or even just ignore the assignment. The Tie::Assert system handles this through the set_error_handler() method that all tie'able classes in the system support, to use it simply call set_error_handler() on the tied object (See 'Obtaining the tied object' above) and pass it either a code fragment, or a code reference to a function to handle the error. Either way the function you provide should accept one parameter, the name of the check. So, if we had had a logging object with a log() method we may set the error handler by calling: tied($variable)->set_error_handler( sub {$logger->log("Assert error, '".shift()."' check failed"); ); If we had a method to do the logging it's even easier. tied($variable)->set_error_handler( \&log_assert_error ); ... sub log_assert_error { my ($check_name) = @_; $logger->log("Assert error, '".$check_name."' check failed");` } Providing your own custom checks The CheckFactory provides functionality sufficient to cover the most common uses, but sometimes there's need to be able to add your own custom checks. The secret here is that the CheckFactory itself simply returns a closure which takes the value as it's sole parameter and returns a boolean indicating whether it's allowed the value or not. To create your own check it's just a case of providing your own closure or function pointer with the same 'true for accept, false for error' behavior. So, if I wanted to add a filter based on only allowing odd numbers.. tied($variable)->add_check(isOdd, sub { $_[0] % 2 }); Enabling and disabling the entire Test::Assert system Sometimes in development there's a need to have stringent checking, but when it hits live the error handler slows the process down too much. The ideal solution to this is to replace the error handler with a lighter version, thus keeping Tie::Assert's checks in the most vital environment, but for times when this is not required it's possible to disable the entire Tie::Assert framework with one single call. Tie::Assert->disable; ... will turn off all assertions, allowing any values to be stored again, and ... Tie::Assert->enable; ... will again enable the assertions, with none of the configuration of them lost during their disabled time. Note that the global enabling and disabling of the Assert system will not change the filters reported as being attached to a variable, they're still attached there even when they're not active. NOTE This module is ALPHA code, it's seemed stable in a number of projects but the interface is liable to change before the final release. Developments expected in future versions include: Adding Tie::Assert::Array This should allow the use of assertions on both the index and value of an array. Adding Tie::Assert::Hash This should allow the use of assertions on both the key and the value of a hash. Boolean Checks Composite methods allowing you to combine multiple checks with AND or OR logic, or reverse the result of a single test with a NOT. PresentIn Checks Basically an enumeration, restricts the value to those provided. Length Checks Restrictions based on the length of a string. More comprehensive error messages The error handlers should also receive the value which caused the error, and the original value. Hopefully a version with all of these changes should be released within a week or so. THANKS TO Mike Castle - Pointed out an error in the Build.PL's requirements. ..and various folks from Perlmonks.org - For helping me thrash out the initial thoughts of this module in the Chatterbox, and also suggesting a better name than the one I had. BUGS No known bugs at present. SEE ALSO Tie::Aspect::CheckFactory, Tie::Aspect::Scalar AUTHOR Paul Golds (Paul.Golds@GMail.com) COPYRIGHT Copyright (c) 2004/2005, Paul Golds. All Rights Reserved. This module is free software. It may be used, redistributed, and/or modified under the same terms as Perl itself.