@workInProgress
@ngdoc overview
@name angular.validator
@namespace Namespace for all filters.
@description
# Overview
Validators are a standard way to check the user input against a specific criteria. For
example, you might need to check that an input field contains a well-formed phone number.

# Syntax
Attach a validator on user input widgets using the `ng:validate` attribute.

<doc:example>
  <doc:source>
    Change me: <input type="text" name="number" ng:validate="integer" value="123">
  </doc:source>
  <doc:scenario>
    it('should validate the default number string', function() {
      expect(element('input[name=number]').attr('class')).
         not().toMatch(/ng-validation-error/);
    });
    it('should not validate "foo"', function() {
      input('number').enter('foo');
      expect(element('input[name=number]').attr('class')).
         toMatch(/ng-validation-error/);
    });
  </doc:scenario>
</doc:example>


# Writing your own Validators
Writing your own validator is easy. To make a function available as a
validator, just define the JavaScript function on the `angular.validator`
object. <angular/> passes in the input to validate as the first argument
to your function. Any additional validator arguments are passed in as
additional arguments to your function.

You can use these variables in the function:

* `this` — The current scope.
* `this.$element` — The DOM element containing the binding. This allows the filter to manipulate
  the DOM in addition to transforming the input.

In this example we have written a upsTrackingNo validator.
It marks the input text "valid" only when the user enters a well-formed
UPS tracking number.

@css ng-validation-error
  When validation fails, this css class is applied to the binding, making its borders red by
  default.

@example
<doc:example>
 <doc:source>
  <script>
   angular.validator('upsTrackingNo', function(input, format) {
     var regexp = new RegExp("^" + format.replace(/9/g, '\\d') + "$");
     return input.match(regexp)?"":"The format must match " + format;
   });
  </script>
  <input type="text" name="trackNo" size="40"
        ng:validate="upsTrackingNo:'1Z 999 999 99 9999 999 9'"
        value="1Z 123 456 78 9012 345 6"/>
 </doc:source>
 <doc:scenario>
  it('should validate correct UPS tracking number', function() {
    expect(element('input[name=trackNo]').attr('class')).
       not().toMatch(/ng-validation-error/);
  });

  it('should not validate in correct UPS tracking number', function() {
    input('trackNo').enter('foo');
    expect(element('input[name=trackNo]').attr('class')).
       toMatch(/ng-validation-error/);
  });
 </doc:scenario>
</doc:example>