Rename ExecutionResult to ExecutionOutcome; rename CollectedResult to ExecutionRecord (#225)

Author: iCharlesHu

README.md

@@ -44,7 +44,7 @@ To experiment with the `SubprocessSpan` trait, Swift 6.2 is required. Currently,
 
 ### Run and Asynchronously Collect Output
 
-The easiest way to spawn a process with `Subprocess` is to simply run it and await its `CollectedResult`:
+The easiest way to spawn a process with `Subprocess` is to simply run it and await its `ExecutionRecord`:
 
 ```swift
 import Subprocess

Sources/Subprocess/API.swift

@@ -28,7 +28,7 @@ import SystemPackage
 ///   - input: The input to send to the executable.
 ///   - output: The method to use for redirecting the standard output.
 ///   - error: The method to use for redirecting the standard error.
-/// - Returns: a `CollectedResult` containing the result of the run.
+/// - Returns: a `ExecutionRecord` containing the result of the run.
 public func run<
     Input: InputProtocol,
     Output: OutputProtocol,
@@ -42,7 +42,7 @@ public func run<
     input: Input = .none,
     output: Output,
     error: Error = .discarded
-) async throws -> CollectedResult<Output, Error> {
+) async throws -> ExecutionRecord<Output, Error> {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -70,7 +70,7 @@ public func run<
 ///   - input: span to write to subprocess' standard input.
 ///   - output: The method to use for redirecting the standard output.
 ///   - error: The method to use for redirecting the standard error.
-/// - Returns: a CollectedResult containing the result of the run.
+/// - Returns: a ExecutionRecord containing the result of the run.
 public func run<
     InputElement: BitwiseCopyable,
     Output: OutputProtocol,
@@ -84,7 +84,7 @@ public func run<
     input: borrowing Span<InputElement>,
     output: Output,
     error: Error = .discarded
-) async throws -> CollectedResult<Output, Error> {
+) async throws -> ExecutionRecord<Output, Error> {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -133,7 +133,7 @@ public func run<
     error: Error = .discarded,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -180,7 +180,7 @@ public func run<Result, Input: InputProtocol, Error: ErrorOutputProtocol>(
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -227,7 +227,7 @@ public func run<Result, Input: InputProtocol, Output: OutputProtocol>(
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Output.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Output.OutputType == Void {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -272,7 +272,7 @@ public func run<Result, Error: ErrorOutputProtocol>(
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -316,7 +316,7 @@ public func run<Result, Output: OutputProtocol>(
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Output.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Output.OutputType == Void {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -366,7 +366,7 @@ public func run<Result>(
             AsyncBufferSequence
         ) async throws -> Result
     )
-) async throws -> ExecutionResult<Result> {
+) async throws -> ExecutionOutcome<Result> {
     let configuration = Configuration(
         executable: executable,
         arguments: arguments,
@@ -386,13 +386,13 @@ public func run<Result>(
 
 #if SubprocessSpan
 /// Run an executable with given configuration asynchronously and returns
-/// a `CollectedResult` containing the output of the child process.
+/// a `ExecutionRecord` containing the output of the child process.
 /// - Parameters:
 ///   - configuration: The configuration to run.
 ///   - input: span to write to subprocess' standard input.
 ///   - output: The method to use for redirecting the standard output.
 ///   - error: The method to use for redirecting the standard error.
-/// - Returns a CollectedResult containing the result of the run.
+/// - Returns a ExecutionRecord containing the result of the run.
 public func run<
     InputElement: BitwiseCopyable,
     Output: OutputProtocol,
@@ -402,7 +402,7 @@ public func run<
     input: borrowing Span<InputElement>,
     output: Output,
     error: Error = .discarded
-) async throws -> CollectedResult<Output, Error> {
+) async throws -> ExecutionRecord<Output, Error> {
     typealias RunResult = (
         processIdentifier: ProcessIdentifier,
         standardOutput: Output.OutputType,
@@ -437,7 +437,7 @@ public func run<
         )
     }
 
-    return CollectedResult(
+    return ExecutionRecord(
         processIdentifier: result.value.processIdentifier,
         terminationStatus: result.terminationStatus,
         standardOutput: result.value.standardOutput,
@@ -447,13 +447,13 @@ public func run<
 #endif
 
 /// Run a `Configuration` asynchronously and returns
-/// a `CollectedResult` containing the output of the child process.
+/// a `ExecutionRecord` containing the output of the child process.
 /// - Parameters:
 ///   - configuration: The `Subprocess` configuration to run.
 ///   - input: The input to send to the executable.
 ///   - output: The method to use for redirecting the standard output.
 ///   - error: The method to use for redirecting the standard error.
-/// - Returns: a `CollectedResult` containing the result of the run.
+/// - Returns: a `ExecutionRecord` containing the result of the run.
 public func run<
     Input: InputProtocol,
     Output: OutputProtocol,
@@ -463,7 +463,7 @@ public func run<
     input: Input = .none,
     output: Output,
     error: Error = .discarded
-) async throws -> CollectedResult<Output, Error> {
+) async throws -> ExecutionRecord<Output, Error> {
     typealias RunResult = (
         processIdentifier: ProcessIdentifier,
         standardOutput: Output.OutputType,
@@ -541,7 +541,7 @@ public func run<
         }
     }
 
-    return CollectedResult(
+    return ExecutionRecord(
         processIdentifier: result.value.processIdentifier,
         terminationStatus: result.terminationStatus,
         standardOutput: result.value.standardOutput,
@@ -572,7 +572,7 @@ public func run<
     error: Error = .discarded,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     let inputPipe = try input.createPipe()
     let outputPipe = try output.createPipe()
     let errorPipe = try error.createPipe(from: outputPipe)
@@ -630,7 +630,7 @@ public func run<
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     let output = SequenceOutput()
     let inputPipe = try input.createPipe()
     let outputPipe = try output.createPipe()
@@ -692,7 +692,7 @@ public func run<Result, Input: InputProtocol, Output: OutputProtocol>(
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Output.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Output.OutputType == Void {
     let error = SequenceOutput()
 
     return try await configuration.run(
@@ -750,7 +750,7 @@ public func run<Result, Error: ErrorOutputProtocol>(
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     let input = CustomWriteInput()
     let output = SequenceOutput()
     let inputPipe = try input.createPipe()
@@ -793,7 +793,7 @@ public func run<Result, Output: OutputProtocol>(
     preferredBufferSize: Int? = nil,
     isolation: isolated (any Actor)? = #isolation,
     body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Output.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Output.OutputType == Void {
     let input = CustomWriteInput()
     let error = SequenceOutput()
 
@@ -838,7 +838,7 @@ public func run<Result>(
             AsyncBufferSequence
         ) async throws -> Result
     )
-) async throws -> ExecutionResult<Result> {
+) async throws -> ExecutionOutcome<Result> {
     let input = CustomWriteInput()
     let output = SequenceOutput()
     let error = SequenceOutput()

Sources/Subprocess/Configuration.swift

@@ -99,7 +99,7 @@ public struct Configuration: Sendable {
                 consuming IOChannel?
             ) async throws -> Result
         )
-    ) async throws -> ExecutionResult<Result> {
+    ) async throws -> ExecutionOutcome<Result> {
         let spawnResults = try await self.spawn(
             withInput: input,
             outputPipe: output,
@@ -115,7 +115,7 @@ public struct Configuration: Sendable {
             execution.processIdentifier.close()
         }
 
-        return try await withAsyncTaskCleanupHandler { () throws -> ExecutionResult<Result> in
+        return try await withAsyncTaskCleanupHandler { () throws -> ExecutionOutcome<Result> in
             let inputIO = _spawnResult.inputWriteEnd()
             let outputIO = _spawnResult.outputReadEnd()
             let errorIO = _spawnResult.errorReadEnd()
@@ -138,7 +138,7 @@ public struct Configuration: Sendable {
                 for: execution.processIdentifier
             )
 
-            return ExecutionResult(
+            return ExecutionOutcome(
                 terminationStatus: terminationStatus,
                 value: try result.get()
             )

Sources/Subprocess/Result.swift

@@ -20,7 +20,7 @@ import SystemPackage
 /// A simple wrapper around the generic result returned by the
 /// `run` closure with the corresponding termination status of
 /// the child process.
-public struct ExecutionResult<Result: Sendable>: Sendable {
+public struct ExecutionOutcome<Result: Sendable>: Sendable {
     /// The termination status of the child process
     public let terminationStatus: TerminationStatus
     /// The result returned by the closure passed to `.run` methods
@@ -34,7 +34,7 @@ public struct ExecutionResult<Result: Sendable>: Sendable {
 
 /// The result of a subprocess execution with its collected
 /// standard output and standard error.
-public struct CollectedResult<
+public struct ExecutionRecord<
     Output: OutputProtocol,
     Error: OutputProtocol
 >: Sendable {
@@ -60,18 +60,18 @@ public struct CollectedResult<
     }
 }
 
-// MARK: - CollectedResult Conformances
+// MARK: - ExecutionRecord Conformances
 
-extension CollectedResult: Equatable where Output.OutputType: Equatable, Error.OutputType: Equatable {}
+extension ExecutionRecord: Equatable where Output.OutputType: Equatable, Error.OutputType: Equatable {}
 
-extension CollectedResult: Hashable where Output.OutputType: Hashable, Error.OutputType: Hashable {}
+extension ExecutionRecord: Hashable where Output.OutputType: Hashable, Error.OutputType: Hashable {}
 
-extension CollectedResult: CustomStringConvertible
+extension ExecutionRecord: CustomStringConvertible
 where Output.OutputType: CustomStringConvertible, Error.OutputType: CustomStringConvertible {
     /// A textual representation of the collected result.
     public var description: String {
         return """
-            CollectedResult(
+            ExecutionRecord(
                 processIdentifier: \(self.processIdentifier),
                 terminationStatus: \(self.terminationStatus.description),
                 standardOutput: \(self.standardOutput.description)
@@ -81,12 +81,12 @@ where Output.OutputType: CustomStringConvertible, Error.OutputType: CustomString
     }
 }
 
-extension CollectedResult: CustomDebugStringConvertible
+extension ExecutionRecord: CustomDebugStringConvertible
 where Output.OutputType: CustomDebugStringConvertible, Error.OutputType: CustomDebugStringConvertible {
     /// A debug-oriented textual representation of the collected result.
     public var debugDescription: String {
         return """
-            CollectedResult(
+            ExecutionRecord(
                 processIdentifier: \(self.processIdentifier),
                 terminationStatus: \(self.terminationStatus.description),
                 standardOutput: \(self.standardOutput.debugDescription)
@@ -96,28 +96,28 @@ where Output.OutputType: CustomDebugStringConvertible, Error.OutputType: CustomD
     }
 }
 
-// MARK: - ExecutionResult Conformances
-extension ExecutionResult: Equatable where Result: Equatable {}
+// MARK: - ExecutionOutcome Conformances
+extension ExecutionOutcome: Equatable where Result: Equatable {}
 
-extension ExecutionResult: Hashable where Result: Hashable {}
+extension ExecutionOutcome: Hashable where Result: Hashable {}
 
-extension ExecutionResult: CustomStringConvertible where Result: CustomStringConvertible {
+extension ExecutionOutcome: CustomStringConvertible where Result: CustomStringConvertible {
     /// A textual representation of the execution result.
     public var description: String {
         return """
-            ExecutionResult(
+            ExecutionOutcome(
                 terminationStatus: \(self.terminationStatus.description),
                 value: \(self.value.description)
             )
             """
     }
 }
 
-extension ExecutionResult: CustomDebugStringConvertible where Result: CustomDebugStringConvertible {
+extension ExecutionOutcome: CustomDebugStringConvertible where Result: CustomDebugStringConvertible {
     /// A debug-oriented textual representation of this execution result.
     public var debugDescription: String {
         return """
-            ExecutionResult(
+            ExecutionOutcome(
                 terminationStatus: \(self.terminationStatus.debugDescription),
                 value: \(self.value.debugDescription)
             )

Tests/SubprocessTests/IntegrationTests.swift

@@ -2632,7 +2632,7 @@ func _run<
     input: Input,
     output: Output,
     error: Error
-) async throws -> CollectedResult<Output, Error> {
+) async throws -> ExecutionRecord<Output, Error> {
     return try await Subprocess.run(
         testSetup.executable,
         arguments: testSetup.arguments,
@@ -2655,7 +2655,7 @@ func _run<
     input: borrowing Span<InputElement>,
     output: Output,
     error: Error
-) async throws -> CollectedResult<Output, Error> {
+) async throws -> ExecutionRecord<Output, Error> {
     return try await Subprocess.run(
         testSetup.executable,
         arguments: testSetup.arguments,
@@ -2678,7 +2678,7 @@ func _run<
     error: Error,
     preferredBufferSize: Int? = nil,
     body: ((Execution, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     return try await Subprocess.run(
         setup.executable,
         arguments: setup.arguments,
@@ -2698,7 +2698,7 @@ func _run<
     _ setup: TestSetup,
     error: Error,
     body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Error.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Error.OutputType == Void {
     return try await Subprocess.run(
         setup.executable,
         arguments: setup.arguments,
@@ -2716,7 +2716,7 @@ func _run<
     _ setup: TestSetup,
     output: Output,
     body: ((Execution, StandardInputWriter, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> where Output.OutputType == Void {
+) async throws -> ExecutionOutcome<Result> where Output.OutputType == Void {
     return try await Subprocess.run(
         setup.executable,
         arguments: setup.arguments,
@@ -2730,7 +2730,7 @@ func _run<
 func _run<Result>(
     _ setup: TestSetup,
     body: ((Execution, StandardInputWriter, AsyncBufferSequence, AsyncBufferSequence) async throws -> Result)
-) async throws -> ExecutionResult<Result> {
+) async throws -> ExecutionOutcome<Result> {
     return try await Subprocess.run(
         setup.executable,
         arguments: setup.arguments,