Include more documentation.

Author: objecthub

CHANGELOG.md

@@ -1,4 +1,9 @@
 # Changelog
 
+## 0.2 (2018-06-10)
+- Bug fixes
+- Support of usage descriptions
+- Initial documentation
+
 ## 0.1 (2018-05-14)
 - Initial version

README.md

@@ -1,6 +1,7 @@
 # Swift CommandLineKit
 
 [![Platform: macOS](https://img.shields.io/badge/Platform-macOS-blue.svg?style=flat)](https://developer.apple.com/osx/)
+[![Platform: Linux](https://img.shields.io/badge/Platform-Linux-blue.svg?style=flat)](https://www.ubuntu.com/)
 [![Language: Swift 4.1](https://img.shields.io/badge/Language-Swift%204.1-green.svg?style=flat)](https://developer.apple.com/swift/)
 [![IDE: Xcode 9.3](https://img.shields.io/badge/IDE-Xcode%209.3-orange.svg?style=flat)](https://developer.apple.com/xcode/)
 [![Carthage: compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)
@@ -18,8 +19,184 @@ functionality:
      based on the library [Linenoise-Swift](https://github.com/andybest/linenoise-swift),
      but supporting unicode input, multiple lines, and styled text.
 
+## Command-line arguments
+
+### Basics
+
+CommandLineKit handles command-line arguments with the following protocol:
+
+   1. A new [Flags](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/Flags.swift)
+      object gets created either for the system-provided command-line arguments or for a
+      custom sequence of arguments.
+   2. For every flag, a [Flag](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/Flag.swift)
+       object is being created and registered in the `Flags` object.
+   3. Once all flag objects are declared and registered, the command-line gets parsed. After parsing
+      is complete, the flag objects can be used to access the extracted options and arguments.
+
+CommandLineKit defines different types of
+[Flag](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/Flag.swift)
+subclasses for handling _options_ (i.e. flags without
+parameters) and _arguments_ (i.e. flags with parameters). Arguments are either _singleton arguments_ (i.e. they
+have exactly one value) or they are _repeated arguments_ (i.e. they have many values). Arguments are
+parameterized with a type which defines how to parse values. The framework natively supports _int_,
+_double_, _string_, and _enum_ types, which means that in practice, just using the built-in flag classes
+are almost always sufficient. Nevertheless,
+[the framework is extensible](https://github.com/objecthub/swift-commandlinekit/tree/master/Sources/CommandLineKit)
+and supports arbitrary argument types.
+
+A flag is identified by a _short name_ character and a _long name_ string. At least one of the two needs to be
+defined. For instance, the "help" option could be defined by the short name "h" and the long name "help".
+On the command-line, a user could either use `-h` or `--help` to refer to this option; i.e. short names are
+prefixed with a single dash, long names are prefixed with a double dash.
+
+An argument is a parameterized flag. The parameters follow directly the flag identifier (typically separated by
+a space). For instance, an integer argument with long name "size" could be defined as: `--size 64`. If the
+argument is repeated, then multiple parameters may follow the flag identifier, as in this
+example: `--size 2 4 8 16`. The sequence is terminated by either the end of the command-line arguments,
+another flag, or the terminator "---". All command-line arguments following the terminator are not being parsed
+and are returned in the `parameters` field of the `Flags` object.
+
+### Example
+
+Here is an [example](https://github.com/objecthub/swift-lispkit/blob/master/Sources/LispKitRepl/main.swift)
+from the [LispKit](https://github.com/objecthub/swift-lispkit) project. It uses factory methods (like `flags.string`,
+`flags.int`, `flags.option`, `flags.strings`, etc.) provided by the
+[Flags](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/Flags.swift)
+class to create and register individual flags.
+
+```swift
+// Create a new flags object for the system-provided command-line arguments
+var flags = Flags()
+
+// Define the various flags
+let filePaths  = flags.strings("f", "filepath",
+                               description: "Adds file path in which programs are searched for.")
+let libPaths   = flags.strings("l", "libpath",
+                               description: "Adds file path in which libraries are searched for.")
+let heapSize   = flags.int("h", "heapsize",
+                           description: "Initial capacity of the heap", value: 1000)
+let importLibs = flags.strings("i", "import",
+                               description: "Imports library automatically after startup.")
+let prelude    = flags.string("p", "prelude",
+                              description: "Path to prelude file which gets executed after " +
+                                           "loading all provided libraries.")
+let prompt     = flags.string("r", "prompt",
+                              description: "String used as prompt in REPL.", value: AppInfo.prompt)
+let quiet      = flags.option("q", "quiet",
+                              description: "In quiet mode, optional messages are not printed.")
+let help       = flags.option("h", "help",
+                              description: "Show description of usage and options of this tools.")
+
+// Parse the command-line arguments and return error message if parsing fails
+if let failure = self.parsingFailure() {
+  print(failure)
+  exit(1)
+}
+```
+
+The framework supports printing the supported options via the `Flags.usageDescription` function. For the
+command-line flags as defined above, this function returns the following usage description:
+
+```
+usage: LispKitRepl [<option> ...] [---] [<program> <arg> ...]
+options:
+  -f, --filepath <value> ...
+      Adds file path in which programs are searched for.
+  -l, --libpath <value> ...
+      Adds file path in which libraries are searched for.
+  -h, --heapsize <value>
+      Initial capacity of the heap
+  -i, --import <value> ...
+      Imports library automatically after startup.
+  -p, --prelude <value>
+      Path to prelude file which gets executed after loading all provided libraries.
+  -r, --prompt <value>
+      String used as prompt in REPL.
+  -q, --quiet
+      In quiet mode, optional messages are not printed.
+  -h, --help
+      Show description of usage and options of this tools.
+```
+
+Command-line tools can inspect whether a flag was set via the `Flag.wasSet` field. For flags with
+parameters, the parameters are stored in the `Flag.value` field. The type of this field is dependent on the
+flag type. For repeated flags, an array is used.
+
+
+## Text style and colors
+
+CommandLineKit provides a
+[TextProperties](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/TextProperties.swift)
+structure for bundling a text color, a background color, and a text style in a single object. Text properties can be
+merged with the `with(:)` functions and applied to a string with the `apply(to:)` function.
+
+Individual enumerations for
+[TextColor](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/TextColor.swift),
+[BackgroundColor](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/BackgroundColor.swift), and
+[TextStyle](https://github.com/objecthub/swift-commandlinekit/blob/master/Sources/CommandLineKit/TextStyle.swift)
+define the individual properties.
+
+## Reading strings
+
+CommandLineKit includes a significantly improved version of the "readline" API originally defined by the library
+[Linenoise-Swift](https://github.com/andybest/linenoise-swift). It supports unicode text, multi-line text entry, and
+styled text. It supports all the existing features such as _advanced keyboard support_, _history_,
+_text completion_, and _hints_.
+
+The following code illustrates the usage of the LineReader API:
+
+```
+if let ln = LineReader() {
+  ln.setCompletionCallback { currentBuffer in
+    let completions = [
+      "Hello!",
+      "Hello Google",
+      "Scheme is awesome!"
+    ]
+    return completions.filter { $0.hasPrefix(currentBuffer) }
+  }
+  ln.setHintsCallback { currentBuffer in
+    let hints = [
+      "Foo",
+      "Lorem Ipsum",
+      "Scheme is awesome!"
+    ]
+    let filtered = hints.filter { $0.hasPrefix(currentBuffer) }
+    if let hint = filtered.first {
+      let hintText = String(hint.dropFirst(currentBuffer.count))
+      return (hintText, TextColor.grey.properties)
+    } else {
+      return nil
+    }
+  }
+  print("Type 'exit' to quit")
+  var done = false
+  while !done {
+    do {
+      let output = try ln.readLine(prompt: "> ",
+                                   maxCount: 200,
+                                   strippingNewline: true,
+                                   promptProperties: TextProperties(.green, nil, .bold),
+                                   readProperties: TextProperties(.blue, nil),
+                                   parenProperties: TextProperties(.red, nil, .bold))
+      print("Entered: \(output)")
+      ln.addHistory(output)
+      if output == "exit" {
+        break
+      }
+    } catch LineReaderError.CTRLC {
+      print("\nCaptured CTRL+C. Quitting.")
+      done = true
+    } catch {
+      print(error)
+    }
+  }
+}
+```
+
 ## Requirements
 
-   - XCode 9.3
-   - Swift 4.1
-   - Carthage or Swift Package Manager
+- [Xcode 9.3](https://developer.apple.com/xcode/)
+- [Swift 4.1](https://developer.apple.com/swift/)
+- [Carthage](https://github.com/Carthage/Carthage)
+- [Swift Package Manager](https://swift.org/package-manager/)

Sources/CommandLineKit/Flag.swift

@@ -234,7 +234,7 @@ public class Argument: Flag {
     var i = index
     while i < args.count {
       let arg = args[i]
-      if arg == "---" || arg.hasPrefix("--") {
+      if arg == Flags.terminator || arg.hasPrefix(Flags.longNamePrefix) {
         guard self.repeated else {
           throw FlagError(.missingValue, self)
         }

Sources/CommandLineKit/Flags.swift

@@ -73,9 +73,13 @@ public class Flags {
 
   /// Initializes a flag set using the default command-line arguments.
   public init() {
+    if let toolPath = CommandLine.arguments.first {
+      self.toolName = URL(fileURLWithPath: toolPath).lastPathComponent
+    } else {
+      self.toolName = "<unknown>"
+    }
     var args = CommandLine.arguments
     args.removeFirst()
-    self.toolName = CommandLine.arguments.first ?? "<unknown>"
     self.arguments = args
   }
 
@@ -131,6 +135,33 @@ public class Flags {
     }
   }
 
+  /// Parses the command-line and returns a readable error message if parsing did not succeed.
+  public func parsingFailure() -> String? {
+    do {
+      try self.parse()
+      return nil
+    } catch let error as FlagError {
+      let flagname = error.flag?.longName ?? error.flag?.shortName?.description
+      var message = error.flag == nil ? "error parsing flags: "
+                                      : "error parsing flag `\(flagname!)`: "
+      switch error.kind {
+        case .unknownFlag(let str):
+          message += "unknown flag `\(str)`"
+        case .missingValue:
+          message += "missing value"
+        case .malformedValue(let str):
+          message += "malformed value `\(str)`"
+        case .illegalFlagCombination(let str):
+          message += "illegal flag combination with `\(str)`"
+        case .tooManyValues(let str):
+          message += "too many values from `\(str)`"
+      }
+      return message
+    } catch {
+      return "unknown error while parsing flags"
+    }
+  }
+  
   /// Registers a new custom flag.
   public func register(_ flag: Flag) {
     if let shortName = flag.shortName {
@@ -208,6 +239,8 @@ public class Flags {
     return flag
   }
 
+  /// Returns a human readable usage description text that can be printed for helping users
+  /// better understand the available flags.
   public func usageDescription(usageName: String = "USAGE:",
                                synopsis: String = "[<option> ...] [--] [<arg> ...]",
                                usageStyle: TextProperties = TextProperties.none,
@@ -231,7 +264,7 @@ public class Flags {
         flagStr += " \(argument.paramIdent)"
       }
       buffer += indent + flagStyle.apply(to: flagStr)
-      buffer += "\n\(indent)\(indent)\(flag.helpDescription)\n"
+      buffer += "\n\(indent)\(indent)\(indent)\(flag.helpDescription)\n"
     }
     return buffer
   }

Sources/CommandLineKit/TextColor.swift

@@ -33,7 +33,9 @@
 
 import Foundation
 
-
+///
+/// Enumeration of all supported text colors.
+/// 
 public enum TextColor: Hashable {
   case black
   case maroon

Sources/CommandLineKit/TextProperties.swift

@@ -33,6 +33,11 @@
 
 import Foundation
 
+///
+/// A `TextProperties` struct bundles a text color, a background color and a text style
+/// in one object. Text properties can be merged with the `with(:)` functions and applied to
+/// a string with the `apply(to:)` function.
+///
 public struct TextProperties: Hashable {
   let textColor: TextColor?
   let backgroundColor: BackgroundColor?

Sources/CommandLineKit/TextStyle.swift

@@ -33,6 +33,9 @@
 
 import Foundation
 
+///
+/// Enumeration of all supported text styles.
+/// 
 public enum TextStyle: UInt8, Hashable {
   case `default` = 0
   case bold = 1