Merge pull request #31 from Typ0genius/main

Update executing commands code documentation

Author: Joannis

README.md

@@ -44,7 +44,47 @@ You can execute a command through SSH using the following code:
 let stdout = try await client.executeCommand("ls -la ~")
 ```
 
-The `executeCommand` function accumulated information into a contiguous `ByteBuffer`. This is useful for non-interactive commands such as `cat` and `ls`. Citadel currently does not expose APIs for streaming into a process' `stdin` or streaming the `stdout` elsewhere. If you want this, please create an issue.
+Additionally, a maximum responsive response size can be set, and `stderr` can be merged with `stdout` so that the answer contains the content of both streams:
+
+```swift
+let stdoutAndStderr = try await client.executeCommand("ls -la ~", maxResponseSize: 42, mergeStreams: true)
+```
+
+The `executeCommand` function accumulated information into a contiguous `ByteBuffer`. This is useful for non-interactive commands such as `cat` and `ls`.
+
+The `executeCommandPair` function or `executeCommandStream` function can be used to access `stdout` and `stderr` independently. Both functions also accumulate information into contiguous separate `ByteBuffers`.
+
+An example of how executeCommandPair can be used:
+
+```swift
+let streams = try await client.executeCommandPair("cat /foo/bar.log")
+
+for try await blob in answer.stdout {
+    // do something with blob
+}
+
+for try await blob in answer.stderr {
+    // do something with blob
+}
+```
+
+An example of how executeCommandStream can be used:
+
+```swift
+let streams = try await client.executeCommandStream("cat /foo/bar.log")
+var asyncStreams = streams.makeAsyncIterator()
+
+while let blob = try await asyncStreams.next() {
+    switch blob {
+        case .stdout(let stdout):
+            // do something with stdout
+        case .stderr(let stderr):
+            // do something with stderr
+    }
+}
+```
+
+Citadel currently does not expose APIs for streaming into a process' `stdin`. If you want this, please create an issue.
 
 ### SFTP Client
 

Sources/Citadel/TTY/Client/TTY.swift

@@ -165,10 +165,11 @@ final class ExecCommandHandler: ChannelDuplexHandler {
 }
 
 extension SSHClient {
-    /// Executes a command on the remote server. This will return the output of the command. If the command fails, the error will be thrown. If the output is too large, the command will fail.
+    /// Executes a command on the remote server. This will return the output of the command (stdout). If the command fails, the error will be thrown. If the output is too large, the command will fail.
     /// - Parameters:
-    ///  - command: The command to execute.
+    /// - command: The command to execute.
     /// - maxResponseSize: The maximum size of the response. If the response is larger, the command will fail.
+    /// - mergeStreams: If the answer should also include stderr.
     public func executeCommand(_ command: String, maxResponseSize: Int = .max, mergeStreams: Bool = false) async throws -> ByteBuffer {
         let promise = eventLoop.makePromise(of: ByteBuffer.self)
 
@@ -217,7 +218,10 @@ extension SSHClient {
             return promise.futureResult
         }.get()
     }
-    
+
+    /// Executes a command on the remote server. This will return the output stream of the command. If the command fails, the error will be thrown.
+    /// - Parameters:
+    /// - command: The command to execute.
     public func executeCommandStream(_ command: String) async throws -> AsyncThrowingStream<ExecCommandOutput, Error> {
         var streamContinuation: AsyncThrowingStream<ExecCommandOutput, Error>.Continuation!
         let stream = AsyncThrowingStream<ExecCommandOutput, Error> { continuation in
@@ -258,7 +262,10 @@ extension SSHClient {
 
         return stream
     }
-    
+
+    /// Executes a command on the remote server. This will return the pair of streams stdout and stderr of the command. If the command fails, the error will be thrown.
+    /// - Parameters:
+    /// - command: The command to execute.
     public func executeCommandPair(_ command: String) async throws -> ExecCommandStream {
         var stdoutContinuation: AsyncThrowingStream<ByteBuffer, Error>.Continuation!
         var stderrContinuation: AsyncThrowingStream<ByteBuffer, Error>.Continuation!