feat: create validator for IPv4 addresses

Closes #97

Author: rafamizes

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Dart Package Versioning](https://dart.dev/tools/pub
 
 ## [Unreleased]
 
+### Added
+
+- IPv4 and ReqIPv4 classes to validate both optional and mandatory IPv4 form
+  fields — [97](https://github.com/dartoos-dev/formdator/issues/97).
+
 ## [0.12.2] - 2021-12-15
 
 ### Fixed

lib/net.dart

@@ -1,7 +1,9 @@
 /// Internet related validators.
 ///
-/// E.g. email, ipv4, ipv6, mac, url.
+/// E.g. Email, IPv4, IPv6, MacAddress, Url.
 library net;
 
 export 'src/net/email.dart';
+export 'src/net/ipv4.dart';
 export 'src/net/req_email.dart';
+export 'src/net/req_ipv4.dart';

lib/src/net/ipv4.dart

@@ -0,0 +1,53 @@
+import 'package:formdator/formdator.dart';
+
+/// Validator of optional IP (version 4) addresses.
+///
+/// Blank field - null value - is a valid input!
+///
+/// If the IP address is required, see [ReqIPv4] or [Req].
+///
+/// It uses the "Dot-decimal notation", which consists of four octets of the
+/// address expressed individually in decimal numbers and separated by periods.
+/// Examples of valid input:
+///
+/// - 192.0.2.235
+/// - 172.16.254.1
+/// - 127.0.0.1
+/// - 10.0.0.1
+/// - 0.0.0.0
+///
+/// See also:
+/// - [Dot Decimal Notation](https://en.wikipedia.org/wiki/Dot-decimal_notation)
+class IPv4 {
+  /// Validates IPv4 addresses using a regular expression that is suitable for
+  /// manually entered IP's. Examples:
+  ///
+  ///
+  /// If the ipv4 field is mandatory, see [ReqIPv4] or [Req].
+  ///
+  /// [mal] the error message in case of a malformed IP address; if omitted, the
+  /// default message will be 'malformed IP address'.
+  IPv4({String? mal})
+      : _ipv4Val = ((String? ipv4) {
+          return (ipv4 == null || _matcher.hasMatch(ipv4))
+              ? null
+              : mal ?? 'malformed IP address';
+        });
+
+  // email validation logic.
+  final ValStr _ipv4Val;
+
+  // lazy loading (on-demand) initialization.
+  static late final RegExp _matcher = _ipv4Pattern();
+
+  /// a suitable pattern for  IPv4 addresses.
+  static RegExp _ipv4Pattern() {
+    return RegExp(
+      r'^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$',
+    );
+  }
+
+  /// Valid - returns null - if [ipv4] is either a well-formed IPV4 address or
+  /// null.
+  String? call(String? ipv4) => _ipv4Val(ipv4);
+}

lib/src/net/req_ipv4.dart

@@ -0,0 +1,31 @@
+import '../core/pair.dart';
+import '../core/req.dart';
+import '../type.dart';
+
+import 'ipv4.dart';
+
+/// Convenience validator for required IPv4 addresses.
+///
+/// It is the composition between the validators [Req] and [IPv4].
+class ReqIPv4 {
+  /// Non-blank and well-formed IPv4 values.
+  ///
+  /// [blank] the error message in case of an IPv4 address left blank; if
+  /// omitted, the default message will be 'required IP'.
+  /// [mal] the error message in case of a malformed IP address; if omitted, the
+  /// default message will be 'malformed IP address'.
+  ReqIPv4({String? blank, String? mal})
+      : this._set(IPv4(mal: mal), blank: blank);
+
+  /// Helper ctor.
+  ReqIPv4._set(IPv4 ip, {String? blank})
+      : _reqIPv4 = Pair.str2(Req(blank: blank ?? 'required IP address'), ip);
+
+  // the required IPv4 logic.
+  final ValObj _reqIPv4;
+
+  /// Valid — returns null — if [ipv4] is a non-blank well-formed IPv4;
+  /// otherwise, returns the blank error message if [ipv4] is null, or the
+  /// malformed error message if [ipv4] is malformed.
+  String? call(String? ipv4) => _reqIPv4(ipv4);
+}

test/net/ipv4_test.dart

@@ -0,0 +1,41 @@
+import 'package:formdator/formdator.dart';
+import 'package:test/test.dart';
+
+/// Most of the test cases were taken from:
+/// - [valid-ipv4-addresses](https://en.wikipedia.org/wiki/ipv4_address#Valid_ipv4_addresses)
+void main() {
+  group('IPv4', () {
+    const error = 'malformed IP';
+    final ipv4 = IPv4(mal: error);
+    test('valid values:', () {
+      expect(ipv4('0.0.0.0'), null);
+      expect(ipv4('1.1.1.10'), null);
+      expect(ipv4('10.0.0.1'), null);
+      expect(ipv4('10.10.10.10'), null);
+      expect(ipv4('127.0.0.1'), null);
+      expect(ipv4('192.0.2.235'), null);
+      expect(ipv4('192.168.18.1'), null);
+      expect(ipv4('172.16.254.1'), null);
+      expect(ipv4('189.47.19.149'), null);
+      expect(ipv4('255.255.255.255'), null);
+    });
+    test('invalid values', () {
+      expect(ipv4('1'), error);
+      expect(ipv4('10.10'), error);
+      expect(ipv4('10.10.10.'), error);
+      expect(ipv4('00.0.0.0'), error);
+      expect(ipv4('0.00.0.0'), error);
+      expect(ipv4('0.0.00.0'), error);
+      expect(ipv4('0.0.0.00'), error);
+      expect(ipv4('0.0.0.0.'), error);
+      expect(ipv4('010.0.0.1'), error);
+      expect(ipv4('127.00.0.1'), error);
+      expect(ipv4('000.021.01.0'), error);
+      expect(ipv4('255.255.255.256'), error);
+      expect(ipv4('256.255.255.255'), error);
+      expect(ipv4('033.033.33.033'), error);
+      expect(ipv4('192.168.000.1'), error);
+      expect(ipv4('999.999.999.999'), error);
+    });
+  });
+}

test/net/req_ipv4_test.dart

@@ -0,0 +1,23 @@
+import 'package:formdator/formdator.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('ReqIPv4', () {
+    const blank = 'required IP address';
+    const mal = 'malformed IP address';
+    final reqIPv4 = ReqIPv4(blank: blank, mal: mal);
+    test('null - blank', () {
+      expect(reqIPv4(null), blank);
+    });
+    test('empty - blank', () {
+      expect(reqIPv4(''), blank);
+    });
+    test('invalid IPv4', () {
+      const invalid = '10.10.10.256';
+      expect(reqIPv4(invalid), mal);
+    });
+    test('valid IPv4', () {
+      expect(reqIPv4('10.0.1.1'), null);
+    });
+  });
+}