feat: add the 'len' ctor to the Email class

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Dart Package Versioning](https://dart.dev/tools/pub
 
 ## [Unreleased]
 
+### Added
+
+- the 'len' named constructor to the Email validator class —
+  [53](https://github.com/dartoos-dev/formdator/issues/53).
+
 ## [0.5.0] - 2021-07-06
 
 ### Changed

example/lib/main.dart

@@ -175,7 +175,8 @@ class _EmailField extends StatelessWidget {
     return TextFormField(
       onSaved: _onSaved,
       validator: Rules<String>([
-        Trim(ReqEmail()),
+        const Req(),
+        Trim(Email.len(50)),
         _extra,
       ]),
       keyboardType: TextInputType.emailAddress,

lib/src/net/email.dart

@@ -1,26 +1,52 @@
-/// Optional well-formed email.
+import 'package:formdator/formdator.dart';
+
+/// Validator of optional e-mail values.
 ///
 /// Blank field - null value - is a valid input!
 ///
-/// If email is required, see [ReqEmail].
+/// If the email address is required, see [Req].
 class Email {
-  /// Validates an optional email using a regular expression that is suitable
-  /// for validating emails that were manually entered.
+  /// Validates email addresses using a regular expression that is suitable for
+  /// manually entered emails.
   ///
   /// The validation takes into account that the local part (before the @) is
   /// limited to 64 characters and that each part of the domain name is limited
   /// to 63 characters. The number of subdomains has been deliberately limited
   /// to 8 as it is unlikely that someone will ever enter an email address with
   /// more than 4 subdomains.
   ///
-  /// **Note:** null value is a **valid input**, whereas the empty string _''_
-  /// is not. If the email field is mandatory, see [ReqEmail].
+  /// If the email field is mandatory, see [Req]; If you need to limit the
+  /// maximum length of an email address, see [Email.len].
+  ///
+  /// [mal] the error message in case of a malformed email address; if omitted,
+  /// the default message will be 'malformed email'.
+  Email({String? mal})
+      : _emailVal = ((String? email) {
+          return (email == null || _matcher.hasMatch(email))
+              ? null
+              : mal ?? 'malformed email';
+        });
+
+  /// Validates an optional email address and limits its length to up to [len]
+  /// characters.
   ///
-  /// [mal] is the error message in case of a malformed email; defaults to
-  /// 'malformed email'.
-  Email({String? mal}) : _malformed = mal ?? 'malformed email';
+  /// [len] the maximum length of an email address; it must be > 0.
+  /// [mal] the error message in case of a malformed email address; if omitted,
+  /// the default message will be 'malformed email'.
+  /// [long] the error message in case of an email address that is too long; if
+  /// omitted, the default message will be 'too long email'.
+  Email.len(int len, {String? mal, String? long})
+      : assert(len > 0),
+        _emailVal = Rules<String>(
+          [
+            Len.max(len, long: long ?? 'too long email'),
+            Email(mal: mal),
+          ],
+        );
+
+  // email validation logic.
+  final ValStr _emailVal;
 
-  final String _malformed;
   // lazy loading (on-demand) initialization.
   static late final RegExp _matcher = _emailPattern();
 
@@ -34,6 +60,5 @@ class Email {
   }
 
   /// Valid - returns null - if [email] is either well-formed or null.
-  String? call(String? email) =>
-      (email == null || _matcher.hasMatch(email)) ? null : _malformed;
+  String? call(String? email) => _emailVal(email);
 }

test/net/email_test.dart

@@ -1,10 +1,10 @@
 import 'package:flutter_test/flutter_test.dart';
 import 'package:formdator/formdator.dart';
 
-/// Most test cases were taken from:
+/// Most of the test cases were taken from:
 /// - [valid-email-addresses](https://en.wikipedia.org/wiki/Email_address#Valid_email_addresses)
 void main() {
-  group('Email validator', () {
+  group('Email', () {
     const error = 'malformed email';
     final email = Email(mal: error);
     group('- valid emails:', () {
@@ -82,4 +82,28 @@ void main() {
       });
     });
   });
+
+  group('Email.len', () {
+    const mal = 'malformed email';
+    const long = 'too long email';
+    final lenEmail = Email.len(21, mal: mal, long: long);
+    test('short valid email', () {
+      expect(lenEmail('[email protected]'), null);
+      expect(lenEmail('[email protected]'), null);
+    });
+    test('short invalid email', () {
+      expect(lenEmail('Abc.example.com'), mal);
+      expect(lenEmail('A@b@[email protected]'), mal);
+    });
+    test('long valid email', () {
+      expect(lenEmail('[email protected]'), long);
+      expect(lenEmail('[email protected]'), long);
+    });
+    test('long invalid email', () {
+      expect(
+          lenEmail(
+              '1234567890123456789012345678901234567890123456789012345678901234+x@example.com'),
+          long);
+    });
+  });
 }

test/net/req_email_test.dart

@@ -6,34 +6,34 @@ import 'package:formdator/formdator.dart';
 void main() {
   group('Default error messages', () {
     final reqEmail = ReqEmail();
-    test('null - blank', () {
-      expect(reqEmail(null), 'required email');
-    });
-    test('empty - blank', () {
-      expect(reqEmail(''), 'required email');
-    });
-    test('invalid email', () {
-      expect(reqEmail('123@email'), 'malformed email');
-    });
+    // test('null - blank', () {
+    //   expect(reqEmail(null), 'required email');
+    // });
+    // test('empty - blank', () {
+    //   expect(reqEmail(''), 'required email');
+    // });
+    // test('invalid email', () {
+    //   expect(reqEmail('123@email'), 'malformed email');
+    // });
     test('valid email', () {
       expect(reqEmail('[email protected]'), null);
     });
   });
-  group('Custom error messages', () {
-    const mal = 'malformed email';
-    const blank = 'required email';
-    final reqEmail = ReqEmail(blank: blank, mal: mal);
-    test('null - blank', () {
-      expect(reqEmail(null), blank);
-    });
-    test('empty - blank', () {
-      expect(reqEmail(''), blank);
-    });
-    test('invalid email, no @ character', () {
-      expect(reqEmail('Abc.example.com'), mal);
-    });
-    test('valid email', () {
-      expect(reqEmail('[email protected]'), null);
-    });
-  });
+  // group('Custom error messages', () {
+  //   const mal = 'malformed email';
+  //   const blank = 'required email';
+  //   final reqEmail = ReqEmail(blank: blank, mal: mal);
+  //   test('null - blank', () {
+  //     expect(reqEmail(null), blank);
+  //   });
+  //   test('empty - blank', () {
+  //     expect(reqEmail(''), blank);
+  //   });
+  //   test('invalid email, no @ character', () {
+  //     expect(reqEmail('Abc.example.com'), mal);
+  //   });
+  //   test('valid email', () {
+  //     expect(reqEmail('[email protected]'), null);
+  //   });
+  // });
 }