[DOC] add example for reading from STDIN

picocli-examples/build.gradle

@@ -80,6 +80,12 @@ normalization {
 }
 
 tasks.withType(Javadoc).all { enabled = false }
+//tasks.named('compileKotlin', org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask.class) {
+tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {
+    compilerOptions {
+        freeCompilerArgs.add('-Xskip-metadata-version-check')
+    }
+}
 //tasks.withType(Javadoc) {
 //    options.addBooleanOption('Xdoclint:none', true)
 //}

picocli-examples/src/main/java/picocli/examples/stdin/PrintFirstLine.java

@@ -0,0 +1,63 @@
+package picocli.examples.stdin;
+
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Option;
+import picocli.CommandLine.Parameters;
+
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.Charset;
+import java.nio.file.Files;
+import java.util.List;
+import java.util.concurrent.Callable;
+
+/**
+ * This example reads a file, or from standard input, and prints the first line.
+ *
+ * It follows the UNIX convention that tools should read from STDIN (standard input)
+ * when the end user specifies the `-` character instead of a file name.
+ *
+ * See POSIX Utility Syntax Guidelines, Guideline 13:
+ * https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02
+ */
+@Command(name = "firstline")
+public class PrintFirstLine implements Callable<Integer> {
+
+    @Parameters(arity = "1..*")
+    List<File> files;
+
+    @Option(names = "--charset", description = "Charset of the file (or STDIN) to read. Default: ${DEFAULT_VALUE}")
+    Charset charset = Charset.defaultCharset();
+
+    public Integer call() throws Exception {
+        for (File file : files) {
+            printFirstLine(file);
+        }
+        return 0;
+    }
+
+    private void printFirstLine(File file) throws IOException {
+        try (BufferedReader reader = createReader(file)) {
+            System.err.println("Created reader for " + file.getAbsolutePath());
+            String line = reader.readLine();
+            System.err.println("Read line: " + line);
+            System.out.println(line);
+        }
+    }
+
+    private BufferedReader createReader(File file) throws IOException {
+        InputStream in = "-".equals(file.toString())
+            ? System.in
+            : Files.newInputStream(file.toPath());
+        return new BufferedReader(new InputStreamReader(in, charset));
+    }
+
+    public static void main(String... args) {
+        int exitCode = new CommandLine(new PrintFirstLine()).execute(args);
+        //System.exit(exitCode); // prevents this method from being testable...
+    }
+}

picocli-examples/src/test/java/picocli/examples/stdin/PrintFirstLineTest.java

@@ -0,0 +1,34 @@
+package picocli.examples.stdin;
+
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.contrib.java.lang.system.SystemOutRule;
+import org.junit.contrib.java.lang.system.TextFromStandardInputStream;
+
+import java.net.URL;
+
+import static org.junit.Assert.*;
+
+public class PrintFirstLineTest {
+
+    @Rule
+    public final SystemOutRule outRule = new SystemOutRule().enableLog().muteForSuccessfulTests();
+
+    @Rule
+    public final TextFromStandardInputStream systemInMock = TextFromStandardInputStream.emptyStandardInputStream();
+
+    @Test
+    public void testMain() {
+        URL resource = PrintFirstLineTest.class.getResource("/PrintFirstLineTest.txt");
+        String path = resource.getPath();
+        PrintFirstLine.main(path);
+        assertEquals("file line 1", outRule.getLog().trim());
+    }
+
+    @Test
+    public void testStandardInput() {
+        systemInMock.provideLines("stdin line1", "stdin line2", "stdin line3");
+        PrintFirstLine.main("-");
+        assertEquals("stdin line1", outRule.getLog().trim());
+    }
+}

picocli-examples/src/test/resources/PrintFirstLineTest.txt

@@ -0,0 +1,3 @@
+file line 1
+file line 2
+file line 3