diff --git a/Package.resolved b/Package.resolved index 0cbf216..f597833 100644 --- a/Package.resolved +++ b/Package.resolved @@ -18,6 +18,15 @@ "revision": "e1577acf2b6e90086d01a6d5e2b8efdaae033568", "version": "2.3.0" } + }, + { + "package": "SwiftDocCPlugin", + "repositoryURL": "https://github.com/apple/swift-docc-plugin", + "state": { + "branch": null, + "revision": "3303b164430d9a7055ba484c8ead67a52f7b74f6", + "version": "1.0.0" + } } ] }, diff --git a/Sources/ScriptSwift/Script+Comparable.swift b/Sources/ScriptSwift/Script+Comparable.swift index da8c8fd..0a05a64 100644 --- a/Sources/ScriptSwift/Script+Comparable.swift +++ b/Sources/ScriptSwift/Script+Comparable.swift @@ -1,8 +1,9 @@ /// Scripting methods whose values are comparable extension Script where T: Comparable { - /// Return Bool value by comparing the piped value and the parameter `number`. - /// + /// This method return true when the piped value is more than `number` and false otherwise. + /// - Parameter number: `Comparable` value + /// - Returns: Bool value by comparing the piped value and the parameter `number` public func more(than number: T) -> Script { switch input { case .success(let input): @@ -12,9 +13,9 @@ extension Script where T: Comparable { } } - /// Return Bool value by comparing the piped value and the parameter `number`. - /// /// This method return true when the piped value is less than `number` and false otherwise. + /// - Parameter number: `Comparable` value + /// - Returns: Bool value by comparing the piped value and the parameter `number` public func less(than number: T) -> Script { switch input { case .success(let input): @@ -24,9 +25,9 @@ extension Script where T: Comparable { } } - /// Return Bool value by comparing the piped value and the parameter `number`. - /// /// This method return true when the piped value is equal to `number` and false otherwise. + /// - Parameter number: `Comparable` value + /// - Returns: Bool value by comparing the piped value and the parameter `number` public func equal(to number: T) -> Script { switch input { case .success(let input): diff --git a/Sources/ScriptSwift/Script+Data.swift b/Sources/ScriptSwift/Script+Data.swift index 2ddc56d..38025d5 100644 --- a/Sources/ScriptSwift/Script+Data.swift +++ b/Sources/ScriptSwift/Script+Data.swift @@ -2,6 +2,9 @@ import struct Foundation.Data import Files extension Script where T == Data { + /// This function writes `Data` value from previous ``Script`` method to a file specified. + /// - Parameter path: `String` representation of path of the file + /// - Returns: ``Script`` object with `File` value or failure public func write(path: String) -> Script { switch input { case .success(let input): @@ -18,6 +21,9 @@ extension Script where T == Data { } } + /// This function writes `Data` value from previous ``Script`` method to a file specified. + /// - Parameter filename: `String` representation of the name of the file + /// - Returns: ``Script`` object with `File` value or failure public func write(to filename: String) -> Script { switch input { case .success(let input): diff --git a/Sources/ScriptSwift/Script+Files.swift b/Sources/ScriptSwift/Script+Files.swift index ebd4298..3077c3d 100644 --- a/Sources/ScriptSwift/Script+Files.swift +++ b/Sources/ScriptSwift/Script+Files.swift @@ -2,6 +2,8 @@ import struct Foundation.Data import Files extension Script where T == File { + /// This function reads file from the value of the previous ``Script`` method. + /// - Returns: ``Script`` object with `Data` representation of the file or failure public func read() -> Script { switch input { case .success(let input): @@ -16,6 +18,9 @@ extension Script where T == File { } } + /// This function reads file from the value of the previous ``Script`` method. + /// - Parameter encoded: This indicates how the file is encoded. + /// - Returns: ``Script`` object with `String` representation of the file or failure public func read(encoded: String.Encoding = .utf8) -> Script { switch input { case .success(let input): diff --git a/Sources/ScriptSwift/Script+String.swift b/Sources/ScriptSwift/Script+String.swift index d2f2aa8..ddf3ebf 100644 --- a/Sources/ScriptSwift/Script+String.swift +++ b/Sources/ScriptSwift/Script+String.swift @@ -6,6 +6,8 @@ extension Script where T == String { self.init(success: "") } + /// This function executes externtal command using the input `String` value. + /// - Returns: ``Script`` object containing `String` value or failure public func exec() -> Script { switch input { case .success(let input): @@ -20,6 +22,8 @@ extension Script where T == String { } } + /// This function pass `self` to next function in the method chain if a file exists using the input `String` value. + /// - Returns: ``Script`` object passed from previous function or failure public func ifExists() -> Script { switch input { case .success(let input): @@ -34,6 +38,9 @@ extension Script where T == String { } } + /// This function passes `String` value only when matched. + /// - Parameter string: `String` value to match + /// - Returns: ``Script`` object with only matched `String` value or failure public func match(_ string: String) -> Script { switch input { case .success(let input): @@ -48,6 +55,8 @@ extension Script where T == String { } } + /// This function returns the number of lines of `String` input value. + /// - Returns: ``Script`` object with `Int` value of the number of lines public func countLines() -> Script { switch input { case .success(let input): @@ -57,6 +66,8 @@ extension Script where T == String { } } + /// This function combines files using input `String` value as file names, and outputs the combined files as `Array` of `String`. + /// - Returns: ``Script`` object with `Array` of `String` public func concat() -> Script<[String]> { switch input { case .success(let input): @@ -72,6 +83,8 @@ extension Script where T == String { } } + /// This function passes multi-line `String` value as `Array` to next ``Script`` method. + /// - Returns: ``Script`` object with `Array` of `String` value public func asArray() -> Script<[String]> { switch input { case .success(let input): diff --git a/Sources/ScriptSwift/Script.swift b/Sources/ScriptSwift/Script.swift index b0f8c0e..debaec5 100644 --- a/Sources/ScriptSwift/Script.swift +++ b/Sources/ScriptSwift/Script.swift @@ -2,6 +2,9 @@ import Files import ShellOut import struct Foundation.Data +/// Script type +/// +/// By using method chain, you can express a workflow of your script in Swift. public struct Script { var input: Result @@ -17,16 +20,14 @@ public struct Script { self.init(input: .failure(failure)) } + /// This function collects inputs from stdin and returns as `String`. + /// - Returns: ``Script`` object containing `String` value or failure public func stdin() -> Script { guard let array: [String] = readLine()?.split(separator: " ").map({ s in String(s) }) else { return .init(success: "") } return .init(success: array.joined(separator: " ")) } - // public func stdin() -> Script<[String]> { - // guard let array: [String] = readLine()?.split(separator: " ").map({ s in String(s) }) else { return .init(success: []) } - // return .init(success: array) - // } - + /// This function accepts inputs and outputs it to stdout. public func stdout() { switch input { case .success(let input): @@ -36,6 +37,9 @@ public struct Script { } } + /// This function executes externtal command. + /// - Parameter command: `Array` of `String` to execute command + /// - Returns: ``Script`` object containing `String` value or failure public func exec(_ command: [String]) -> Script { do { return .init(success: try shellOut(to: command)) @@ -44,6 +48,9 @@ public struct Script { } } + /// This function executes externtal command. + /// - Parameter command: `String` to execute command + /// - Returns: ``Script`` object containing `String` value or failure public func exec(_ command: String) -> Script { do { return .init(success: try shellOut(to: command)) @@ -52,6 +59,9 @@ public struct Script { } } + /// This function pass `self` to next function in the method chain if a file exists. + /// - Parameter filename: `String` to represent name of a file + /// - Returns: ``Script`` object passed from previous function or failure public func ifExists(_ filename: String) -> Script { do { _ = try File(path: filename) @@ -61,6 +71,9 @@ public struct Script { } } + /// This function lets user modify the contained value in the method chain. + /// - Parameter transform: A closure to modify the contained value + /// - Returns: ``Script`` object with modified value or failure public func map(_ transform: (T) -> N) -> Script { switch input { case .success(let input): @@ -70,6 +83,8 @@ public struct Script { } } + /// This function returns the contained value, ending the method chain. + /// - Returns: The contained value or exit with failure public func raw() -> T { switch input { case .success(let input): @@ -79,6 +94,8 @@ public struct Script { } } + /// This function returns the contained value or error as `String`. + /// - Returns: `String` representaion of the contained value or error public func asString() -> String { switch input { case .success(let input): diff --git a/Sources/ScriptSwift/SystemCall.swift b/Sources/ScriptSwift/SystemCall.swift index 5c74c4a..4eee7a9 100644 --- a/Sources/ScriptSwift/SystemCall.swift +++ b/Sources/ScriptSwift/SystemCall.swift @@ -6,6 +6,9 @@ import Glibc let _exit = Glibc.exit #endif +/// This function exit current process with error if given. +/// - Parameter error: `Error` object +/// - Returns: `Never` func exit(withError error: Error? = nil) -> Never { guard let error = error else { _exit(0)