From 114cd03be94c5c06ee587852a1797ed4e3ecd50b Mon Sep 17 00:00:00 2001
From: Andrea Cosentino <ancosen@gmail.com>
Date: Wed, 28 Oct 2026 13:32:09 +0100
Subject: [PATCH] Javadoc: Document how FileInputStream option values are
 opened

The default FileInputStream converter, the '<' code in
PatternOptionBuilder and TypeHandler.openFile() open the file as soon
as the value is converted. The Javadoc didn't say that the caller has
to close the stream, or that opening something like a named pipe
blocks, just as new FileInputStream(String) does. Document both and add
the missing '<' row to the PatternOptionBuilder table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../java/org/apache/commons/cli/PatternOptionBuilder.java  | 4 ++++
 src/main/java/org/apache/commons/cli/TypeHandler.java      | 7 +++++++
 2 files changed, 11 insertions(+)

diff --git a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
index f68cfaeac..40389b444 100644
--- a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
+++ b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
@@ -57,6 +57,10 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  * <td>g:</td>
  * <td>-g [string]</td>
  * </tr>
+ * <tr>
+ * <td>h&lt;</td>
+ * <td>-h [file name] (opens the existing file for reading, the caller must close the stream)</td>
+ * </tr>
  * </table>
  *
  * <p>
diff --git a/src/main/java/org/apache/commons/cli/TypeHandler.java b/src/main/java/org/apache/commons/cli/TypeHandler.java
index 4709c7811..402c915f8 100644
--- a/src/main/java/org/apache/commons/cli/TypeHandler.java
+++ b/src/main/java/org/apache/commons/cli/TypeHandler.java
@@ -36,6 +36,10 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  * Options with custom converters and/or verifiers, using the default serialization methods, this class should be properly configured with the custom converters
  * and verifiers for the specific class.
  * </p>
+ * <p>
+ * The default converter for {@link FileInputStream} opens the named file each time it converts a value, and the caller must close the returned stream. As
+ * with {@link FileInputStream#FileInputStream(String)}, opening a special file such as a named pipe can block.
+ * </p>
  */
 public class TypeHandler {
 
@@ -206,6 +210,9 @@ public static TypeHandler getDefault() {
 
     /**
      * Returns the opened FileInputStream represented by {@code string}.
+     * <p>
+     * The caller must close the returned stream.
+     * </p>
      *
      * @param string The file location.
      * @return The file input stream represented by {@code string}.