Rename allowGmailDots to allowNonstandardDots

Author: RohanNagar

CHANGELOG.md

@@ -132,18 +132,19 @@ the `Email` object (similar to the `normalize()` method).
   ```
 
 
-### Support for Leading and Trailing Dots in the Local-Part (GMail Allowed)
+### Support for Leading and Trailing Dots in the Local-Part
 
-While technically disallowed under published RFCs, GMail considers email addresses that have
-local-parts that start with or end with a dot `.` character as valid. For example, GMail
-considers `[email protected]` valid, even though it is not actually valid according to RFC.
+While technically disallowed under published RFCs, some email providers (ex: GMail)
+consider email addresses that have local-parts that start with or end with a dot `.` character
+as valid. For example, GMail considers `[email protected]` valid, even though it is not
+actually valid according to RFC.
 
 JMail now gives you the option to consider these addresses valid as well. You must use an
-`EmailValidator` with the `allowGmailDots` rule added to it to allow these addresses to pass validation.
+`EmailValidator` with the `allowNonstandardDots` rule added to it to allow these addresses to pass validation.
 
 ```java
 EmailValidator validator = JMail.strictValidator()
-        .allowGmailDots();
+        .allowNonstandardDots();
 
 validator.isValid("[email protected]"); // returns true
 ```

src/main/java/com/sanctionco/jmail/EmailValidator.java

@@ -48,12 +48,12 @@ public final class EmailValidator {
       = ValidationRules::requireAscii;
 
   private final Map<Predicate<Email>, FailureReason> validationPredicates;
-  private final boolean allowGmailDots;
+  private final boolean allowNonstandardDots;
 
   EmailValidator(Map<Predicate<Email>, FailureReason> validationPredicates,
-                 boolean allowGmailDots) {
+                 boolean allowNonstandardDots) {
     this.validationPredicates = Collections.unmodifiableMap(validationPredicates);
-    this.allowGmailDots = allowGmailDots;
+    this.allowNonstandardDots = allowNonstandardDots;
   }
 
   EmailValidator() {
@@ -80,7 +80,7 @@ public EmailValidator withRules(Map<Predicate<Email>, FailureReason> rules) {
     Map<Predicate<Email>, FailureReason> ruleMap = new HashMap<>(validationPredicates);
     ruleMap.putAll(rules);
 
-    return new EmailValidator(ruleMap, allowGmailDots);
+    return new EmailValidator(ruleMap, allowNonstandardDots);
   }
 
   /**
@@ -170,14 +170,14 @@ public EmailValidator withRule(Predicate<Email> rule, String failureReason) {
    * {@code .} character.</p>
    *
    * <p>While not allowed according to RFC, a leading or trailing dot character in the local-part
-   * <strong>is allowed</strong> by GMail, hence the naming of this method.</p>
+   * <strong>is allowed</strong> by some mail providers (such as GMail).</p>
    *
    * <p>For example, {@code "[email protected]"} would be considered valid if you use the
    * {@code EmailValidator} returned by this method.</p>
    *
    * @return the new {@code EmailValidator} instance
    */
-  public EmailValidator allowGmailDots() {
+  public EmailValidator allowNonstandardDots() {
     return new EmailValidator(this.validationPredicates, true);
   }
 
@@ -361,7 +361,7 @@ public EmailValidator requireAscii() {
    * @return the result of the validation
    */
   public boolean isValid(String email) {
-    return JMail.validate(email, allowGmailDots)
+    return JMail.validate(email, allowNonstandardDots)
         .getEmail()
         .filter(e -> !testPredicates(e).isPresent())
         .isPresent();
@@ -404,7 +404,7 @@ public void enforceValid(String email) throws InvalidEmailException {
    *         {@link Email} object if successful, or the {@link FailureReason} if not
    */
   public EmailValidationResult validate(String email) {
-    EmailValidationResult result = JMail.validate(email, allowGmailDots);
+    EmailValidationResult result = JMail.validate(email, allowNonstandardDots);
 
     // If failed basic validation, just return it
     if (!result.getEmail().isPresent()) return result;
@@ -425,7 +425,7 @@ public EmailValidationResult validate(String email) {
    *         is invalid according to all registered validation rules
    */
   public Optional<Email> tryParse(String email) {
-    return JMail.validate(email, allowGmailDots).getEmail()
+    return JMail.validate(email, allowNonstandardDots).getEmail()
         .filter(e -> !testPredicates(e).isPresent());
   }
 

src/main/java/com/sanctionco/jmail/JMail.java

@@ -129,24 +129,28 @@ public static EmailValidationResult validate(String email) {
   }
 
   /**
-   * Package-private validate method that exposes an additional option {@code allowGmailDots}.
+   * Package-private validate method that exposes an additional option {@code allowNonstandardDots}.
    *
    * @param email the email address to parse and validate
-   * @param allowGmailDots true if a leading or trailing dot in the local-part should be allowed
+   * @param allowNonstandardDots true if a leading or trailing dot in the local-part should be
+   *                             allowed
    * @return a {@link EmailValidationResult} containing success or failure, along with the parsed
    *         {@link Email} object if successful, or the {@link FailureReason} if not
    */
-  static EmailValidationResult validate(String email, boolean allowGmailDots) {
-    return validateInternal(email, allowGmailDots);
+  static EmailValidationResult validate(String email, boolean allowNonstandardDots) {
+    return validateInternal(email, allowNonstandardDots);
   }
 
   /**
    * Internal parsing method.
    *
    * @param email the email address to parse
+   * @param allowNonstandardDots true if a leading or trailing dot in the local-part should be
+   *                             allowed
    * @return a new {@link Email} instance if valid, empty if invalid
    */
-  private static EmailValidationResult validateInternal(String email, boolean allowGmailDots) {
+  private static EmailValidationResult validateInternal(String email,
+                                                        boolean allowNonstandardDots) {
     // email cannot be null
     if (email == null) return EmailValidationResult.failure(FailureReason.NULL_ADDRESS);
 
@@ -179,10 +183,9 @@ private static EmailValidationResult validateInternal(String email, boolean allo
     // email cannot be more than 320 chars
     if (size > 320) return EmailValidationResult.failure(FailureReason.ADDRESS_TOO_LONG);
 
-    // email cannot start with '.'
     // email cannot start with '.'
     // unless we are configured to allow it (GMail doesn't care about a starting dot)
-    if (email.charAt(0) == '.' && !allowGmailDots) {
+    if (email.charAt(0) == '.' && !allowNonstandardDots) {
       return EmailValidationResult.failure(FailureReason.STARTS_WITH_DOT);
     }
 
@@ -240,7 +243,7 @@ private static EmailValidationResult validateInternal(String email, boolean allo
         }
 
         EmailValidationResult innerResult
-            = validateInternal(email.substring(i + 1, size - 1), allowGmailDots);
+            = validateInternal(email.substring(i + 1, size - 1), allowNonstandardDots);
 
         // If the address passed validation, return success with the identifier included.
         // Otherwise, just return the failed internal result
@@ -530,7 +533,7 @@ private static EmailValidationResult validateInternal(String email, boolean allo
     // Check that local-part does not end with '.'
     if (localPart.charAt(localPart.length() - 1) == '.') {
       // unless we are configured to allow it (GMail doesn't care about a trailing dot)
-      if (!allowGmailDots) {
+      if (!allowNonstandardDots) {
         return EmailValidationResult.failure(FailureReason.LOCAL_PART_ENDS_WITH_DOT);
       }
 

src/test/java/com/sanctionco/jmail/EmailValidatorTest.java

@@ -308,38 +308,38 @@ void invalidatesCorrectlyWithMap(String email) {
   }
 
   @Nested
-  class AllowGmailDots {
+  class AllowNonstandardDots {
     @ParameterizedTest(name = "{0}")
     @ValueSource(strings = {
         "[email protected]", "[email protected]", "[email protected]"})
     void rejectsInvalidDots(String email) {
-      runInvalidTest(JMail.validator().allowGmailDots(),
+      runInvalidTest(JMail.validator().allowNonstandardDots(),
           email, FailureReason.MULTIPLE_DOT_SEPARATORS);
     }
 
     @ParameterizedTest(name = "{0}")
     @ValueSource(strings = {
         "[email protected]", "[email protected]", "[email protected]"})
-    void allowsGmailDots(String email) {
-      runValidTest(JMail.validator().allowGmailDots(), email);
+    void allowsNonstandardDots(String email) {
+      runValidTest(JMail.validator().allowNonstandardDots(), email);
     }
   }
 
   @Nested
-  class DisallowIpDomainAllowGmailDotsCombination {
+  class DisallowIpDomainAllowNonstandardDotsCombination {
     @ParameterizedTest(name = "{0}")
     @ValueSource(strings = {
         "test@[1.2.3.4]", "test@[5.6.7.8]"})
     void rejects(String email) {
-      runInvalidTest(JMail.validator().allowGmailDots().disallowIpDomain(),
+      runInvalidTest(JMail.validator().allowNonstandardDots().disallowIpDomain(),
           email, FailureReason.CONTAINS_IP_DOMAIN);
     }
 
     @ParameterizedTest(name = "{0}")
     @ValueSource(strings = {
         "[email protected]", "[email protected]", "[email protected]"})
     void allows(String email) {
-      runValidTest(JMail.validator().allowGmailDots().disallowIpDomain(), email);
+      runValidTest(JMail.validator().allowNonstandardDots().disallowIpDomain(), email);
     }
   }
 

src/test/java/com/sanctionco/jmail/JMailTest.java

@@ -211,14 +211,14 @@ void isInvalidCanValidate() {
   }
 
   @Nested
-  class AllowGmailDots {
+  class AllowNonstandardDots {
     @ParameterizedTest(name = "{0}")
     @MethodSource({
         "com.sanctionco.jmail.helpers.AdditionalEmailProvider#provideInvalidEmails",
         "com.sanctionco.jmail.helpers.AdditionalEmailProvider#provideInvalidWhitespaceEmails",
         "com.sanctionco.jmail.helpers.AdditionalEmailProvider#provideInvalidControlEmails"})
     @CsvFileSource(resources = "/invalid-addresses.csv", delimiterString = " ;", numLinesToSkip = 1)
-    void ensureFailuresWhenAllowGmailDotsIsTrue(String email) {
+    void ensureFailures(String email) {
       // This test only works for addresses that will fail
       // even when we allow a starting or trailing dot in the local-part
       assumeTrue(email.charAt(0) != '.' && !email.contains(".@"));
@@ -228,7 +228,7 @@ void ensureFailuresWhenAllowGmailDotsIsTrue(String email) {
     }
 
     @Test
-    void ensureOnlyDotFailsWhenAllowGmailDotsIsTrue() {
+    void ensureOnlyDotFails() {
       assertThat(JMail.validate("[email protected]", true))
           .returns(true, EmailValidationResult::isFailure)
           .returns(FailureReason.LOCAL_PART_MISSING, EmailValidationResult::getFailureReason);;