CLT documentation refactoring

- Updated to Lux 0.3.5 to fix Json escaped quotes
- Moved explanations and examples in the doc command
- Added colors to the documentation

Package.resolved

@@ -15,17 +15,26 @@
         "repositoryURL": "https://github.com/ABridoux/lux",
         "state": {
           "branch": null,
-          "revision": "b97bc3f12e516669ab95e05161b91062f7934a64",
-          "version": "0.2.1"
+          "revision": "8174cedcd6542b59b9e88b577ba87f10fa1ab312",
+          "version": "0.3.5"
+        }
+      },
+      {
+        "package": "Splash",
+        "repositoryURL": "https://github.com/JohnSundell/Splash",
+        "state": {
+          "branch": null,
+          "revision": "ca9a1b7bff35381fe5ae9fe2ec9333cc5f2a586c",
+          "version": "0.13.0"
         }
       },
       {
         "package": "swift-argument-parser",
         "repositoryURL": "https://github.com/apple/swift-argument-parser",
         "state": {
           "branch": null,
-          "revision": "3d79b2b5a2e5af52c14e462044702ea7728f5770",
-          "version": "0.1.0"
+          "revision": "eb51f949cdd0c9d88abba9ce79d37eb7ea1231d0",
+          "version": "0.2.0"
         }
       }
     ]

Sources/ScoutCLT/AddCommand.swift → Sources/ScoutCLT/Add/AddCommand.swift

@@ -2,68 +2,14 @@ import ArgumentParser
 import Scout
 import Foundation
 
-private let discussion =
-"""
-Notes
-=====
-- All the keys which do not exist in the path will be created
-- Enclose the value with slash signs to force the value as a string: /valueAsString/ (Plist, Json)
-- Enclose the value with interrogative signs to force the value as a boolean: ?valueToBoolean? (Plist, Json)
-- Enclose the value with tilde signs to force the value as a real: ~valueToReal~ (Plist)
-- Enclose the value with chevron signs to force the value as a integer: <valueToInteger> (Plist)
-- When adding an element in an array , use the index -1 to add the element at the end of the array
-
-Examples
-========
-Given the following Json (as input stream or file)
-
-{
-  "people": {
-    "Tom": {
-      "height": 175,
-      "age": 68,
-      "hobbies": [
-        "cooking",
-        "guitar"
-      ]
-    },
-    "Arnaud": {
-      "height": 180,
-      "age": 23,
-      "hobbies": [
-        "video games",
-        "party",
-        "tennis"
-      ]
-    }
-  }
-}
-
-`scout add "people.Franklin.height"=165` will create a new dictionary Franklin and add a height key into it with the value 165
-
-`scout add "people.Tom.hobbies[-1]"="Playing music"` will add the hobby "Playing music" to Tom hobbies at the end of the array
-
-`scout add "people.Arnaud.hobbies[1]"=reading` will insert the hobby "reading" to Arnaud hobbies between the hobby "video games" and "party"
-
-`scout add "people.Franklin.hobbies[0]"=football` will create a new dictionary Franklin, add a hobbies array into it, and insert the value "football" in the array
-
-`scout add "people.Franklin.height"=/165/` will create a new dictionary Franklin and add a height key into it with the String value "165"
-
-`scout add "people.Franklin.height"=~165~` will create a new dictionary Franklin and add a height key into it with the Real value 165 (Plist only)
-
-More
-====
-You can find more examples here: https://github.com/ABridoux/scout/tree/master/Playground
-"""
-
 struct AddCommand: ParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "add",
         abstract: "Add value at a given path",
-        discussion: discussion)
+        discussion: "To find examples and advanced explanations, please type `scout doc add`")
 
     @Argument(help: PathAndValue.help)
-    var pathsAndValues: [PathAndValue]
+    var pathsAndValues = [PathAndValue]()
 
     @Option(name: [.short, .customLong("input")], help: "A file path from which to read the data")
     var inputFilePath: String?
@@ -74,8 +20,8 @@ struct AddCommand: ParsableCommand {
     @Option(name: [.short, .customLong("modify")], help: "Read and write the data into the same file at the given path")
     var modifyFilePath: String?
 
-    @Flag(name: [.short, .long], default: false, inversion: .prefixedNo, help: "Output the modified data")
-    var verbose: Bool
+    @Flag(name: [.short, .long], inversion: .prefixedNo, help: "Output the modified data")
+    var verbose = false
 
     func run() throws {
 

Sources/ScoutCLT/Add/AddDocumentation.swift

@@ -0,0 +1,70 @@
+import ArgumentParser
+import Lux
+
+struct AddDocumentation: Documentation {
+    private static let jsonInjector = JSONInjector(type: .terminal)
+    private static let zshInjector = ZshInjector(type: .terminal)
+
+    private static let jsonExample =
+    """
+    {
+      "people": {
+        "Tom": {
+          "height": 175,
+          "age": 68,
+          "hobbies": [
+            "cooking",
+            "guitar"
+          ]
+        },
+        "Arnaud": {
+          "height": 180,
+          "age": 23,
+          "hobbies": [
+            "video games",
+            "party",
+            "tennis"
+          ]
+        }
+      }
+    }
+    """
+
+    private static let examples = [(#"`scout add "people.Franklin.height=165"`"#, #"will create a new dictionary Franklin and add a height key into it with the value 165"#),
+                                   (#"`scout add "people.Tom.hobbies[-1]"="Playing music"`"#, #"will add the hobby "Playing music" to Tom hobbies at the end of the array"#),
+                                   (#"`scout add "people.Arnaud.hobbies[1]=reading"`"#, #"will insert the hobby "reading" to Arnaud hobbies between the hobby "video games" and "party""#),
+                                   (#"`scout add "people.Franklin.hobbies[0]"=football`"#, """
+                                                                                            will create a new dictionary Franklin,
+                                                                                                add a hobbies array into it, and insert the value "football" in the array
+                                                                                            """),
+                                   (#"`scout add "people.Franklin.height=/165/"`"#, #"will create a new dictionary Franklin and add a height key into it with the String value "165""#),
+                                   (#"`scout add "people.Franklin.height=~165~"`"#, #"will create a new dictionary Franklin and add a height key into it with the Real value 165 (Plist only)"#)]
+
+    static let text =
+    """
+
+    Add command
+    ============
+
+    Notes
+    -----
+    - You add delete multiple values in one command
+    - Specify the \(zshInjector.delegate.inject(.optionNameOrFlag, in: .terminal, "-v")) flag to see the modified data
+
+    - All the keys which do not exist in the path will be created
+    - Enclose the value with slash signs to force the value as a string: /valueAsString/ (Plist, Json)
+    - Enclose the value with interrogative signs to force the value as a boolean: ?valueToBoolean? (Plist, Json)
+    - Enclose the value with tilde signs to force the value as a real: ~valueToReal~ (Plist)
+    - Enclose the value with chevron signs to force the value as a integer: <valueToInteger> (Plist)
+    - When adding an element in an array, use the index -1 to add the element at the end of the array
+
+    Examples
+    --------
+
+    JSON file
+
+    \(jsonInjector.inject(in: jsonExample))
+
+    \(examplesText(from: examples))
+    """
+}

Sources/ScoutCLT/ColorDelegates/ColorFile.swift

@@ -1,29 +1,29 @@
 struct JsonColors: Codable {
-    var punctuation: Int?
-    var keyName: Int?
-    var keyValue: Int?
+    var punctuation: Int? = nil
+    var keyName: Int? = nil
+    var keyValue: Int? = nil
 }
 
 struct PlistColors: Codable {
-    var tag: Int?
-    var keyName: Int?
-    var keyValue: Int?
-    var header: Int?
-    var comment: Int?
+    var tag: Int? = nil
+    var keyName: Int? = nil
+    var keyValue: Int? = nil
+    var header: Int? = nil
+    var comment: Int? = nil
 }
 
 struct XmlColors: Codable {
-    var punctuation: Int?
-    var openingTag: Int?
-    var closingTag: Int?
-    var key: Int?
-    var header: Int?
-    var comment: Int?
+    var punctuation: Int? = nil
+    var openingTag: Int? = nil
+    var closingTag: Int? = nil
+    var key: Int? = nil
+    var header: Int? = nil
+    var comment: Int? = nil
 }
 
 /// Plist file to specify custom colors
 struct ColorFile: Codable {
-    var json: JsonColors?
-    var plist: PlistColors?
-    var xml: XmlColors?
+    var json: JsonColors? = nil
+    var plist: PlistColors? = nil
+    var xml: XmlColors? = nil
 }

Sources/ScoutCLT/ColorDelegates/JSONInjectorDelegate.swift

@@ -13,24 +13,26 @@ final class JSONInjectorColorDelegate: JSONDelegate {
     }
 
     required init() {
-        fatalError("init() has not been implemented")
+        colors = JsonColors()
+        super.init()
     }
 
     // MARK: - Functions
 
-    override func injection(for category: JSONCategory, type: TextType) -> String {
+    override func terminalModifier(for category: JSONCategory) -> TerminalModifier {
         var colorCode: Int?
 
+        // retrieve the color code in the colors plist if any
         switch category {
         case .punctuation: colorCode = colors.punctuation
         case .keyName: colorCode = colors.keyName
         case .keyValue: colorCode = colors.keyValue
         }
 
         if let code = colorCode {
-            return String.colorPrefix(code)
+            return TerminalModifier(colorCode: code)
         } else {
-            return super.injection(for: category, type: type)
+            return super.terminalModifier(for: category)
         }
     }
 }

Sources/ScoutCLT/ColorDelegates/PlistInjectorColorDelegate.swift

@@ -13,12 +13,13 @@ final class PlistInjectorColorDelegate: PlistDelegate {
     }
 
     required init() {
-        fatalError("init() has not been implemented")
+        colors = PlistColors()
+        super.init()
     }
 
     // MARK: - Functions
 
-    override func injection(for category: PlistCategory, type: TextType) -> String {
+    override func terminalModifier(for category: PlistCategory) -> TerminalModifier {
         var colorCode: Int?
 
         switch category {
@@ -30,9 +31,9 @@ final class PlistInjectorColorDelegate: PlistDelegate {
         }
 
         if let code = colorCode {
-            return String.colorPrefix(code)
+            return TerminalModifier(colorCode: code)
         } else {
-            return super.injection(for: category, type: type)
+            return super.terminalModifier(for: category)
         }
     }
 }

Sources/ScoutCLT/ColorDelegates/XMLInjectorColorDelegate.swift

@@ -13,12 +13,13 @@ final class XMLInjectorColorDelegate: XMLEnhancedDelegate {
     }
 
     required init() {
-        fatalError("init() has not been implemented")
+        colors = XmlColors()
+        super.init()
     }
 
     // MARK: - Functions
 
-    override func injection(for category: XMLEnhancedCategory, type: TextType) -> String {
+    override func terminalModifier(for category: XMLEnhancedCategory) -> TerminalModifier {
         var colorCode: Int?
 
         switch category {
@@ -31,9 +32,9 @@ final class XMLInjectorColorDelegate: XMLEnhancedDelegate {
         }
 
         if let code = colorCode {
-            return String.colorPrefix(code)
+            return TerminalModifier(colorCode: code)
         } else {
-            return super.injection(for: category, type: type)
+            return super.terminalModifier(for: category)
         }
     }
 }

Sources/ScoutCLT/Command.swift

@@ -0,0 +1,5 @@
+import ArgumentParser
+
+enum Command: String, ExpressibleByArgument {
+    case read, set, delete, add
+}

Sources/ScoutCLT/DeleteCommand.swift → Sources/ScoutCLT/Delete/DeleteCommand.swift

@@ -9,12 +9,12 @@ struct DeleteCommand: ParsableCommand {
     static let configuration = CommandConfiguration(
         commandName: "delete",
         abstract: "Delete a value at a given path",
-        discussion: "When accessing an array value by its index, use the index -1 to access to the last element")
+        discussion: "To find examples and advanced explanations, please type `scout doc delete`")
 
     // MARK: - Properties
 
     @Argument(help: "Paths to indicate the keys to be deleted")
-    var readingPaths: [Path]
+    var readingPaths = [Path]()
 
     @Option(name: [.short, .customLong("input")], help: "A file path from which to read the data")
     var inputFilePath: String?
@@ -25,8 +25,8 @@ struct DeleteCommand: ParsableCommand {
     @Option(name: [.short, .customLong("modify")], help: "Read and write the data into the same file at the given path")
     var modifyFilePath: String?
 
-    @Flag(name: [.short, .long], default: false, inversion: .prefixedNo, help: "Output the modified data")
-    var verbose: Bool
+    @Flag(name: [.short, .long], inversion: .prefixedNo, help: "Output the modified data")
+    var verbose = false
 
     // MARK: - Functions