Merge pull request #129 from benasher44/basher/improve-argument-help

Improve Argument help message

Sources/Commandant/Argument.swift

@@ -20,17 +20,39 @@ public struct Argument<T> {
 	/// be shown in help messages.
 	public let usage: String
 
-	public init(defaultValue: T? = nil, usage: String) {
+	/// A human-readable string that describes this argument as a paramater shown
+	/// in the list of possible parameters in help messages (e.g. for "paths", the
+	/// user would see <paths…>).
+	public let usageParameter: String?
+
+	public init(defaultValue: T? = nil, usage: String, usageParameter: String? = nil) {
 		self.defaultValue = defaultValue
 		self.usage = usage
+		self.usageParameter = usageParameter
 	}
 
 	fileprivate func invalidUsageError<ClientError>(_ value: String) -> CommandantError<ClientError> {
-		let description = "Invalid value for '\(self)': \(value)"
+		let description = "Invalid value for '\(self.usageParameterDescription)': \(value)"
 		return .usageError(description: description)
 	}
 }
 
+extension Argument {
+	/// A string describing this argument as a parameter in help messages. This falls back
+	/// to `"\(self)"` if `usageParameter` is `nil`
+	internal var usageParameterDescription: String {
+		return self.usageParameter.map { "<\($0)>" } ?? "\(self)"
+	}
+}
+
+extension Argument where T: Sequence {
+	/// A string describing this argument as a parameter in help messages. This falls back
+	/// to `"\(self)"` if `usageParameter` is `nil`
+	internal var usageParameterDescription: String {
+		return self.usageParameter.map { "<\($0)…>" } ?? "\(self)"
+	}
+}
+
 // MARK: - Operators
 
 extension CommandMode {

Sources/Commandant/Errors.swift

@@ -88,7 +88,9 @@ internal func informativeUsageError<T: ArgumentProtocol, ClientError>(_ argument
 	var example = ""
 
 	var valueExample = ""
-	if let defaultValue = argument.defaultValue {
+	if argument.usageParameter != nil {
+		valueExample = argument.usageParameterDescription
+	} else if let defaultValue = argument.defaultValue {
 		valueExample = "\(defaultValue)"
 	}
 
@@ -106,7 +108,9 @@ internal func informativeUsageError<T: ArgumentProtocol, ClientError>(_ argument
 	var example = ""
 
 	var valueExample = ""
-	if let defaultValue = argument.defaultValue {
+	if argument.usageParameter != nil {
+		valueExample = argument.usageParameterDescription
+	} else if let defaultValue = argument.defaultValue {
 		valueExample = "\(defaultValue)"
 	}