IDefaultProvider.sequence(...) produces a sequence of default providers

Author: mkarg

docs/index.adoc

@@ -869,6 +869,8 @@ JCommander jc = JCommander.newBuilder()
 
 For the most common cases, there is no need to actually implement `IDefaultProvider`, as JCommander contains the classes `PropertyFileDefaultProvider` and `EnvironmentVariableDefaultProvider` for reading defaults from a property file (`jcommander.properties` by default) or from an environment variable (`JCOMMANDER_OPTS` by default).
 
+A *sequence* of multiple default providers can be used with `IDefaultProvider.sequenceOf(...)`, in which case the providers are queried in sequence, and the first non-null default value is applied.
+
 
 == Help parameter
 

src/main/java/com/beust/jcommander/IDefaultProvider.java

@@ -32,4 +32,26 @@ public interface IDefaultProvider {
    * @return the default value for this option.
    */
   String getDefaultValueFor(String optionName);
+
+  /**
+   * Returns a default provider which attempts to query a default value from a sequence
+   * of default providers. The first produced non-null value will get finally returned.
+   *
+   * @param defaultProviders A sorted sequence of default providers.
+   * @return The first non-null value provided,
+   *         or {@code null} if all providers returned {@code null}.
+   */
+  static IDefaultProvider sequenceOf(final IDefaultProvider... defaultProviders) {
+    return new IDefaultProvider() {
+      @Override
+      public String getDefaultValueFor(final String optionName) {
+        for (final var defaultProvider : defaultProviders) {
+            final var defaultValue = defaultProvider.getDefaultValueFor(optionName);
+            if (defaultValue != null)
+                return defaultValue;
+        }
+        return null;
+      }
+    };
+  }
 }

src/test/java/com/beust/jcommander/defaultprovider/SequenceDefaultProviderTest.java

@@ -0,0 +1,71 @@
+/**
+ * Copyright (C) 2025 the original author or authors.
+ * See the notice.md file distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.beust.jcommander.defaultprovider;
+
+import static org.testng.Assert.*;
+import static org.testng.Assert.assertEquals;
+
+import java.util.function.Function;
+
+import org.testng.annotations.Test;
+
+import com.beust.jcommander.IDefaultProvider;
+
+public final class SequenceDefaultProviderTest {
+
+	@Test
+	public final void shouldProvideFirstNonNullValue() {
+        // given
+		final IDefaultProvider defaultProvider = IDefaultProvider.sequenceOf(
+            always(null),
+            always("one"),
+            always("two"));
+
+		// when
+        final var defaultValue = defaultProvider.getDefaultValueFor("test");
+
+		// then
+		assertEquals(defaultValue, "one");
+	}
+
+    	@Test
+	public final void shouldProvideNullWhenNoProviderProducesSomeValue() {
+        // given
+		final IDefaultProvider defaultProvider = IDefaultProvider.sequenceOf(
+            always(null),
+            always(null),
+            always(null));
+
+		// when
+        final var defaultValue = defaultProvider.getDefaultValueFor("test");
+
+		// then
+		assertEquals(defaultValue, null);
+	}
+
+    private static final IDefaultProvider always(final String defaultValue) {
+        return new IDefaultProvider() {
+            @Override
+            public String getDefaultValueFor(final String optionName) {
+                return defaultValue;
+            }
+        };
+    }
+
+}