Introduce formatter methods to customize version output (#252)

* Intriduce formatter methods to customize version output * Cleanup
semver4j · Apr 25, 2024 · 22bf498 · 22bf498
1 parent a01df7f
commit 22bf498
Show file tree

Hide file tree

Showing 3 changed files with 73 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -41,6 +41,7 @@ and [Ivy](https://ant.apache.org/ivy/history/latest-milestone/settings/version-m
         * [Internal](#internal)
     * [Modifying the version](#modifying-the-version)
     * [Builder](#builder)
+    * [Formatting](#formatting)
 * [Contributing](#contributing)
 * [Thanks](#thanks)
 
@@ -254,6 +255,19 @@ And is an equivalent of:
 Semver semver = new Semver("1.2.0+5bb76cdb");
 ```
 
+### Formatting
+
+Sometimes you want to format `Semver` using custom formatters. You can do this using
+a `format(Function<Semver, String> formatter)` method from the `Semver` class:
+
+```java
+Semver semver = new Semver("1.2.3-alpha.1+sha.1234");
+String customVersion = semver.format(sem -> format("%d:%d:%d", sem.getMajor(), sem.getMinor(), sem.getPatch())); // 1:2:2
+```
+
+There is also a method in the `SemverBuilder` called `toVersion(Function<Semver, String> formatter)` which behaves
+exactly the same.
+
 ## Contributing
 
 Any pull request or bug report are welcome!

diff --git a/src/main/java/org/semver4j/Semver.java b/src/main/java/org/semver4j/Semver.java
@@ -7,8 +7,8 @@
 import org.semver4j.internal.StrictParser.Version;
 
 import java.util.*;
+import java.util.function.Function;
 
-import static java.lang.String.format;
 import static java.lang.String.join;
 import static java.util.Collections.emptyList;
 import static java.util.Objects.hash;
@@ -570,6 +570,13 @@ public boolean satisfies(@NotNull final RangesList rangesList) {
         return rangesList.isSatisfiedBy(this);
     }
 
+    /**
+     * Format {@link Semver} object using custom formatting rules.
+     */
+    public String format(Function<Semver, String> formatter) {
+        return formatter.apply(this);
+    }
+
     @Override
     public boolean equals(@Nullable final Object o) {
         if (this == o) {
@@ -685,7 +692,7 @@ public Semver toSemver() {
          */
         @NotNull
         public String toVersion() {
-            String resultVersion = format(Locale.ROOT, "%d.%d.%d", major, minor, patch);
+            String resultVersion = String.format(Locale.ROOT, "%d.%d.%d", major, minor, patch);
             if (!preRelease.isEmpty()) {
                 resultVersion += "-" + join(".", preRelease);
             }
@@ -694,5 +701,12 @@ public String toVersion() {
             }
             return resultVersion;
         }
+
+        /**
+         * Format {@link Semver} object using custom formatting rules.
+         */
+        public String toVersion(Function<Semver, String> formatter) {
+            return formatter.apply(toSemver());
+        }
     }
 }
diff --git a/src/test/java/org/semver4j/SemverTest.java b/src/test/java/org/semver4j/SemverTest.java
@@ -1237,4 +1237,47 @@ void shouldBuildBasicSemver() {
         //then
         assertThat(semver.getVersion()).isEqualTo("1.2.3");
     }
+
+    @Test
+    void shouldUseCustomFormatterInBuilder() {
+        //given
+        Semver.Builder builder = Semver.of()
+                .withMajor(1)
+                .withMinor(2)
+                .withPatch(3)
+                .withPreRelease("alpha")
+                .withBuild("5bb76cdb");
+
+        //when
+        String version = builder.toVersion(semver -> {
+            String preRelease = join("&", semver.getPreRelease());
+            String build = join("&", semver.getBuild());
+            return format(Locale.ROOT, "%d:%d:%d|%s*%s", semver.getMajor(), semver.getMinor(), semver.getPatch(), preRelease, build);
+        });
+
+        //then
+        assertThat(version).isEqualTo("1:2:3|alpha*5bb76cdb");
+    }
+
+    @Test
+    void shouldUseCustomFormatter() {
+        //given
+        Semver actualSemver = Semver.of()
+                .withMajor(1)
+                .withMinor(2)
+                .withPatch(3)
+                .withPreRelease("alpha")
+                .withBuild("5bb76cdb")
+                .toSemver();
+
+        //when
+        String version = actualSemver.format(semver -> {
+            String preRelease = join("&", semver.getPreRelease());
+            String build = join("&", semver.getBuild());
+            return format(Locale.ROOT, "%d:%d:%d|%s*%s", semver.getMajor(), semver.getMinor(), semver.getPatch(), preRelease, build);
+        });
+
+        //then
+        assertThat(version).isEqualTo("1:2:3|alpha*5bb76cdb");
+    }
 }