Merge pull request #15 from cowwoc/v10.2

Version 10.2

Author: cowwoc

README.md

@@ -3,7 +3,7 @@
 
 # <img src="docs/checklist.svg" width=64 height=64 alt="checklist"> Requirements API
 
-[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/10.1/docs/api/)
+[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/10.2/docs/api/)
 [![Changelog](https://img.shields.io/badge/changelog-A345D5.svg)](docs/Changelog.md)
 [![javascript, typescript](https://img.shields.io/badge/other%20languages-javascript,%20typescript-457FD5.svg)](../../../requirements.js)
 
@@ -22,7 +22,7 @@ To get started, add this Maven dependency:
 <dependency>
   <groupId>com.github.cowwoc.requirements</groupId>
   <artifactId>java</artifactId>
-  <version>10.1</version>
+  <version>10.2</version>
 </dependency>
 ```
 
@@ -152,14 +152,14 @@ This library offers the following features:
 Designed for discovery using your favorite IDE's auto-complete feature.
 The main entry points are:
 
-* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/10.1/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#requireThat(T,java.lang.String))
+* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/10.2/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#requireThat(T,java.lang.String))
   for method preconditions.
-* [that(value, name)](https://cowwoc.github.io/requirements.java/10.1/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#that(T,java.lang.String))
+* [that(value, name)](https://cowwoc.github.io/requirements.java/10.2/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#that(T,java.lang.String))
   for [class invariants, method postconditions and private methods](docs/Features.md#assertion-support). 
-* [checkIf(value, name)](https://cowwoc.github.io/requirements.java/10.1/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#checkIf(T,java.lang.String))
+* [checkIf(value, name)](https://cowwoc.github.io/requirements.java/10.2/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#checkIf(T,java.lang.String))
   for multiple failures and customized error handling.
 
-See the [API documentation](https://cowwoc.github.io/requirements.java/10.1/docs/api/) for more details.
+See the [API documentation](https://cowwoc.github.io/requirements.java/10.2/docs/api/) for more details.
 
 ## Best practices
 

docs/Changelog.md

@@ -2,6 +2,10 @@
 
 See https://github.com/cowwoc/requirements.java/commits/master for a full list.
 
+## Version 10.2 - 2024/12/07
+
+* Improvement: Escape linefeed characters in diffs.
+
 ## Version 10.1 - 2024/12/06
 
 * Improvements

docs/Supported_Libraries.md

@@ -1,11 +1,11 @@
 Each module uses a separate class pair for validation. For example, 
-[DefaultJavaValidators](https://cowwoc.github.io/requirements.java/10.1/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html)
+[DefaultJavaValidators](https://cowwoc.github.io/requirements.java/10.2/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html)
 and
-[JavaValidators](https://cowwoc.github.io/requirements.java/10.1/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/JavaValidators.html)
+[JavaValidators](https://cowwoc.github.io/requirements.java/10.2/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/JavaValidators.html)
 validate the core Java API. Similarly,
-[DefaultGuavaValidators](https://cowwoc.github.io/requirements.java/10.1/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/DefaultGuavaValidators.html)
+[DefaultGuavaValidators](https://cowwoc.github.io/requirements.java/10.2/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/DefaultGuavaValidators.html)
 and
-[GuavaValidators](https://cowwoc.github.io/requirements.java/10.1/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/GuavaValidators.html)
+[GuavaValidators](https://cowwoc.github.io/requirements.java/10.2/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/guava/GuavaValidators.html)
 validate the Guava API.
 
 The following table lists validators for third-party libraries: 

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/diff/AbstractDiffWriter.java

@@ -11,6 +11,8 @@
 import java.util.Map.Entry;
 import java.util.function.Consumer;
 
+import static com.github.cowwoc.requirements10.java.internal.message.diff.DiffConstants.LINEFEED_MARKER;
+
 /**
  * Base implementation for all diff writers.
  */
@@ -126,7 +128,7 @@ protected void splitLines(CharSequence text, Consumer<String> lineConsumer)
 		{
 			boolean isLastLine = i == lines.length - 1;
 			line.delete(0, line.length());
-			line.append(lines[i]);
+			line.append(lines[i].replace("\r", LINEFEED_MARKER));
 			if (!isLastLine)
 				line.append(DiffConstants.NEWLINE_MARKER);
 			if (!line.isEmpty())

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/diff/DiffConstants.java

@@ -11,6 +11,10 @@
  */
 public final class DiffConstants
 {
+	/**
+	 * Character denoting a linefeed character.
+	 */
+	public static final String LINEFEED_MARKER = "\\r";
 	/**
 	 * Character denoting a newline character.
 	 */

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/section/ContextSection.java

@@ -26,7 +26,7 @@ public int getMaxKeyLength()
 	}
 
 	@Override
-	public List<String> getLines(int maxKeyLength)
+	public List<String> getLinesWithPaddedKeys(int maxKeyLength)
 	{
 		// Align the colons vertically
 		List<String> lines = new ArrayList<>();

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/section/MessageBuilder.java

@@ -188,7 +188,7 @@ private String toString(List<MessageSection> context)
 		StringJoiner lines = new StringJoiner("\n");
 		for (MessageSection section : context)
 		{
-			for (String line : section.getLines(maxKeyLength))
+			for (String line : section.getLinesWithPaddedKeys(maxKeyLength))
 				lines.add(line);
 		}
 		return lines.toString();

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/section/MessageSection.java

@@ -9,13 +9,13 @@ public sealed interface MessageSection permits ContextSection, StringSection
 {
 	/**
 	 * @return if the section contains key-value pairs, returns the maximum length of all keys; otherwise
-	 *   returns 0
+	 * returns 0
 	 */
 	int getMaxKeyLength();
 
 	/**
 	 * @param maxKeyLength the maximum key length across all sections
-	 * @return this section's lines
+	 * @return this section's lines, with the keys padded to fill {@code maxKeyLength} characters
 	 */
-	List<String> getLines(int maxKeyLength);
+	List<String> getLinesWithPaddedKeys(int maxKeyLength);
 }

java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/section/StringSection.java

@@ -20,7 +20,7 @@ public int getMaxKeyLength()
 	}
 
 	@Override
-	public List<String> getLines(int maxKeyLength)
+	public List<String> getLinesWithPaddedKeys(int maxKeyLength)
 	{
 		return List.of(value);
 	}

test/src/test/java/com/github/cowwoc/requirements10/test/java/internal/diff/DiffTest.java

@@ -29,6 +29,7 @@
 import static com.github.cowwoc.requirements10.java.internal.message.diff.DiffConstants.DIFF_EQUAL;
 import static com.github.cowwoc.requirements10.java.internal.message.diff.DiffConstants.DIFF_INSERT;
 import static com.github.cowwoc.requirements10.java.internal.message.diff.DiffConstants.EOS_MARKER;
+import static com.github.cowwoc.requirements10.java.internal.message.diff.DiffConstants.LINEFEED_MARKER;
 import static com.github.cowwoc.requirements10.java.internal.message.diff.DiffConstants.NEWLINE_MARKER;
 import static com.github.cowwoc.requirements10.java.internal.message.diff.TextOnly.DIFF_PADDING;
 import static org.testng.Assert.fail;
@@ -204,6 +205,34 @@ public void diffNewlinePostfix()
 		}
 	}
 
+	/**
+	 * Test multi-line text-mode diffs where actual contains a trailing linefeed character.
+	 */
+	@Test
+	public void diffLinefeedPostfix()
+	{
+		try (ApplicationScope scope = new TestApplicationScope(NONE))
+		{
+			String actual = EXTEND_LENGTH("actual") + "\r";
+			String expected = EXTEND_LENGTH("expected");
+			new TestValidatorsImpl(scope).requireThat(actual, "actual").isEqualTo(expected);
+			fail("Expected method to throw exception");
+		}
+		catch (IllegalArgumentException e)
+		{
+			String actualMessage = e.getMessage();
+			String expectedMessage = "actual  : \"" + EXTEND_LENGTH("actual") + LINEFEED_MARKER + "\"" +
+				DIFF_PADDING.repeat(("\"" + EXTEND_LENGTH("expected") + "\"").length()) + EOS_MARKER + "\n" +
+				"diff    : " + DIFF_DELETE.repeat(("\"" + EXTEND_LENGTH("actual") + LINEFEED_MARKER +
+				"\"").length()) + DIFF_INSERT.repeat(("\"" + EXTEND_LENGTH("expected") + "\"").length()) +
+				DIFF_EQUAL.repeat(EOS_MARKER.length()) + "\n" +
+				"expected: " + DIFF_PADDING.repeat(("\"" + EXTEND_LENGTH("actual") + LINEFEED_MARKER + "\"").
+				length()) + "\"" + EXTEND_LENGTH("expected") + "\"" + EOS_MARKER;
+			assert (actualMessage.contains(expectedMessage)) : "**************** Actual:\n" + actualMessage +
+				"\n**************** Expected:\n" + expectedMessage;
+		}
+	}
+
 	/**
 	 * Test multi-line text-mode diffs containing matching text across different lines.
 	 */