krishna03 / pmvalidation

A modular, extendable text validation library for iOS.

PMValidation is a modular, extendable text validation library for iOS. It comes with several common validation types for often-used tasks like validating registration forms, however it was architected to be easily extended with your own validation types.

Features

• Validate individual string objects or listen to changes from UIKit objects
• Modular – validation types can be used together to create complex validation constraints
• Extensible - Easily create your own validation types by subclassing PMValidationType
• Comes with several useful validation types to satisfy most validation needs
• Easily implement form validation by using PMValidationManager to register many UIKit objects

Overview

At its simplest, PMValidation starts with an instance of PMValidationUnit. Each PMValidationUnit controls one or more PMValidationType objects, and PMValidationUnit provides an overall validation state for the types registered with it. All validation types are subclasses of PMValidationType, and you can do the same to easily create your own validator types.

Generally, a PMValidationUnit handles the validation of one text object. When you are validating more than one text object, such as with a validation form, the PMValidationManager class is useful. This class controls one or more PMValidationUnit objects, providing an overall validation status and notification routing.

Getting Started

The included validation form example project should give you a good overview of how PMValidation works.

The basics

Here's a basic example, creating a string length constraint which passes validation while the string is between 4 and 8 characters.

PMValidationLengthType *length_type = [PMValidationLengthType validator];
length_type.minimumCharacters = 4;
length_type.maximumCharacters = 8;

PMValidationUnit *unit = [PMValidationUnit validationUnit];
[unit registerValidationType:length_type];

// listen for validation updates from unit
[[NSNotificationCenter defaultCenter] addObserverForName:PMValidationUnitUpdateNotification object:unit queue:nil usingBlock:
		^(NSNotification *notification) {
        PMValidationUnit *unit = (PMValidationUnit *)notification.object;
        
				if (!unit.isValid) {
					NSDictionary *errors = [notification.userInfo valueForKey:@"errors"];
				}   
    }
];

// validate the string 
[unit validateText:@"Velvet Underground"];

That example only uses one validation type class, but you can add as many as you want to create very complex validation tests. Of course, power users may want to take advantage of the PMValidationRegexType class, which allows use of a regular expression as a validation test. For complex use cases this can be preferable – PMValidationEmailType uses a regular expression internally – but using more basic type classes together can provide greater readability. YMMV.

Validating static strings is cool, but let's hook up a PMValidationUnit to a UITextField so we can dynamically validate it as its text changes. While we could do this with just a PMValidationUnit, it's a bit easier to use PMValidationManager for this.

PMValidationManager *manager = [PMValidationManager validationManager];
PMValidationEmailType *email_type = [PMValidationEmailType validator];
PMValidationUnit *email_unit = [manager registerTextField:self.emailTextField
                                       forValidationTypes:[NSSet setWithObjects:email_type, nil]
                                               identifier:@"email"];
																							 
// listen for validation updates from the manager
[[NSNotificationCenter defaultCenter] addObserverForName:PMValidationStatusNotification object:manager queue:nil usingBlock:
	^(NSNotification *notification) {
    	BOOL is_valid = [(NSNumber *)[notification.userInfo objectForKey:@"status"] boolValue];
			if (!is_valid) {
				NSDictionary *units = [notification.userInfo objectForKey:@"units"];
				NSDictionary *email_dict = [units objectForKey:email_type.identifier];
				NSDictionary *email_errors = [email_dict objectForKey:@"errors"];
			} 
   }
];

Class reference

Management
PMValidationUnit	PMValidationUnit handles the validation of one object at a time, such as a static string or a UIKit text object. It receives updates from one or more PMValidationType objects.
PMValidationManager	PMValidationManager manages the operation of PMValidationUnit instances, and acts as the interface for receiving validation updates.
Validation Types
PMValidationType	PMValidationType is the base validation class. This base class has no inherent validation test, and will always return YES for any string sent to the isTextValid: method. All other validation classes inherit from this base class.
PMValidationEmailType	This validation class validates a target string as an e-mail address, determining whether it is well-formed.
PMValidationLengthType	This validation class validates a target string based on minimum or maximum length constraints. Either constraint can be used alone, or can be used together.
PMValidationRegexType	This validation class validates a target string with a regular expression.
PMValidationStringCompareType	This validation class validates the target string by comparing it to another string.
PMValidationUITextCompareType	This validation class validates the target string by comparing it to a UIKit text object.

Credits

PMValidation was created by Brett Walker of Poet & Mountain for its iPhone app Imprints.

Compatibility

• Requires iOS 5.0 or later
• PMValidation does not currently use ARC.

License

PMValidation is licensed under the MIT License.