New PathSortBuilder

Author: ComputerDaddyGuy

README.md

@@ -132,12 +132,12 @@ filtering/
 Files and directories can be sorted using a custom comparator (default is alphabetical order).
 If the provided comparator considers two paths equal (i.e., returns `0`), an alphabetical comparator is applied as a tie-breaker to ensure consistent results across all systems.  
 
-The `PrettyPrintOptions.Sorts` class provides a set of basic, ready-to-use comparators.
+The `PathSorts` class provides a set of basic, ready-to-use comparators, as well as a builder for creating your own tailor-made sorts.
 
 ```java
 // Example: Sorting.java
 var prettyPrinter = FileTreePrettyPrinter.builder()
-    .customizeOptions(options -> options.sort(PrettyPrintOptions.Sorts.DIRECTORY_FIRST))
+    .customizeOptions(options -> options.sort(PathSorts.DIRECTORY_FIRST))
     .build();
 ```
 ```

ROADMAP.md

@@ -28,7 +28,7 @@
 ## To do
 - [x] More `PathMatchers` functions!
 - [x] Helper class for line extension
-- [ ] Helper class for sorting
+- [x] Helper class for sorting
 - [ ] Option: custom emojis
 - [ ] Option: hide number of skipped files and folders for child limit
 - [ ] Rework/fix Github wiki to be up to date

src/example/java/io/github/computerdaddyguy/jfiletreeprettyprinter/example/ProjectStructure.java

@@ -4,7 +4,7 @@
 import io.github.computerdaddyguy.jfiletreeprettyprinter.FileTreePrettyPrinter;
 import io.github.computerdaddyguy.jfiletreeprettyprinter.LineExtensionBuilder;
 import io.github.computerdaddyguy.jfiletreeprettyprinter.PathMatchers;
-import io.github.computerdaddyguy.jfiletreeprettyprinter.PrettyPrintOptions.Sorts;
+import io.github.computerdaddyguy.jfiletreeprettyprinter.PathSorts;
 import java.nio.file.Path;
 import java.util.Comparator;
 import java.util.function.Function;
@@ -48,15 +48,7 @@ public static void main(String[] args) {
 		var fileFilter = PathMatchers.allOf(
 
 			// Hide files with names starting with "."
-			PathMatchers.not(PathMatchers.hasNameStartingWith(".")),
-
-			// Inside "jfiletreeprettyprinter" folder, keep only "FileTreePrettyPrinter.java"
-			// Files in other folders are not restricted by this rule.
-			PathMatchers.ifMatchesThenElse(
-				/*  if  */ PathMatchers.hasDirectParentMatching(PathMatchers.hasName("jfiletreeprettyprinter")),
-				/* then */ PathMatchers.hasName("FileTreePrettyPrinter.java"),
-				/* else */ path -> true
-			)
+			PathMatchers.not(PathMatchers.hasNameStartingWith("."))
 		);
 
 		/*
@@ -66,6 +58,7 @@ public static void main(String[] args) {
 			// Hide all files under renderer and scanner packages
 			.add(PathMatchers.hasAbsolutePathMatchingGlob("**/io/github/computerdaddyguy/jfiletreeprettyprinter/renderer"), 0)
 			.add(PathMatchers.hasAbsolutePathMatchingGlob("**/io/github/computerdaddyguy/jfiletreeprettyprinter/scanner"), 0)
+			.add(PathMatchers.hasAbsolutePathMatchingGlob("**/io/github/computerdaddyguy/jfiletreeprettyprinter"), 3)
 			.build();
 
 		/*
@@ -79,9 +72,14 @@ public static void main(String[] args) {
 			.build();
 
 		/*
-		 * Sort all paths by directory first (then alphabetically by default)
+		 * Sort all paths by directory first (with highest precedence),
+		 * then "FileTreePrettyPrinter.java" has precedence "-100".
+		 * All other files have default precedence "0", and are then sorted alphabetically by default.
 		 */
-		Comparator<Path> pathComparator = Sorts.DIRECTORY_FIRST;
+		Comparator<Path> pathComparator = PathSorts.builder()
+			.addFirst(PathMatchers.isDirectory())
+			.add(PathMatchers.hasName("FileTreePrettyPrinter.java"), -100) // Default precedence is "0"
+			.build();
 
 		/*
 		 * Build the final FileTreePrettyPrinter
@@ -110,25 +108,27 @@ public static void main(String[] args) {
 		        Expected result
 		 ================================
 		 
-			📂 JFileTreePrettyPrinter/
-			├─ 📂 assets/
-			│  └─ 🖼️ project-structure.png	// This image
-			├─ 📂 src/main/java/
-			│  └─ 📂 io/github/computerdaddyguy/jfiletreeprettyprinter/
-			│     ├─ 📂 renderer/
-			│     │  └─ ... (5 files and 2 directories skipped)
-			│     ├─ 📂 scanner/
-			│     │  └─ ... (4 files skipped)
-			│     └─ ☕ FileTreePrettyPrinter.java	// Main entry point
-			├─ 🗺️ CHANGELOG.md
-			├─ 📖 CONTRIBUTING.md
-			├─ 📄 LICENSE
-			├─ 📖 README.md		// You're reading at this!
-			├─ 🗺️ ROADMAP.md
-			├─ 🛡️ SECURITY.md
-			├─ 🏗️ pom.xml
-			├─ 📖 release_process.md
-			└─ 📜 runMutationTests.sh
+		📂 JFileTreePrettyPrinter/
+		├─ 📂 assets/
+		│  └─ 🖼️ project-structure.png	// This image
+		├─ 📂 src/main/java/
+		│  └─ 📂 io/github/computerdaddyguy/jfiletreeprettyprinter/
+		│     ├─ 📂 renderer/
+		│     │  └─ ... (5 files and 2 directories skipped)
+		│     ├─ 📂 scanner/
+		│     │  └─ ... (4 files skipped)
+		│     ├─ ☕ FileTreePrettyPrinter.java	// Main entry point
+		│     └─ ... (8 files skipped)
+		├─ 🗺️ CHANGELOG.md
+		├─ 📖 CONTRIBUTING.md
+		├─ 📄 LICENSE
+		├─ 📖 README.md		// You're reading at this!
+		├─ 🗺️ ROADMAP.md
+		├─ 🛡️ SECURITY.md
+		├─ 🏗️ pom.xml
+		├─ 📖 release_process.md
+		└─ 📜 runMutationTests.sh
+		
 		 */
 	}
 

src/example/java/io/github/computerdaddyguy/jfiletreeprettyprinter/example/Sorting.java

@@ -1,13 +1,13 @@
 package io.github.computerdaddyguy.jfiletreeprettyprinter.example;
 
 import io.github.computerdaddyguy.jfiletreeprettyprinter.FileTreePrettyPrinter;
-import io.github.computerdaddyguy.jfiletreeprettyprinter.PrettyPrintOptions;
+import io.github.computerdaddyguy.jfiletreeprettyprinter.PathSorts;
 
 public class Sorting {
 
 	public static void main(String[] args) {
 		var prettyPrinter = FileTreePrettyPrinter.builder()
-			.customizeOptions(options -> options.sort(PrettyPrintOptions.Sorts.DIRECTORY_FIRST))
+			.customizeOptions(options -> options.sort(PathSorts.DIRECTORY_FIRST))
 			.build();
 		var tree = prettyPrinter.prettyPrint("src/example/resources/sorting");
 		System.out.println(tree);

src/main/java/io/github/computerdaddyguy/jfiletreeprettyprinter/FileTreePrettyPrinterBuilder.java

@@ -31,7 +31,11 @@
 @NullMarked
 public class FileTreePrettyPrinterBuilder {
 
-	private PrettyPrintOptions options = PrettyPrintOptions.createDefault();
+	private PrettyPrintOptions options;
+
+	/* package */ FileTreePrettyPrinterBuilder() {
+		options = PrettyPrintOptions.createDefault();
+	}
 
 	/**
 	 * Builds the pretty printer using the configured options.

src/main/java/io/github/computerdaddyguy/jfiletreeprettyprinter/PathSortBuilder.java

@@ -0,0 +1,138 @@
+package io.github.computerdaddyguy.jfiletreeprettyprinter;
+
+import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Function;
+import java.util.function.ToIntFunction;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A builder for creating a {@link Comparator Comparator<Path>} that defines
+ * a custom sorting order for file system paths based on rule precedence.
+ * <p>
+ * Each rule assigns an integer "precedence" value to paths. The first rule
+ * that matches a path determines its precedence. Paths are then sorted by
+ * ascending precedence value (lower values come first), followed by an
+ * alphabetical fallback comparison.
+ * </p>
+ *
+ * <p>
+ * Predefined precedence constants:
+ * </p>
+ * <ul>
+ *   <li>{@link #HIGHEST_PRECEDENCE} ({@code Integer.MIN_VALUE}) — top priority</li>
+ *   <li>{@link #DEFAULT_PRECEDENCE} ({@code 0}) — default order</li>
+ *   <li>{@link #LOWEST_PRECEDENCE} ({@code Integer.MAX_VALUE}) — last priority</li>
+ * </ul>
+ *
+ * <h2>Example usage:</h2>
+ * <pre>{@code
+ * var customSort = PathSortBuilder.newInstance()
+ *     .addFirst(PathMatchers.hasName("README.md"))     // always first
+ *     .addLast(PathMatchers.hasName("target"))         // always last
+ *     .add(path -> path.toString().contains("core") ? -10 : 0) // custom priority rule
+ *     .build();
+ *
+ * var printer = FileTreePrettyPrinter.builder()
+ *     .customizeOptions(options -> options.sort(customSort))
+ *     .build();
+ * }</pre>
+ */
+@NullMarked
+public class PathSortBuilder {
+
+	/** Highest possible precedence — items appear first. */
+	public static final int HIGHEST_PRECEDENCE = Integer.MIN_VALUE;
+
+	/** Default precedence (neutral value). */
+	public static final int DEFAULT_PRECEDENCE = 0;
+
+	/** Lowest possible precedence — items appear last. */
+	public static final int LOWEST_PRECEDENCE = Integer.MAX_VALUE;
+
+	private List<ToIntFunction<Path>> orders;
+
+	/* package */ PathSortBuilder() {
+		this.orders = new ArrayList<>();
+	}
+
+	/**
+	 * Builds the final {@link Comparator Comparator&lt;Path&gt;} based on the configured rules.
+	 * <p>
+	 * Rules are tested in the order they were added. The first matching rule
+	 * having a result different than {@link DEFAULT_PRECEDENCE} (meaning, {@code 0})
+	 * determines the precedence value for a given path. Paths are sorted by
+	 * this precedence, and then alphabetically as a tiebreaker.
+	 * </p>
+	 *
+	 * @return a comparator defining the final path order
+	 */
+	public Comparator<Path> build() {
+		var immutOrders = List.copyOf(orders);
+		Function<Path, Integer> finalFunction = path -> {
+			int result = DEFAULT_PRECEDENCE;
+			for (var rule : immutOrders) {
+				result = rule.applyAsInt(path);
+				if (result != DEFAULT_PRECEDENCE) {
+					break;
+				}
+			}
+			return result;
+		};
+		return Comparator.comparing(finalFunction).thenComparing(PathSorts.ALPHABETICAL);
+	}
+
+	/**
+	 * Adds a custom rule function defining a precedence for a path.
+	 *
+	 * @param order a function returning a precedence value
+	 * @return this builder for chaining
+	 *
+	 * @throws NullPointerException if {@code order} is null
+	 */
+	public PathSortBuilder add(ToIntFunction<Path> order) {
+		Objects.requireNonNull(order, "order is null");
+		this.orders.add(order);
+		return this;
+	}
+
+	/**
+	 * Adds a rule that assigns a precedence value to all paths matching
+	 * the specified {@link PathMatcher}.
+	 *
+	 * @param pathMatcher the matcher to test paths
+	 * @param order the precedence value to assign
+	 * @return this builder for chaining
+	 *
+	 * @throws NullPointerException if {@code pathMatcher} is null
+	 */
+	public PathSortBuilder add(PathMatcher pathMatcher, int order) {
+		Objects.requireNonNull(pathMatcher, "pathMatcher is null");
+		return add(path -> pathMatcher.matches(path) ? order : DEFAULT_PRECEDENCE);
+	}
+
+	/**
+	 * Adds a rule that forces matching paths to appear first in the sort order.
+	 *
+	 * @param pathMatcher the matcher identifying high-priority paths
+	 * @return this builder for chaining
+	 */
+	public PathSortBuilder addFirst(PathMatcher pathMatcher) {
+		return add(pathMatcher, HIGHEST_PRECEDENCE);
+	}
+
+	/**
+	 * Adds a rule that forces matching paths to appear last in the sort order.
+	 *
+	 * @param pathMatcher the matcher identifying low-priority paths
+	 * @return this builder for chaining
+	 */
+	public PathSortBuilder addLast(PathMatcher pathMatcher) {
+		return add(pathMatcher, LOWEST_PRECEDENCE);
+	}
+
+}