Update docs for isStdin/isStdout

ajalt · ajalt · commit 979fcdf1cf2d · 2021-02-09T09:48:55.000-08:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- `InputStream.isCliktParameterDefaultStdin` and `OutputStream.isCliktParameterDefaultStdout` to check if the streams returned from `inputStream`/`outputStream` options are proxying stdin/stdout ([#272](https://github.com/ajalt/clikt/issues/272))
+
 ### Changed
 - Make parameters of `mutuallyExclusiveOptions` covariant to allow validation without explicit type annotations. ([#265](https://github.com/ajalt/clikt/issues/265))
 - Update kotlin to 1.4.30
diff --git a/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/inputStream.kt b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/inputStream.kt
@@ -10,40 +10,20 @@ import java.nio.file.FileSystem
 import java.nio.file.FileSystems
 import java.nio.file.Files
 
-private fun convertToInputStream(s: String, fileSystem: FileSystem, context: Context, fail: (String) -> Unit): InputStream {
-    return if (s == "-") {
-        UnclosableInputStream(System.`in`)
-    } else {
-        val path = convertToPath(
-                path = s,
-                mustExist = true,
-                canBeFile = true,
-                canBeFolder = false,
-                mustBeWritable = false,
-                mustBeReadable = true,
-                canBeSymlink = true,
-                fileSystem = fileSystem,
-                context = context,
-                fail = fail
-        )
-        Files.newInputStream(path)
-    }
-}
-
-//<editor-fold desc="options">
+// region ========== Options ==========
 
 /**
  * Convert the option to an [InputStream].
  *
  * The value given on the command line must be either a path to a readable file, or `-`. If `-` is
  * given, stdin will be used.
  *
- * If stdin is used, the resulting [InputStream] will be a proxy for [System.in] that will not close
+ * If stdin is used, the resulting [InputStream] will be a proxy for [System. in] that will not close
  * the underlying stream. So you can always [close][InputStream.close] the resulting stream without
- * worrying about accidentally closing [System.in].
+ * worrying about accidentally closing [System. in].
  */
 fun RawOption.inputStream(
-        fileSystem: FileSystem = FileSystems.getDefault()
+    fileSystem: FileSystem = FileSystems.getDefault(),
 ): NullableOption<InputStream, InputStream> {
     return convert({ localization.fileMetavar() }, CompletionCandidates.Path) { s ->
         convertToInputStream(s, fileSystem, context) { fail(it) }
@@ -57,21 +37,21 @@ fun NullableOption<InputStream, InputStream>.defaultStdin(): OptionWithValues<In
     return default(UnclosableInputStream(System.`in`), "-")
 }
 
-//</editor-fold>
-//<editor-fold desc="arguments">
+// endregion
+// region ========== Arguments ==========
 
 /**
  * Convert the argument to an [InputStream].
  *
  * The value given on the command line must be either a path to a readable file, or `-`. If `-` is
  * given, stdin will be used.
  *
- * If stdin is used, the resulting [InputStream] will be a proxy for [System.in] that will not close
+ * If stdin is used, the resulting [InputStream] will be a proxy for [System. in] that will not close
  * the underlying stream. So you can always [close][InputStream.close] the resulting stream without
- * worrying about accidentally closing [System.in].
+ * worrying about accidentally closing [System. in].
  */
 fun RawArgument.inputStream(
-        fileSystem: FileSystem = FileSystems.getDefault()
+    fileSystem: FileSystem = FileSystems.getDefault(),
 ): ProcessedArgument<InputStream, InputStream> {
     return convert(completionCandidates = CompletionCandidates.Path) { s ->
         convertToInputStream(s, fileSystem, context) { fail(it) }
@@ -85,12 +65,40 @@ fun ProcessedArgument<InputStream, InputStream>.defaultStdin(): ArgumentDelegate
     return default(UnclosableInputStream(System.`in`))
 }
 
-//</editor-fold>
+// endregion
 
 /**
- * Checks whether this stream is an unclosable [System.`in`] proxy.
+ * Checks whether this stream was returned from an [inputStream] parameter, and that it is
+ * reading from [System. in] (because `-` was given, or no value was given and the parameter uses
+ * [defaultStdin]).
  */
-fun InputStream.isCliktParameterDefaultStdin(): Boolean = this is UnclosableInputStream
+val InputStream.isCliktParameterDefaultStdin: Boolean
+    get() = this is UnclosableInputStream
+
+private fun convertToInputStream(
+    s: String,
+    fileSystem: FileSystem,
+    context: Context,
+    fail: (String) -> Unit,
+): InputStream {
+    return if (s == "-") {
+        UnclosableInputStream(System.`in`)
+    } else {
+        val path = convertToPath(
+            path = s,
+            mustExist = true,
+            canBeFile = true,
+            canBeFolder = false,
+            mustBeWritable = false,
+            mustBeReadable = true,
+            canBeSymlink = true,
+            fileSystem = fileSystem,
+            context = context,
+            fail = fail
+        )
+        Files.newInputStream(path)
+    }
+}
 
 private class UnclosableInputStream(private var delegate: InputStream?) : InputStream() {
     private val stream get() = delegate ?: throw IOException("Stream closed")
@@ -108,3 +116,5 @@ private class UnclosableInputStream(private var delegate: InputStream?) : InputS
         delegate = null
     }
 }
+
+// endregion
diff --git a/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/outputStream.kt b/clikt/src/jvmMain/kotlin/com/github/ajalt/clikt/parameters/types/outputStream.kt
@@ -11,35 +11,7 @@ import java.nio.file.FileSystems
 import java.nio.file.Files
 import java.nio.file.StandardOpenOption.*
 
-private fun convertToOutputStream(
-        s: String,
-        createIfNotExist: Boolean,
-        truncateExisting: Boolean,
-        fileSystem: FileSystem,
-        context: Context,
-        fail: (String) -> Unit
-): OutputStream {
-    return if (s == "-") {
-        UnclosableOutputStream(System.out)
-    } else {
-        val path = convertToPath(
-                s,
-                mustExist = !createIfNotExist,
-                canBeFile = true,
-                canBeFolder = false,
-                mustBeWritable = !createIfNotExist,
-                mustBeReadable = false,
-                canBeSymlink = true,
-                fileSystem = fileSystem,
-                context = context
-        ) { fail(it) }
-        val openType = if (truncateExisting) TRUNCATE_EXISTING else APPEND
-        val options = arrayOf(WRITE, CREATE, openType)
-        Files.newOutputStream(path, *options)
-    }
-}
-
-//<editor-fold desc="options">
+// region ========== Options ==========
 
 /**
  * Convert the option to an [OutputStream].
@@ -55,9 +27,9 @@ private fun convertToOutputStream(
  * @param truncateExisting If true, existing files will be truncated when opened. By default, the file will be appended to.
  */
 fun RawOption.outputStream(
-        createIfNotExist: Boolean = true,
-        truncateExisting: Boolean = false,
-        fileSystem: FileSystem = FileSystems.getDefault()
+    createIfNotExist: Boolean = true,
+    truncateExisting: Boolean = false,
+    fileSystem: FileSystem = FileSystems.getDefault(),
 ): NullableOption<OutputStream, OutputStream> {
     return convert({ localization.fileMetavar() }, CompletionCandidates.Path) { s ->
         convertToOutputStream(s, createIfNotExist, truncateExisting, fileSystem, context) { fail(it) }
@@ -71,8 +43,8 @@ fun NullableOption<OutputStream, OutputStream>.defaultStdout(): OptionWithValues
     return default(UnclosableOutputStream(System.out), "-")
 }
 
-//</editor-fold>
-//<editor-fold desc="arguments">
+// endregion
+// region ========== Arguments ==========
 
 /**
  * Convert the argument to an [OutputStream].
@@ -88,9 +60,9 @@ fun NullableOption<OutputStream, OutputStream>.defaultStdout(): OptionWithValues
  * @param truncateExisting If true, existing files will be truncated when opened. By default, the file will be appended to.
  */
 fun RawArgument.outputStream(
-        createIfNotExist: Boolean = true,
-        truncateExisting: Boolean = false,
-        fileSystem: FileSystem = FileSystems.getDefault()
+    createIfNotExist: Boolean = true,
+    truncateExisting: Boolean = false,
+    fileSystem: FileSystem = FileSystems.getDefault(),
 ): ProcessedArgument<OutputStream, OutputStream> {
     return convert(completionCandidates = CompletionCandidates.Path) { s ->
         convertToOutputStream(s, createIfNotExist, truncateExisting, fileSystem, context) { fail(it) }
@@ -104,12 +76,43 @@ fun ProcessedArgument<OutputStream, OutputStream>.defaultStdout(): ArgumentDeleg
     return default(UnclosableOutputStream(System.out))
 }
 
-//</editor-fold>
+// endregion
 
 /**
- * Checks whether this stream is an unclosable [System.out] proxy.
+ * Checks whether this stream was returned from an [outputStream] parameter, and that it is
+ * writing to [System.out] (because `-` was given, or no value was given and the parameter uses
+ * [defaultStdout]).
  */
-fun OutputStream.isCliktParameterDefaultStdout(): Boolean = this is UnclosableOutputStream
+val OutputStream.isCliktParameterDefaultStdout: Boolean
+    get() = this is UnclosableOutputStream
+
+private fun convertToOutputStream(
+    s: String,
+    createIfNotExist: Boolean,
+    truncateExisting: Boolean,
+    fileSystem: FileSystem,
+    context: Context,
+    fail: (String) -> Unit,
+): OutputStream {
+    return if (s == "-") {
+        UnclosableOutputStream(System.out)
+    } else {
+        val path = convertToPath(
+            s,
+            mustExist = !createIfNotExist,
+            canBeFile = true,
+            canBeFolder = false,
+            mustBeWritable = !createIfNotExist,
+            mustBeReadable = false,
+            canBeSymlink = true,
+            fileSystem = fileSystem,
+            context = context
+        ) { fail(it) }
+        val openType = if (truncateExisting) TRUNCATE_EXISTING else APPEND
+        val options = arrayOf(WRITE, CREATE, openType)
+        Files.newOutputStream(path, *options)
+    }
+}
 
 private class UnclosableOutputStream(private var delegate: OutputStream?) : OutputStream() {
     private val stream get() = delegate ?: throw IOException("Stream closed")
diff --git a/clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/parameters/types/InputStreamTest.kt b/clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/parameters/types/InputStreamTest.kt
@@ -78,7 +78,7 @@ class InputStreamTest {
             val option by option().inputStream(fs).defaultStdin()
 
             override fun run_() {
-                option.isCliktParameterDefaultStdin().shouldBeTrue()
+                option.isCliktParameterDefaultStdin.shouldBeTrue()
             }
         }
 
@@ -93,7 +93,7 @@ class InputStreamTest {
             val option by option().inputStream(fs)
 
             override fun run_() {
-                option?.isCliktParameterDefaultStdin()?.shouldBeFalse()
+                option?.isCliktParameterDefaultStdin?.shouldBeFalse()
             }
         }
 
@@ -106,7 +106,7 @@ class InputStreamTest {
             val stream by argument().inputStream(fs).defaultStdin()
 
             override fun run_() {
-                stream.isCliktParameterDefaultStdin().shouldBeTrue()
+                stream.isCliktParameterDefaultStdin.shouldBeTrue()
             }
         }
 
@@ -121,7 +121,7 @@ class InputStreamTest {
             val stream by argument().inputStream(fs)
 
             override fun run_() {
-                stream.isCliktParameterDefaultStdin().shouldBeFalse()
+                stream.isCliktParameterDefaultStdin.shouldBeFalse()
             }
         }
 
diff --git a/clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/parameters/types/OutputStreamTest.kt b/clikt/src/jvmTest/kotlin/com/github/ajalt/clikt/parameters/types/OutputStreamTest.kt
@@ -84,7 +84,7 @@ class OutputStreamTest {
             val option by option().outputStream(fileSystem = fs).defaultStdout()
 
             override fun run_() {
-                option.isCliktParameterDefaultStdout().shouldBeTrue()
+                option.isCliktParameterDefaultStdout.shouldBeTrue()
             }
         }
 
@@ -97,7 +97,7 @@ class OutputStreamTest {
             val option by option().outputStream(fileSystem = fs)
 
             override fun run_() {
-                option?.isCliktParameterDefaultStdout()?.shouldBeFalse()
+                option?.isCliktParameterDefaultStdout?.shouldBeFalse()
             }
         }
 
@@ -110,7 +110,7 @@ class OutputStreamTest {
             val stream by argument().outputStream(fileSystem = fs).defaultStdout()
 
             override fun run_() {
-                stream.isCliktParameterDefaultStdout().shouldBeTrue()
+                stream.isCliktParameterDefaultStdout.shouldBeTrue()
             }
         }
 
@@ -123,7 +123,7 @@ class OutputStreamTest {
             val stream by argument().outputStream(fileSystem = fs)
 
             override fun run_() {
-                stream.isCliktParameterDefaultStdout().shouldBeFalse()
+                stream.isCliktParameterDefaultStdout.shouldBeFalse()
             }
         }
 
diff --git a/docs/parameters.md b/docs/parameters.md
@@ -145,6 +145,9 @@ reading or writing. They support the unix convention of passing `-` to specify s
 rather than a file on the filesystem. You'll need to close the streams yourself. You can also use
 [stdin][defaultStdin] or [stdout][defaultStdout] as their default values.
 
+If you need to check if one of these streams is pointing to a file rather than stdin or stdout, you
+can use [`isCliktParameterDefaultStdin`][isStdin] or [`isCliktParameterDefaultStdout`][isStdout].
+
 ## Custom Types
 
 You can convert parameter values to a custom type by using
@@ -338,6 +341,8 @@ been set, so (unlike in transforms) you can reference other parameters:
 [float]:          api/clikt/com.github.ajalt.clikt.parameters.types/float.md
 [inputStream]:    api/clikt/com.github.ajalt.clikt.parameters.types/input-stream.md
 [int]:            api/clikt/com.github.ajalt.clikt.parameters.types/int.md
+[isStdin]:        api/clikt/com.github.ajalt.clikt.parameters.types/java.io.-input-stream/is-clikt-parameter-default-stdin.md
+[isStdout]:       api/clikt/com.github.ajalt.clikt.parameters.types/java.io.-output-stream/is-clikt-parameter-default-stdout.md
 [long]:           api/clikt/com.github.ajalt.clikt.parameters.types/long.md
 [outputStream]:   api/clikt/com.github.ajalt.clikt.parameters.types/output-stream.md
 [path]:           api/clikt/com.github.ajalt.clikt.parameters.types/path.md

Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ class InputStreamTest {`
`78`	`78`	`val option by option().inputStream(fs).defaultStdin()`
`79`	`79`
`80`	`80`	`override fun run_() {`
`81`		`- option.isCliktParameterDefaultStdin().shouldBeTrue()`
	`81`	`+ option.isCliktParameterDefaultStdin.shouldBeTrue()`
`82`	`82`	`}`
`83`	`83`	`}`
`84`	`84`
`@@ -93,7 +93,7 @@ class InputStreamTest {`
`93`	`93`	`val option by option().inputStream(fs)`
`94`	`94`
`95`	`95`	`override fun run_() {`
`96`		`- option?.isCliktParameterDefaultStdin()?.shouldBeFalse()`
	`96`	`+ option?.isCliktParameterDefaultStdin?.shouldBeFalse()`
`97`	`97`	`}`
`98`	`98`	`}`
`99`	`99`
`@@ -106,7 +106,7 @@ class InputStreamTest {`
`106`	`106`	`val stream by argument().inputStream(fs).defaultStdin()`
`107`	`107`
`108`	`108`	`override fun run_() {`
`109`		`- stream.isCliktParameterDefaultStdin().shouldBeTrue()`
	`109`	`+ stream.isCliktParameterDefaultStdin.shouldBeTrue()`
`110`	`110`	`}`
`111`	`111`	`}`
`112`	`112`
`@@ -121,7 +121,7 @@ class InputStreamTest {`
`121`	`121`	`val stream by argument().inputStream(fs)`
`122`	`122`
`123`	`123`	`override fun run_() {`
`124`		`- stream.isCliktParameterDefaultStdin().shouldBeFalse()`
	`124`	`+ stream.isCliktParameterDefaultStdin.shouldBeFalse()`
`125`	`125`	`}`
`126`	`126`	`}`
`127`	`127`
Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@ class OutputStreamTest {`
`84`	`84`	`val option by option().outputStream(fileSystem = fs).defaultStdout()`
`85`	`85`
`86`	`86`	`override fun run_() {`
`87`		`- option.isCliktParameterDefaultStdout().shouldBeTrue()`
	`87`	`+ option.isCliktParameterDefaultStdout.shouldBeTrue()`
`88`	`88`	`}`
`89`	`89`	`}`
`90`	`90`
`@@ -97,7 +97,7 @@ class OutputStreamTest {`
`97`	`97`	`val option by option().outputStream(fileSystem = fs)`
`98`	`98`
`99`	`99`	`override fun run_() {`
`100`		`- option?.isCliktParameterDefaultStdout()?.shouldBeFalse()`
	`100`	`+ option?.isCliktParameterDefaultStdout?.shouldBeFalse()`
`101`	`101`	`}`
`102`	`102`	`}`
`103`	`103`
`@@ -110,7 +110,7 @@ class OutputStreamTest {`
`110`	`110`	`val stream by argument().outputStream(fileSystem = fs).defaultStdout()`
`111`	`111`
`112`	`112`	`override fun run_() {`
`113`		`- stream.isCliktParameterDefaultStdout().shouldBeTrue()`
	`113`	`+ stream.isCliktParameterDefaultStdout.shouldBeTrue()`
`114`	`114`	`}`
`115`	`115`	`}`
`116`	`116`
`@@ -123,7 +123,7 @@ class OutputStreamTest {`
`123`	`123`	`val stream by argument().outputStream(fileSystem = fs)`
`124`	`124`
`125`	`125`	`override fun run_() {`
`126`		`- stream.isCliktParameterDefaultStdout().shouldBeFalse()`
	`126`	`+ stream.isCliktParameterDefaultStdout.shouldBeFalse()`
`127`	`127`	`}`
`128`	`128`	`}`
`129`	`129`