diff --git a/CHANGELOG.md b/CHANGELOG.md index 1be2bcecc..29c5ac34b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ * Update Yams to 3.0.0. [Keith Smiley](https://github.com/keith) +* Extract all supported delimiters from document XML. + [Eneko Alonso](https://github.com/eneko) * Add `SwiftDeclarationAttributeKind` values introduced in Swift 5.2. [JP Simard](https://github.com/jpsim) diff --git a/Source/SourceKittenFramework/File.swift b/Source/SourceKittenFramework/File.swift index 0d6525679..758763ff4 100644 --- a/Source/SourceKittenFramework/File.swift +++ b/Source/SourceKittenFramework/File.swift @@ -459,6 +459,10 @@ public func parseFullXMLDocs(_ xmlDocs: String) -> [String: SourceKitRepresentab .replacingOccurrences(of: "", with: "") .replacingOccurrences(of: "", with: "`") .replacingOccurrences(of: "", with: "`") + .replacingOccurrences(of: "", with: "_") + .replacingOccurrences(of: "", with: "_") +// .replacingOccurrences(of: "", with: "**") +// .replacingOccurrences(of: "", with: "**") return SWXMLHash.parse(cleanXMLDocs).children.first.map { rootXML in var docs = [String: SourceKitRepresentable]() docs[SwiftDocKey.docType.rawValue] = rootXML.element?.name @@ -484,12 +488,40 @@ public func parseFullXMLDocs(_ xmlDocs: String) -> [String: SourceKitRepresentab } docs[SwiftDocKey.docParameters.rawValue] = parameters.map(docParameters(from:)) as [SourceKitRepresentable] } + docs[SwiftDocKey.docAbstract.rawValue] = commentPartsXML["Abstract"].childrenAsArray() docs[SwiftDocKey.docDiscussion.rawValue] = commentPartsXML["Discussion"].childrenAsArray() docs[SwiftDocKey.docResultDiscussion.rawValue] = commentPartsXML["ResultDiscussion"].childrenAsArray() + docs[SwiftDocKey.docThrowsDiscussion.rawValue] = commentPartsXML["ThrowsDiscussion"].childrenAsArray() + populateDelimiters(docs: &docs, discussion: commentPartsXML["Discussion"]) return docs } } +/// Delimiters extracted from discussion (supported by Xcode) +/// - see: https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/MarkupFunctionality.html +func populateDelimiters(docs: inout [String: SourceKitRepresentable], discussion: XMLIndexer) { + docs[SwiftDocKey.docAttention.rawValue] = discussion["Attention"].childrenAsArray() + docs[SwiftDocKey.docAuthor.rawValue] = discussion["Author"].childrenAsArray() + docs[SwiftDocKey.docAuthors.rawValue] = discussion["Authors"].childrenAsArray() + docs[SwiftDocKey.docBug.rawValue] = discussion["Bug"].childrenAsArray() + docs[SwiftDocKey.docComplexity.rawValue] = discussion["Complexity"].childrenAsArray() + docs[SwiftDocKey.docCopyright.rawValue] = discussion["Copyright"].childrenAsArray() + docs[SwiftDocKey.docDate.rawValue] = discussion["Date"].childrenAsArray() + docs[SwiftDocKey.docExperiment.rawValue] = discussion["Experiment"].childrenAsArray() + docs[SwiftDocKey.docImportant.rawValue] = discussion["Important"].childrenAsArray() + docs[SwiftDocKey.docInvariant.rawValue] = discussion["Invariant"].childrenAsArray() + docs[SwiftDocKey.docNote.rawValue] = discussion["Note"].childrenAsArray() + docs[SwiftDocKey.docPostcondition.rawValue] = discussion["Postcondition"].childrenAsArray() + docs[SwiftDocKey.docPrecondition.rawValue] = discussion["Precondition"].childrenAsArray() + docs[SwiftDocKey.docRemark.rawValue] = discussion["Remark"].childrenAsArray() + docs[SwiftDocKey.docRequires.rawValue] = discussion["Requires"].childrenAsArray() + docs[SwiftDocKey.docSeeAlso.rawValue] = discussion["See"].childrenAsArray() + docs[SwiftDocKey.docSince.rawValue] = discussion["Since"].childrenAsArray() + docs[SwiftDocKey.docToDo.rawValue] = discussion["TODO"].childrenAsArray() + docs[SwiftDocKey.docVersion.rawValue] = discussion["Version"].childrenAsArray() + docs[SwiftDocKey.docWarning.rawValue] = discussion["Warning"].childrenAsArray() +} + private extension XMLIndexer { /** Returns an `[SourceKitRepresentable]` of `[String: SourceKitRepresentable]` items from `indexer` children, if any. diff --git a/Source/SourceKittenFramework/SwiftDocKey.swift b/Source/SourceKittenFramework/SwiftDocKey.swift index 1e9e8c54f..40ca09f58 100644 --- a/Source/SourceKittenFramework/SwiftDocKey.swift +++ b/Source/SourceKittenFramework/SwiftDocKey.swift @@ -53,6 +53,8 @@ public enum SwiftDocKey: String { case documentationComment = "key.doc.comment" /// Declaration of documented token (String). case docDeclaration = "key.doc.declaration" + /// Abstract of documented token + case docAbstract = "key.doc.abstract" /// Discussion documentation of documented token ([SourceKitRepresentable]). case docDiscussion = "key.doc.discussion" /// File where the documented token is located (String). @@ -65,6 +67,8 @@ public enum SwiftDocKey: String { case docParameters = "key.doc.parameters" /// Parsed declaration (String). case docResultDiscussion = "key.doc.result_discussion" + /// Throws delimiter from documented token + case docThrowsDiscussion = "key.doc.throws_discussion" /// Parsed scope start (Int64). case docType = "key.doc.type" /// Parsed scope start end (Int64). @@ -90,6 +94,49 @@ public enum SwiftDocKey: String { /// Annotations ([String]). case annotations = "key.annotations" + // MARK: Delimiters extracted from discussion + + /// Content of `- attention:` delimiter + case docAttention = "key.doc.attention" + /// Content of `- author:` delimiter + case docAuthor = "key.doc.author" + /// Content of `- authors:` delimiter + case docAuthors = "key.doc.authors" + /// Content of `- bug:` delimiter + case docBug = "key.doc.bug" + /// Content of `- complexity:` delimiter + case docComplexity = "key.doc.complexity" + /// Content of `- copyright:` delimiter + case docCopyright = "key.doc.copyright" + /// Content of `- date:` delimiter + case docDate = "key.doc.date" + /// Content of `- experiment:` delimiter + case docExperiment = "key.doc.experiment" + /// Content of `- important:` delimiter + case docImportant = "key.doc.important" + /// Content of `- invariant:` delimiter + case docInvariant = "key.doc.invariant" + /// Content of `- note:` delimiter + case docNote = "key.doc.note" + /// Content of `- postcondition:` delimiter + case docPostcondition = "key.doc.postcondition" + /// Content of `- precondition:` delimiter + case docPrecondition = "key.doc.precondition" + /// Content of `- remark:` delimiter + case docRemark = "key.doc.remark" + /// Content of `- requires:` delimiter + case docRequires = "key.doc.requires" + /// Content of `- see:` and `- seealso:` delimiters + case docSeeAlso = "key.doc.see_also" + /// Content of `- since:` delimiter + case docSince = "key.doc.since" + /// Content of `- toDo:` delimiter + case docToDo = "key.doc.to_do" + /// Content of `- version:` delimiter + case docVersion = "key.doc.version" + /// Content of `- warning:` delimiter + case docWarning = "key.doc.warning" + // MARK: Typed SwiftDocKey Getters /** diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.0.json b/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.0.json index 405846175..c516a4275 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.0.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.0.json @@ -53,6 +53,11 @@ ], "key.bodylength" : 2222, "key.bodyoffset" : 248, + "key.doc.abstract" : [ + { + "Para" : "šŸš² A two-wheeled, human-powered mode of transportation." + } + ], "key.doc.column" : 14, "key.doc.comment" : "šŸš² A two-wheeled, human-powered mode of transportation.", "key.doc.declaration" : "public class Bicycle", @@ -88,6 +93,11 @@ ], "key.bodylength" : 49, "key.bodyoffset" : 492, + "key.doc.abstract" : [ + { + "Para" : "Frame and construction style." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Frame and construction style.\n\n- Road: For streets or trails.\n- Touring: For long journeys.\n- Cruiser: For casual trips around town.\n- Hybrid: For general-purpose transportation.", "key.doc.declaration" : "public enum Bicycle.Bicycle.Style", @@ -213,6 +223,11 @@ ], "key.bodylength" : 60, "key.bodyoffset" : 733, + "key.doc.abstract" : [ + { + "Para" : "Mechanism for converting pedal power into motion." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Mechanism for converting pedal power into motion.\n\n- Fixed: A single, fixed gear.\n- Freewheel: A variable-speed, disengageable gear.", "key.doc.declaration" : "public enum Bicycle.Bicycle.Gearing", @@ -304,6 +319,11 @@ "key.annotated_decl" : "enum Bicycle<\/Type>.Handlebar<\/Declaration>", "key.bodylength" : 47, "key.bodyoffset" : 1009, + "key.doc.abstract" : [ + { + "Para" : "Hardware used for steering." + } + ], "key.doc.column" : 10, "key.doc.comment" : "Hardware used for steering.\n\n- Riser: A casual handlebar.\n- CafĆ©: An upright handlebar.\n- Drop: A classic handlebar.\n- Bullhorn: A powerful handlebar.", "key.doc.declaration" : "enum Bicycle.Bicycle.Handlebar", @@ -420,6 +440,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let style: Style<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The style of the bicycle." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The style of the bicycle.", "key.doc.declaration" : "let style: Style", @@ -448,6 +473,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let gearing: Gearing<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The gearing of the bicycle." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The gearing of the bicycle.", "key.doc.declaration" : "let gearing: Gearing", @@ -476,6 +506,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let handlebar: Handlebar<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The handlebar of the bicycle." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The handlebar of the bicycle.", "key.doc.declaration" : "let handlebar: Handlebar", @@ -504,6 +539,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let frameSize: Int<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The size of the frame, in centimeters." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The size of the frame, in centimeters.", "key.doc.declaration" : "let frameSize: Int", @@ -539,6 +579,11 @@ "key.offset" : 1374 } ], + "key.doc.abstract" : [ + { + "Para" : "The number of trips travelled by the bicycle." + } + ], "key.doc.column" : 22, "key.doc.comment" : "The number of trips travelled by the bicycle.", "key.doc.declaration" : "private(set) var numberOfTrips: Int {\n get\n }", @@ -575,6 +620,11 @@ "key.offset" : 1479 } ], + "key.doc.abstract" : [ + { + "Para" : "The total distance travelled by the bicycle, in meters." + } + ], "key.doc.column" : 22, "key.doc.comment" : "The total distance travelled by the bicycle, in meters.", "key.doc.declaration" : "private(set) var distanceTravelled: Double {\n get\n }", @@ -606,6 +656,11 @@ "key.annotated_decl" : "init(style: Style<\/Type>, gearing: Gearing<\/Type>, handlebar: Handlebar<\/Type>, frameSize centimeters: Int<\/Type>)<\/Declaration>", "key.bodylength" : 192, "key.bodyoffset" : 2010, + "key.doc.abstract" : [ + { + "Para" : "Initializes a new bicycle with the provided parts and specifications." + } + ], "key.doc.column" : 5, "key.doc.comment" : "Initializes a new bicycle with the provided parts and specifications.\n\n- parameter style: The style of the bicycle\n- parameter gearing: The gearing of the bicycle\n- parameter handlebar: The handlebar of the bicycle\n- parameter centimeters: The frame size of the bicycle, in centimeters\n\n- returns: A beautiful, brand-new, custom built just for you.", "key.doc.declaration" : "init(style: Style, gearing: Gearing, handlebar: Handlebar, frameSize centimeters: Int)", @@ -678,6 +733,11 @@ "key.annotated_decl" : "func travel(distance meters: Double<\/Type>)<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 2356, + "key.doc.abstract" : [ + { + "Para" : "Take a bike out for a spin." + } + ], "key.doc.column" : 10, "key.doc.comment" : "Take a bike out for a spin.\n\n- parameter meters: The distance to travel in meters.", "key.doc.declaration" : "func travel(distance meters: Double)", diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.1.json b/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.1.json index 90d47f8f1..7771b73ee 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.1.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/Bicycle@swift-5.1.json @@ -53,6 +53,11 @@ ], "key.bodylength" : 2222, "key.bodyoffset" : 248, + "key.doc.abstract" : [ + { + "Para" : "šŸš² A two-wheeled, human-powered mode of transportation." + } + ], "key.doc.column" : 14, "key.doc.comment" : "šŸš² A two-wheeled, human-powered mode of transportation.", "key.doc.declaration" : "public class Bicycle", @@ -88,6 +93,11 @@ ], "key.bodylength" : 49, "key.bodyoffset" : 492, + "key.doc.abstract" : [ + { + "Para" : "Frame and construction style." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Frame and construction style.\n\n- Road: For streets or trails.\n- Touring: For long journeys.\n- Cruiser: For casual trips around town.\n- Hybrid: For general-purpose transportation.", "key.doc.declaration" : "public enum Bicycle.Bicycle.Style", @@ -213,6 +223,11 @@ ], "key.bodylength" : 60, "key.bodyoffset" : 733, + "key.doc.abstract" : [ + { + "Para" : "Mechanism for converting pedal power into motion." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Mechanism for converting pedal power into motion.\n\n- Fixed: A single, fixed gear.\n- Freewheel: A variable-speed, disengageable gear.", "key.doc.declaration" : "public enum Bicycle.Bicycle.Gearing", @@ -304,6 +319,11 @@ "key.annotated_decl" : "enum Bicycle<\/Type>.Handlebar<\/Declaration>", "key.bodylength" : 47, "key.bodyoffset" : 1009, + "key.doc.abstract" : [ + { + "Para" : "Hardware used for steering." + } + ], "key.doc.column" : 10, "key.doc.comment" : "Hardware used for steering.\n\n- Riser: A casual handlebar.\n- CafĆ©: An upright handlebar.\n- Drop: A classic handlebar.\n- Bullhorn: A powerful handlebar.", "key.doc.declaration" : "enum Bicycle.Bicycle.Handlebar", @@ -420,6 +440,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let style: Style<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The style of the bicycle." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The style of the bicycle.", "key.doc.declaration" : "let style: Style", @@ -448,6 +473,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let gearing: Gearing<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The gearing of the bicycle." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The gearing of the bicycle.", "key.doc.declaration" : "let gearing: Gearing", @@ -476,6 +506,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let handlebar: Handlebar<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The handlebar of the bicycle." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The handlebar of the bicycle.", "key.doc.declaration" : "let handlebar: Handlebar", @@ -504,6 +539,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "let frameSize: Int<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The size of the frame, in centimeters." + } + ], "key.doc.column" : 9, "key.doc.comment" : "The size of the frame, in centimeters.", "key.doc.declaration" : "let frameSize: Int", @@ -539,6 +579,11 @@ "key.offset" : 1374 } ], + "key.doc.abstract" : [ + { + "Para" : "The number of trips travelled by the bicycle." + } + ], "key.doc.column" : 22, "key.doc.comment" : "The number of trips travelled by the bicycle.", "key.doc.declaration" : "private(set) var numberOfTrips: Int {\n get\n }", @@ -575,6 +620,11 @@ "key.offset" : 1479 } ], + "key.doc.abstract" : [ + { + "Para" : "The total distance travelled by the bicycle, in meters." + } + ], "key.doc.column" : 22, "key.doc.comment" : "The total distance travelled by the bicycle, in meters.", "key.doc.declaration" : "private(set) var distanceTravelled: Double {\n get\n }", @@ -606,6 +656,11 @@ "key.annotated_decl" : "init(style: Style<\/Type>, gearing: Gearing<\/Type>, handlebar: Handlebar<\/Type>, frameSize centimeters: Int<\/Type>)<\/Declaration>", "key.bodylength" : 192, "key.bodyoffset" : 2010, + "key.doc.abstract" : [ + { + "Para" : "Initializes a new bicycle with the provided parts and specifications." + } + ], "key.doc.column" : 5, "key.doc.comment" : "Initializes a new bicycle with the provided parts and specifications.\n\n- parameter style: The style of the bicycle\n- parameter gearing: The gearing of the bicycle\n- parameter handlebar: The handlebar of the bicycle\n- parameter centimeters: The frame size of the bicycle, in centimeters\n\n- returns: A beautiful, brand-new, custom built just for you.", "key.doc.declaration" : "init(style: Style, gearing: Gearing, handlebar: Handlebar, frameSize centimeters: Int)", @@ -678,6 +733,11 @@ "key.annotated_decl" : "func travel(distance meters: Double<\/Type>)<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 2356, + "key.doc.abstract" : [ + { + "Para" : "Take a bike out for a spin." + } + ], "key.doc.column" : 10, "key.doc.comment" : "Take a bike out for a spin.\n\n- parameter meters: The distance to travel in meters.", "key.doc.declaration" : "func travel(distance meters: Double)", diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.0.json b/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.0.json index 51acbd176..91fb365d6 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.0.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.0.json @@ -16,6 +16,11 @@ ], "key.bodylength" : 1029, "key.bodyoffset" : 231, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an argument that can be provided on the command line.", "key.doc.declaration" : "public struct Argument", @@ -65,6 +70,11 @@ "key.offset" : 443 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this argument. This is the value that will be used if the argument is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this argument. This is the value that will be used\nif the argument is never explicitly specified on the command line.\n\nIf this is nil, this argument is always required.", "key.doc.declaration" : "public let defaultValue: T?", @@ -105,6 +115,11 @@ "key.offset" : 585 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this argument. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this argument. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -140,6 +155,11 @@ "key.offset" : 804 } ], + "key.doc.abstract" : [ + { + "Para" : "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 )." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string that describes this argument as a paramater shown\nin the list of possible parameters in help messages (e.g. for \"paths\", the\nuser would see ).", "key.doc.declaration" : "public let usageParameter: String?", @@ -268,6 +288,11 @@ "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 251, "key.bodyoffset" : 1283, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -299,6 +324,11 @@ ], "key.bodylength" : 62, "key.bodyoffset" : 1470, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -339,6 +369,11 @@ "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 254, "key.bodyoffset" : 1575, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -370,6 +405,11 @@ ], "key.bodylength" : 65, "key.bodyoffset" : 1762, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -418,6 +458,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 1979, "key.bodyoffset" : 1877, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -449,6 +494,11 @@ ], "key.bodylength" : 518, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument) -> Result> where T : ArgumentProtocol", @@ -562,6 +612,11 @@ ], "key.bodylength" : 778, "key.bodyoffset" : 3076, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument list in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument list in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument<[T]>) -> Result<[T], CommandantError> where T : ArgumentProtocol", @@ -688,6 +743,11 @@ ], "key.bodylength" : 296, "key.bodyoffset" : 266, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Represents an argument passed on the command line.", "key.doc.declaration" : "private enum RawArgument : Equatable", @@ -732,6 +792,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case key(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A key corresponding to an option (e.g., `verbose` for `--verbose`)." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A key corresponding to an option (e.g., `verbose` for `--verbose`).", "key.doc.declaration" : "", @@ -769,6 +834,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case value(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A value, either associated with an option or passed as a positional argument." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A value, either associated with an option or passed as a positional\nargument.", "key.doc.declaration" : "", @@ -806,6 +876,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case flag(OrderedSet<\/Type><Character<\/Type>>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "One or more flag arguments (e.g ā€˜rā€™ and ā€˜fā€™ for `-rf`)" + } + ], "key.doc.column" : 7, "key.doc.comment" : "One or more flag arguments (e.g 'r' and 'f' for `-rf`)", "key.doc.declaration" : "", @@ -843,6 +918,11 @@ "key.annotated_decl" : "private enum RawArgument : Equatable<\/Type><\/Declaration>", "key.bodylength" : 214, "key.bodyoffset" : 613, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "private enum RawArgument : Equatable", "key.doc.file" : "Sources\/Commandant\/ArgumentParser.swift", @@ -886,6 +966,11 @@ ], "key.bodylength" : 173, "key.bodyoffset" : 652, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -943,6 +1028,11 @@ ], "key.bodylength" : 3711, "key.bodyoffset" : 924, + "key.doc.abstract" : [ + { + "Para" : "Destructively parses a list of command-line arguments." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Destructively parses a list of command-line arguments.", "key.doc.declaration" : "public final class ArgumentParser", @@ -976,6 +1066,11 @@ "key.offset" : 991 } ], + "key.doc.abstract" : [ + { + "Para" : "The remaining arguments to be extracted, in their raw form." + } + ], "key.doc.column" : 14, "key.doc.comment" : "The remaining arguments to be extracted, in their raw form.", "key.doc.declaration" : "private var rawArguments: [Commandant.RawArgument]", @@ -1014,6 +1109,11 @@ ], "key.bodylength" : 741, "key.bodyoffset" : 1151, + "key.doc.abstract" : [ + { + "Para" : "Initializes the generator from a simple list of command-line arguments." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the generator from a simple list of command-line arguments.", "key.doc.declaration" : "public init(_ arguments: [String])", @@ -1087,6 +1187,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 1978, + "key.doc.abstract" : [ + { + "Para" : "Returns the remaining arguments." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Returns the remaining arguments.", "key.doc.declaration" : "internal var remainingArguments: [String]? { get }", @@ -1124,6 +1229,11 @@ ], "key.bodylength" : 281, "key.bodyoffset" : 2323, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was enabled or disabled, or nil if it was not given at all." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was enabled or disabled, or nil if it\nwas not given at all.\n\nIf the key is found, it is then removed from the list of arguments\nremaining to be parsed.", "key.doc.declaration" : "internal func consumeBoolean(forKey key: String) -> Bool?", @@ -1207,6 +1317,11 @@ ], "key.bodylength" : 503, "key.bodyoffset" : 2999, + "key.doc.abstract" : [ + { + "Para" : "Returns the value associated with the given flag, or nil if the flag was not specified. If the key is presented, but no value was given, an error is returned." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the value associated with the given flag, or nil if the flag was\nnot specified. If the key is presented, but no value was given, an error\nis returned.\n\nIf a value is found, the key and the value are both removed from the\nlist of arguments remaining to be parsed.", "key.doc.declaration" : "internal func consumeValue(forKey key: String) -> Result>", @@ -1307,6 +1422,11 @@ ], "key.bodylength" : 164, "key.bodyoffset" : 3688, + "key.doc.abstract" : [ + { + "Para" : "Returns the next positional argument that hasnā€™t yet been returned, or nil if there are no more positional arguments." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the next positional argument that hasn't yet been returned, or\nnil if there are no more positional arguments.", "key.doc.declaration" : "internal func consumePositionalArgument() -> String?", @@ -1347,6 +1467,11 @@ ], "key.bodylength" : 143, "key.bodyoffset" : 4007, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consume(key: String) -> Bool", @@ -1403,6 +1528,11 @@ ], "key.bodylength" : 316, "key.bodyoffset" : 4317, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given flag was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given flag was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consumeBoolean(flag: Character) -> Bool", @@ -1461,6 +1591,11 @@ ], "key.bodylength" : 189, "key.bodyoffset" : 253, + "key.doc.abstract" : [ + { + "Para" : "Represents a value that can be converted from a command-line argument." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a value that can be converted from a command-line argument.", "key.doc.declaration" : "public protocol ArgumentProtocol", @@ -1489,6 +1624,11 @@ "key.annotated_decl" : "static var name: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 322, + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable name for this type.", "key.doc.declaration" : "static var name: String { get }", @@ -1517,6 +1657,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "static func from(string: String<\/Type>) -> `Self`?<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Attempts to parse a value from the given command-line argument.", "key.doc.declaration" : "static func from(string: String) -> `Self`?", @@ -1555,6 +1700,11 @@ "key.annotated_decl" : "struct Int : FixedWidthInteger<\/Type>, SignedInteger<\/Type><\/Declaration>", "key.bodylength" : 113, "key.bodyoffset" : 478, + "key.doc.abstract" : [ + { + "Para" : "A signed integer value type." + } + ], "key.doc.declaration" : "struct Int : FixedWidthInteger, SignedInteger", "key.doc.discussion" : [ { @@ -1600,6 +1750,11 @@ "key.offset" : 480 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.file" : "Sources\/Commandant\/ArgumentProtocol.swift", @@ -1640,6 +1795,11 @@ ], "key.bodylength" : 23, "key.bodyoffset" : 566, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func from(string: String) -> `Self`?", "key.doc.file" : "Sources\/Commandant\/ArgumentProtocol.swift", @@ -1681,19 +1841,24 @@ "key.annotated_decl" : "struct String<\/Declaration>", "key.bodylength" : 110, "key.bodyoffset" : 630, + "key.doc.abstract" : [ + { + "Para" : "A Unicode string value that is a collection of characters." + } + ], "key.doc.declaration" : "struct String", "key.doc.discussion" : [ { "Para" : "A string is a series of characters, such as `\"Swift\"`, that forms a collection. Strings in Swift are Unicode correct and locale insensitive, and are designed to be efficient. The `String` type bridges with the Objective-C class `NSString` and offers interoperability with C functions that works with strings." }, { - "Para" : "You can create new strings using string literals or string interpolations. A is a series of characters enclosed in quotes." + "Para" : "You can create new strings using string literals or string interpolations. A _string literal_ is a series of characters enclosed in quotes." }, { "CodeListing" : "" }, { - "Para" : " are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." + "Para" : "_String interpolations_ are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." }, { "CodeListing" : "" @@ -1729,7 +1894,7 @@ "Para" : "Basic string operations are not sensitive to locale settings, ensuring that string comparisons and other operations always have a single, stable result, allowing strings to be used as keys in `Dictionary` instances and for other purposes." }, { - "Para" : "A string is a collection of , which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." + "Para" : "A string is a collection of _extended grapheme clusters_, which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." }, { "Para" : "For example, to retrieve the first word of a longer string, you can search for a space and then create a substring from a prefix of the string up to that point:" @@ -1795,7 +1960,7 @@ "Para" : "When you need to know the length of a string, you must first consider what youā€™ll use the length for. Are you measuring the number of characters that will be displayed on the screen, or are you measuring the amount of storage needed for the string in a particular encoding? A single string can have greatly differing lengths when measured by its different views." }, { - "Para" : "For example, an ASCII character like the capital letter is represented by a single element in each of its four views. The Unicode scalar value of is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." + "Para" : "For example, an ASCII character like the capital letter _A_ is represented by a single element in each of its four views. The Unicode scalar value of _A_ is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." }, { "CodeListing" : "" @@ -1840,13 +2005,13 @@ "CodeListing" : "" }, { - "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O() time and space." + "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O(_n_) time and space." }, { "Para" : "When a stringā€™s contiguous storage fills up, a new buffer must be allocated and data must be moved to the new storage. String buffers use an exponential growth strategy that makes appending to a string a constant time operation when averaged over many append operations." }, { - "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O() time and space, where is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." + "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O(_n_) time and space, where _n_ is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." }, { "Para" : "For more information about the Unicode terms used in this discussion, see the . In particular, this discussion mentions , , and ." @@ -1891,6 +2056,11 @@ "key.offset" : 632 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.file" : "Sources\/Commandant\/ArgumentProtocol.swift", @@ -1931,6 +2101,11 @@ ], "key.bodylength" : 18, "key.bodyoffset" : 720, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func from(string: String) -> `Self`?", "key.doc.file" : "Sources\/Commandant\/ArgumentProtocol.swift", @@ -1972,6 +2147,11 @@ "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 826, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -1990,7 +2170,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2083,6 +2263,11 @@ "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 1027, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -2101,7 +2286,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2209,6 +2394,11 @@ ], "key.bodylength" : 483, "key.bodyoffset" : 280, + "key.doc.abstract" : [ + { + "Para" : "Represents a subcommand that can be executed with its own set of arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a subcommand that can be executed with its own set of arguments.", "key.doc.declaration" : "public protocol CommandProtocol", @@ -2235,6 +2425,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "associatedtype Options : OptionsProtocol<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.comment" : "The command's options type.", "key.doc.declaration" : "associatedtype Options : OptionsProtocol", @@ -2283,6 +2478,11 @@ "key.annotated_decl" : "var verb: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 532, + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.comment" : "The action that users should specify to use this subcommand (e.g.,\n`help`).", "key.doc.declaration" : "var verb: String { get }", @@ -2313,6 +2513,11 @@ "key.annotated_decl" : "var function: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 648, + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.comment" : "A human-readable, high-level description of what this command is used\nfor.", "key.doc.declaration" : "var function: String { get }", @@ -2341,6 +2546,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "func run(_ options: Options<\/Type>) -> Result<\/Type><(), ClientError<\/Type>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Runs this subcommand with the given options.", "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", @@ -2386,6 +2596,11 @@ ], "key.bodylength" : 957, "key.bodyoffset" : 843, + "key.doc.abstract" : [ + { + "Para" : "A type-erased command." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A type-erased command.", "key.doc.declaration" : "public struct CommandWrapper where ClientError : Error", @@ -2549,6 +2764,11 @@ ], "key.bodylength" : 633, "key.bodyoffset" : 1165, + "key.doc.abstract" : [ + { + "Para" : "Creates a command that wraps another." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Creates a command that wraps another.", "key.doc.declaration" : "fileprivate init(_ command: C) where ClientError == C.ClientError, C : CommandProtocol", @@ -2622,6 +2842,11 @@ ], "key.bodylength" : 216, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Describes the \"mode\" in which a command should run.", "key.doc.declaration" : "public enum CommandMode", @@ -2654,6 +2879,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case arguments(ArgumentParser<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Options should be parsed from the given command-line arguments." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Options should be parsed from the given command-line arguments.", "key.doc.declaration" : "", @@ -2691,6 +2921,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usage<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Each option should record its usage information in an error, for presentation to the user." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Each option should record its usage information in an error, for\npresentation to the user.", "key.doc.declaration" : "", @@ -2740,6 +2975,11 @@ ], "key.bodylength" : 1204, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Maintains the list of commands available to run.", "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", @@ -2829,6 +3069,11 @@ ], "key.bodylength" : 69, "key.bodyoffset" : 2369, + "key.doc.abstract" : [ + { + "Para" : "All available commands." + } + ], "key.doc.column" : 13, "key.doc.comment" : "All available commands.", "key.doc.declaration" : "public var commands: [CommandWrapper] { get }", @@ -2898,6 +3143,11 @@ ], "key.bodylength" : 106, "key.bodyoffset" : 2775, + "key.doc.abstract" : [ + { + "Para" : "Registers the given commands, making those available to run." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Registers the given commands, making those available to run.\n\nIf another commands were already registered with the same `verb`s, those\nwill be overwritten.", "key.doc.declaration" : "public func register(_ commands: C...) -> CommandRegistry where ClientError == C.ClientError, C : CommandProtocol", @@ -2971,6 +3221,11 @@ ], "key.bodylength" : 54, "key.bodyoffset" : 3164, + "key.doc.abstract" : [ + { + "Para" : "Runs the command corresponding to the given verb, passing it the given arguments." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Runs the command corresponding to the given verb, passing it the given\narguments.\n\nReturns the results of the execution, or nil if no such command exists.", "key.doc.declaration" : "public func run(command verb: String, arguments: [String]) -> Result<(), CommandantError>?", @@ -3016,6 +3271,11 @@ ], "key.bodylength" : 32, "key.bodyoffset" : 3382, + "key.doc.abstract" : [ + { + "Para" : "Returns the command matching the given verb, or nil if no such command is registered." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Returns the command matching the given verb, or nil if no such command\nis registered.", "key.doc.declaration" : "public subscript(verb: String) -> CommandWrapper? { get }", @@ -3054,6 +3314,11 @@ "key.annotated_decl" : "public final class CommandRegistry<ClientError> where ClientError : Error<\/Type><\/Declaration>", "key.bodylength" : 4074, "key.bodyoffset" : 3446, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -3085,6 +3350,11 @@ ], "key.bodylength" : 97, "key.bodyoffset" : 4332, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3144,6 +3414,11 @@ ], "key.bodylength" : 945, "key.bodyoffset" : 5328, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing `arguments` and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing `arguments`\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(arguments: [String], defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3253,6 +3528,11 @@ ], "key.bodylength" : 933, "key.bodyoffset" : 6585, + "key.doc.abstract" : [ + { + "Para" : "Finds and executes a subcommand which exists in your $PATH. The executable name must be in the form of `executable-verb`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Finds and executes a subcommand which exists in your $PATH. The executable\nname must be in the form of `executable-verb`.\n\n- Returns: The exit status of found subcommand or nil.", "key.doc.declaration" : "private func executeSubcommandIfExists(_ executableName: String, verb: String, arguments: [String]) -> Int32?", @@ -3383,6 +3663,11 @@ ], "key.bodylength" : 157, "key.bodyoffset" : 372, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Possible errors that can originate from Commandant.\n\n`ClientError` should be the type of error (if any) that can occur when\nrunning commands.", "key.doc.declaration" : "public enum CommandantError : Error", @@ -3449,6 +3734,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usageError(description: String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An option was used incorrectly." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An option was used incorrectly.", "key.doc.declaration" : "", @@ -3486,6 +3776,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case commandError(ClientError<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An error occurred while running a command." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An error occurred while running a command.", "key.doc.declaration" : "", @@ -3523,6 +3818,11 @@ "key.annotated_decl" : "public enum CommandantError<ClientError> : Error<\/Type><\/Declaration>", "key.bodylength" : 187, "key.bodyoffset" : 584, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandantError : Error", "key.doc.discussion" : [ @@ -3571,6 +3871,11 @@ ], "key.bodylength" : 151, "key.bodyoffset" : 618, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -3623,6 +3928,11 @@ ], "key.bodylength" : 105, "key.bodyoffset" : 992, + "key.doc.abstract" : [ + { + "Para" : "Constructs an `InvalidArgument` error that indicates a missing value for the argument by the given name." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an `InvalidArgument` error that indicates a missing value for\nthe argument by the given name.", "key.doc.declaration" : "internal func missingArgumentError(_ argumentName: String) -> CommandantError", @@ -3696,6 +4006,11 @@ ], "key.bodylength" : 179, "key.bodyoffset" : 1339, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error by combining the example of key (and value, if applicable) with the usage description." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error by combining the example of key (and value, if applicable)\nwith the usage description.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, usage: String) -> CommandantError", @@ -3798,6 +4113,11 @@ ], "key.bodylength" : 265, "key.bodyoffset" : 1813, + "key.doc.abstract" : [ + { + "Para" : "Combines the text of the two errors, if theyā€™re both `UsageError`s. Otherwise, uses whichever one is not (biased toward the left)." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Combines the text of the two errors, if they're both `UsageError`s.\nOtherwise, uses whichever one is not (biased toward the left).", "key.doc.declaration" : "internal func combineUsageErrors(_ lhs: CommandantError, _ rhs: CommandantError) -> CommandantError", @@ -3854,6 +4174,11 @@ ], "key.bodylength" : 96, "key.bodyoffset" : 2260, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that indicates unrecognized arguments remains." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that indicates unrecognized arguments remains.", "key.doc.declaration" : "internal func unrecognizedArgumentsError(_ options: [String]) -> CommandantError", @@ -3918,6 +4243,11 @@ ], "key.bodylength" : 192, "key.bodyoffset" : 2631, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument, with the given example of value usage if applicable." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument, with the given\nexample of value usage if applicable.", "key.doc.declaration" : "internal func informativeUsageError(_ valueExample: String, argument: Argument) -> CommandantError", @@ -4020,6 +4350,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3018, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument) -> CommandantError where T : ArgumentProtocol", @@ -4168,6 +4503,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3598, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument list." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument list.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument<[T]>) -> CommandantError where T : ArgumentProtocol", @@ -4324,6 +4664,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 4257, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option, with the given example of key (and value, if applicable) usage." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option, with the given\nexample of key (and value, if applicable) usage.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, option: Option) -> CommandantError", @@ -4426,6 +4771,11 @@ ], "key.bodylength" : 89, "key.bodyoffset" : 4522, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : ArgumentProtocol", @@ -4540,6 +4890,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 4801, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : ArgumentProtocol", @@ -4654,6 +5009,11 @@ ], "key.bodylength" : 91, "key.bodyoffset" : 5070, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]>) -> CommandantError where T : ArgumentProtocol", @@ -4768,6 +5128,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 5353, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]?>) -> CommandantError where T : ArgumentProtocol", @@ -4882,6 +5247,11 @@ ], "key.bodylength" : 121, "key.bodyoffset" : 5616, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the given boolean option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the given boolean option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError", @@ -4992,6 +5362,11 @@ ], "key.bodylength" : 1127, "key.bodyoffset" : 601, + "key.doc.abstract" : [ + { + "Para" : "A basic implementation of a `help` command, using information available in a `CommandRegistry`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A basic implementation of a `help` command, using information available in a\n`CommandRegistry`.\n\nIf you want to use this command, initialize it with the registry, then add\nit to that same registry:\n\n\tlet commands: CommandRegistry = ā€¦\n\tlet helpCommand = HelpCommand(registry: commands)\n\tcommands.register(helpCommand)", "key.doc.declaration" : "public struct HelpCommand : CommandProtocol where ClientError : Error", @@ -5073,6 +5448,11 @@ "key.offset" : 603 } ], + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "associatedtype Options : OptionsProtocol", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -5110,6 +5490,11 @@ "key.offset" : 657 } ], + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var verb: String { get }", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -5147,6 +5532,11 @@ "key.offset" : 683 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var function: String { get }", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -5211,6 +5601,11 @@ ], "key.bodylength" : 102, "key.bodyoffset" : 931, + "key.doc.abstract" : [ + { + "Para" : "Initializes the command to provide help from the given registry of commands." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the command to provide help from the given registry of\ncommands.", "key.doc.declaration" : "public init(registry: CommandRegistry, function: String? = nil)", @@ -5251,6 +5646,11 @@ ], "key.bodylength" : 625, "key.bodyoffset" : 1101, + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -5464,6 +5864,11 @@ ], "key.bodylength" : 99, "key.bodyoffset" : 2100, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5524,6 +5929,11 @@ ], "key.bodylength" : 233, "key.bodyoffset" : 1421, + "key.doc.abstract" : [ + { + "Para" : "Represents a record of options for a command, which can be parsed from a list of command-line arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a record of options for a command, which can be parsed from\na list of command-line arguments.\n\nThis is most helpful when used in conjunction with the `Option` and `Switch`\ntypes, and `<*>` and `<|` combinators.\n\nExample:\n\n\tstruct LogOptions: OptionsProtocol {\n\t\tlet verbosity: Int\n\t\tlet outputFilename: String\n\t\tlet shouldDelete: Bool\n\t\tlet logName: String\n\n\t\tstatic func create(_ verbosity: Int) -> (String) -> (Bool) -> (String) -> LogOptions {\n\t\t\treturn { outputFilename in { shouldDelete in { logName in LogOptions(verbosity: verbosity, outputFilename: outputFilename, shouldDelete: shouldDelete, logName: logName) } } }\n\t\t}\n\n\t\tstatic func evaluate(_ m: CommandMode) -> Result> {\n\t\t\treturn create\n\t\t\t\t<*> m <| Option(key: \"verbose\", defaultValue: 0, usage: \"the verbosity level with which to read the logs\")\n\t\t\t\t<*> m <| Option(key: \"outputFilename\", defaultValue: \"\", usage: \"a file to print output to, instead of stdout\")\n\t\t\t\t<*> m <| Switch(flag: \"d\", key: \"delete\", usage: \"delete the logs when finished\")\n\t\t\t\t<*> m <| Argument(usage: \"the log to read\")\n\t\t}\n\t}", "key.doc.declaration" : "public protocol OptionsProtocol", @@ -5579,6 +5989,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "static func evaluate(_ m: CommandMode<\/Type>) -> Result<\/Type><Self<\/Type>, CommandantError<\/Type><ClientError<\/Type>>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Evaluates this set of options in the given mode.\n\nReturns the parsed options or a `UsageError`.", "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", @@ -5629,6 +6044,11 @@ ], "key.bodylength" : 154, "key.bodyoffset" : 1765, + "key.doc.abstract" : [ + { + "Para" : "An `OptionsProtocol` that has no options." + } + ], "key.doc.column" : 15, "key.doc.comment" : "An `OptionsProtocol` that has no options.", "key.doc.declaration" : "public struct NoOptions : OptionsProtocol where ClientError : Error", @@ -5731,6 +6151,11 @@ ], "key.bodylength" : 33, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5783,6 +6208,11 @@ ], "key.bodylength" : 786, "key.bodyoffset" : 2013, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an option that can be provided on the command line.", "key.doc.declaration" : "public struct Option", @@ -5832,6 +6262,11 @@ "key.offset" : 2132 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that controls this option. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that controls this option. For example, a key of `verbose` would\nbe used for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -5867,6 +6302,11 @@ "key.offset" : 2303 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this option. This is the value that will be used if the option is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this option. This is the value that will be used\nif the option is never explicitly specified on the command line.", "key.doc.declaration" : "public let defaultValue: T", @@ -5902,12 +6342,17 @@ "key.offset" : 2637 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.\n\nFor boolean operations, this should describe the effect of _not_ using\nthe default value (i.e., what will happen if you disable\/enable the flag\ndifferently from the default).", "key.doc.declaration" : "public let usage: String", "key.doc.discussion" : [ { - "Para" : "For boolean operations, this should describe the effect of using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." + "Para" : "For boolean operations, this should describe the effect of _not_ using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." } ], "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -5972,6 +6417,11 @@ "key.annotated_decl" : "public struct Option<T><\/Declaration>", "key.bodylength" : 58, "key.bodyoffset" : 2845, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Option", "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -6015,6 +6465,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 2879, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -6075,6 +6530,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 4545, + "key.doc.abstract" : [ + { + "Para" : "Applies `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: (T) -> U, value: Result>) -> Result>", @@ -6175,6 +6635,11 @@ ], "key.bodylength" : 346, "key.bodyoffset" : 4978, + "key.doc.abstract" : [ + { + "Para" : "Applies the function in `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies the function in `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: Result<((T) -> U), CommandantError>, value: Result>) -> Result>", @@ -6268,6 +6733,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 4309, "key.bodyoffset" : 5350, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -6299,6 +6769,11 @@ ], "key.bodylength" : 230, "key.bodyoffset" : 5677, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : ArgumentProtocol", @@ -6429,6 +6904,11 @@ ], "key.bodylength" : 852, "key.bodyoffset" : 6216, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : ArgumentProtocol", @@ -6559,6 +7039,11 @@ ], "key.bodylength" : 232, "key.bodyoffset" : 7401, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]>) -> Result<[T], CommandantError> where T : ArgumentProtocol", @@ -6689,6 +7174,11 @@ ], "key.bodylength" : 1117, "key.bodyoffset" : 7946, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]?>) -> Result<[T]?, CommandantError> where T : ArgumentProtocol", @@ -6819,6 +7309,11 @@ ], "key.bodylength" : 272, "key.bodyoffset" : 9385, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result>", @@ -6916,6 +7411,11 @@ ], "key.bodylength" : 348, "key.bodyoffset" : 82, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.comment" : "A poor man's ordered set.", "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", @@ -7101,6 +7601,11 @@ "key.annotated_decl" : "internal struct OrderedSet<T> : Equatable<\/Type> where T : Hashable<\/Type><\/Declaration>", "key.bodylength" : 331, "key.bodyoffset" : 467, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", "key.doc.file" : "Sources\/Commandant\/OrderedSet.swift", @@ -7137,6 +7642,16 @@ "key.annotated_decl" : "subscript(position: Int<\/Type>) -> T<\/Type> { get }<\/Declaration>", "key.bodylength" : 28, "key.bodyoffset" : 500, + "key.doc.abstract" : [ + { + "Para" : "Accesses the element at the specified position." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "subscript(position: Self.Index) -> Self.Element { get }", "key.doc.discussion" : [ { @@ -7193,10 +7708,20 @@ "key.annotated_decl" : "var count: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 24, "key.bodyoffset" : 548, + "key.doc.abstract" : [ + { + "Para" : "The number of elements in the collection." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1) if the collection conforms to `RandomAccessCollection`; otherwise, O(_n_), where _n_ is the length of the collection." + } + ], "key.doc.declaration" : "var count: Int { get }", "key.doc.discussion" : [ { - "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O() operation." + "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O(_n_) operation." }, { "Complexity" : "" @@ -7230,6 +7755,16 @@ "key.annotated_decl" : "var isEmpty: Bool<\/Type> { get }<\/Declaration>", "key.bodylength" : 26, "key.bodyoffset" : 595, + "key.doc.abstract" : [ + { + "Para" : "A Boolean value indicating whether the collection is empty." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "var isEmpty: Bool { get }", "key.doc.discussion" : [ { @@ -7270,6 +7805,11 @@ "key.annotated_decl" : "var startIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 29, "key.bodyoffset" : 646, + "key.doc.abstract" : [ + { + "Para" : "The position of the first element in a nonempty collection." + } + ], "key.doc.declaration" : "var startIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7304,6 +7844,11 @@ "key.annotated_decl" : "var endIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 27, "key.bodyoffset" : 698, + "key.doc.abstract" : [ + { + "Para" : "The collectionā€™s ā€œpast the endā€ positionā€”that is, the position one greater than the last valid subscript argument." + } + ], "key.doc.declaration" : "var endIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7344,6 +7889,11 @@ "key.annotated_decl" : "func index(after i: Int<\/Type>) -> Int<\/Type><\/Declaration>", "key.bodylength" : 34, "key.bodyoffset" : 762, + "key.doc.abstract" : [ + { + "Para" : "Returns the position immediately after the given index." + } + ], "key.doc.declaration" : "func index(after i: Self.Index) -> Self.Index", "key.doc.discussion" : [ { @@ -7416,6 +7966,11 @@ ], "key.bodylength" : 244, "key.bodyoffset" : 175, + "key.doc.abstract" : [ + { + "Para" : "A value that represents either a success or a failure, including an associated value in each case." + } + ], "key.doc.declaration" : "enum Result where Failure : Error", "key.doc.full_as_xml" : "Result<\/Name>s:s6ResultO<\/USR>enum Result<Success, Failure> where Failure : Error<\/Declaration>A value that represents either a success or a failure, including an associated value in each case.<\/Para><\/Abstract><\/CommentParts><\/Other>", "key.doc.name" : "Result", @@ -7501,6 +8056,11 @@ ], "key.bodylength" : 724, "key.bodyoffset" : 397, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes a parameterless command line flag that defaults to false and can only\nbe switched on. Canonical examples include `--force` and `--recurse`.\n\nFor a boolean toggle that can be enabled and disabled use `Option`.", "key.doc.declaration" : "public struct Switch", @@ -7538,6 +8098,11 @@ "key.offset" : 515 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that enables this switch. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that enables this switch. For example, a key of `verbose` would be\nused for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -7573,6 +8138,11 @@ "key.offset" : 828 } ], + "key.doc.abstract" : [ + { + "Para" : "Optional single letter flag that enables this switch. For example, `-v` would be used as a shorthand for `--verbose`." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Optional single letter flag that enables this switch. For example, `-v` would\nbe used as a shorthand for `--verbose`.\n\nMultiple flags can be grouped together as a single argument and will split\nwhen parsing (e.g. `rm -rf` treats 'r' and 'f' as inidividual flags).", "key.doc.declaration" : "public let flag: Character?", @@ -7613,6 +8183,11 @@ "key.offset" : 968 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -7678,6 +8253,11 @@ "key.annotated_decl" : "public struct Switch<\/Declaration>", "key.bodylength" : 140, "key.bodyoffset" : 1167, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Switch", "key.doc.discussion" : [ @@ -7726,6 +8306,11 @@ ], "key.bodylength" : 104, "key.bodyoffset" : 1201, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -7796,6 +8381,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 650, "key.bodyoffset" : 1355, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -7827,6 +8417,11 @@ ], "key.bodylength" : 333, "key.bodyoffset" : 1670, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean switch in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean switch in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Switch) -> Result>", diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.1.json b/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.1.json index 35fd11e83..c634ae782 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.1.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/Commandant@swift-5.1.json @@ -16,6 +16,11 @@ ], "key.bodylength" : 1029, "key.bodyoffset" : 231, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an argument that can be provided on the command line.", "key.doc.declaration" : "public struct Argument", @@ -65,6 +70,11 @@ "key.offset" : 443 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this argument. This is the value that will be used if the argument is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this argument. This is the value that will be used\nif the argument is never explicitly specified on the command line.\n\nIf this is nil, this argument is always required.", "key.doc.declaration" : "public let defaultValue: T?", @@ -105,6 +115,11 @@ "key.offset" : 585 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this argument. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this argument. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -140,6 +155,11 @@ "key.offset" : 804 } ], + "key.doc.abstract" : [ + { + "Para" : "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 )." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string that describes this argument as a paramater shown\nin the list of possible parameters in help messages (e.g. for \"paths\", the\nuser would see ).", "key.doc.declaration" : "public let usageParameter: String?", @@ -268,6 +288,11 @@ "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 251, "key.bodyoffset" : 1283, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -299,6 +324,11 @@ ], "key.bodylength" : 62, "key.bodyoffset" : 1470, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -339,6 +369,11 @@ "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 254, "key.bodyoffset" : 1575, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -370,6 +405,11 @@ ], "key.bodylength" : 65, "key.bodyoffset" : 1762, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -418,6 +458,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 1979, "key.bodyoffset" : 1877, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -449,6 +494,11 @@ ], "key.bodylength" : 518, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument) -> Result> where T : Commandant.ArgumentProtocol", @@ -562,6 +612,11 @@ ], "key.bodylength" : 778, "key.bodyoffset" : 3076, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument list in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument list in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument<[T]>) -> Result<[T], CommandantError> where T : Commandant.ArgumentProtocol", @@ -688,6 +743,11 @@ ], "key.bodylength" : 296, "key.bodyoffset" : 266, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Represents an argument passed on the command line.", "key.doc.declaration" : "private enum RawArgument : Equatable", @@ -732,6 +792,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case key(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A key corresponding to an option (e.g., `verbose` for `--verbose`)." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A key corresponding to an option (e.g., `verbose` for `--verbose`).", "key.doc.declaration" : "", @@ -769,6 +834,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case value(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A value, either associated with an option or passed as a positional argument." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A value, either associated with an option or passed as a positional\nargument.", "key.doc.declaration" : "", @@ -806,6 +876,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case flag(OrderedSet<\/Type><Character<\/Type>>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "One or more flag arguments (e.g ā€˜rā€™ and ā€˜fā€™ for `-rf`)" + } + ], "key.doc.column" : 7, "key.doc.comment" : "One or more flag arguments (e.g 'r' and 'f' for `-rf`)", "key.doc.declaration" : "", @@ -843,6 +918,11 @@ "key.annotated_decl" : "private enum RawArgument : Equatable<\/Type><\/Declaration>", "key.bodylength" : 214, "key.bodyoffset" : 613, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "private enum RawArgument : Equatable", "key.doc.file" : "Sources\/Commandant\/ArgumentParser.swift", @@ -886,6 +966,11 @@ ], "key.bodylength" : 173, "key.bodyoffset" : 652, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -903,6 +988,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentParser.swift", "key.fully_annotated_decl" : "fileprivate<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -946,6 +1036,11 @@ ], "key.bodylength" : 3711, "key.bodyoffset" : 924, + "key.doc.abstract" : [ + { + "Para" : "Destructively parses a list of command-line arguments." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Destructively parses a list of command-line arguments.", "key.doc.declaration" : "public final class ArgumentParser", @@ -979,6 +1074,11 @@ "key.offset" : 991 } ], + "key.doc.abstract" : [ + { + "Para" : "The remaining arguments to be extracted, in their raw form." + } + ], "key.doc.column" : 14, "key.doc.comment" : "The remaining arguments to be extracted, in their raw form.", "key.doc.declaration" : "private var rawArguments: [Commandant.RawArgument]", @@ -1017,6 +1117,11 @@ ], "key.bodylength" : 741, "key.bodyoffset" : 1151, + "key.doc.abstract" : [ + { + "Para" : "Initializes the generator from a simple list of command-line arguments." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the generator from a simple list of command-line arguments.", "key.doc.declaration" : "public init(_ arguments: [String])", @@ -1090,6 +1195,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 1978, + "key.doc.abstract" : [ + { + "Para" : "Returns the remaining arguments." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Returns the remaining arguments.", "key.doc.declaration" : "internal var remainingArguments: [String]? { get }", @@ -1127,6 +1237,11 @@ ], "key.bodylength" : 281, "key.bodyoffset" : 2323, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was enabled or disabled, or nil if it was not given at all." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was enabled or disabled, or nil if it\nwas not given at all.\n\nIf the key is found, it is then removed from the list of arguments\nremaining to be parsed.", "key.doc.declaration" : "internal func consumeBoolean(forKey key: String) -> Bool?", @@ -1210,6 +1325,11 @@ ], "key.bodylength" : 503, "key.bodyoffset" : 2999, + "key.doc.abstract" : [ + { + "Para" : "Returns the value associated with the given flag, or nil if the flag was not specified. If the key is presented, but no value was given, an error is returned." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the value associated with the given flag, or nil if the flag was\nnot specified. If the key is presented, but no value was given, an error\nis returned.\n\nIf a value is found, the key and the value are both removed from the\nlist of arguments remaining to be parsed.", "key.doc.declaration" : "internal func consumeValue(forKey key: String) -> Result>", @@ -1310,6 +1430,11 @@ ], "key.bodylength" : 164, "key.bodyoffset" : 3688, + "key.doc.abstract" : [ + { + "Para" : "Returns the next positional argument that hasnā€™t yet been returned, or nil if there are no more positional arguments." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the next positional argument that hasn't yet been returned, or\nnil if there are no more positional arguments.", "key.doc.declaration" : "internal func consumePositionalArgument() -> String?", @@ -1350,6 +1475,11 @@ ], "key.bodylength" : 143, "key.bodyoffset" : 4007, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consume(key: String) -> Bool", @@ -1406,6 +1536,11 @@ ], "key.bodylength" : 316, "key.bodyoffset" : 4317, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given flag was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given flag was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consumeBoolean(flag: Character) -> Bool", @@ -1464,6 +1599,11 @@ ], "key.bodylength" : 189, "key.bodyoffset" : 253, + "key.doc.abstract" : [ + { + "Para" : "Represents a value that can be converted from a command-line argument." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a value that can be converted from a command-line argument.", "key.doc.declaration" : "public protocol ArgumentProtocol", @@ -1492,6 +1632,11 @@ "key.annotated_decl" : "static var name: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 322, + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable name for this type.", "key.doc.declaration" : "static var name: String { get }", @@ -1520,6 +1665,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "static func from(string: String<\/Type>) -> `Self`?<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Attempts to parse a value from the given command-line argument.", "key.doc.declaration" : "static func from(string: String) -> `Self`?", @@ -1558,6 +1708,11 @@ "key.annotated_decl" : "@frozen struct Int : FixedWidthInteger<\/Type>, SignedInteger<\/Type><\/Declaration>", "key.bodylength" : 113, "key.bodyoffset" : 478, + "key.doc.abstract" : [ + { + "Para" : "A signed integer value type." + } + ], "key.doc.declaration" : "struct Int : FixedWidthInteger, SignedInteger", "key.doc.discussion" : [ { @@ -1603,6 +1758,11 @@ "key.offset" : 480 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.discussion" : [ @@ -1614,6 +1774,11 @@ "key.doc.full_as_xml" : "name<\/Name>s:10Commandant16ArgumentProtocolP4nameSSvpZ<\/USR>static var name: String { get }<\/Declaration>A human-readable name for this type.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 12, "key.doc.name" : "name", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> let<\/syntaxtype.keyword> name<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.static>", @@ -1648,6 +1813,11 @@ ], "key.bodylength" : 23, "key.bodyoffset" : 566, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func from(string: String) -> `Self`?", "key.doc.discussion" : [ @@ -1659,6 +1829,11 @@ "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> `Self`?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 15, "key.doc.name" : "from(string:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> Int<\/ref.struct>?<\/decl.function.returntype><\/decl.function.method.static>", @@ -1694,19 +1869,24 @@ "key.annotated_decl" : "@frozen struct String<\/Declaration>", "key.bodylength" : 110, "key.bodyoffset" : 630, + "key.doc.abstract" : [ + { + "Para" : "A Unicode string value that is a collection of characters." + } + ], "key.doc.declaration" : "struct String", "key.doc.discussion" : [ { "Para" : "A string is a series of characters, such as `\"Swift\"`, that forms a collection. Strings in Swift are Unicode correct and locale insensitive, and are designed to be efficient. The `String` type bridges with the Objective-C class `NSString` and offers interoperability with C functions that works with strings." }, { - "Para" : "You can create new strings using string literals or string interpolations. A is a series of characters enclosed in quotes." + "Para" : "You can create new strings using string literals or string interpolations. A _string literal_ is a series of characters enclosed in quotes." }, { "CodeListing" : "" }, { - "Para" : " are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." + "Para" : "_String interpolations_ are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." }, { "CodeListing" : "" @@ -1742,7 +1922,7 @@ "Para" : "Basic string operations are not sensitive to locale settings, ensuring that string comparisons and other operations always have a single, stable result, allowing strings to be used as keys in `Dictionary` instances and for other purposes." }, { - "Para" : "A string is a collection of , which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." + "Para" : "A string is a collection of _extended grapheme clusters_, which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." }, { "Para" : "For example, to retrieve the first word of a longer string, you can search for a space and then create a substring from a prefix of the string up to that point:" @@ -1808,7 +1988,7 @@ "Para" : "When you need to know the length of a string, you must first consider what youā€™ll use the length for. Are you measuring the number of characters that will be displayed on the screen, or are you measuring the amount of storage needed for the string in a particular encoding? A single string can have greatly differing lengths when measured by its different views." }, { - "Para" : "For example, an ASCII character like the capital letter is represented by a single element in each of its four views. The Unicode scalar value of is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." + "Para" : "For example, an ASCII character like the capital letter _A_ is represented by a single element in each of its four views. The Unicode scalar value of _A_ is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." }, { "CodeListing" : "" @@ -1853,13 +2033,13 @@ "CodeListing" : "" }, { - "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O() time and space." + "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O(_n_) time and space." }, { "Para" : "When a stringā€™s contiguous storage fills up, a new buffer must be allocated and data must be moved to the new storage. String buffers use an exponential growth strategy that makes appending to a string a constant time operation when averaged over many append operations." }, { - "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O() time and space, where is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." + "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O(_n_) time and space, where _n_ is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." }, { "Para" : "For more information about the Unicode terms used in this discussion, see the . In particular, this discussion mentions , , and ." @@ -1904,6 +2084,11 @@ "key.offset" : 632 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.discussion" : [ @@ -1915,6 +2100,11 @@ "key.doc.full_as_xml" : "name<\/Name>s:10Commandant16ArgumentProtocolP4nameSSvpZ<\/USR>static var name: String { get }<\/Declaration>A human-readable name for this type.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 12, "key.doc.name" : "name", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> let<\/syntaxtype.keyword> name<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.static>", @@ -1949,6 +2139,11 @@ ], "key.bodylength" : 18, "key.bodyoffset" : 720, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func from(string: String) -> `Self`?", "key.doc.discussion" : [ @@ -1960,6 +2155,11 @@ "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> `Self`?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 15, "key.doc.name" : "from(string:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> String<\/ref.struct>?<\/decl.function.returntype><\/decl.function.method.static>", @@ -1995,6 +2195,11 @@ "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 826, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -2013,7 +2218,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2106,6 +2311,11 @@ "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 1027, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -2124,7 +2334,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2232,6 +2442,11 @@ ], "key.bodylength" : 483, "key.bodyoffset" : 280, + "key.doc.abstract" : [ + { + "Para" : "Represents a subcommand that can be executed with its own set of arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a subcommand that can be executed with its own set of arguments.", "key.doc.declaration" : "public protocol CommandProtocol", @@ -2258,6 +2473,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "associatedtype Options : OptionsProtocol<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.comment" : "The command's options type.", "key.doc.declaration" : "associatedtype Options : Commandant.OptionsProtocol", @@ -2306,6 +2526,11 @@ "key.annotated_decl" : "var verb: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 532, + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.comment" : "The action that users should specify to use this subcommand (e.g.,\n`help`).", "key.doc.declaration" : "var verb: String { get }", @@ -2336,6 +2561,11 @@ "key.annotated_decl" : "var function: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 648, + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.comment" : "A human-readable, high-level description of what this command is used\nfor.", "key.doc.declaration" : "var function: String { get }", @@ -2364,6 +2594,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "func run(_ options: Options<\/Type>) -> Result<\/Type><(), ClientError<\/Type>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Runs this subcommand with the given options.", "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", @@ -2409,6 +2644,11 @@ ], "key.bodylength" : 957, "key.bodyoffset" : 843, + "key.doc.abstract" : [ + { + "Para" : "A type-erased command." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A type-erased command.", "key.doc.declaration" : "public struct CommandWrapper where ClientError : Error", @@ -2572,6 +2812,11 @@ ], "key.bodylength" : 633, "key.bodyoffset" : 1165, + "key.doc.abstract" : [ + { + "Para" : "Creates a command that wraps another." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Creates a command that wraps another.", "key.doc.declaration" : "fileprivate init(_ command: C) where ClientError == C.ClientError, C : Commandant.CommandProtocol", @@ -2645,6 +2890,11 @@ ], "key.bodylength" : 216, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Describes the \"mode\" in which a command should run.", "key.doc.declaration" : "public enum CommandMode", @@ -2677,6 +2927,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case arguments(ArgumentParser<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Options should be parsed from the given command-line arguments." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Options should be parsed from the given command-line arguments.", "key.doc.declaration" : "", @@ -2714,6 +2969,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usage<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Each option should record its usage information in an error, for presentation to the user." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Each option should record its usage information in an error, for\npresentation to the user.", "key.doc.declaration" : "", @@ -2763,6 +3023,11 @@ ], "key.bodylength" : 1204, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Maintains the list of commands available to run.", "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", @@ -2852,6 +3117,11 @@ ], "key.bodylength" : 69, "key.bodyoffset" : 2369, + "key.doc.abstract" : [ + { + "Para" : "All available commands." + } + ], "key.doc.column" : 13, "key.doc.comment" : "All available commands.", "key.doc.declaration" : "public var commands: [CommandWrapper] { get }", @@ -2921,6 +3191,11 @@ ], "key.bodylength" : 106, "key.bodyoffset" : 2775, + "key.doc.abstract" : [ + { + "Para" : "Registers the given commands, making those available to run." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Registers the given commands, making those available to run.\n\nIf another commands were already registered with the same `verb`s, those\nwill be overwritten.", "key.doc.declaration" : "public func register(_ commands: C...) -> CommandRegistry where ClientError == C.ClientError, C : Commandant.CommandProtocol", @@ -2994,6 +3269,11 @@ ], "key.bodylength" : 54, "key.bodyoffset" : 3164, + "key.doc.abstract" : [ + { + "Para" : "Runs the command corresponding to the given verb, passing it the given arguments." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Runs the command corresponding to the given verb, passing it the given\narguments.\n\nReturns the results of the execution, or nil if no such command exists.", "key.doc.declaration" : "public func run(command verb: String, arguments: [String]) -> Result<(), CommandantError>?", @@ -3039,6 +3319,11 @@ ], "key.bodylength" : 32, "key.bodyoffset" : 3382, + "key.doc.abstract" : [ + { + "Para" : "Returns the command matching the given verb, or nil if no such command is registered." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Returns the command matching the given verb, or nil if no such command\nis registered.", "key.doc.declaration" : "public subscript(verb: String) -> CommandWrapper? { get }", @@ -3077,6 +3362,11 @@ "key.annotated_decl" : "public final class CommandRegistry<ClientError> where ClientError : Error<\/Type><\/Declaration>", "key.bodylength" : 4074, "key.bodyoffset" : 3446, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -3108,6 +3398,11 @@ ], "key.bodylength" : 97, "key.bodyoffset" : 4332, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3167,6 +3462,11 @@ ], "key.bodylength" : 945, "key.bodyoffset" : 5328, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing `arguments` and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing `arguments`\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(arguments: [String], defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3276,6 +3576,11 @@ ], "key.bodylength" : 933, "key.bodyoffset" : 6585, + "key.doc.abstract" : [ + { + "Para" : "Finds and executes a subcommand which exists in your $PATH. The executable name must be in the form of `executable-verb`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Finds and executes a subcommand which exists in your $PATH. The executable\nname must be in the form of `executable-verb`.\n\n- Returns: The exit status of found subcommand or nil.", "key.doc.declaration" : "private func executeSubcommandIfExists(_ executableName: String, verb: String, arguments: [String]) -> Int32?", @@ -3406,6 +3711,11 @@ ], "key.bodylength" : 157, "key.bodyoffset" : 372, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Possible errors that can originate from Commandant.\n\n`ClientError` should be the type of error (if any) that can occur when\nrunning commands.", "key.doc.declaration" : "public enum CommandantError : Error", @@ -3472,6 +3782,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usageError(description: String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An option was used incorrectly." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An option was used incorrectly.", "key.doc.declaration" : "", @@ -3509,6 +3824,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case commandError(ClientError<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An error occurred while running a command." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An error occurred while running a command.", "key.doc.declaration" : "", @@ -3546,6 +3866,11 @@ "key.annotated_decl" : "public enum CommandantError<ClientError> : Error<\/Type><\/Declaration>", "key.bodylength" : 187, "key.bodyoffset" : 584, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandantError : Error", "key.doc.discussion" : [ @@ -3594,6 +3919,11 @@ ], "key.bodylength" : 151, "key.bodyoffset" : 618, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -3611,6 +3941,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Errors.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -3649,6 +3984,11 @@ ], "key.bodylength" : 105, "key.bodyoffset" : 992, + "key.doc.abstract" : [ + { + "Para" : "Constructs an `InvalidArgument` error that indicates a missing value for the argument by the given name." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an `InvalidArgument` error that indicates a missing value for\nthe argument by the given name.", "key.doc.declaration" : "internal func missingArgumentError(_ argumentName: String) -> CommandantError", @@ -3722,6 +4062,11 @@ ], "key.bodylength" : 179, "key.bodyoffset" : 1339, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error by combining the example of key (and value, if applicable) with the usage description." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error by combining the example of key (and value, if applicable)\nwith the usage description.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, usage: String) -> CommandantError", @@ -3824,6 +4169,11 @@ ], "key.bodylength" : 265, "key.bodyoffset" : 1813, + "key.doc.abstract" : [ + { + "Para" : "Combines the text of the two errors, if theyā€™re both `UsageError`s. Otherwise, uses whichever one is not (biased toward the left)." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Combines the text of the two errors, if they're both `UsageError`s.\nOtherwise, uses whichever one is not (biased toward the left).", "key.doc.declaration" : "internal func combineUsageErrors(_ lhs: CommandantError, _ rhs: CommandantError) -> CommandantError", @@ -3880,6 +4230,11 @@ ], "key.bodylength" : 96, "key.bodyoffset" : 2260, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that indicates unrecognized arguments remains." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that indicates unrecognized arguments remains.", "key.doc.declaration" : "internal func unrecognizedArgumentsError(_ options: [String]) -> CommandantError", @@ -3944,6 +4299,11 @@ ], "key.bodylength" : 192, "key.bodyoffset" : 2631, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument, with the given example of value usage if applicable." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument, with the given\nexample of value usage if applicable.", "key.doc.declaration" : "internal func informativeUsageError(_ valueExample: String, argument: Argument) -> CommandantError", @@ -4046,6 +4406,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3018, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4194,6 +4559,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3598, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument list." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument list.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument<[T]>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4350,6 +4720,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 4257, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option, with the given example of key (and value, if applicable) usage." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option, with the given\nexample of key (and value, if applicable) usage.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, option: Option) -> CommandantError", @@ -4452,6 +4827,11 @@ ], "key.bodylength" : 89, "key.bodyoffset" : 4522, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4566,6 +4946,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 4801, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4680,6 +5065,11 @@ ], "key.bodylength" : 91, "key.bodyoffset" : 5070, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4794,6 +5184,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 5353, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]?>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4908,6 +5303,11 @@ ], "key.bodylength" : 121, "key.bodyoffset" : 5616, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the given boolean option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the given boolean option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError", @@ -5018,6 +5418,11 @@ ], "key.bodylength" : 1127, "key.bodyoffset" : 601, + "key.doc.abstract" : [ + { + "Para" : "A basic implementation of a `help` command, using information available in a `CommandRegistry`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A basic implementation of a `help` command, using information available in a\n`CommandRegistry`.\n\nIf you want to use this command, initialize it with the registry, then add\nit to that same registry:\n\n\tlet commands: CommandRegistry = ā€¦\n\tlet helpCommand = HelpCommand(registry: commands)\n\tcommands.register(helpCommand)", "key.doc.declaration" : "public struct HelpCommand : CommandProtocol where ClientError : Error", @@ -5099,6 +5504,11 @@ "key.offset" : 603 } ], + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "associatedtype Options : Commandant.OptionsProtocol", "key.doc.discussion" : [ @@ -5110,6 +5520,11 @@ "key.doc.full_as_xml" : "Options<\/Name>s:10Commandant15CommandProtocolP7OptionsQa<\/USR>associatedtype Options : Commandant.OptionsProtocol<\/Declaration>The commandā€™s options type.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 15, "key.doc.name" : "Options", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> typealias<\/syntaxtype.keyword> HelpCommand<\/ref.struct><ClientError>.Options<\/decl.name> = HelpOptions<\/ref.struct><ClientError<\/ref.generic_type_param>><\/decl.typealias>", @@ -5141,6 +5556,11 @@ "key.offset" : 657 } ], + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var verb: String { get }", "key.doc.discussion" : [ @@ -5152,6 +5572,11 @@ "key.doc.full_as_xml" : "verb<\/Name>s:10Commandant15CommandProtocolP4verbSSvp<\/USR>var verb: String { get }<\/Declaration>The action that users should specify to use this subcommand (e.g., help<\/codeVoice>).<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 21, "key.doc.name" : "verb", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> let<\/syntaxtype.keyword> verb<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.instance>", @@ -5183,6 +5608,11 @@ "key.offset" : 683 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var function: String { get }", "key.doc.discussion" : [ @@ -5194,6 +5624,11 @@ "key.doc.full_as_xml" : "function<\/Name>s:10Commandant15CommandProtocolP8functionSSvp<\/USR>var function: String { get }<\/Declaration>A human-readable, high-level description of what this command is used for.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 25, "key.doc.name" : "function", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> let<\/syntaxtype.keyword> function<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.instance>", @@ -5252,6 +5687,11 @@ ], "key.bodylength" : 102, "key.bodyoffset" : 931, + "key.doc.abstract" : [ + { + "Para" : "Initializes the command to provide help from the given registry of commands." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the command to provide help from the given registry of\ncommands.", "key.doc.declaration" : "public init(registry: CommandRegistry, function: String? = nil)", @@ -5292,6 +5732,11 @@ ], "key.bodylength" : 625, "key.bodyoffset" : 1101, + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", "key.doc.discussion" : [ @@ -5303,6 +5748,11 @@ "key.doc.full_as_xml" : "run(_:)<\/Name>s:10Commandant15CommandProtocolP3runys6ResultOyyt11ClientErrorQzG7OptionsQzF<\/USR>func run(_ options: Options) -> Result<(), ClientError><\/Declaration>Runs this subcommand with the given options.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 28, "key.doc.name" : "run(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> func<\/syntaxtype.keyword> run<\/decl.name>(_<\/decl.var.parameter.argument_label> options<\/decl.var.parameter.name>: Options<\/ref.typealias><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><()<\/tuple>, ClientError<\/ref.generic_type_param>><\/decl.function.returntype><\/decl.function.method.instance>", @@ -5510,6 +5960,11 @@ ], "key.bodylength" : 99, "key.bodyoffset" : 2100, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5524,6 +5979,11 @@ "key.doc.full_as_xml" : "evaluate(_:)<\/Name>s:10Commandant15OptionsProtocolP8evaluateys6ResultOyxAA0A5ErrorOy06ClientF0QzGGAA11CommandModeOFZ<\/USR>static func evaluate(_ m: CommandMode) -> Result<Self, CommandantError<ClientError>><\/Declaration>Evaluates this set of options in the given mode.<\/Para><\/Abstract>Returns the parsed options or a UsageError<\/codeVoice>.<\/Para>This documentation comment was inherited from OptionsProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 43, "key.doc.name" : "evaluate(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `OptionsProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> evaluate<\/decl.name>(_<\/decl.var.parameter.argument_label> m<\/decl.var.parameter.name>: CommandMode<\/ref.enum><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><HelpOptions<\/ref.struct>, CommandantError<\/ref.enum><ClientError<\/ref.generic_type_param>>><\/decl.function.returntype><\/decl.function.method.static>", @@ -5573,6 +6033,11 @@ ], "key.bodylength" : 233, "key.bodyoffset" : 1421, + "key.doc.abstract" : [ + { + "Para" : "Represents a record of options for a command, which can be parsed from a list of command-line arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a record of options for a command, which can be parsed from\na list of command-line arguments.\n\nThis is most helpful when used in conjunction with the `Option` and `Switch`\ntypes, and `<*>` and `<|` combinators.\n\nExample:\n\n\tstruct LogOptions: OptionsProtocol {\n\t\tlet verbosity: Int\n\t\tlet outputFilename: String\n\t\tlet shouldDelete: Bool\n\t\tlet logName: String\n\n\t\tstatic func create(_ verbosity: Int) -> (String) -> (Bool) -> (String) -> LogOptions {\n\t\t\treturn { outputFilename in { shouldDelete in { logName in LogOptions(verbosity: verbosity, outputFilename: outputFilename, shouldDelete: shouldDelete, logName: logName) } } }\n\t\t}\n\n\t\tstatic func evaluate(_ m: CommandMode) -> Result> {\n\t\t\treturn create\n\t\t\t\t<*> m <| Option(key: \"verbose\", defaultValue: 0, usage: \"the verbosity level with which to read the logs\")\n\t\t\t\t<*> m <| Option(key: \"outputFilename\", defaultValue: \"\", usage: \"a file to print output to, instead of stdout\")\n\t\t\t\t<*> m <| Switch(flag: \"d\", key: \"delete\", usage: \"delete the logs when finished\")\n\t\t\t\t<*> m <| Argument(usage: \"the log to read\")\n\t\t}\n\t}", "key.doc.declaration" : "public protocol OptionsProtocol", @@ -5628,6 +6093,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "static func evaluate(_ m: CommandMode<\/Type>) -> Result<\/Type><Self<\/Type>, CommandantError<\/Type><ClientError<\/Type>>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Evaluates this set of options in the given mode.\n\nReturns the parsed options or a `UsageError`.", "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", @@ -5678,6 +6148,11 @@ ], "key.bodylength" : 154, "key.bodyoffset" : 1765, + "key.doc.abstract" : [ + { + "Para" : "An `OptionsProtocol` that has no options." + } + ], "key.doc.column" : 15, "key.doc.comment" : "An `OptionsProtocol` that has no options.", "key.doc.declaration" : "public struct NoOptions : OptionsProtocol where ClientError : Error", @@ -5780,6 +6255,11 @@ ], "key.bodylength" : 33, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5794,6 +6274,11 @@ "key.doc.full_as_xml" : "evaluate(_:)<\/Name>s:10Commandant15OptionsProtocolP8evaluateys6ResultOyxAA0A5ErrorOy06ClientF0QzGGAA11CommandModeOFZ<\/USR>static func evaluate(_ m: CommandMode) -> Result<Self, CommandantError<ClientError>><\/Declaration>Evaluates this set of options in the given mode.<\/Para><\/Abstract>Returns the parsed options or a UsageError<\/codeVoice>.<\/Para>This documentation comment was inherited from OptionsProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 43, "key.doc.name" : "evaluate(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `OptionsProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/Option.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> evaluate<\/decl.name>(_<\/decl.var.parameter.argument_label> m<\/decl.var.parameter.name>: CommandMode<\/ref.enum><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><NoOptions<\/ref.struct>, CommandantError<\/ref.enum><ClientError<\/ref.generic_type_param>>><\/decl.function.returntype><\/decl.function.method.static>", @@ -5835,6 +6320,11 @@ ], "key.bodylength" : 786, "key.bodyoffset" : 2013, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an option that can be provided on the command line.", "key.doc.declaration" : "public struct Option", @@ -5884,6 +6374,11 @@ "key.offset" : 2132 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that controls this option. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that controls this option. For example, a key of `verbose` would\nbe used for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -5919,6 +6414,11 @@ "key.offset" : 2303 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this option. This is the value that will be used if the option is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this option. This is the value that will be used\nif the option is never explicitly specified on the command line.", "key.doc.declaration" : "public let defaultValue: T", @@ -5954,12 +6454,17 @@ "key.offset" : 2637 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.\n\nFor boolean operations, this should describe the effect of _not_ using\nthe default value (i.e., what will happen if you disable\/enable the flag\ndifferently from the default).", "key.doc.declaration" : "public let usage: String", "key.doc.discussion" : [ { - "Para" : "For boolean operations, this should describe the effect of using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." + "Para" : "For boolean operations, this should describe the effect of _not_ using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." } ], "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -6024,6 +6529,11 @@ "key.annotated_decl" : "public struct Option<T><\/Declaration>", "key.bodylength" : 58, "key.bodyoffset" : 2845, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Option", "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -6067,6 +6577,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 2879, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -6084,6 +6599,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Option.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -6130,6 +6650,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 4545, + "key.doc.abstract" : [ + { + "Para" : "Applies `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: (T) -> U, value: Result>) -> Result>", @@ -6230,6 +6755,11 @@ ], "key.bodylength" : 346, "key.bodyoffset" : 4978, + "key.doc.abstract" : [ + { + "Para" : "Applies the function in `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies the function in `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: Result<((T) -> U), CommandantError>, value: Result>) -> Result>", @@ -6323,6 +6853,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 4309, "key.bodyoffset" : 5350, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -6354,6 +6889,11 @@ ], "key.bodylength" : 230, "key.bodyoffset" : 5677, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : Commandant.ArgumentProtocol", @@ -6484,6 +7024,11 @@ ], "key.bodylength" : 852, "key.bodyoffset" : 6216, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : Commandant.ArgumentProtocol", @@ -6614,6 +7159,11 @@ ], "key.bodylength" : 232, "key.bodyoffset" : 7401, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]>) -> Result<[T], CommandantError> where T : Commandant.ArgumentProtocol", @@ -6744,6 +7294,11 @@ ], "key.bodylength" : 1117, "key.bodyoffset" : 7946, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]?>) -> Result<[T]?, CommandantError> where T : Commandant.ArgumentProtocol", @@ -6874,6 +7429,11 @@ ], "key.bodylength" : 272, "key.bodyoffset" : 9385, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result>", @@ -6971,6 +7531,11 @@ ], "key.bodylength" : 348, "key.bodyoffset" : 82, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.comment" : "A poor man's ordered set.", "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", @@ -7156,6 +7721,11 @@ "key.annotated_decl" : "internal struct OrderedSet<T> : Equatable<\/Type> where T : Hashable<\/Type><\/Declaration>", "key.bodylength" : 331, "key.bodyoffset" : 467, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", "key.doc.file" : "Sources\/Commandant\/OrderedSet.swift", @@ -7192,6 +7762,16 @@ "key.annotated_decl" : "subscript(position: Int<\/Type>) -> T<\/Type> { get }<\/Declaration>", "key.bodylength" : 28, "key.bodyoffset" : 500, + "key.doc.abstract" : [ + { + "Para" : "Accesses the element at the specified position." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "subscript(position: Self.Index) -> Self.Element { get }", "key.doc.discussion" : [ { @@ -7212,6 +7792,11 @@ ], "key.doc.full_as_xml" : "subscript(_:)<\/Name>s:Sly7ElementQz5IndexQzcip<\/USR>subscript(position: Self.Index) -> Self.Element { get }<\/Declaration>Accesses the element at the specified position.<\/Para><\/Abstract>position<\/Name>in<\/Direction>The position of the element to access. position<\/codeVoice> must be a valid index of the collection that is not equal to the endIndex<\/codeVoice> property.<\/Para><\/Discussion><\/Parameter><\/Parameters>The following example accesses an element of an array through its subscript to print its value:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>You can subscript a collection with any valid index other than the collectionā€™s end index. The end index refers to the position one past the last element of a collection, so it doesnā€™t correspond with an element.<\/Para>O(1)<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "subscript(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.parameters" : [ { "discussion" : [ @@ -7251,10 +7836,20 @@ "key.annotated_decl" : "var count: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 24, "key.bodyoffset" : 548, + "key.doc.abstract" : [ + { + "Para" : "The number of elements in the collection." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1) if the collection conforms to `RandomAccessCollection`; otherwise, O(_n_), where _n_ is the length of the collection." + } + ], "key.doc.declaration" : "var count: Int { get }", "key.doc.discussion" : [ { - "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O() operation." + "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O(_n_) operation." }, { "Complexity" : "" @@ -7265,6 +7860,11 @@ ], "key.doc.full_as_xml" : "count<\/Name>s:Sl5countSivp<\/USR>var count: Int { get }<\/Declaration>The number of elements in the collection.<\/Para><\/Abstract>To check whether a collection is empty, use its isEmpty<\/codeVoice> property instead of comparing count<\/codeVoice> to zero. Unless the collection guarantees random-access performance, calculating count<\/codeVoice> can be an O(n<\/emphasis>) operation.<\/Para>O(1) if the collection conforms to RandomAccessCollection<\/codeVoice>; otherwise, O(n<\/emphasis>), where n<\/emphasis> is the length of the collection.<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "count", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> count<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7291,6 +7891,16 @@ "key.annotated_decl" : "var isEmpty: Bool<\/Type> { get }<\/Declaration>", "key.bodylength" : 26, "key.bodyoffset" : 595, + "key.doc.abstract" : [ + { + "Para" : "A Boolean value indicating whether the collection is empty." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "var isEmpty: Bool { get }", "key.doc.discussion" : [ { @@ -7308,6 +7918,11 @@ ], "key.doc.full_as_xml" : "isEmpty<\/Name>s:Sl7isEmptySbvp<\/USR>var isEmpty: Bool { get }<\/Declaration>A Boolean value indicating whether the collection is empty.<\/Para><\/Abstract>When you need to check whether your collection is empty, use the isEmpty<\/codeVoice> property instead of checking that the count<\/codeVoice> property is equal to zero. For collections that donā€™t conform to RandomAccessCollection<\/codeVoice>, accessing the count<\/codeVoice> property iterates through the elements of the collection.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>O(1)<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "isEmpty", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> isEmpty<\/decl.name>: Bool<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7334,6 +7949,11 @@ "key.annotated_decl" : "var startIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 29, "key.bodyoffset" : 646, + "key.doc.abstract" : [ + { + "Para" : "The position of the first element in a nonempty collection." + } + ], "key.doc.declaration" : "var startIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7345,6 +7965,11 @@ ], "key.doc.full_as_xml" : "startIndex<\/Name>s:Sl10startIndex0B0Qzvp<\/USR>var startIndex: Self.Index { get }<\/Declaration>The position of the first element in a nonempty collection.<\/Para><\/Abstract>If the collection is empty, startIndex<\/codeVoice> is equal to endIndex<\/codeVoice>.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "startIndex", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> startIndex<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7371,6 +7996,11 @@ "key.annotated_decl" : "var endIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 27, "key.bodyoffset" : 698, + "key.doc.abstract" : [ + { + "Para" : "The collectionā€™s ā€œpast the endā€ positionā€”that is, the position one greater than the last valid subscript argument." + } + ], "key.doc.declaration" : "var endIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7388,6 +8018,11 @@ ], "key.doc.full_as_xml" : "endIndex<\/Name>s:Sl8endIndex0B0Qzvp<\/USR>var endIndex: Self.Index { get }<\/Declaration>The collectionā€™s ā€œpast the endā€ positionā€”that is, the position one greater than the last valid subscript argument.<\/Para><\/Abstract>When you need a range that includes the last element of a collection, use the half-open range operator (..<<\/codeVoice>) with endIndex<\/codeVoice>. The ..<<\/codeVoice> operator creates a range that doesnā€™t include the upper bound, so itā€™s always safe to use with endIndex<\/codeVoice>. For example:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>If the collection is empty, endIndex<\/codeVoice> is equal to startIndex<\/codeVoice>.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "endIndex", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> endIndex<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7414,6 +8049,11 @@ "key.annotated_decl" : "func index(after i: Int<\/Type>) -> Int<\/Type><\/Declaration>", "key.bodylength" : 34, "key.bodyoffset" : 762, + "key.doc.abstract" : [ + { + "Para" : "Returns the position immediately after the given index." + } + ], "key.doc.declaration" : "func index(after i: Self.Index) -> Self.Index", "key.doc.discussion" : [ { @@ -7425,6 +8065,11 @@ ], "key.doc.full_as_xml" : "index(after:)<\/Name>s:Sl5index5after5IndexQzAD_tF<\/USR>func index(after i: Self.Index) -> Self.Index<\/Declaration>Returns the position immediately after the given index.<\/Para><\/Abstract>i<\/Name>in<\/Direction>A valid index of the collection. i<\/codeVoice> must be less than endIndex<\/codeVoice>.<\/Para><\/Discussion><\/Parameter><\/Parameters>The index value immediately after i<\/codeVoice>.<\/Para><\/ResultDiscussion>The successor of an index must be well defined. For an index i<\/codeVoice> into a collection c<\/codeVoice>, calling c.index(after: i)<\/codeVoice> returns the same index every time.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.name" : "index(after:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.parameters" : [ { "discussion" : [ @@ -7489,6 +8134,11 @@ ], "key.bodylength" : 244, "key.bodyoffset" : 175, + "key.doc.abstract" : [ + { + "Para" : "A value that represents either a success or a failure, including an associated value in each case." + } + ], "key.doc.declaration" : "enum Result where Failure : Error", "key.doc.full_as_xml" : "Result<\/Name>s:s6ResultO<\/USR>enum Result<Success, Failure> where Failure : Error<\/Declaration>A value that represents either a success or a failure, including an associated value in each case.<\/Para><\/Abstract><\/CommentParts><\/Other>", "key.doc.name" : "Result", @@ -7574,6 +8224,11 @@ ], "key.bodylength" : 724, "key.bodyoffset" : 397, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes a parameterless command line flag that defaults to false and can only\nbe switched on. Canonical examples include `--force` and `--recurse`.\n\nFor a boolean toggle that can be enabled and disabled use `Option`.", "key.doc.declaration" : "public struct Switch", @@ -7611,6 +8266,11 @@ "key.offset" : 515 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that enables this switch. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that enables this switch. For example, a key of `verbose` would be\nused for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -7646,6 +8306,11 @@ "key.offset" : 828 } ], + "key.doc.abstract" : [ + { + "Para" : "Optional single letter flag that enables this switch. For example, `-v` would be used as a shorthand for `--verbose`." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Optional single letter flag that enables this switch. For example, `-v` would\nbe used as a shorthand for `--verbose`.\n\nMultiple flags can be grouped together as a single argument and will split\nwhen parsing (e.g. `rm -rf` treats 'r' and 'f' as inidividual flags).", "key.doc.declaration" : "public let flag: Character?", @@ -7686,6 +8351,11 @@ "key.offset" : 968 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -7751,6 +8421,11 @@ "key.annotated_decl" : "public struct Switch<\/Declaration>", "key.bodylength" : 140, "key.bodyoffset" : 1167, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Switch", "key.doc.discussion" : [ @@ -7799,6 +8474,11 @@ ], "key.bodylength" : 104, "key.bodyoffset" : 1201, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -7816,6 +8496,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Switch.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7872,6 +8557,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 650, "key.bodyoffset" : 1355, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -7903,6 +8593,11 @@ ], "key.bodylength" : 333, "key.bodyoffset" : 1670, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean switch in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean switch in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Switch) -> Result>", diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/CommandantSPM@swift-5.1.json b/Tests/SourceKittenFrameworkTests/Fixtures/CommandantSPM@swift-5.1.json index 35fd11e83..a077d79e9 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/CommandantSPM@swift-5.1.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/CommandantSPM@swift-5.1.json @@ -16,6 +16,11 @@ ], "key.bodylength" : 1029, "key.bodyoffset" : 231, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an argument that can be provided on the command line.", "key.doc.declaration" : "public struct Argument", @@ -65,6 +70,11 @@ "key.offset" : 443 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this argument. This is the value that will be used if the argument is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this argument. This is the value that will be used\nif the argument is never explicitly specified on the command line.\n\nIf this is nil, this argument is always required.", "key.doc.declaration" : "public let defaultValue: T?", @@ -105,6 +115,11 @@ "key.offset" : 585 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this argument. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this argument. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -140,6 +155,11 @@ "key.offset" : 804 } ], + "key.doc.abstract" : [ + { + "Para" : "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 )." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string that describes this argument as a paramater shown\nin the list of possible parameters in help messages (e.g. for \"paths\", the\nuser would see ).", "key.doc.declaration" : "public let usageParameter: String?", @@ -264,10 +284,14 @@ "key.usr" : "s:10Commandant8ArgumentV" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 251, "key.bodyoffset" : 1283, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -299,6 +323,11 @@ ], "key.bodylength" : 62, "key.bodyoffset" : 1470, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -335,10 +364,14 @@ "key.usr" : "s:10Commandant8ArgumentV" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 254, "key.bodyoffset" : 1575, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -370,6 +403,11 @@ ], "key.bodylength" : 65, "key.bodyoffset" : 1762, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -414,10 +452,14 @@ "key.offset" : 1835 }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 1979, "key.bodyoffset" : 1877, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -449,6 +491,11 @@ ], "key.bodylength" : 518, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument) -> Result> where T : Commandant.ArgumentProtocol", @@ -562,6 +609,11 @@ ], "key.bodylength" : 778, "key.bodyoffset" : 3076, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument list in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument list in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument<[T]>) -> Result<[T], CommandantError> where T : Commandant.ArgumentProtocol", @@ -688,6 +740,11 @@ ], "key.bodylength" : 296, "key.bodyoffset" : 266, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Represents an argument passed on the command line.", "key.doc.declaration" : "private enum RawArgument : Equatable", @@ -732,6 +789,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case key(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A key corresponding to an option (e.g., `verbose` for `--verbose`)." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A key corresponding to an option (e.g., `verbose` for `--verbose`).", "key.doc.declaration" : "", @@ -753,6 +815,9 @@ "key.parsed_declaration" : "case key(String)", "key.parsed_scope.end" : 14, "key.parsed_scope.start" : 14, + "key.substructure" : [ + + ], "key.typename" : "(RawArgument.Type) -> (String) -> RawArgument", "key.typeusr" : "$sy10Commandant11RawArgument33_BA859BFBBE9DF3838A11641CB273713ELLOSScADmcD", "key.usr" : "s:10Commandant11RawArgument33_BA859BFBBE9DF3838A11641CB273713ELLO3keyyADSScADmF" @@ -769,6 +834,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case value(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A value, either associated with an option or passed as a positional argument." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A value, either associated with an option or passed as a positional\nargument.", "key.doc.declaration" : "", @@ -790,6 +860,9 @@ "key.parsed_declaration" : "case value(String)", "key.parsed_scope.end" : 18, "key.parsed_scope.start" : 18, + "key.substructure" : [ + + ], "key.typename" : "(RawArgument.Type) -> (String) -> RawArgument", "key.typeusr" : "$sy10Commandant11RawArgument33_BA859BFBBE9DF3838A11641CB273713ELLOSScADmcD", "key.usr" : "s:10Commandant11RawArgument33_BA859BFBBE9DF3838A11641CB273713ELLO5valueyADSScADmF" @@ -806,6 +879,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case flag(OrderedSet<\/Type><Character<\/Type>>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "One or more flag arguments (e.g ā€˜rā€™ and ā€˜fā€™ for `-rf`)" + } + ], "key.doc.column" : 7, "key.doc.comment" : "One or more flag arguments (e.g 'r' and 'f' for `-rf`)", "key.doc.declaration" : "", @@ -827,6 +905,9 @@ "key.parsed_declaration" : "case flag(OrderedSet)", "key.parsed_scope.end" : 21, "key.parsed_scope.start" : 21, + "key.substructure" : [ + + ], "key.typename" : "(RawArgument.Type) -> (OrderedSet) -> RawArgument", "key.typeusr" : "$sy10Commandant11RawArgument33_BA859BFBBE9DF3838A11641CB273713ELLOAA10OrderedSetVySJGcADmcD", "key.usr" : "s:10Commandant11RawArgument33_BA859BFBBE9DF3838A11641CB273713ELLO4flagyAdA10OrderedSetVySJGcADmF" @@ -839,10 +920,14 @@ "key.usr" : "s:10Commandant11RawArgument33_BA859BFBBE9DF3838A11641CB273713ELLO" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "private enum RawArgument : Equatable<\/Type><\/Declaration>", "key.bodylength" : 214, "key.bodyoffset" : 613, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "private enum RawArgument : Equatable", "key.doc.file" : "Sources\/Commandant\/ArgumentParser.swift", @@ -886,6 +971,11 @@ ], "key.bodylength" : 173, "key.bodyoffset" : 652, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -903,6 +993,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentParser.swift", "key.fully_annotated_decl" : "fileprivate<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -946,6 +1041,11 @@ ], "key.bodylength" : 3711, "key.bodyoffset" : 924, + "key.doc.abstract" : [ + { + "Para" : "Destructively parses a list of command-line arguments." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Destructively parses a list of command-line arguments.", "key.doc.declaration" : "public final class ArgumentParser", @@ -979,11 +1079,16 @@ "key.offset" : 991 } ], + "key.doc.abstract" : [ + { + "Para" : "The remaining arguments to be extracted, in their raw form." + } + ], "key.doc.column" : 14, "key.doc.comment" : "The remaining arguments to be extracted, in their raw form.", - "key.doc.declaration" : "private var rawArguments: [Commandant.RawArgument]", + "key.doc.declaration" : "private var rawArguments: [RawArgument]", "key.doc.file" : "Sources\/Commandant\/ArgumentParser.swift", - "key.doc.full_as_xml" : "rawArguments<\/Name>s:10Commandant14ArgumentParserC12rawArguments33_BA859BFBBE9DF3838A11641CB273713ELLSayAA03RawB0AELLOGvp<\/USR>private var rawArguments: [Commandant.RawArgument]<\/Declaration>The remaining arguments to be extracted, in their raw form.<\/Para><\/Abstract><\/CommentParts><\/Other>", + "key.doc.full_as_xml" : "rawArguments<\/Name>s:10Commandant14ArgumentParserC12rawArguments33_BA859BFBBE9DF3838A11641CB273713ELLSayAA03RawB0AELLOGvp<\/USR>private var rawArguments: [RawArgument]<\/Declaration>The remaining arguments to be extracted, in their raw form.<\/Para><\/Abstract><\/CommentParts><\/Other>", "key.doc.line" : 42, "key.doc.name" : "rawArguments", "key.doc.type" : "Other", @@ -1017,6 +1122,11 @@ ], "key.bodylength" : 741, "key.bodyoffset" : 1151, + "key.doc.abstract" : [ + { + "Para" : "Initializes the generator from a simple list of command-line arguments." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the generator from a simple list of command-line arguments.", "key.doc.declaration" : "public init(_ arguments: [String])", @@ -1040,9 +1150,9 @@ "key.parsed_scope.start" : 45, "key.substructure" : [ { - "key.annotated_decl" : "let params: [ArraySlice<\/Type><String<\/Type>>]<\/Declaration>", + "key.annotated_decl" : "let params: [Array<\/Type><String<\/Type>>.SubSequence<\/Type>]<\/Declaration>", "key.filepath" : "Sources\/Commandant\/ArgumentParser.swift", - "key.fully_annotated_decl" : "let<\/syntaxtype.keyword> params<\/decl.name>: [ArraySlice<\/ref.struct><String<\/ref.struct>>]<\/decl.var.type><\/decl.var.local>", + "key.fully_annotated_decl" : "let<\/syntaxtype.keyword> params<\/decl.name>: [Array<\/ref.struct><String<\/ref.struct>>.SubSequence<\/ref.typealias>]<\/decl.var.type><\/decl.var.local>", "key.kind" : "source.lang.swift.decl.var.local", "key.length" : 91, "key.name" : "params", @@ -1057,9 +1167,9 @@ "key.usr" : "s:10Commandant14ArgumentParserCyACSaySSGcfc6paramsL_Says10ArraySliceVySSGGvp" }, { - "key.annotated_decl" : "let options: ArraySlice<\/Type><String<\/Type>><\/Declaration>", + "key.annotated_decl" : "let options: Array<\/Type><String<\/Type>>.SubSequence<\/Type><\/Declaration>", "key.filepath" : "Sources\/Commandant\/ArgumentParser.swift", - "key.fully_annotated_decl" : "let<\/syntaxtype.keyword> options<\/decl.name>: ArraySlice<\/ref.struct><String<\/ref.struct>><\/decl.var.type><\/decl.var.local>", + "key.fully_annotated_decl" : "let<\/syntaxtype.keyword> options<\/decl.name>: Array<\/ref.struct><String<\/ref.struct>>.SubSequence<\/ref.typealias><\/decl.var.type><\/decl.var.local>", "key.kind" : "source.lang.swift.decl.var.local", "key.length" : 27, "key.name" : "options", @@ -1090,6 +1200,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 1978, + "key.doc.abstract" : [ + { + "Para" : "Returns the remaining arguments." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Returns the remaining arguments.", "key.doc.declaration" : "internal var remainingArguments: [String]? { get }", @@ -1127,6 +1242,11 @@ ], "key.bodylength" : 281, "key.bodyoffset" : 2323, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was enabled or disabled, or nil if it was not given at all." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was enabled or disabled, or nil if it\nwas not given at all.\n\nIf the key is found, it is then removed from the list of arguments\nremaining to be parsed.", "key.doc.declaration" : "internal func consumeBoolean(forKey key: String) -> Bool?", @@ -1210,6 +1330,11 @@ ], "key.bodylength" : 503, "key.bodyoffset" : 2999, + "key.doc.abstract" : [ + { + "Para" : "Returns the value associated with the given flag, or nil if the flag was not specified. If the key is presented, but no value was given, an error is returned." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the value associated with the given flag, or nil if the flag was\nnot specified. If the key is presented, but no value was given, an error\nis returned.\n\nIf a value is found, the key and the value are both removed from the\nlist of arguments remaining to be parsed.", "key.doc.declaration" : "internal func consumeValue(forKey key: String) -> Result>", @@ -1310,6 +1435,11 @@ ], "key.bodylength" : 164, "key.bodyoffset" : 3688, + "key.doc.abstract" : [ + { + "Para" : "Returns the next positional argument that hasnā€™t yet been returned, or nil if there are no more positional arguments." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the next positional argument that hasn't yet been returned, or\nnil if there are no more positional arguments.", "key.doc.declaration" : "internal func consumePositionalArgument() -> String?", @@ -1350,6 +1480,11 @@ ], "key.bodylength" : 143, "key.bodyoffset" : 4007, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consume(key: String) -> Bool", @@ -1406,6 +1541,11 @@ ], "key.bodylength" : 316, "key.bodyoffset" : 4317, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given flag was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given flag was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consumeBoolean(flag: Character) -> Bool", @@ -1464,6 +1604,11 @@ ], "key.bodylength" : 189, "key.bodyoffset" : 253, + "key.doc.abstract" : [ + { + "Para" : "Represents a value that can be converted from a command-line argument." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a value that can be converted from a command-line argument.", "key.doc.declaration" : "public protocol ArgumentProtocol", @@ -1492,6 +1637,11 @@ "key.annotated_decl" : "static var name: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 322, + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable name for this type.", "key.doc.declaration" : "static var name: String { get }", @@ -1519,19 +1669,24 @@ }, { "key.accessibility" : "source.lang.swift.accessibility.public", - "key.annotated_decl" : "static func from(string: String<\/Type>) -> `Self`?<\/Declaration>", + "key.annotated_decl" : "static func from(string: String<\/Type>) -> Self<\/Type>?<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Attempts to parse a value from the given command-line argument.", - "key.doc.declaration" : "static func from(string: String) -> `Self`?", + "key.doc.declaration" : "static func from(string: String) -> Self?", "key.doc.file" : "Sources\/Commandant\/ArgumentProtocol.swift", - "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> `Self`?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract><\/CommentParts><\/Function>", + "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> Self?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract><\/CommentParts><\/Function>", "key.doc.line" : 15, "key.doc.name" : "from(string:)", "key.doc.type" : "Function", "key.doclength" : 68, "key.docoffset" : 331, "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", - "key.fully_annotated_decl" : "static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> `Self`?<\/decl.function.returntype><\/decl.function.method.static>", + "key.fully_annotated_decl" : "static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> Self<\/ref.generic_type_param>?<\/decl.function.returntype><\/decl.function.method.static>", "key.kind" : "source.lang.swift.decl.function.method.static", "key.length" : 41, "key.name" : "from(string:)", @@ -1554,17 +1709,21 @@ "key.usr" : "s:10Commandant16ArgumentProtocolP" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "@frozen struct Int : FixedWidthInteger<\/Type>, SignedInteger<\/Type><\/Declaration>", "key.bodylength" : 113, "key.bodyoffset" : 478, - "key.doc.declaration" : "struct Int : FixedWidthInteger, SignedInteger", + "key.doc.abstract" : [ + { + "Para" : "A signed integer value type." + } + ], + "key.doc.declaration" : "@frozen struct Int : FixedWidthInteger, SignedInteger", "key.doc.discussion" : [ { "Para" : "On 32-bit platforms, `Int` is the same size as `Int32`, and on 64-bit platforms, `Int` is the same size as `Int64`." } ], - "key.doc.full_as_xml" : "Int<\/Name>s:Si<\/USR>struct Int : FixedWidthInteger, SignedInteger<\/Declaration>A signed integer value type.<\/Para><\/Abstract>On 32-bit platforms, Int<\/codeVoice> is the same size as Int32<\/codeVoice>, and on 64-bit platforms, Int<\/codeVoice> is the same size as Int64<\/codeVoice>.<\/Para><\/Discussion><\/CommentParts><\/Class>", + "key.doc.full_as_xml" : "Int<\/Name>s:Si<\/USR>@frozen struct Int : FixedWidthInteger, SignedInteger<\/Declaration>A signed integer value type.<\/Para><\/Abstract>On 32-bit platforms, Int<\/codeVoice> is the same size as Int32<\/codeVoice>, and on 64-bit platforms, Int<\/codeVoice> is the same size as Int64<\/codeVoice>.<\/Para><\/Discussion><\/CommentParts><\/Class>", "key.doc.name" : "Int", "key.doc.type" : "Class", "key.elements" : [ @@ -1603,6 +1762,11 @@ "key.offset" : 480 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.discussion" : [ @@ -1614,6 +1778,11 @@ "key.doc.full_as_xml" : "name<\/Name>s:10Commandant16ArgumentProtocolP4nameSSvpZ<\/USR>static var name: String { get }<\/Declaration>A human-readable name for this type.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 12, "key.doc.name" : "name", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> let<\/syntaxtype.keyword> name<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.static>", @@ -1648,17 +1817,27 @@ ], "key.bodylength" : 23, "key.bodyoffset" : 566, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, - "key.doc.declaration" : "static func from(string: String) -> `Self`?", + "key.doc.declaration" : "static func from(string: String) -> Self?", "key.doc.discussion" : [ { "Note" : "" } ], "key.doc.file" : "Sources\/Commandant\/ArgumentProtocol.swift", - "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> `Self`?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", + "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> Self?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 15, "key.doc.name" : "from(string:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> Int<\/ref.struct>?<\/decl.function.returntype><\/decl.function.method.static>", @@ -1690,23 +1869,27 @@ "key.usr" : "s:Si" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "@frozen struct String<\/Declaration>", "key.bodylength" : 110, "key.bodyoffset" : 630, - "key.doc.declaration" : "struct String", + "key.doc.abstract" : [ + { + "Para" : "A Unicode string value that is a collection of characters." + } + ], + "key.doc.declaration" : "@frozen struct String", "key.doc.discussion" : [ { "Para" : "A string is a series of characters, such as `\"Swift\"`, that forms a collection. Strings in Swift are Unicode correct and locale insensitive, and are designed to be efficient. The `String` type bridges with the Objective-C class `NSString` and offers interoperability with C functions that works with strings." }, { - "Para" : "You can create new strings using string literals or string interpolations. A is a series of characters enclosed in quotes." + "Para" : "You can create new strings using string literals or string interpolations. A _string literal_ is a series of characters enclosed in quotes." }, { "CodeListing" : "" }, { - "Para" : " are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." + "Para" : "_String interpolations_ are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." }, { "CodeListing" : "" @@ -1742,7 +1925,7 @@ "Para" : "Basic string operations are not sensitive to locale settings, ensuring that string comparisons and other operations always have a single, stable result, allowing strings to be used as keys in `Dictionary` instances and for other purposes." }, { - "Para" : "A string is a collection of , which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." + "Para" : "A string is a collection of _extended grapheme clusters_, which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." }, { "Para" : "For example, to retrieve the first word of a longer string, you can search for a space and then create a substring from a prefix of the string up to that point:" @@ -1808,7 +1991,7 @@ "Para" : "When you need to know the length of a string, you must first consider what youā€™ll use the length for. Are you measuring the number of characters that will be displayed on the screen, or are you measuring the amount of storage needed for the string in a particular encoding? A single string can have greatly differing lengths when measured by its different views." }, { - "Para" : "For example, an ASCII character like the capital letter is represented by a single element in each of its four views. The Unicode scalar value of is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." + "Para" : "For example, an ASCII character like the capital letter _A_ is represented by a single element in each of its four views. The Unicode scalar value of _A_ is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." }, { "CodeListing" : "" @@ -1853,19 +2036,19 @@ "CodeListing" : "" }, { - "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O() time and space." + "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O(_n_) time and space." }, { "Para" : "When a stringā€™s contiguous storage fills up, a new buffer must be allocated and data must be moved to the new storage. String buffers use an exponential growth strategy that makes appending to a string a constant time operation when averaged over many append operations." }, { - "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O() time and space, where is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." + "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O(_n_) time and space, where _n_ is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." }, { "Para" : "For more information about the Unicode terms used in this discussion, see the . In particular, this discussion mentions , , and ." } ], - "key.doc.full_as_xml" : "String<\/Name>s:SS<\/USR>struct String<\/Declaration>A Unicode string value that is a collection of characters.<\/Para><\/Abstract>A string is a series of characters, such as "Swift"<\/codeVoice>, that forms a collection. Strings in Swift are Unicode correct and locale insensitive, and are designed to be efficient. The String<\/codeVoice> type bridges with the Objective-C class NSString<\/codeVoice> and offers interoperability with C functions that works with strings.<\/Para>You can create new strings using string literals or string interpolations. A string literal<\/emphasis> is a series of characters enclosed in quotes.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>String interpolations<\/emphasis> are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Combine strings using the concatenation operator (+<\/codeVoice>).<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Multiline string literals are enclosed in three double quotation marks ("""<\/codeVoice>), with each delimiter on its own line. Indentation is stripped from each line of a multiline string literal to match the indentation of the closing delimiter.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Modifying and Comparing Strings]]><\/rawHTML>Strings always have value semantics. Modifying a copy of a string leaves the original unaffected.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Comparing strings for equality using the equal-to operator (==<\/codeVoice>) or a relational operator (like <<\/codeVoice> or >=<\/codeVoice>) is always performed using Unicode canonical representation. As a result, different representations of a string compare as being equal.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The Unicode scalar value "\\u{301}"<\/codeVoice> modifies the preceding character to include an accent, so "e\\u{301}"<\/codeVoice> has the same canonical representation as the single Unicode scalar value "Ć©"<\/codeVoice>.<\/Para>Basic string operations are not sensitive to locale settings, ensuring that string comparisons and other operations always have a single, stable result, allowing strings to be used as keys in Dictionary<\/codeVoice> instances and for other purposes.<\/Para>]]><\/rawHTML>Accessing String Elements]]><\/rawHTML>A string is a collection of extended grapheme clusters<\/emphasis>, which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift Character<\/codeVoice> type. Each element of a string is represented by a Character<\/codeVoice> instance.<\/Para>For example, to retrieve the first word of a longer string, you can search for a space and then create a substring from a prefix of the string up to that point:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The firstName<\/codeVoice> constant is an instance of the Substring<\/codeVoice> typeā€”a type that represents substrings of a string while sharing the original stringā€™s storage. Substrings present the same interface as strings.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Accessing a Stringā€™s Unicode Representation]]><\/rawHTML>If you need to access the contents of a string as encoded in different Unicode encodings, use one of the stringā€™s unicodeScalars<\/codeVoice>, utf16<\/codeVoice>, or utf8<\/codeVoice> properties. Each property provides access to a view of the string as a series of code units, each encoded in a different Unicode encoding.<\/Para>To demonstrate the different views available for every string, the following examples use this String<\/codeVoice> instance:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The cafe<\/codeVoice> string is a collection of the nine characters that are visible when the string is displayed.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Unicode Scalar View]]><\/rawHTML>A stringā€™s unicodeScalars<\/codeVoice> property is a collection of Unicode scalar values, the 21-bit codes that are the basic unit of Unicode. Each scalar value is represented by a Unicode.Scalar<\/codeVoice> instance and is equivalent to a UTF-32 code unit.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The unicodeScalars<\/codeVoice> viewā€™s elements comprise each Unicode scalar value in the cafe<\/codeVoice> string. In particular, because cafe<\/codeVoice> was declared using the decomposed form of the "Ć©"<\/codeVoice> character, unicodeScalars<\/codeVoice> contains the scalar values for both the letter "e"<\/codeVoice> (101) and the accent character "Ā“"<\/codeVoice> (769).<\/Para>]]><\/rawHTML>UTF-16 View]]><\/rawHTML>A stringā€™s utf16<\/codeVoice> property is a collection of UTF-16 code units, the 16-bit encoding form of the stringā€™s Unicode scalar values. Each code unit is stored as a UInt16<\/codeVoice> instance.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The elements of the utf16<\/codeVoice> view are the code units for the string when encoded in UTF-16. These elements match those accessed through indexed NSString<\/codeVoice> APIs.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>UTF-8 View]]><\/rawHTML>A stringā€™s utf8<\/codeVoice> property is a collection of UTF-8 code units, the 8-bit encoding form of the stringā€™s Unicode scalar values. Each code unit is stored as a UInt8<\/codeVoice> instance.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The elements of the utf8<\/codeVoice> view are the code units for the string when encoded in UTF-8. This representation matches the one used when String<\/codeVoice> instances are passed to C APIs.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Measuring the Length of a String]]><\/rawHTML>When you need to know the length of a string, you must first consider what youā€™ll use the length for. Are you measuring the number of characters that will be displayed on the screen, or are you measuring the amount of storage needed for the string in a particular encoding? A single string can have greatly differing lengths when measured by its different views.<\/Para>For example, an ASCII character like the capital letter A<\/emphasis> is represented by a single element in each of its four views. The Unicode scalar value of A<\/emphasis> is 65<\/codeVoice>, which is small enough to fit in a single code unit in both UTF-16 and UTF-8.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>On the other hand, an emoji flag character is constructed from a pair of Unicode scalar values, like "\\u{1F1F5}"<\/codeVoice> and "\\u{1F1F7}"<\/codeVoice>. Each of these scalar values, in turn, is too large to fit into a single UTF-16 or UTF-8 code unit. As a result, each view of the string "šŸ‡µšŸ‡·"<\/codeVoice> reports a different length.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>To check whether a string is empty, use its isEmpty<\/codeVoice> property instead of comparing the length of one of the views to 0<\/codeVoice>. Unlike with isEmpty<\/codeVoice>, calculating a viewā€™s count<\/codeVoice> property requires iterating through the elements of the string.<\/Para>]]><\/rawHTML>Accessing String View Elements]]><\/rawHTML>To find individual elements of a string, use the appropriate view for your task. For example, to retrieve the first word of a longer string, you can search the string for a space and then create a new string from a prefix of the string up to that point.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Strings and their views share indices, so you can access the UTF-8 view of the name<\/codeVoice> string using the same firstSpace<\/codeVoice> index.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Note that an index into one view may not have an exact corresponding position in another view. For example, the flag<\/codeVoice> string declared above comprises a single character, but is composed of eight code units when encoded as UTF-8. The following code creates constants for the first and second positions in the flag.utf8<\/codeVoice> view. Accessing the utf8<\/codeVoice> view with these indices yields the first and second code UTF-8 units.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>When used to access the elements of the flag<\/codeVoice> string itself, however, the secondCodeUnit<\/codeVoice> index does not correspond to the position of a specific character. Instead of only accessing the specific UTF-8 code unit, that index is treated as the position of the character at the indexā€™s encoded offset. In the case of secondCodeUnit<\/codeVoice>, that character is still the flag itself.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>If you need to validate that an index from one stringā€™s view corresponds with an exact position in another view, use the indexā€™s samePosition(in:)<\/codeVoice> method or the init(_:within:)<\/codeVoice> initializer.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Performance Optimizations]]><\/rawHTML>Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O(n<\/emphasis>) time and space.<\/Para>When a stringā€™s contiguous storage fills up, a new buffer must be allocated and data must be moved to the new storage. String buffers use an exponential growth strategy that makes appending to a string a constant time operation when averaged over many append operations.<\/Para>]]><\/rawHTML>Bridging Between String and NSString]]><\/rawHTML>Any String<\/codeVoice> instance can be bridged to NSString<\/codeVoice> using the type-cast operator (as<\/codeVoice>), and any String<\/codeVoice> instance that originates in Objective-C may use an NSString<\/codeVoice> instance as its storage. Because any arbitrary subclass of NSString<\/codeVoice> can become a String<\/codeVoice> instance, there are no guarantees about representation or efficiency when a String<\/codeVoice> instance is backed by NSString<\/codeVoice> storage. Because NSString<\/codeVoice> is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O(n<\/emphasis>) time and space, where n<\/emphasis> is the length of the stringā€™s encoded representation (or more, if the underlying NSString<\/codeVoice> has unusual performance characteristics).<\/Para>For more information about the Unicode terms used in this discussion, see the Unicode.org glossary<\/Link>. In particular, this discussion mentions extended grapheme clusters<\/Link>, Unicode scalar values<\/Link>, and canonical equivalence<\/Link>.<\/Para><\/Discussion><\/CommentParts><\/Class>", + "key.doc.full_as_xml" : "String<\/Name>s:SS<\/USR>@frozen struct String<\/Declaration>A Unicode string value that is a collection of characters.<\/Para><\/Abstract>A string is a series of characters, such as "Swift"<\/codeVoice>, that forms a collection. Strings in Swift are Unicode correct and locale insensitive, and are designed to be efficient. The String<\/codeVoice> type bridges with the Objective-C class NSString<\/codeVoice> and offers interoperability with C functions that works with strings.<\/Para>You can create new strings using string literals or string interpolations. A string literal<\/emphasis> is a series of characters enclosed in quotes.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>String interpolations<\/emphasis> are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Combine strings using the concatenation operator (+<\/codeVoice>).<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Multiline string literals are enclosed in three double quotation marks ("""<\/codeVoice>), with each delimiter on its own line. Indentation is stripped from each line of a multiline string literal to match the indentation of the closing delimiter.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Modifying and Comparing Strings]]><\/rawHTML>Strings always have value semantics. Modifying a copy of a string leaves the original unaffected.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Comparing strings for equality using the equal-to operator (==<\/codeVoice>) or a relational operator (like <<\/codeVoice> or >=<\/codeVoice>) is always performed using Unicode canonical representation. As a result, different representations of a string compare as being equal.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The Unicode scalar value "\\u{301}"<\/codeVoice> modifies the preceding character to include an accent, so "e\\u{301}"<\/codeVoice> has the same canonical representation as the single Unicode scalar value "Ć©"<\/codeVoice>.<\/Para>Basic string operations are not sensitive to locale settings, ensuring that string comparisons and other operations always have a single, stable result, allowing strings to be used as keys in Dictionary<\/codeVoice> instances and for other purposes.<\/Para>]]><\/rawHTML>Accessing String Elements]]><\/rawHTML>A string is a collection of extended grapheme clusters<\/emphasis>, which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift Character<\/codeVoice> type. Each element of a string is represented by a Character<\/codeVoice> instance.<\/Para>For example, to retrieve the first word of a longer string, you can search for a space and then create a substring from a prefix of the string up to that point:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The firstName<\/codeVoice> constant is an instance of the Substring<\/codeVoice> typeā€”a type that represents substrings of a string while sharing the original stringā€™s storage. Substrings present the same interface as strings.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Accessing a Stringā€™s Unicode Representation]]><\/rawHTML>If you need to access the contents of a string as encoded in different Unicode encodings, use one of the stringā€™s unicodeScalars<\/codeVoice>, utf16<\/codeVoice>, or utf8<\/codeVoice> properties. Each property provides access to a view of the string as a series of code units, each encoded in a different Unicode encoding.<\/Para>To demonstrate the different views available for every string, the following examples use this String<\/codeVoice> instance:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The cafe<\/codeVoice> string is a collection of the nine characters that are visible when the string is displayed.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Unicode Scalar View]]><\/rawHTML>A stringā€™s unicodeScalars<\/codeVoice> property is a collection of Unicode scalar values, the 21-bit codes that are the basic unit of Unicode. Each scalar value is represented by a Unicode.Scalar<\/codeVoice> instance and is equivalent to a UTF-32 code unit.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The unicodeScalars<\/codeVoice> viewā€™s elements comprise each Unicode scalar value in the cafe<\/codeVoice> string. In particular, because cafe<\/codeVoice> was declared using the decomposed form of the "Ć©"<\/codeVoice> character, unicodeScalars<\/codeVoice> contains the scalar values for both the letter "e"<\/codeVoice> (101) and the accent character "Ā“"<\/codeVoice> (769).<\/Para>]]><\/rawHTML>UTF-16 View]]><\/rawHTML>A stringā€™s utf16<\/codeVoice> property is a collection of UTF-16 code units, the 16-bit encoding form of the stringā€™s Unicode scalar values. Each code unit is stored as a UInt16<\/codeVoice> instance.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The elements of the utf16<\/codeVoice> view are the code units for the string when encoded in UTF-16. These elements match those accessed through indexed NSString<\/codeVoice> APIs.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>UTF-8 View]]><\/rawHTML>A stringā€™s utf8<\/codeVoice> property is a collection of UTF-8 code units, the 8-bit encoding form of the stringā€™s Unicode scalar values. Each code unit is stored as a UInt8<\/codeVoice> instance.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The elements of the utf8<\/codeVoice> view are the code units for the string when encoded in UTF-8. This representation matches the one used when String<\/codeVoice> instances are passed to C APIs.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Measuring the Length of a String]]><\/rawHTML>When you need to know the length of a string, you must first consider what youā€™ll use the length for. Are you measuring the number of characters that will be displayed on the screen, or are you measuring the amount of storage needed for the string in a particular encoding? A single string can have greatly differing lengths when measured by its different views.<\/Para>For example, an ASCII character like the capital letter A<\/emphasis> is represented by a single element in each of its four views. The Unicode scalar value of A<\/emphasis> is 65<\/codeVoice>, which is small enough to fit in a single code unit in both UTF-16 and UTF-8.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>On the other hand, an emoji flag character is constructed from a pair of Unicode scalar values, like "\\u{1F1F5}"<\/codeVoice> and "\\u{1F1F7}"<\/codeVoice>. Each of these scalar values, in turn, is too large to fit into a single UTF-16 or UTF-8 code unit. As a result, each view of the string "šŸ‡µšŸ‡·"<\/codeVoice> reports a different length.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>To check whether a string is empty, use its isEmpty<\/codeVoice> property instead of comparing the length of one of the views to 0<\/codeVoice>. Unlike with isEmpty<\/codeVoice>, calculating a viewā€™s count<\/codeVoice> property requires iterating through the elements of the string.<\/Para>]]><\/rawHTML>Accessing String View Elements]]><\/rawHTML>To find individual elements of a string, use the appropriate view for your task. For example, to retrieve the first word of a longer string, you can search the string for a space and then create a new string from a prefix of the string up to that point.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Strings and their views share indices, so you can access the UTF-8 view of the name<\/codeVoice> string using the same firstSpace<\/codeVoice> index.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>Note that an index into one view may not have an exact corresponding position in another view. For example, the flag<\/codeVoice> string declared above comprises a single character, but is composed of eight code units when encoded as UTF-8. The following code creates constants for the first and second positions in the flag.utf8<\/codeVoice> view. Accessing the utf8<\/codeVoice> view with these indices yields the first and second code UTF-8 units.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>When used to access the elements of the flag<\/codeVoice> string itself, however, the secondCodeUnit<\/codeVoice> index does not correspond to the position of a specific character. Instead of only accessing the specific UTF-8 code unit, that index is treated as the position of the character at the indexā€™s encoded offset. In the case of secondCodeUnit<\/codeVoice>, that character is still the flag itself.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>If you need to validate that an index from one stringā€™s view corresponds with an exact position in another view, use the indexā€™s samePosition(in:)<\/codeVoice> method or the init(_:within:)<\/codeVoice> initializer.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>]]><\/rawHTML>Performance Optimizations]]><\/rawHTML>Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O(n<\/emphasis>) time and space.<\/Para>When a stringā€™s contiguous storage fills up, a new buffer must be allocated and data must be moved to the new storage. String buffers use an exponential growth strategy that makes appending to a string a constant time operation when averaged over many append operations.<\/Para>]]><\/rawHTML>Bridging Between String and NSString]]><\/rawHTML>Any String<\/codeVoice> instance can be bridged to NSString<\/codeVoice> using the type-cast operator (as<\/codeVoice>), and any String<\/codeVoice> instance that originates in Objective-C may use an NSString<\/codeVoice> instance as its storage. Because any arbitrary subclass of NSString<\/codeVoice> can become a String<\/codeVoice> instance, there are no guarantees about representation or efficiency when a String<\/codeVoice> instance is backed by NSString<\/codeVoice> storage. Because NSString<\/codeVoice> is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O(n<\/emphasis>) time and space, where n<\/emphasis> is the length of the stringā€™s encoded representation (or more, if the underlying NSString<\/codeVoice> has unusual performance characteristics).<\/Para>For more information about the Unicode terms used in this discussion, see the Unicode.org glossary<\/Link>. In particular, this discussion mentions extended grapheme clusters<\/Link>, Unicode scalar values<\/Link>, and canonical equivalence<\/Link>.<\/Para><\/Discussion><\/CommentParts><\/Class>", "key.doc.name" : "String", "key.doc.type" : "Class", "key.elements" : [ @@ -1904,6 +2087,11 @@ "key.offset" : 632 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.discussion" : [ @@ -1915,6 +2103,11 @@ "key.doc.full_as_xml" : "name<\/Name>s:10Commandant16ArgumentProtocolP4nameSSvpZ<\/USR>static var name: String { get }<\/Declaration>A human-readable name for this type.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 12, "key.doc.name" : "name", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> let<\/syntaxtype.keyword> name<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.static>", @@ -1949,17 +2142,27 @@ ], "key.bodylength" : 18, "key.bodyoffset" : 720, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, - "key.doc.declaration" : "static func from(string: String) -> `Self`?", + "key.doc.declaration" : "static func from(string: String) -> Self?", "key.doc.discussion" : [ { "Note" : "" } ], "key.doc.file" : "Sources\/Commandant\/ArgumentProtocol.swift", - "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> `Self`?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", + "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> Self?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 15, "key.doc.name" : "from(string:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> String<\/ref.struct>?<\/decl.function.returntype><\/decl.function.method.static>", @@ -1991,10 +2194,14 @@ "key.usr" : "s:SS" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 826, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -2013,7 +2220,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2083,7 +2290,7 @@ "key.parsed_scope.start" : 35, "key.related_decls" : [ { - "key.annotated_decl" : "from(string: String) -> `Self`?<\/RelatedName>" + "key.annotated_decl" : "from(string: String) -> Self?<\/RelatedName>" }, { "key.annotated_decl" : "from(string: String) -> Self?<\/RelatedName>" @@ -2102,10 +2309,14 @@ "key.usr" : "s:SY" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 1027, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -2124,7 +2335,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2194,7 +2405,7 @@ "key.parsed_scope.start" : 41, "key.related_decls" : [ { - "key.annotated_decl" : "from(string: String) -> `Self`?<\/RelatedName>" + "key.annotated_decl" : "from(string: String) -> Self?<\/RelatedName>" }, { "key.annotated_decl" : "from(string: String) -> Self?<\/RelatedName>" @@ -2232,6 +2443,11 @@ ], "key.bodylength" : 483, "key.bodyoffset" : 280, + "key.doc.abstract" : [ + { + "Para" : "Represents a subcommand that can be executed with its own set of arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a subcommand that can be executed with its own set of arguments.", "key.doc.declaration" : "public protocol CommandProtocol", @@ -2258,6 +2474,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "associatedtype Options : OptionsProtocol<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.comment" : "The command's options type.", "key.doc.declaration" : "associatedtype Options : Commandant.OptionsProtocol", @@ -2306,6 +2527,11 @@ "key.annotated_decl" : "var verb: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 532, + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.comment" : "The action that users should specify to use this subcommand (e.g.,\n`help`).", "key.doc.declaration" : "var verb: String { get }", @@ -2336,6 +2562,11 @@ "key.annotated_decl" : "var function: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 648, + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.comment" : "A human-readable, high-level description of what this command is used\nfor.", "key.doc.declaration" : "var function: String { get }", @@ -2364,6 +2595,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "func run(_ options: Options<\/Type>) -> Result<\/Type><(), ClientError<\/Type>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Runs this subcommand with the given options.", "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", @@ -2409,6 +2645,11 @@ ], "key.bodylength" : 957, "key.bodyoffset" : 843, + "key.doc.abstract" : [ + { + "Para" : "A type-erased command." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A type-erased command.", "key.doc.declaration" : "public struct CommandWrapper where ClientError : Error", @@ -2572,6 +2813,11 @@ ], "key.bodylength" : 633, "key.bodyoffset" : 1165, + "key.doc.abstract" : [ + { + "Para" : "Creates a command that wraps another." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Creates a command that wraps another.", "key.doc.declaration" : "fileprivate init(_ command: C) where ClientError == C.ClientError, C : Commandant.CommandProtocol", @@ -2645,6 +2891,11 @@ ], "key.bodylength" : 216, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Describes the \"mode\" in which a command should run.", "key.doc.declaration" : "public enum CommandMode", @@ -2677,6 +2928,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case arguments(ArgumentParser<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Options should be parsed from the given command-line arguments." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Options should be parsed from the given command-line arguments.", "key.doc.declaration" : "", @@ -2698,6 +2954,9 @@ "key.parsed_declaration" : "case arguments(ArgumentParser)", "key.parsed_scope.end" : 70, "key.parsed_scope.start" : 70, + "key.substructure" : [ + + ], "key.typename" : "(CommandMode.Type) -> (ArgumentParser) -> CommandMode", "key.typeusr" : "$sy10Commandant11CommandModeOAA14ArgumentParserCcACmcD", "key.usr" : "s:10Commandant11CommandModeO9argumentsyAcA14ArgumentParserCcACmF" @@ -2714,6 +2973,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usage<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Each option should record its usage information in an error, for presentation to the user." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Each option should record its usage information in an error, for\npresentation to the user.", "key.doc.declaration" : "", @@ -2763,6 +3027,11 @@ ], "key.bodylength" : 1204, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Maintains the list of commands available to run.", "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", @@ -2816,7 +3085,7 @@ }, { "key.accessibility" : "source.lang.swift.accessibility.private", - "key.annotated_decl" : "private var commandsByVerb: [String<\/Type> : CommandWrapper<\/Type><ClientError>]<\/Declaration>", + "key.annotated_decl" : "private var commandsByVerb: [String<\/Type> : CommandWrapper<\/Type><ClientError<\/Type>>]<\/Declaration>", "key.attributes" : [ { "key.attribute" : "source.decl.attribute.private", @@ -2825,7 +3094,7 @@ } ], "key.filepath" : "Sources\/Commandant\/Command.swift", - "key.fully_annotated_decl" : "private<\/syntaxtype.keyword> var<\/syntaxtype.keyword> commandsByVerb<\/decl.name>: [String<\/ref.struct> : CommandWrapper<\/ref.struct><ClientError>]<\/decl.var.type><\/decl.var.instance>", + "key.fully_annotated_decl" : "private<\/syntaxtype.keyword> var<\/syntaxtype.keyword> commandsByVerb<\/decl.name>: [String<\/ref.struct> : CommandWrapper<\/ref.struct><ClientError<\/ref.generic_type_param>>]<\/decl.var.type><\/decl.var.instance>", "key.kind" : "source.lang.swift.decl.var.instance", "key.length" : 63, "key.name" : "commandsByVerb", @@ -2852,6 +3121,11 @@ ], "key.bodylength" : 69, "key.bodyoffset" : 2369, + "key.doc.abstract" : [ + { + "Para" : "All available commands." + } + ], "key.doc.column" : 13, "key.doc.comment" : "All available commands.", "key.doc.declaration" : "public var commands: [CommandWrapper] { get }", @@ -2921,6 +3195,11 @@ ], "key.bodylength" : 106, "key.bodyoffset" : 2775, + "key.doc.abstract" : [ + { + "Para" : "Registers the given commands, making those available to run." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Registers the given commands, making those available to run.\n\nIf another commands were already registered with the same `verb`s, those\nwill be overwritten.", "key.doc.declaration" : "public func register(_ commands: C...) -> CommandRegistry where ClientError == C.ClientError, C : Commandant.CommandProtocol", @@ -2994,6 +3273,11 @@ ], "key.bodylength" : 54, "key.bodyoffset" : 3164, + "key.doc.abstract" : [ + { + "Para" : "Runs the command corresponding to the given verb, passing it the given arguments." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Runs the command corresponding to the given verb, passing it the given\narguments.\n\nReturns the results of the execution, or nil if no such command exists.", "key.doc.declaration" : "public func run(command verb: String, arguments: [String]) -> Result<(), CommandantError>?", @@ -3039,6 +3323,11 @@ ], "key.bodylength" : 32, "key.bodyoffset" : 3382, + "key.doc.abstract" : [ + { + "Para" : "Returns the command matching the given verb, or nil if no such command is registered." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Returns the command matching the given verb, or nil if no such command\nis registered.", "key.doc.declaration" : "public subscript(verb: String) -> CommandWrapper? { get }", @@ -3073,10 +3362,14 @@ "key.usr" : "s:10Commandant15CommandRegistryC" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public final class CommandRegistry<ClientError> where ClientError : Error<\/Type><\/Declaration>", "key.bodylength" : 4074, "key.bodyoffset" : 3446, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -3108,6 +3401,11 @@ ], "key.bodylength" : 97, "key.bodyoffset" : 4332, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3167,6 +3465,11 @@ ], "key.bodylength" : 945, "key.bodyoffset" : 5328, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing `arguments` and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing `arguments`\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(arguments: [String], defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3276,6 +3579,11 @@ ], "key.bodylength" : 933, "key.bodyoffset" : 6585, + "key.doc.abstract" : [ + { + "Para" : "Finds and executes a subcommand which exists in your $PATH. The executable name must be in the form of `executable-verb`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Finds and executes a subcommand which exists in your $PATH. The executable\nname must be in the form of `executable-verb`.\n\n- Returns: The exit status of found subcommand or nil.", "key.doc.declaration" : "private func executeSubcommandIfExists(_ executableName: String, verb: String, arguments: [String]) -> Int32?", @@ -3406,6 +3714,11 @@ ], "key.bodylength" : 157, "key.bodyoffset" : 372, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Possible errors that can originate from Commandant.\n\n`ClientError` should be the type of error (if any) that can occur when\nrunning commands.", "key.doc.declaration" : "public enum CommandantError : Error", @@ -3472,6 +3785,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usageError(description: String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An option was used incorrectly." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An option was used incorrectly.", "key.doc.declaration" : "", @@ -3493,6 +3811,9 @@ "key.parsed_declaration" : "case usageError(description: String)", "key.parsed_scope.end" : 17, "key.parsed_scope.start" : 17, + "key.substructure" : [ + + ], "key.typename" : " (CommandantError.Type) -> (String) -> CommandantError", "key.typeusr" : "$sy10Commandant0A5ErrorOyxGSS_tcADmcluD", "key.usr" : "s:10Commandant0A5ErrorO05usageB0yACyxGSS_tcAEmlF" @@ -3509,6 +3830,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case commandError(ClientError<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An error occurred while running a command." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An error occurred while running a command.", "key.doc.declaration" : "", @@ -3530,6 +3856,9 @@ "key.parsed_declaration" : "case commandError(ClientError)", "key.parsed_scope.end" : 20, "key.parsed_scope.start" : 20, + "key.substructure" : [ + + ], "key.typename" : " (CommandantError.Type) -> (ClientError) -> CommandantError", "key.typeusr" : "$sy10Commandant0A5ErrorOyxGxcADmcluD", "key.usr" : "s:10Commandant0A5ErrorO07commandB0yACyxGxcAEmlF" @@ -3542,10 +3871,14 @@ "key.usr" : "s:10Commandant0A5ErrorO" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public enum CommandantError<ClientError> : Error<\/Type><\/Declaration>", "key.bodylength" : 187, "key.bodyoffset" : 584, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandantError : Error", "key.doc.discussion" : [ @@ -3594,6 +3927,11 @@ ], "key.bodylength" : 151, "key.bodyoffset" : 618, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -3611,6 +3949,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Errors.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -3649,6 +3992,11 @@ ], "key.bodylength" : 105, "key.bodyoffset" : 992, + "key.doc.abstract" : [ + { + "Para" : "Constructs an `InvalidArgument` error that indicates a missing value for the argument by the given name." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an `InvalidArgument` error that indicates a missing value for\nthe argument by the given name.", "key.doc.declaration" : "internal func missingArgumentError(_ argumentName: String) -> CommandantError", @@ -3722,6 +4070,11 @@ ], "key.bodylength" : 179, "key.bodyoffset" : 1339, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error by combining the example of key (and value, if applicable) with the usage description." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error by combining the example of key (and value, if applicable)\nwith the usage description.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, usage: String) -> CommandantError", @@ -3824,6 +4177,11 @@ ], "key.bodylength" : 265, "key.bodyoffset" : 1813, + "key.doc.abstract" : [ + { + "Para" : "Combines the text of the two errors, if theyā€™re both `UsageError`s. Otherwise, uses whichever one is not (biased toward the left)." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Combines the text of the two errors, if they're both `UsageError`s.\nOtherwise, uses whichever one is not (biased toward the left).", "key.doc.declaration" : "internal func combineUsageErrors(_ lhs: CommandantError, _ rhs: CommandantError) -> CommandantError", @@ -3880,6 +4238,11 @@ ], "key.bodylength" : 96, "key.bodyoffset" : 2260, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that indicates unrecognized arguments remains." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that indicates unrecognized arguments remains.", "key.doc.declaration" : "internal func unrecognizedArgumentsError(_ options: [String]) -> CommandantError", @@ -3944,6 +4307,11 @@ ], "key.bodylength" : 192, "key.bodyoffset" : 2631, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument, with the given example of value usage if applicable." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument, with the given\nexample of value usage if applicable.", "key.doc.declaration" : "internal func informativeUsageError(_ valueExample: String, argument: Argument) -> CommandantError", @@ -4046,6 +4414,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3018, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4194,6 +4567,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3598, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument list." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument list.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument<[T]>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4350,6 +4728,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 4257, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option, with the given example of key (and value, if applicable) usage." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option, with the given\nexample of key (and value, if applicable) usage.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, option: Option) -> CommandantError", @@ -4452,6 +4835,11 @@ ], "key.bodylength" : 89, "key.bodyoffset" : 4522, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4566,6 +4954,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 4801, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4680,6 +5073,11 @@ ], "key.bodylength" : 91, "key.bodyoffset" : 5070, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4794,6 +5192,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 5353, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]?>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4908,6 +5311,11 @@ ], "key.bodylength" : 121, "key.bodyoffset" : 5616, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the given boolean option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the given boolean option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError", @@ -5018,6 +5426,11 @@ ], "key.bodylength" : 1127, "key.bodyoffset" : 601, + "key.doc.abstract" : [ + { + "Para" : "A basic implementation of a `help` command, using information available in a `CommandRegistry`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A basic implementation of a `help` command, using information available in a\n`CommandRegistry`.\n\nIf you want to use this command, initialize it with the registry, then add\nit to that same registry:\n\n\tlet commands: CommandRegistry = ā€¦\n\tlet helpCommand = HelpCommand(registry: commands)\n\tcommands.register(helpCommand)", "key.doc.declaration" : "public struct HelpCommand : CommandProtocol where ClientError : Error", @@ -5099,6 +5512,11 @@ "key.offset" : 603 } ], + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "associatedtype Options : Commandant.OptionsProtocol", "key.doc.discussion" : [ @@ -5110,6 +5528,11 @@ "key.doc.full_as_xml" : "Options<\/Name>s:10Commandant15CommandProtocolP7OptionsQa<\/USR>associatedtype Options : Commandant.OptionsProtocol<\/Declaration>The commandā€™s options type.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 15, "key.doc.name" : "Options", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> typealias<\/syntaxtype.keyword> HelpCommand<\/ref.struct><ClientError>.Options<\/decl.name> = HelpOptions<\/ref.struct><ClientError<\/ref.generic_type_param>><\/decl.typealias>", @@ -5141,6 +5564,11 @@ "key.offset" : 657 } ], + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var verb: String { get }", "key.doc.discussion" : [ @@ -5152,6 +5580,11 @@ "key.doc.full_as_xml" : "verb<\/Name>s:10Commandant15CommandProtocolP4verbSSvp<\/USR>var verb: String { get }<\/Declaration>The action that users should specify to use this subcommand (e.g., help<\/codeVoice>).<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 21, "key.doc.name" : "verb", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> let<\/syntaxtype.keyword> verb<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.instance>", @@ -5183,6 +5616,11 @@ "key.offset" : 683 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var function: String { get }", "key.doc.discussion" : [ @@ -5194,6 +5632,11 @@ "key.doc.full_as_xml" : "function<\/Name>s:10Commandant15CommandProtocolP8functionSSvp<\/USR>var function: String { get }<\/Declaration>A human-readable, high-level description of what this command is used for.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 25, "key.doc.name" : "function", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> let<\/syntaxtype.keyword> function<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.instance>", @@ -5252,6 +5695,11 @@ ], "key.bodylength" : 102, "key.bodyoffset" : 931, + "key.doc.abstract" : [ + { + "Para" : "Initializes the command to provide help from the given registry of commands." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the command to provide help from the given registry of\ncommands.", "key.doc.declaration" : "public init(registry: CommandRegistry, function: String? = nil)", @@ -5292,6 +5740,11 @@ ], "key.bodylength" : 625, "key.bodyoffset" : 1101, + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", "key.doc.discussion" : [ @@ -5303,6 +5756,11 @@ "key.doc.full_as_xml" : "run(_:)<\/Name>s:10Commandant15CommandProtocolP3runys6ResultOyyt11ClientErrorQzG7OptionsQzF<\/USR>func run(_ options: Options) -> Result<(), ClientError><\/Declaration>Runs this subcommand with the given options.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 28, "key.doc.name" : "run(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> func<\/syntaxtype.keyword> run<\/decl.name>(_<\/decl.var.parameter.argument_label> options<\/decl.var.parameter.name>: Options<\/ref.typealias><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><()<\/tuple>, ClientError<\/ref.generic_type_param>><\/decl.function.returntype><\/decl.function.method.instance>", @@ -5510,6 +5968,11 @@ ], "key.bodylength" : 99, "key.bodyoffset" : 2100, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5524,6 +5987,11 @@ "key.doc.full_as_xml" : "evaluate(_:)<\/Name>s:10Commandant15OptionsProtocolP8evaluateys6ResultOyxAA0A5ErrorOy06ClientF0QzGGAA11CommandModeOFZ<\/USR>static func evaluate(_ m: CommandMode) -> Result<Self, CommandantError<ClientError>><\/Declaration>Evaluates this set of options in the given mode.<\/Para><\/Abstract>Returns the parsed options or a UsageError<\/codeVoice>.<\/Para>This documentation comment was inherited from OptionsProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 43, "key.doc.name" : "evaluate(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `OptionsProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> evaluate<\/decl.name>(_<\/decl.var.parameter.argument_label> m<\/decl.var.parameter.name>: CommandMode<\/ref.enum><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><HelpOptions<\/ref.struct>, CommandantError<\/ref.enum><ClientError<\/ref.generic_type_param>>><\/decl.function.returntype><\/decl.function.method.static>", @@ -5573,6 +6041,11 @@ ], "key.bodylength" : 233, "key.bodyoffset" : 1421, + "key.doc.abstract" : [ + { + "Para" : "Represents a record of options for a command, which can be parsed from a list of command-line arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a record of options for a command, which can be parsed from\na list of command-line arguments.\n\nThis is most helpful when used in conjunction with the `Option` and `Switch`\ntypes, and `<*>` and `<|` combinators.\n\nExample:\n\n\tstruct LogOptions: OptionsProtocol {\n\t\tlet verbosity: Int\n\t\tlet outputFilename: String\n\t\tlet shouldDelete: Bool\n\t\tlet logName: String\n\n\t\tstatic func create(_ verbosity: Int) -> (String) -> (Bool) -> (String) -> LogOptions {\n\t\t\treturn { outputFilename in { shouldDelete in { logName in LogOptions(verbosity: verbosity, outputFilename: outputFilename, shouldDelete: shouldDelete, logName: logName) } } }\n\t\t}\n\n\t\tstatic func evaluate(_ m: CommandMode) -> Result> {\n\t\t\treturn create\n\t\t\t\t<*> m <| Option(key: \"verbose\", defaultValue: 0, usage: \"the verbosity level with which to read the logs\")\n\t\t\t\t<*> m <| Option(key: \"outputFilename\", defaultValue: \"\", usage: \"a file to print output to, instead of stdout\")\n\t\t\t\t<*> m <| Switch(flag: \"d\", key: \"delete\", usage: \"delete the logs when finished\")\n\t\t\t\t<*> m <| Argument(usage: \"the log to read\")\n\t\t}\n\t}", "key.doc.declaration" : "public protocol OptionsProtocol", @@ -5628,6 +6101,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "static func evaluate(_ m: CommandMode<\/Type>) -> Result<\/Type><Self<\/Type>, CommandantError<\/Type><ClientError<\/Type>>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Evaluates this set of options in the given mode.\n\nReturns the parsed options or a `UsageError`.", "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", @@ -5678,6 +6156,11 @@ ], "key.bodylength" : 154, "key.bodyoffset" : 1765, + "key.doc.abstract" : [ + { + "Para" : "An `OptionsProtocol` that has no options." + } + ], "key.doc.column" : 15, "key.doc.comment" : "An `OptionsProtocol` that has no options.", "key.doc.declaration" : "public struct NoOptions : OptionsProtocol where ClientError : Error", @@ -5780,6 +6263,11 @@ ], "key.bodylength" : 33, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5794,6 +6282,11 @@ "key.doc.full_as_xml" : "evaluate(_:)<\/Name>s:10Commandant15OptionsProtocolP8evaluateys6ResultOyxAA0A5ErrorOy06ClientF0QzGGAA11CommandModeOFZ<\/USR>static func evaluate(_ m: CommandMode) -> Result<Self, CommandantError<ClientError>><\/Declaration>Evaluates this set of options in the given mode.<\/Para><\/Abstract>Returns the parsed options or a UsageError<\/codeVoice>.<\/Para>This documentation comment was inherited from OptionsProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 43, "key.doc.name" : "evaluate(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `OptionsProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/Option.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> evaluate<\/decl.name>(_<\/decl.var.parameter.argument_label> m<\/decl.var.parameter.name>: CommandMode<\/ref.enum><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><NoOptions<\/ref.struct>, CommandantError<\/ref.enum><ClientError<\/ref.generic_type_param>>><\/decl.function.returntype><\/decl.function.method.static>", @@ -5835,6 +6328,11 @@ ], "key.bodylength" : 786, "key.bodyoffset" : 2013, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an option that can be provided on the command line.", "key.doc.declaration" : "public struct Option", @@ -5884,6 +6382,11 @@ "key.offset" : 2132 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that controls this option. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that controls this option. For example, a key of `verbose` would\nbe used for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -5919,6 +6422,11 @@ "key.offset" : 2303 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this option. This is the value that will be used if the option is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this option. This is the value that will be used\nif the option is never explicitly specified on the command line.", "key.doc.declaration" : "public let defaultValue: T", @@ -5954,12 +6462,17 @@ "key.offset" : 2637 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.\n\nFor boolean operations, this should describe the effect of _not_ using\nthe default value (i.e., what will happen if you disable\/enable the flag\ndifferently from the default).", "key.doc.declaration" : "public let usage: String", "key.doc.discussion" : [ { - "Para" : "For boolean operations, this should describe the effect of using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." + "Para" : "For boolean operations, this should describe the effect of _not_ using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." } ], "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -6020,10 +6533,14 @@ "key.usr" : "s:10Commandant6OptionV" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public struct Option<T><\/Declaration>", "key.bodylength" : 58, "key.bodyoffset" : 2845, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Option", "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -6067,6 +6584,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 2879, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -6084,6 +6606,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Option.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -6130,6 +6657,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 4545, + "key.doc.abstract" : [ + { + "Para" : "Applies `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: (T) -> U, value: Result>) -> Result>", @@ -6230,6 +6762,11 @@ ], "key.bodylength" : 346, "key.bodyoffset" : 4978, + "key.doc.abstract" : [ + { + "Para" : "Applies the function in `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies the function in `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: Result<((T) -> U), CommandantError>, value: Result>) -> Result>", @@ -6319,10 +6856,14 @@ "key.usr" : "s:10Commandant3lmgoiys6ResultOyq_AA0A5ErrorOyq0_GGADyq_xcAGG_ADyxAGGtr1_lF" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 4309, "key.bodyoffset" : 5350, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -6354,6 +6895,11 @@ ], "key.bodylength" : 230, "key.bodyoffset" : 5677, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : Commandant.ArgumentProtocol", @@ -6484,6 +7030,11 @@ ], "key.bodylength" : 852, "key.bodyoffset" : 6216, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : Commandant.ArgumentProtocol", @@ -6614,6 +7165,11 @@ ], "key.bodylength" : 232, "key.bodyoffset" : 7401, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]>) -> Result<[T], CommandantError> where T : Commandant.ArgumentProtocol", @@ -6744,6 +7300,11 @@ ], "key.bodylength" : 1117, "key.bodyoffset" : 7946, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]?>) -> Result<[T]?, CommandantError> where T : Commandant.ArgumentProtocol", @@ -6874,6 +7435,11 @@ ], "key.bodylength" : 272, "key.bodyoffset" : 9385, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result>", @@ -6971,6 +7537,11 @@ ], "key.bodylength" : 348, "key.bodyoffset" : 82, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.comment" : "A poor man's ordered set.", "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", @@ -7036,7 +7607,7 @@ }, { "key.accessibility" : "source.lang.swift.accessibility.fileprivate", - "key.annotated_decl" : "fileprivate var values: [T]<\/Declaration>", + "key.annotated_decl" : "fileprivate var values: [T<\/Type>]<\/Declaration>", "key.attributes" : [ { "key.attribute" : "source.decl.attribute.fileprivate", @@ -7045,7 +7616,7 @@ } ], "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", - "key.fully_annotated_decl" : "fileprivate<\/syntaxtype.keyword> var<\/syntaxtype.keyword> values<\/decl.name>: [T]<\/decl.var.type><\/decl.var.instance>", + "key.fully_annotated_decl" : "fileprivate<\/syntaxtype.keyword> var<\/syntaxtype.keyword> values<\/decl.name>: [T<\/ref.generic_type_param>]<\/decl.var.type><\/decl.var.instance>", "key.kind" : "source.lang.swift.decl.var.instance", "key.length" : 20, "key.name" : "values", @@ -7113,7 +7684,7 @@ }, { "key.accessibility" : "source.lang.swift.accessibility.internal", - "key.annotated_decl" : "@discardableResult mutating func remove(_ member: T<\/Type>) -> T<\/Type>?<\/Declaration>", + "key.annotated_decl" : "@discardableResult mutating mutating func remove(_ member: T<\/Type>) -> T<\/Type>?<\/Declaration>", "key.attributes" : [ { "key.attribute" : "source.decl.attribute.mutating", @@ -7129,7 +7700,7 @@ "key.bodylength" : 115, "key.bodyoffset" : 313, "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", - "key.fully_annotated_decl" : "@discardableResult<\/syntaxtype.attribute.name><\/syntaxtype.attribute.builtin> mutating<\/syntaxtype.keyword> func<\/syntaxtype.keyword> remove<\/decl.name>(_<\/decl.var.parameter.argument_label> member<\/decl.var.parameter.name>: T<\/ref.generic_type_param><\/decl.var.parameter.type><\/decl.var.parameter>) -> T<\/ref.generic_type_param>?<\/decl.function.returntype><\/decl.function.method.instance>", + "key.fully_annotated_decl" : "@discardableResult<\/syntaxtype.attribute.name><\/syntaxtype.attribute.builtin> mutating<\/syntaxtype.keyword> mutating<\/syntaxtype.keyword> func<\/syntaxtype.keyword> remove<\/decl.name>(_<\/decl.var.parameter.argument_label> member<\/decl.var.parameter.name>: T<\/ref.generic_type_param><\/decl.var.parameter.type><\/decl.var.parameter>) -> T<\/ref.generic_type_param>?<\/decl.function.returntype><\/decl.function.method.instance>", "key.kind" : "source.lang.swift.decl.function.method.instance", "key.length" : 148, "key.name" : "remove(_:)", @@ -7152,10 +7723,14 @@ "key.usr" : "s:10Commandant10OrderedSetV" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "internal struct OrderedSet<T> : Equatable<\/Type> where T : Hashable<\/Type><\/Declaration>", "key.bodylength" : 331, "key.bodyoffset" : 467, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", "key.doc.file" : "Sources\/Commandant\/OrderedSet.swift", @@ -7188,10 +7763,19 @@ "key.parsed_scope.start" : 21, "key.substructure" : [ { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "subscript(position: Int<\/Type>) -> T<\/Type> { get }<\/Declaration>", "key.bodylength" : 28, "key.bodyoffset" : 500, + "key.doc.abstract" : [ + { + "Para" : "Accesses the element at the specified position." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "subscript(position: Self.Index) -> Self.Element { get }", "key.doc.discussion" : [ { @@ -7212,6 +7796,11 @@ ], "key.doc.full_as_xml" : "subscript(_:)<\/Name>s:Sly7ElementQz5IndexQzcip<\/USR>subscript(position: Self.Index) -> Self.Element { get }<\/Declaration>Accesses the element at the specified position.<\/Para><\/Abstract>position<\/Name>in<\/Direction>The position of the element to access. position<\/codeVoice> must be a valid index of the collection that is not equal to the endIndex<\/codeVoice> property.<\/Para><\/Discussion><\/Parameter><\/Parameters>The following example accesses an element of an array through its subscript to print its value:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>You can subscript a collection with any valid index other than the collectionā€™s end index. The end index refers to the position one past the last element of a collection, so it doesnā€™t correspond with an element.<\/Para>O(1)<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "subscript(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.parameters" : [ { "discussion" : [ @@ -7247,14 +7836,23 @@ "key.usr" : "s:Sly7ElementQz5IndexQzcip" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "var count: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 24, "key.bodyoffset" : 548, + "key.doc.abstract" : [ + { + "Para" : "The number of elements in the collection." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1) if the collection conforms to `RandomAccessCollection`; otherwise, O(_n_), where _n_ is the length of the collection." + } + ], "key.doc.declaration" : "var count: Int { get }", "key.doc.discussion" : [ { - "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O() operation." + "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O(_n_) operation." }, { "Complexity" : "" @@ -7265,6 +7863,11 @@ ], "key.doc.full_as_xml" : "count<\/Name>s:Sl5countSivp<\/USR>var count: Int { get }<\/Declaration>The number of elements in the collection.<\/Para><\/Abstract>To check whether a collection is empty, use its isEmpty<\/codeVoice> property instead of comparing count<\/codeVoice> to zero. Unless the collection guarantees random-access performance, calculating count<\/codeVoice> can be an O(n<\/emphasis>) operation.<\/Para>O(1) if the collection conforms to RandomAccessCollection<\/codeVoice>; otherwise, O(n<\/emphasis>), where n<\/emphasis> is the length of the collection.<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "count", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> count<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7287,10 +7890,19 @@ "key.usr" : "s:Sl5countSivp" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "var isEmpty: Bool<\/Type> { get }<\/Declaration>", "key.bodylength" : 26, "key.bodyoffset" : 595, + "key.doc.abstract" : [ + { + "Para" : "A Boolean value indicating whether the collection is empty." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "var isEmpty: Bool { get }", "key.doc.discussion" : [ { @@ -7308,6 +7920,11 @@ ], "key.doc.full_as_xml" : "isEmpty<\/Name>s:Sl7isEmptySbvp<\/USR>var isEmpty: Bool { get }<\/Declaration>A Boolean value indicating whether the collection is empty.<\/Para><\/Abstract>When you need to check whether your collection is empty, use the isEmpty<\/codeVoice> property instead of checking that the count<\/codeVoice> property is equal to zero. For collections that donā€™t conform to RandomAccessCollection<\/codeVoice>, accessing the count<\/codeVoice> property iterates through the elements of the collection.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>O(1)<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "isEmpty", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> isEmpty<\/decl.name>: Bool<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7330,10 +7947,14 @@ "key.usr" : "s:Sl7isEmptySbvp" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "var startIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 29, "key.bodyoffset" : 646, + "key.doc.abstract" : [ + { + "Para" : "The position of the first element in a nonempty collection." + } + ], "key.doc.declaration" : "var startIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7345,6 +7966,11 @@ ], "key.doc.full_as_xml" : "startIndex<\/Name>s:Sl10startIndex0B0Qzvp<\/USR>var startIndex: Self.Index { get }<\/Declaration>The position of the first element in a nonempty collection.<\/Para><\/Abstract>If the collection is empty, startIndex<\/codeVoice> is equal to endIndex<\/codeVoice>.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "startIndex", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> startIndex<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7367,10 +7993,14 @@ "key.usr" : "s:Sl10startIndex0B0Qzvp" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "var endIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 27, "key.bodyoffset" : 698, + "key.doc.abstract" : [ + { + "Para" : "The collectionā€™s ā€œpast the endā€ positionā€”that is, the position one greater than the last valid subscript argument." + } + ], "key.doc.declaration" : "var endIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7388,6 +8018,11 @@ ], "key.doc.full_as_xml" : "endIndex<\/Name>s:Sl8endIndex0B0Qzvp<\/USR>var endIndex: Self.Index { get }<\/Declaration>The collectionā€™s ā€œpast the endā€ positionā€”that is, the position one greater than the last valid subscript argument.<\/Para><\/Abstract>When you need a range that includes the last element of a collection, use the half-open range operator (..<<\/codeVoice>) with endIndex<\/codeVoice>. The ..<<\/codeVoice> operator creates a range that doesnā€™t include the upper bound, so itā€™s always safe to use with endIndex<\/codeVoice>. For example:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>If the collection is empty, endIndex<\/codeVoice> is equal to startIndex<\/codeVoice>.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "endIndex", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> endIndex<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7410,10 +8045,14 @@ "key.usr" : "s:Sl8endIndex0B0Qzvp" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "func index(after i: Int<\/Type>) -> Int<\/Type><\/Declaration>", "key.bodylength" : 34, "key.bodyoffset" : 762, + "key.doc.abstract" : [ + { + "Para" : "Returns the position immediately after the given index." + } + ], "key.doc.declaration" : "func index(after i: Self.Index) -> Self.Index", "key.doc.discussion" : [ { @@ -7425,6 +8064,11 @@ ], "key.doc.full_as_xml" : "index(after:)<\/Name>s:Sl5index5after5IndexQzAD_tF<\/USR>func index(after i: Self.Index) -> Self.Index<\/Declaration>Returns the position immediately after the given index.<\/Para><\/Abstract>i<\/Name>in<\/Direction>A valid index of the collection. i<\/codeVoice> must be less than endIndex<\/codeVoice>.<\/Para><\/Discussion><\/Parameter><\/Parameters>The index value immediately after i<\/codeVoice>.<\/Para><\/ResultDiscussion>The successor of an index must be well defined. For an index i<\/codeVoice> into a collection c<\/codeVoice>, calling c.index(after: i)<\/codeVoice> returns the same index every time.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.name" : "index(after:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.parameters" : [ { "discussion" : [ @@ -7489,8 +8133,13 @@ ], "key.bodylength" : 244, "key.bodyoffset" : 175, - "key.doc.declaration" : "enum Result where Failure : Error", - "key.doc.full_as_xml" : "Result<\/Name>s:s6ResultO<\/USR>enum Result<Success, Failure> where Failure : Error<\/Declaration>A value that represents either a success or a failure, including an associated value in each case.<\/Para><\/Abstract><\/CommentParts><\/Other>", + "key.doc.abstract" : [ + { + "Para" : "A value that represents either a success or a failure, including an associated value in each case." + } + ], + "key.doc.declaration" : "@frozen enum Result where Failure : Error", + "key.doc.full_as_xml" : "Result<\/Name>s:s6ResultO<\/USR>@frozen enum Result<Success, Failure> where Failure : Error<\/Declaration>A value that represents either a success or a failure, including an associated value in each case.<\/Para><\/Abstract><\/CommentParts><\/Other>", "key.doc.name" : "Result", "key.doc.type" : "Other", "key.fully_annotated_decl" : "@frozen<\/syntaxtype.attribute.name><\/syntaxtype.attribute.builtin> enum<\/syntaxtype.keyword> Result<\/decl.name><Success<\/decl.generic_type_param.name><\/decl.generic_type_param>, Failure<\/decl.generic_type_param.name><\/decl.generic_type_param>> where<\/syntaxtype.keyword> Failure : Error<\/ref.protocol><\/decl.generic_type_requirement><\/decl.enum>", @@ -7574,6 +8223,11 @@ ], "key.bodylength" : 724, "key.bodyoffset" : 397, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes a parameterless command line flag that defaults to false and can only\nbe switched on. Canonical examples include `--force` and `--recurse`.\n\nFor a boolean toggle that can be enabled and disabled use `Option`.", "key.doc.declaration" : "public struct Switch", @@ -7611,6 +8265,11 @@ "key.offset" : 515 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that enables this switch. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that enables this switch. For example, a key of `verbose` would be\nused for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -7646,6 +8305,11 @@ "key.offset" : 828 } ], + "key.doc.abstract" : [ + { + "Para" : "Optional single letter flag that enables this switch. For example, `-v` would be used as a shorthand for `--verbose`." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Optional single letter flag that enables this switch. For example, `-v` would\nbe used as a shorthand for `--verbose`.\n\nMultiple flags can be grouped together as a single argument and will split\nwhen parsing (e.g. `rm -rf` treats 'r' and 'f' as inidividual flags).", "key.doc.declaration" : "public let flag: Character?", @@ -7686,6 +8350,11 @@ "key.offset" : 968 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -7747,10 +8416,14 @@ "key.usr" : "s:10Commandant6SwitchV" }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public struct Switch<\/Declaration>", "key.bodylength" : 140, "key.bodyoffset" : 1167, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Switch", "key.doc.discussion" : [ @@ -7799,6 +8472,11 @@ ], "key.bodylength" : 104, "key.bodyoffset" : 1201, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -7816,6 +8494,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Switch.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7868,10 +8551,14 @@ "key.offset" : 1313 }, { - "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 650, "key.bodyoffset" : 1355, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -7903,6 +8590,11 @@ ], "key.bodylength" : 333, "key.bodyoffset" : 1670, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean switch in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean switch in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Switch) -> Result>", diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/Extension@swift-5.0.json b/Tests/SourceKittenFrameworkTests/Fixtures/Extension@swift-5.0.json index e35ca07e9..511178ff1 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/Extension@swift-5.0.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/Extension@swift-5.0.json @@ -9,6 +9,11 @@ "key.annotated_decl" : "class Base<\/Declaration>", "key.bodylength" : 166, "key.bodyoffset" : 29, + "key.doc.abstract" : [ + { + "Para" : "Doc for Base" + } + ], "key.doc.column" : 7, "key.doc.comment" : "Doc for Base", "key.doc.declaration" : "class Base", @@ -35,6 +40,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "typealias Base<\/Type>.Index = Int<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Doc for Base.Index" + } + ], "key.doc.column" : 15, "key.doc.comment" : "Doc for Base.Index", "key.doc.declaration" : "typealias Extension.Base.Index = Int", @@ -65,6 +75,11 @@ "key.annotated_decl" : "func f(index: Index<\/Type>)<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 134, + "key.doc.abstract" : [ + { + "Para" : "Doc for Base.f" + } + ], "key.doc.column" : 10, "key.doc.comment" : "Doc for Base.f", "key.doc.declaration" : "func f(index: Index)", @@ -98,6 +113,11 @@ "key.annotated_decl" : "class Base<\/Type>.Nested<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 188, + "key.doc.abstract" : [ + { + "Para" : "Doc for Base.Nested" + } + ], "key.doc.column" : 11, "key.doc.comment" : "Doc for Base.Nested", "key.doc.declaration" : "class Extension.Base.Nested", @@ -133,6 +153,11 @@ "key.annotated_decl" : "class Base<\/Declaration>", "key.bodylength" : 155, "key.bodyoffset" : 214, + "key.doc.abstract" : [ + { + "Para" : "Doc for Base" + } + ], "key.doc.column" : 7, "key.doc.declaration" : "class Base", "key.doc.file" : "Extension.swift", @@ -155,6 +180,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "typealias ExtendedIndex = Double<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Doc for Base.ExtendedIndex" + } + ], "key.doc.column" : 15, "key.doc.comment" : "Doc for Base.ExtendedIndex", "key.doc.declaration" : "typealias ExtendedIndex = Double", @@ -185,6 +215,11 @@ "key.annotated_decl" : "func extendedF(index: ExtendedIndex<\/Type>)<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 362, + "key.doc.abstract" : [ + { + "Para" : "Doc for Base.extendedF" + } + ], "key.doc.column" : 10, "key.doc.comment" : "Doc for Base.extendedF", "key.doc.declaration" : "func extendedF(index: ExtendedIndex)", @@ -223,6 +258,11 @@ "key.annotated_decl" : "class Base<\/Type>.Nested<\/Declaration>", "key.bodylength" : 1, "key.bodyoffset" : 436, + "key.doc.abstract" : [ + { + "Para" : "Doc for Base.Nested" + } + ], "key.doc.column" : 11, "key.doc.declaration" : "class Extension.Base.Nested", "key.doc.file" : "Extension.swift", diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/LinuxCommandantSPM@swift-5.1.json b/Tests/SourceKittenFrameworkTests/Fixtures/LinuxCommandantSPM@swift-5.1.json index 56db1349c..9fbac4343 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/LinuxCommandantSPM@swift-5.1.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/LinuxCommandantSPM@swift-5.1.json @@ -16,6 +16,11 @@ ], "key.bodylength" : 1029, "key.bodyoffset" : 231, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an argument that can be provided on the command line.", "key.doc.declaration" : "public struct Argument", @@ -65,6 +70,11 @@ "key.offset" : 443 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this argument. This is the value that will be used if the argument is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this argument. This is the value that will be used\nif the argument is never explicitly specified on the command line.\n\nIf this is nil, this argument is always required.", "key.doc.declaration" : "public let defaultValue: T?", @@ -105,6 +115,11 @@ "key.offset" : 585 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this argument. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this argument. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -140,6 +155,11 @@ "key.offset" : 804 } ], + "key.doc.abstract" : [ + { + "Para" : "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 )." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string that describes this argument as a paramater shown\nin the list of possible parameters in help messages (e.g. for \"paths\", the\nuser would see ).", "key.doc.declaration" : "public let usageParameter: String?", @@ -268,6 +288,11 @@ "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 251, "key.bodyoffset" : 1283, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -299,6 +324,11 @@ ], "key.bodylength" : 62, "key.bodyoffset" : 1470, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -339,6 +369,11 @@ "key.annotated_decl" : "public struct Argument<T><\/Declaration>", "key.bodylength" : 254, "key.bodyoffset" : 1575, + "key.doc.abstract" : [ + { + "Para" : "Describes an argument that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Argument", "key.doc.file" : "Sources\/Commandant\/Argument.swift", @@ -370,6 +405,11 @@ ], "key.bodylength" : 65, "key.bodyoffset" : 1762, + "key.doc.abstract" : [ + { + "Para" : "A string describing this argument as a parameter in help messages. This falls back to `\"\\(self)\"` if `usageParameter` is `nil`" + } + ], "key.doc.column" : 15, "key.doc.comment" : "A string describing this argument as a parameter in help messages. This falls back\nto `\"\\(self)\"` if `usageParameter` is `nil`", "key.doc.declaration" : "internal var usageParameterDescription: String { get }", @@ -418,6 +458,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 1979, "key.bodyoffset" : 1877, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -449,6 +494,11 @@ ], "key.bodylength" : 518, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument) -> Result> where T : Commandant.ArgumentProtocol", @@ -562,6 +612,11 @@ ], "key.bodylength" : 778, "key.bodyoffset" : 3076, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given argument list in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given argument list in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the argument's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, argument: Argument<[T]>) -> Result<[T], CommandantError> where T : Commandant.ArgumentProtocol", @@ -688,6 +743,11 @@ ], "key.bodylength" : 296, "key.bodyoffset" : 266, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Represents an argument passed on the command line.", "key.doc.declaration" : "private enum RawArgument : Equatable", @@ -732,6 +792,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case key(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A key corresponding to an option (e.g., `verbose` for `--verbose`)." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A key corresponding to an option (e.g., `verbose` for `--verbose`).", "key.doc.declaration" : "", @@ -769,6 +834,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case value(String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "A value, either associated with an option or passed as a positional argument." + } + ], "key.doc.column" : 7, "key.doc.comment" : "A value, either associated with an option or passed as a positional\nargument.", "key.doc.declaration" : "", @@ -806,6 +876,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.internal", "key.annotated_decl" : "case flag(OrderedSet<\/Type><Character<\/Type>>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "One or more flag arguments (e.g ā€˜rā€™ and ā€˜fā€™ for `-rf`)" + } + ], "key.doc.column" : 7, "key.doc.comment" : "One or more flag arguments (e.g 'r' and 'f' for `-rf`)", "key.doc.declaration" : "", @@ -843,6 +918,11 @@ "key.annotated_decl" : "private enum RawArgument : Equatable<\/Type><\/Declaration>", "key.bodylength" : 214, "key.bodyoffset" : 613, + "key.doc.abstract" : [ + { + "Para" : "Represents an argument passed on the command line." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "private enum RawArgument : Equatable", "key.doc.file" : "Sources\/Commandant\/ArgumentParser.swift", @@ -886,6 +966,11 @@ ], "key.bodylength" : 173, "key.bodyoffset" : 652, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -903,6 +988,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentParser.swift", "key.fully_annotated_decl" : "fileprivate<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -946,6 +1036,11 @@ ], "key.bodylength" : 3711, "key.bodyoffset" : 924, + "key.doc.abstract" : [ + { + "Para" : "Destructively parses a list of command-line arguments." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Destructively parses a list of command-line arguments.", "key.doc.declaration" : "public final class ArgumentParser", @@ -979,6 +1074,11 @@ "key.offset" : 991 } ], + "key.doc.abstract" : [ + { + "Para" : "The remaining arguments to be extracted, in their raw form." + } + ], "key.doc.column" : 14, "key.doc.comment" : "The remaining arguments to be extracted, in their raw form.", "key.doc.declaration" : "private var rawArguments: [Commandant.RawArgument]", @@ -1017,6 +1117,11 @@ ], "key.bodylength" : 741, "key.bodyoffset" : 1151, + "key.doc.abstract" : [ + { + "Para" : "Initializes the generator from a simple list of command-line arguments." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the generator from a simple list of command-line arguments.", "key.doc.declaration" : "public init(_ arguments: [String])", @@ -1090,6 +1195,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 1978, + "key.doc.abstract" : [ + { + "Para" : "Returns the remaining arguments." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Returns the remaining arguments.", "key.doc.declaration" : "internal var remainingArguments: [String]? { get }", @@ -1127,6 +1237,11 @@ ], "key.bodylength" : 281, "key.bodyoffset" : 2323, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was enabled or disabled, or nil if it was not given at all." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was enabled or disabled, or nil if it\nwas not given at all.\n\nIf the key is found, it is then removed from the list of arguments\nremaining to be parsed.", "key.doc.declaration" : "internal func consumeBoolean(forKey key: String) -> Bool?", @@ -1210,6 +1325,11 @@ ], "key.bodylength" : 503, "key.bodyoffset" : 2999, + "key.doc.abstract" : [ + { + "Para" : "Returns the value associated with the given flag, or nil if the flag was not specified. If the key is presented, but no value was given, an error is returned." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the value associated with the given flag, or nil if the flag was\nnot specified. If the key is presented, but no value was given, an error\nis returned.\n\nIf a value is found, the key and the value are both removed from the\nlist of arguments remaining to be parsed.", "key.doc.declaration" : "internal func consumeValue(forKey key: String) -> Result>", @@ -1310,6 +1430,11 @@ ], "key.bodylength" : 164, "key.bodyoffset" : 3688, + "key.doc.abstract" : [ + { + "Para" : "Returns the next positional argument that hasnā€™t yet been returned, or nil if there are no more positional arguments." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns the next positional argument that hasn't yet been returned, or\nnil if there are no more positional arguments.", "key.doc.declaration" : "internal func consumePositionalArgument() -> String?", @@ -1350,6 +1475,11 @@ ], "key.bodylength" : 143, "key.bodyoffset" : 4007, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given key was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given key was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consume(key: String) -> Bool", @@ -1406,6 +1536,11 @@ ], "key.bodylength" : 316, "key.bodyoffset" : 4317, + "key.doc.abstract" : [ + { + "Para" : "Returns whether the given flag was specified and removes it from the list of arguments remaining." + } + ], "key.doc.column" : 16, "key.doc.comment" : "Returns whether the given flag was specified and removes it from the\nlist of arguments remaining.", "key.doc.declaration" : "internal func consumeBoolean(flag: Character) -> Bool", @@ -1464,6 +1599,11 @@ ], "key.bodylength" : 189, "key.bodyoffset" : 253, + "key.doc.abstract" : [ + { + "Para" : "Represents a value that can be converted from a command-line argument." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a value that can be converted from a command-line argument.", "key.doc.declaration" : "public protocol ArgumentProtocol", @@ -1492,6 +1632,11 @@ "key.annotated_decl" : "static var name: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 322, + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable name for this type.", "key.doc.declaration" : "static var name: String { get }", @@ -1520,6 +1665,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "static func from(string: String<\/Type>) -> `Self`?<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Attempts to parse a value from the given command-line argument.", "key.doc.declaration" : "static func from(string: String) -> `Self`?", @@ -1558,6 +1708,11 @@ "key.annotated_decl" : "@frozen struct Int : FixedWidthInteger<\/Type>, SignedInteger<\/Type><\/Declaration>", "key.bodylength" : 113, "key.bodyoffset" : 478, + "key.doc.abstract" : [ + { + "Para" : "A signed integer value type." + } + ], "key.doc.declaration" : "struct Int : FixedWidthInteger, SignedInteger", "key.doc.discussion" : [ { @@ -1603,6 +1758,11 @@ "key.offset" : 480 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.discussion" : [ @@ -1614,6 +1774,11 @@ "key.doc.full_as_xml" : "name<\/Name>s:10Commandant16ArgumentProtocolP4nameSSvpZ<\/USR>static var name: String { get }<\/Declaration>A human-readable name for this type.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 12, "key.doc.name" : "name", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> let<\/syntaxtype.keyword> name<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.static>", @@ -1648,6 +1813,11 @@ ], "key.bodylength" : 23, "key.bodyoffset" : 566, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func from(string: String) -> `Self`?", "key.doc.discussion" : [ @@ -1659,6 +1829,11 @@ "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> `Self`?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 15, "key.doc.name" : "from(string:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> Int<\/ref.struct>?<\/decl.function.returntype><\/decl.function.method.static>", @@ -1694,19 +1869,24 @@ "key.annotated_decl" : "@frozen struct String<\/Declaration>", "key.bodylength" : 110, "key.bodyoffset" : 630, + "key.doc.abstract" : [ + { + "Para" : "A Unicode string value that is a collection of characters." + } + ], "key.doc.declaration" : "struct String", "key.doc.discussion" : [ { "Para" : "A string is a series of characters, such as `\"Swift\"`, that forms a collection. Strings in Swift are Unicode correct and locale insensitive, and are designed to be efficient. The `String` type bridges with the Objective-C class `NSString` and offers interoperability with C functions that works with strings." }, { - "Para" : "You can create new strings using string literals or string interpolations. A is a series of characters enclosed in quotes." + "Para" : "You can create new strings using string literals or string interpolations. A _string literal_ is a series of characters enclosed in quotes." }, { "CodeListing" : "" }, { - "Para" : " are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." + "Para" : "_String interpolations_ are string literals that evaluate any included expressions and convert the results to string form. String interpolations give you an easy way to build a string from multiple pieces. Wrap each expression in a string interpolation in parentheses, prefixed by a backslash." }, { "CodeListing" : "" @@ -1742,7 +1922,7 @@ "Para" : "Basic string operations are not sensitive to locale settings, ensuring that string comparisons and other operations always have a single, stable result, allowing strings to be used as keys in `Dictionary` instances and for other purposes." }, { - "Para" : "A string is a collection of , which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." + "Para" : "A string is a collection of _extended grapheme clusters_, which approximate human-readable characters. Many individual characters, such as ā€œĆ©ā€, ā€œź¹€ā€, and ā€œšŸ‡®šŸ‡³ā€, can be made up of multiple Unicode scalar values. These scalar values are combined by Unicodeā€™s boundary algorithms into extended grapheme clusters, represented by the Swift `Character` type. Each element of a string is represented by a `Character` instance." }, { "Para" : "For example, to retrieve the first word of a longer string, you can search for a space and then create a substring from a prefix of the string up to that point:" @@ -1808,7 +1988,7 @@ "Para" : "When you need to know the length of a string, you must first consider what youā€™ll use the length for. Are you measuring the number of characters that will be displayed on the screen, or are you measuring the amount of storage needed for the string in a particular encoding? A single string can have greatly differing lengths when measured by its different views." }, { - "Para" : "For example, an ASCII character like the capital letter is represented by a single element in each of its four views. The Unicode scalar value of is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." + "Para" : "For example, an ASCII character like the capital letter _A_ is represented by a single element in each of its four views. The Unicode scalar value of _A_ is `65`, which is small enough to fit in a single code unit in both UTF-16 and UTF-8." }, { "CodeListing" : "" @@ -1853,13 +2033,13 @@ "CodeListing" : "" }, { - "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O() time and space." + "Para" : "Although strings in Swift have value semantics, strings use a copy-on-write strategy to store their data in a buffer. This buffer can then be shared by different copies of a string. A stringā€™s data is only copied lazily, upon mutation, when more than one string instance is using the same buffer. Therefore, the first in any sequence of mutating operations may cost O(_n_) time and space." }, { "Para" : "When a stringā€™s contiguous storage fills up, a new buffer must be allocated and data must be moved to the new storage. String buffers use an exponential growth strategy that makes appending to a string a constant time operation when averaged over many append operations." }, { - "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O() time and space, where is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." + "Para" : "Any `String` instance can be bridged to `NSString` using the type-cast operator (`as`), and any `String` instance that originates in Objective-C may use an `NSString` instance as its storage. Because any arbitrary subclass of `NSString` can become a `String` instance, there are no guarantees about representation or efficiency when a `String` instance is backed by `NSString` storage. Because `NSString` is immutable, it is just as though the storage was shared by a copy. The first in any sequence of mutating operations causes elements to be copied into unique, contiguous storage which may cost O(_n_) time and space, where _n_ is the length of the stringā€™s encoded representation (or more, if the underlying `NSString` has unusual performance characteristics)." }, { "Para" : "For more information about the Unicode terms used in this discussion, see the . In particular, this discussion mentions , , and ." @@ -1904,6 +2084,11 @@ "key.offset" : 632 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable name for this type." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "static var name: String { get }", "key.doc.discussion" : [ @@ -1915,6 +2100,11 @@ "key.doc.full_as_xml" : "name<\/Name>s:10Commandant16ArgumentProtocolP4nameSSvpZ<\/USR>static var name: String { get }<\/Declaration>A human-readable name for this type.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 12, "key.doc.name" : "name", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> let<\/syntaxtype.keyword> name<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.static>", @@ -1949,6 +2139,11 @@ ], "key.bodylength" : 18, "key.bodyoffset" : 720, + "key.doc.abstract" : [ + { + "Para" : "Attempts to parse a value from the given command-line argument." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func from(string: String) -> `Self`?", "key.doc.discussion" : [ @@ -1960,6 +2155,11 @@ "key.doc.full_as_xml" : "from(string:)<\/Name>s:10Commandant16ArgumentProtocolP4from6stringxSgSS_tFZ<\/USR>static func from(string: String) -> `Self`?<\/Declaration>Attempts to parse a value from the given command-line argument.<\/Para><\/Abstract>This documentation comment was inherited from ArgumentProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 15, "key.doc.name" : "from(string:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `ArgumentProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/ArgumentProtocol.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> from<\/decl.name>(string<\/decl.var.parameter.argument_label>: String<\/ref.struct><\/decl.var.parameter.type><\/decl.var.parameter>) -> String<\/ref.struct>?<\/decl.function.returntype><\/decl.function.method.static>", @@ -1995,6 +2195,11 @@ "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 826, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -2013,7 +2218,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2106,6 +2311,11 @@ "key.annotated_decl" : "protocol RawRepresentable<\/Declaration>", "key.bodylength" : 112, "key.bodyoffset" : 1027, + "key.doc.abstract" : [ + { + "Para" : "A type that can be converted to and from an associated raw value." + } + ], "key.doc.declaration" : "protocol RawRepresentable", "key.doc.discussion" : [ { @@ -2124,7 +2334,7 @@ "CodeListing" : "" }, { - "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that correspond to a case of `Counter`." + "Para" : "You can create a `Counter` instance from an integer value between 1 and 5 by using the `init?(rawValue:)` initializer declared in the `RawRepresentable` protocol. This initializer is failable because although every case of the `Counter` type has a corresponding `Int` value, there are many `Int` values that _donā€™t_ correspond to a case of `Counter`." }, { "CodeListing" : "" @@ -2232,6 +2442,11 @@ ], "key.bodylength" : 483, "key.bodyoffset" : 280, + "key.doc.abstract" : [ + { + "Para" : "Represents a subcommand that can be executed with its own set of arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a subcommand that can be executed with its own set of arguments.", "key.doc.declaration" : "public protocol CommandProtocol", @@ -2258,6 +2473,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "associatedtype Options : OptionsProtocol<\/Type><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.comment" : "The command's options type.", "key.doc.declaration" : "associatedtype Options : Commandant.OptionsProtocol", @@ -2306,6 +2526,11 @@ "key.annotated_decl" : "var verb: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 532, + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.comment" : "The action that users should specify to use this subcommand (e.g.,\n`help`).", "key.doc.declaration" : "var verb: String { get }", @@ -2336,6 +2561,11 @@ "key.annotated_decl" : "var function: String<\/Type> { get }<\/Declaration>", "key.bodylength" : 5, "key.bodyoffset" : 648, + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.comment" : "A human-readable, high-level description of what this command is used\nfor.", "key.doc.declaration" : "var function: String { get }", @@ -2364,6 +2594,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "func run(_ options: Options<\/Type>) -> Result<\/Type><(), ClientError<\/Type>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Runs this subcommand with the given options.", "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", @@ -2409,6 +2644,11 @@ ], "key.bodylength" : 957, "key.bodyoffset" : 843, + "key.doc.abstract" : [ + { + "Para" : "A type-erased command." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A type-erased command.", "key.doc.declaration" : "public struct CommandWrapper where ClientError : Error", @@ -2572,6 +2812,11 @@ ], "key.bodylength" : 633, "key.bodyoffset" : 1165, + "key.doc.abstract" : [ + { + "Para" : "Creates a command that wraps another." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Creates a command that wraps another.", "key.doc.declaration" : "fileprivate init(_ command: C) where ClientError == C.ClientError, C : Commandant.CommandProtocol", @@ -2645,6 +2890,11 @@ ], "key.bodylength" : 216, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Describes the \"mode\" in which a command should run.", "key.doc.declaration" : "public enum CommandMode", @@ -2677,6 +2927,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case arguments(ArgumentParser<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Options should be parsed from the given command-line arguments." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Options should be parsed from the given command-line arguments.", "key.doc.declaration" : "", @@ -2714,6 +2969,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usage<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Each option should record its usage information in an error, for presentation to the user." + } + ], "key.doc.column" : 7, "key.doc.comment" : "Each option should record its usage information in an error, for\npresentation to the user.", "key.doc.declaration" : "", @@ -2763,6 +3023,11 @@ ], "key.bodylength" : 1204, "key.bodyoffset" : 2212, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.comment" : "Maintains the list of commands available to run.", "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", @@ -2852,6 +3117,11 @@ ], "key.bodylength" : 69, "key.bodyoffset" : 2369, + "key.doc.abstract" : [ + { + "Para" : "All available commands." + } + ], "key.doc.column" : 13, "key.doc.comment" : "All available commands.", "key.doc.declaration" : "public var commands: [CommandWrapper] { get }", @@ -2921,6 +3191,11 @@ ], "key.bodylength" : 106, "key.bodyoffset" : 2775, + "key.doc.abstract" : [ + { + "Para" : "Registers the given commands, making those available to run." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Registers the given commands, making those available to run.\n\nIf another commands were already registered with the same `verb`s, those\nwill be overwritten.", "key.doc.declaration" : "public func register(_ commands: C...) -> CommandRegistry where ClientError == C.ClientError, C : Commandant.CommandProtocol", @@ -2994,6 +3269,11 @@ ], "key.bodylength" : 54, "key.bodyoffset" : 3164, + "key.doc.abstract" : [ + { + "Para" : "Runs the command corresponding to the given verb, passing it the given arguments." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Runs the command corresponding to the given verb, passing it the given\narguments.\n\nReturns the results of the execution, or nil if no such command exists.", "key.doc.declaration" : "public func run(command verb: String, arguments: [String]) -> Result<(), CommandantError>?", @@ -3039,6 +3319,11 @@ ], "key.bodylength" : 32, "key.bodyoffset" : 3382, + "key.doc.abstract" : [ + { + "Para" : "Returns the command matching the given verb, or nil if no such command is registered." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Returns the command matching the given verb, or nil if no such command\nis registered.", "key.doc.declaration" : "public subscript(verb: String) -> CommandWrapper? { get }", @@ -3077,6 +3362,11 @@ "key.annotated_decl" : "public final class CommandRegistry<ClientError> where ClientError : Error<\/Type><\/Declaration>", "key.bodylength" : 4074, "key.bodyoffset" : 3446, + "key.doc.abstract" : [ + { + "Para" : "Maintains the list of commands available to run." + } + ], "key.doc.column" : 20, "key.doc.declaration" : "public final class CommandRegistry where ClientError : Error", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -3108,6 +3398,11 @@ ], "key.bodylength" : 97, "key.bodyoffset" : 4332, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing CommandLine.arguments\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3167,6 +3462,11 @@ ], "key.bodylength" : 945, "key.bodyoffset" : 5328, + "key.doc.abstract" : [ + { + "Para" : "Hands off execution to the CommandRegistry, by parsing `arguments` and then running whichever command has been identified in the argument list." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Hands off execution to the CommandRegistry, by parsing `arguments`\nand then running whichever command has been identified in the argument\nlist.\n\nIf the chosen command executes successfully, the process will exit with\na successful exit code.\n\nIf the chosen command fails, the provided error handler will be invoked,\nthen the process will exit with a failure exit code.\n\nIf a matching command could not be found but there is any `executable-verb`\nstyle subcommand executable in the caller's `$PATH`, the subcommand will\nbe executed.\n\nIf a matching command could not be found or a usage error occurred,\na helpful error message will be written to `stderr`, then the process\nwill exit with a failure error code.", "key.doc.declaration" : "public func main(arguments: [String], defaultVerb: String, errorHandler: (ClientError) -> Void) -> Never", @@ -3276,6 +3576,11 @@ ], "key.bodylength" : 933, "key.bodyoffset" : 6585, + "key.doc.abstract" : [ + { + "Para" : "Finds and executes a subcommand which exists in your $PATH. The executable name must be in the form of `executable-verb`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Finds and executes a subcommand which exists in your $PATH. The executable\nname must be in the form of `executable-verb`.\n\n- Returns: The exit status of found subcommand or nil.", "key.doc.declaration" : "private func executeSubcommandIfExists(_ executableName: String, verb: String, arguments: [String]) -> Int32?", @@ -3406,6 +3711,11 @@ ], "key.bodylength" : 157, "key.bodyoffset" : 372, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Possible errors that can originate from Commandant.\n\n`ClientError` should be the type of error (if any) that can occur when\nrunning commands.", "key.doc.declaration" : "public enum CommandantError : Error", @@ -3472,6 +3782,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case usageError(description: String<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An option was used incorrectly." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An option was used incorrectly.", "key.doc.declaration" : "", @@ -3509,6 +3824,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "case commandError(ClientError<\/Type>)<\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "An error occurred while running a command." + } + ], "key.doc.column" : 7, "key.doc.comment" : "An error occurred while running a command.", "key.doc.declaration" : "", @@ -3546,6 +3866,11 @@ "key.annotated_decl" : "public enum CommandantError<ClientError> : Error<\/Type><\/Declaration>", "key.bodylength" : 187, "key.bodyoffset" : 584, + "key.doc.abstract" : [ + { + "Para" : "Possible errors that can originate from Commandant." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandantError : Error", "key.doc.discussion" : [ @@ -3594,6 +3919,11 @@ ], "key.bodylength" : 151, "key.bodyoffset" : 618, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -3611,6 +3941,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Errors.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -3649,6 +3984,11 @@ ], "key.bodylength" : 105, "key.bodyoffset" : 992, + "key.doc.abstract" : [ + { + "Para" : "Constructs an `InvalidArgument` error that indicates a missing value for the argument by the given name." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an `InvalidArgument` error that indicates a missing value for\nthe argument by the given name.", "key.doc.declaration" : "internal func missingArgumentError(_ argumentName: String) -> CommandantError", @@ -3722,6 +4062,11 @@ ], "key.bodylength" : 179, "key.bodyoffset" : 1339, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error by combining the example of key (and value, if applicable) with the usage description." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error by combining the example of key (and value, if applicable)\nwith the usage description.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, usage: String) -> CommandantError", @@ -3824,6 +4169,11 @@ ], "key.bodylength" : 265, "key.bodyoffset" : 1813, + "key.doc.abstract" : [ + { + "Para" : "Combines the text of the two errors, if theyā€™re both `UsageError`s. Otherwise, uses whichever one is not (biased toward the left)." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Combines the text of the two errors, if they're both `UsageError`s.\nOtherwise, uses whichever one is not (biased toward the left).", "key.doc.declaration" : "internal func combineUsageErrors(_ lhs: CommandantError, _ rhs: CommandantError) -> CommandantError", @@ -3880,6 +4230,11 @@ ], "key.bodylength" : 96, "key.bodyoffset" : 2260, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that indicates unrecognized arguments remains." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that indicates unrecognized arguments remains.", "key.doc.declaration" : "internal func unrecognizedArgumentsError(_ options: [String]) -> CommandantError", @@ -3944,6 +4299,11 @@ ], "key.bodylength" : 192, "key.bodyoffset" : 2631, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument, with the given example of value usage if applicable." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument, with the given\nexample of value usage if applicable.", "key.doc.declaration" : "internal func informativeUsageError(_ valueExample: String, argument: Argument) -> CommandantError", @@ -4046,6 +4406,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3018, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4194,6 +4559,11 @@ ], "key.bodylength" : 378, "key.bodyoffset" : 3598, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the argument list." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the argument list.", "key.doc.declaration" : "internal func informativeUsageError(_ argument: Argument<[T]>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4350,6 +4720,11 @@ ], "key.bodylength" : 76, "key.bodyoffset" : 4257, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option, with the given example of key (and value, if applicable) usage." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option, with the given\nexample of key (and value, if applicable) usage.", "key.doc.declaration" : "internal func informativeUsageError(_ keyValueExample: String, option: Option) -> CommandantError", @@ -4452,6 +4827,11 @@ ], "key.bodylength" : 89, "key.bodyoffset" : 4522, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4566,6 +4946,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 4801, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4680,6 +5065,11 @@ ], "key.bodylength" : 91, "key.bodyoffset" : 5070, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4794,6 +5184,11 @@ ], "key.bodylength" : 78, "key.bodyoffset" : 5353, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option<[T]?>) -> CommandantError where T : Commandant.ArgumentProtocol", @@ -4908,6 +5303,11 @@ ], "key.bodylength" : 121, "key.bodyoffset" : 5616, + "key.doc.abstract" : [ + { + "Para" : "Constructs an error that describes how to use the given boolean option." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Constructs an error that describes how to use the given boolean option.", "key.doc.declaration" : "internal func informativeUsageError(_ option: Option) -> CommandantError", @@ -5018,6 +5418,11 @@ ], "key.bodylength" : 1127, "key.bodyoffset" : 601, + "key.doc.abstract" : [ + { + "Para" : "A basic implementation of a `help` command, using information available in a `CommandRegistry`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "A basic implementation of a `help` command, using information available in a\n`CommandRegistry`.\n\nIf you want to use this command, initialize it with the registry, then add\nit to that same registry:\n\n\tlet commands: CommandRegistry = ā€¦\n\tlet helpCommand = HelpCommand(registry: commands)\n\tcommands.register(helpCommand)", "key.doc.declaration" : "public struct HelpCommand : CommandProtocol where ClientError : Error", @@ -5099,6 +5504,11 @@ "key.offset" : 603 } ], + "key.doc.abstract" : [ + { + "Para" : "The commandā€™s options type." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "associatedtype Options : Commandant.OptionsProtocol", "key.doc.discussion" : [ @@ -5110,6 +5520,11 @@ "key.doc.full_as_xml" : "Options<\/Name>s:10Commandant15CommandProtocolP7OptionsQa<\/USR>associatedtype Options : Commandant.OptionsProtocol<\/Declaration>The commandā€™s options type.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 15, "key.doc.name" : "Options", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> typealias<\/syntaxtype.keyword> HelpCommand<\/ref.struct><ClientError>.Options<\/decl.name> = HelpOptions<\/ref.struct><ClientError<\/ref.generic_type_param>><\/decl.typealias>", @@ -5141,6 +5556,11 @@ "key.offset" : 657 } ], + "key.doc.abstract" : [ + { + "Para" : "The action that users should specify to use this subcommand (e.g., `help`)." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var verb: String { get }", "key.doc.discussion" : [ @@ -5152,6 +5572,11 @@ "key.doc.full_as_xml" : "verb<\/Name>s:10Commandant15CommandProtocolP4verbSSvp<\/USR>var verb: String { get }<\/Declaration>The action that users should specify to use this subcommand (e.g., help<\/codeVoice>).<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 21, "key.doc.name" : "verb", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> let<\/syntaxtype.keyword> verb<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.instance>", @@ -5183,6 +5608,11 @@ "key.offset" : 683 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable, high-level description of what this command is used for." + } + ], "key.doc.column" : 6, "key.doc.declaration" : "var function: String { get }", "key.doc.discussion" : [ @@ -5194,6 +5624,11 @@ "key.doc.full_as_xml" : "function<\/Name>s:10Commandant15CommandProtocolP8functionSSvp<\/USR>var function: String { get }<\/Declaration>A human-readable, high-level description of what this command is used for.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.line" : 25, "key.doc.name" : "function", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> let<\/syntaxtype.keyword> function<\/decl.name>: String<\/ref.struct><\/decl.var.type><\/decl.var.instance>", @@ -5252,6 +5687,11 @@ ], "key.bodylength" : 102, "key.bodyoffset" : 931, + "key.doc.abstract" : [ + { + "Para" : "Initializes the command to provide help from the given registry of commands." + } + ], "key.doc.column" : 9, "key.doc.comment" : "Initializes the command to provide help from the given registry of\ncommands.", "key.doc.declaration" : "public init(registry: CommandRegistry, function: String? = nil)", @@ -5292,6 +5732,11 @@ ], "key.bodylength" : 625, "key.bodyoffset" : 1101, + "key.doc.abstract" : [ + { + "Para" : "Runs this subcommand with the given options." + } + ], "key.doc.column" : 7, "key.doc.declaration" : "func run(_ options: Options) -> Result<(), ClientError>", "key.doc.discussion" : [ @@ -5303,6 +5748,11 @@ "key.doc.full_as_xml" : "run(_:)<\/Name>s:10Commandant15CommandProtocolP3runys6ResultOyyt11ClientErrorQzG7OptionsQzF<\/USR>func run(_ options: Options) -> Result<(), ClientError><\/Declaration>Runs this subcommand with the given options.<\/Para><\/Abstract>This documentation comment was inherited from CommandProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 28, "key.doc.name" : "run(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CommandProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> func<\/syntaxtype.keyword> run<\/decl.name>(_<\/decl.var.parameter.argument_label> options<\/decl.var.parameter.name>: Options<\/ref.typealias><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><()<\/tuple>, ClientError<\/ref.generic_type_param>><\/decl.function.returntype><\/decl.function.method.instance>", @@ -5510,6 +5960,11 @@ ], "key.bodylength" : 99, "key.bodyoffset" : 2100, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5524,6 +5979,11 @@ "key.doc.full_as_xml" : "evaluate(_:)<\/Name>s:10Commandant15OptionsProtocolP8evaluateys6ResultOyxAA0A5ErrorOy06ClientF0QzGGAA11CommandModeOFZ<\/USR>static func evaluate(_ m: CommandMode) -> Result<Self, CommandantError<ClientError>><\/Declaration>Evaluates this set of options in the given mode.<\/Para><\/Abstract>Returns the parsed options or a UsageError<\/codeVoice>.<\/Para>This documentation comment was inherited from OptionsProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 43, "key.doc.name" : "evaluate(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `OptionsProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/HelpCommand.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> evaluate<\/decl.name>(_<\/decl.var.parameter.argument_label> m<\/decl.var.parameter.name>: CommandMode<\/ref.enum><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><HelpOptions<\/ref.struct>, CommandantError<\/ref.enum><ClientError<\/ref.generic_type_param>>><\/decl.function.returntype><\/decl.function.method.static>", @@ -5573,6 +6033,11 @@ ], "key.bodylength" : 233, "key.bodyoffset" : 1421, + "key.doc.abstract" : [ + { + "Para" : "Represents a record of options for a command, which can be parsed from a list of command-line arguments." + } + ], "key.doc.column" : 17, "key.doc.comment" : "Represents a record of options for a command, which can be parsed from\na list of command-line arguments.\n\nThis is most helpful when used in conjunction with the `Option` and `Switch`\ntypes, and `<*>` and `<|` combinators.\n\nExample:\n\n\tstruct LogOptions: OptionsProtocol {\n\t\tlet verbosity: Int\n\t\tlet outputFilename: String\n\t\tlet shouldDelete: Bool\n\t\tlet logName: String\n\n\t\tstatic func create(_ verbosity: Int) -> (String) -> (Bool) -> (String) -> LogOptions {\n\t\t\treturn { outputFilename in { shouldDelete in { logName in LogOptions(verbosity: verbosity, outputFilename: outputFilename, shouldDelete: shouldDelete, logName: logName) } } }\n\t\t}\n\n\t\tstatic func evaluate(_ m: CommandMode) -> Result> {\n\t\t\treturn create\n\t\t\t\t<*> m <| Option(key: \"verbose\", defaultValue: 0, usage: \"the verbosity level with which to read the logs\")\n\t\t\t\t<*> m <| Option(key: \"outputFilename\", defaultValue: \"\", usage: \"a file to print output to, instead of stdout\")\n\t\t\t\t<*> m <| Switch(flag: \"d\", key: \"delete\", usage: \"delete the logs when finished\")\n\t\t\t\t<*> m <| Argument(usage: \"the log to read\")\n\t\t}\n\t}", "key.doc.declaration" : "public protocol OptionsProtocol", @@ -5628,6 +6093,11 @@ { "key.accessibility" : "source.lang.swift.accessibility.public", "key.annotated_decl" : "static func evaluate(_ m: CommandMode<\/Type>) -> Result<\/Type><Self<\/Type>, CommandantError<\/Type><ClientError<\/Type>>><\/Declaration>", + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.comment" : "Evaluates this set of options in the given mode.\n\nReturns the parsed options or a `UsageError`.", "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", @@ -5678,6 +6148,11 @@ ], "key.bodylength" : 154, "key.bodyoffset" : 1765, + "key.doc.abstract" : [ + { + "Para" : "An `OptionsProtocol` that has no options." + } + ], "key.doc.column" : 15, "key.doc.comment" : "An `OptionsProtocol` that has no options.", "key.doc.declaration" : "public struct NoOptions : OptionsProtocol where ClientError : Error", @@ -5780,6 +6255,11 @@ ], "key.bodylength" : 33, "key.bodyoffset" : 1884, + "key.doc.abstract" : [ + { + "Para" : "Evaluates this set of options in the given mode." + } + ], "key.doc.column" : 14, "key.doc.declaration" : "static func evaluate(_ m: CommandMode) -> Result>", "key.doc.discussion" : [ @@ -5794,6 +6274,11 @@ "key.doc.full_as_xml" : "evaluate(_:)<\/Name>s:10Commandant15OptionsProtocolP8evaluateys6ResultOyxAA0A5ErrorOy06ClientF0QzGGAA11CommandModeOFZ<\/USR>static func evaluate(_ m: CommandMode) -> Result<Self, CommandantError<ClientError>><\/Declaration>Evaluates this set of options in the given mode.<\/Para><\/Abstract>Returns the parsed options or a UsageError<\/codeVoice>.<\/Para>This documentation comment was inherited from OptionsProtocol<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.line" : 43, "key.doc.name" : "evaluate(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `OptionsProtocol`." + } + ], "key.doc.type" : "Function", "key.filepath" : "Sources\/Commandant\/Option.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> static<\/syntaxtype.keyword> func<\/syntaxtype.keyword> evaluate<\/decl.name>(_<\/decl.var.parameter.argument_label> m<\/decl.var.parameter.name>: CommandMode<\/ref.enum><\/decl.var.parameter.type><\/decl.var.parameter>) -> Result<\/ref.enum><NoOptions<\/ref.struct>, CommandantError<\/ref.enum><ClientError<\/ref.generic_type_param>>><\/decl.function.returntype><\/decl.function.method.static>", @@ -5835,6 +6320,11 @@ ], "key.bodylength" : 786, "key.bodyoffset" : 2013, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes an option that can be provided on the command line.", "key.doc.declaration" : "public struct Option", @@ -5884,6 +6374,11 @@ "key.offset" : 2132 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that controls this option. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that controls this option. For example, a key of `verbose` would\nbe used for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -5919,6 +6414,11 @@ "key.offset" : 2303 } ], + "key.doc.abstract" : [ + { + "Para" : "The default value for this option. This is the value that will be used if the option is never explicitly specified on the command line." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The default value for this option. This is the value that will be used\nif the option is never explicitly specified on the command line.", "key.doc.declaration" : "public let defaultValue: T", @@ -5954,12 +6454,17 @@ "key.offset" : 2637 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.\n\nFor boolean operations, this should describe the effect of _not_ using\nthe default value (i.e., what will happen if you disable\/enable the flag\ndifferently from the default).", "key.doc.declaration" : "public let usage: String", "key.doc.discussion" : [ { - "Para" : "For boolean operations, this should describe the effect of using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." + "Para" : "For boolean operations, this should describe the effect of _not_ using the default value (i.e., what will happen if you disable\/enable the flag differently from the default)." } ], "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -6024,6 +6529,11 @@ "key.annotated_decl" : "public struct Option<T><\/Declaration>", "key.bodylength" : 58, "key.bodyoffset" : 2845, + "key.doc.abstract" : [ + { + "Para" : "Describes an option that can be provided on the command line." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Option", "key.doc.file" : "Sources\/Commandant\/Option.swift", @@ -6067,6 +6577,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 2879, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -6084,6 +6599,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Option.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -6130,6 +6650,11 @@ ], "key.bodylength" : 22, "key.bodyoffset" : 4545, + "key.doc.abstract" : [ + { + "Para" : "Applies `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: (T) -> U, value: Result>) -> Result>", @@ -6230,6 +6755,11 @@ ], "key.bodylength" : 346, "key.bodyoffset" : 4978, + "key.doc.abstract" : [ + { + "Para" : "Applies the function in `f` to the value in the given result." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Applies the function in `f` to the value in the given result.\n\nIn the context of command-line option parsing, this is used to chain\ntogether the parsing of multiple arguments. See OptionsProtocol for an example.", "key.doc.declaration" : "public func <*> (f: Result<((T) -> U), CommandantError>, value: Result>) -> Result>", @@ -6323,6 +6853,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 4309, "key.bodyoffset" : 5350, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -6354,6 +6889,11 @@ ], "key.bodylength" : 230, "key.bodyoffset" : 5677, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : Commandant.ArgumentProtocol", @@ -6484,6 +7024,11 @@ ], "key.bodylength" : 852, "key.bodyoffset" : 6216, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result> where T : Commandant.ArgumentProtocol", @@ -6614,6 +7159,11 @@ ], "key.bodylength" : 232, "key.bodyoffset" : 7401, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]>) -> Result<[T], CommandantError> where T : Commandant.ArgumentProtocol", @@ -6744,6 +7294,11 @@ ], "key.bodylength" : 1117, "key.bodyoffset" : 7946, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, `nil` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option<[T]?>) -> Result<[T]?, CommandantError> where T : Commandant.ArgumentProtocol", @@ -6874,6 +7429,11 @@ ], "key.bodylength" : 272, "key.bodyoffset" : 9385, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean option in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean option in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Option) -> Result>", @@ -6971,6 +7531,11 @@ ], "key.bodylength" : 348, "key.bodyoffset" : 82, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.comment" : "A poor man's ordered set.", "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", @@ -7156,6 +7721,11 @@ "key.annotated_decl" : "internal struct OrderedSet<T> : Equatable<\/Type> where T : Hashable<\/Type><\/Declaration>", "key.bodylength" : 331, "key.bodyoffset" : 467, + "key.doc.abstract" : [ + { + "Para" : "A poor manā€™s ordered set." + } + ], "key.doc.column" : 17, "key.doc.declaration" : "internal struct OrderedSet : Equatable where T : Hashable", "key.doc.file" : "Sources\/Commandant\/OrderedSet.swift", @@ -7192,6 +7762,16 @@ "key.annotated_decl" : "subscript(position: Int<\/Type>) -> T<\/Type> { get }<\/Declaration>", "key.bodylength" : 28, "key.bodyoffset" : 500, + "key.doc.abstract" : [ + { + "Para" : "Accesses the element at the specified position." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "subscript(position: Self.Index) -> Self.Element { get }", "key.doc.discussion" : [ { @@ -7212,6 +7792,11 @@ ], "key.doc.full_as_xml" : "subscript(_:)<\/Name>s:Sly7ElementQz5IndexQzcip<\/USR>subscript(position: Self.Index) -> Self.Element { get }<\/Declaration>Accesses the element at the specified position.<\/Para><\/Abstract>position<\/Name>in<\/Direction>The position of the element to access. position<\/codeVoice> must be a valid index of the collection that is not equal to the endIndex<\/codeVoice> property.<\/Para><\/Discussion><\/Parameter><\/Parameters>The following example accesses an element of an array through its subscript to print its value:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>You can subscript a collection with any valid index other than the collectionā€™s end index. The end index refers to the position one past the last element of a collection, so it doesnā€™t correspond with an element.<\/Para>O(1)<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "subscript(_:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.parameters" : [ { "discussion" : [ @@ -7251,10 +7836,20 @@ "key.annotated_decl" : "var count: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 24, "key.bodyoffset" : 548, + "key.doc.abstract" : [ + { + "Para" : "The number of elements in the collection." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1) if the collection conforms to `RandomAccessCollection`; otherwise, O(_n_), where _n_ is the length of the collection." + } + ], "key.doc.declaration" : "var count: Int { get }", "key.doc.discussion" : [ { - "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O() operation." + "Para" : "To check whether a collection is empty, use its `isEmpty` property instead of comparing `count` to zero. Unless the collection guarantees random-access performance, calculating `count` can be an O(_n_) operation." }, { "Complexity" : "" @@ -7265,6 +7860,11 @@ ], "key.doc.full_as_xml" : "count<\/Name>s:Sl5countSivp<\/USR>var count: Int { get }<\/Declaration>The number of elements in the collection.<\/Para><\/Abstract>To check whether a collection is empty, use its isEmpty<\/codeVoice> property instead of comparing count<\/codeVoice> to zero. Unless the collection guarantees random-access performance, calculating count<\/codeVoice> can be an O(n<\/emphasis>) operation.<\/Para>O(1) if the collection conforms to RandomAccessCollection<\/codeVoice>; otherwise, O(n<\/emphasis>), where n<\/emphasis> is the length of the collection.<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "count", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> count<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7291,6 +7891,16 @@ "key.annotated_decl" : "var isEmpty: Bool<\/Type> { get }<\/Declaration>", "key.bodylength" : 26, "key.bodyoffset" : 595, + "key.doc.abstract" : [ + { + "Para" : "A Boolean value indicating whether the collection is empty." + } + ], + "key.doc.complexity" : [ + { + "Para" : "O(1)" + } + ], "key.doc.declaration" : "var isEmpty: Bool { get }", "key.doc.discussion" : [ { @@ -7308,6 +7918,11 @@ ], "key.doc.full_as_xml" : "isEmpty<\/Name>s:Sl7isEmptySbvp<\/USR>var isEmpty: Bool { get }<\/Declaration>A Boolean value indicating whether the collection is empty.<\/Para><\/Abstract>When you need to check whether your collection is empty, use the isEmpty<\/codeVoice> property instead of checking that the count<\/codeVoice> property is equal to zero. For collections that donā€™t conform to RandomAccessCollection<\/codeVoice>, accessing the count<\/codeVoice> property iterates through the elements of the collection.<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>O(1)<\/Para><\/Complexity>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "isEmpty", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> isEmpty<\/decl.name>: Bool<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7334,6 +7949,11 @@ "key.annotated_decl" : "var startIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 29, "key.bodyoffset" : 646, + "key.doc.abstract" : [ + { + "Para" : "The position of the first element in a nonempty collection." + } + ], "key.doc.declaration" : "var startIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7345,6 +7965,11 @@ ], "key.doc.full_as_xml" : "startIndex<\/Name>s:Sl10startIndex0B0Qzvp<\/USR>var startIndex: Self.Index { get }<\/Declaration>The position of the first element in a nonempty collection.<\/Para><\/Abstract>If the collection is empty, startIndex<\/codeVoice> is equal to endIndex<\/codeVoice>.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "startIndex", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> startIndex<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7371,6 +7996,11 @@ "key.annotated_decl" : "var endIndex: Int<\/Type> { get }<\/Declaration>", "key.bodylength" : 27, "key.bodyoffset" : 698, + "key.doc.abstract" : [ + { + "Para" : "The collectionā€™s ā€œpast the endā€ positionā€”that is, the position one greater than the last valid subscript argument." + } + ], "key.doc.declaration" : "var endIndex: Self.Index { get }", "key.doc.discussion" : [ { @@ -7388,6 +8018,11 @@ ], "key.doc.full_as_xml" : "endIndex<\/Name>s:Sl8endIndex0B0Qzvp<\/USR>var endIndex: Self.Index { get }<\/Declaration>The collectionā€™s ā€œpast the endā€ positionā€”that is, the position one greater than the last valid subscript argument.<\/Para><\/Abstract>When you need a range that includes the last element of a collection, use the half-open range operator (..<<\/codeVoice>) with endIndex<\/codeVoice>. The ..<<\/codeVoice> operator creates a range that doesnā€™t include the upper bound, so itā€™s always safe to use with endIndex<\/codeVoice>. For example:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>If the collection is empty, endIndex<\/codeVoice> is equal to startIndex<\/codeVoice>.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "endIndex", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/OrderedSet.swift", "key.fully_annotated_decl" : "var<\/syntaxtype.keyword> endIndex<\/decl.name>: Int<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7414,6 +8049,11 @@ "key.annotated_decl" : "func index(after i: Int<\/Type>) -> Int<\/Type><\/Declaration>", "key.bodylength" : 34, "key.bodyoffset" : 762, + "key.doc.abstract" : [ + { + "Para" : "Returns the position immediately after the given index." + } + ], "key.doc.declaration" : "func index(after i: Self.Index) -> Self.Index", "key.doc.discussion" : [ { @@ -7425,6 +8065,11 @@ ], "key.doc.full_as_xml" : "index(after:)<\/Name>s:Sl5index5after5IndexQzAD_tF<\/USR>func index(after i: Self.Index) -> Self.Index<\/Declaration>Returns the position immediately after the given index.<\/Para><\/Abstract>i<\/Name>in<\/Direction>A valid index of the collection. i<\/codeVoice> must be less than endIndex<\/codeVoice>.<\/Para><\/Discussion><\/Parameter><\/Parameters>The index value immediately after i<\/codeVoice>.<\/Para><\/ResultDiscussion>The successor of an index must be well defined. For an index i<\/codeVoice> into a collection c<\/codeVoice>, calling c.index(after: i)<\/codeVoice> returns the same index every time.<\/Para>This documentation comment was inherited from Collection<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Function>", "key.doc.name" : "index(after:)", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `Collection`." + } + ], "key.doc.parameters" : [ { "discussion" : [ @@ -7489,6 +8134,11 @@ ], "key.bodylength" : 244, "key.bodyoffset" : 175, + "key.doc.abstract" : [ + { + "Para" : "A value that represents either a success or a failure, including an associated value in each case." + } + ], "key.doc.declaration" : "enum Result where Failure : Error", "key.doc.full_as_xml" : "Result<\/Name>s:s6ResultO<\/USR>enum Result<Success, Failure> where Failure : Error<\/Declaration>A value that represents either a success or a failure, including an associated value in each case.<\/Para><\/Abstract><\/CommentParts><\/Other>", "key.doc.name" : "Result", @@ -7574,6 +8224,11 @@ ], "key.bodylength" : 724, "key.bodyoffset" : 397, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.comment" : "Describes a parameterless command line flag that defaults to false and can only\nbe switched on. Canonical examples include `--force` and `--recurse`.\n\nFor a boolean toggle that can be enabled and disabled use `Option`.", "key.doc.declaration" : "public struct Switch", @@ -7611,6 +8266,11 @@ "key.offset" : 515 } ], + "key.doc.abstract" : [ + { + "Para" : "The key that enables this switch. For example, a key of `verbose` would be used for a `--verbose` option." + } + ], "key.doc.column" : 13, "key.doc.comment" : "The key that enables this switch. For example, a key of `verbose` would be\nused for a `--verbose` option.", "key.doc.declaration" : "public let key: String", @@ -7646,6 +8306,11 @@ "key.offset" : 828 } ], + "key.doc.abstract" : [ + { + "Para" : "Optional single letter flag that enables this switch. For example, `-v` would be used as a shorthand for `--verbose`." + } + ], "key.doc.column" : 13, "key.doc.comment" : "Optional single letter flag that enables this switch. For example, `-v` would\nbe used as a shorthand for `--verbose`.\n\nMultiple flags can be grouped together as a single argument and will split\nwhen parsing (e.g. `rm -rf` treats 'r' and 'f' as inidividual flags).", "key.doc.declaration" : "public let flag: Character?", @@ -7686,6 +8351,11 @@ "key.offset" : 968 } ], + "key.doc.abstract" : [ + { + "Para" : "A human-readable string describing the purpose of this option. This will be shown in help messages." + } + ], "key.doc.column" : 13, "key.doc.comment" : "A human-readable string describing the purpose of this option. This will\nbe shown in help messages.", "key.doc.declaration" : "public let usage: String", @@ -7751,6 +8421,11 @@ "key.annotated_decl" : "public struct Switch<\/Declaration>", "key.bodylength" : 140, "key.bodyoffset" : 1167, + "key.doc.abstract" : [ + { + "Para" : "Describes a parameterless command line flag that defaults to false and can only be switched on. Canonical examples include `--force` and `--recurse`." + } + ], "key.doc.column" : 15, "key.doc.declaration" : "public struct Switch", "key.doc.discussion" : [ @@ -7799,6 +8474,11 @@ ], "key.bodylength" : 104, "key.bodyoffset" : 1201, + "key.doc.abstract" : [ + { + "Para" : "A textual representation of this instance." + } + ], "key.doc.declaration" : "var description: String { get }", "key.doc.discussion" : [ { @@ -7816,6 +8496,11 @@ ], "key.doc.full_as_xml" : "description<\/Name>s:s23CustomStringConvertibleP11descriptionSSvp<\/USR>var description: String { get }<\/Declaration>A textual representation of this instance.<\/Para><\/Abstract>Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:)<\/codeVoice> initializer. This initializer works with any type, and uses the custom description<\/codeVoice> property for types that conform to CustomStringConvertible<\/codeVoice>:<\/Para><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/zCodeLineNumbered><\/CodeListing>The conversion of p<\/codeVoice> to a string in the assignment to s<\/codeVoice> uses the Point<\/codeVoice> typeā€™s description<\/codeVoice> property.<\/Para>This documentation comment was inherited from CustomStringConvertible<\/codeVoice>.<\/Para><\/Note><\/Discussion><\/CommentParts><\/Other>", "key.doc.name" : "description", + "key.doc.note" : [ + { + "Para" : "This documentation comment was inherited from `CustomStringConvertible`." + } + ], "key.doc.type" : "Other", "key.filepath" : "Sources\/Commandant\/Switch.swift", "key.fully_annotated_decl" : "public<\/syntaxtype.keyword> var<\/syntaxtype.keyword> description<\/decl.name>: String<\/ref.struct><\/decl.var.type> { get<\/syntaxtype.keyword> }<\/decl.var.instance>", @@ -7872,6 +8557,11 @@ "key.annotated_decl" : "public enum CommandMode<\/Declaration>", "key.bodylength" : 650, "key.bodyoffset" : 1355, + "key.doc.abstract" : [ + { + "Para" : "Describes the ā€œmodeā€ in which a command should run." + } + ], "key.doc.column" : 13, "key.doc.declaration" : "public enum CommandMode", "key.doc.file" : "Sources\/Commandant\/Command.swift", @@ -7903,6 +8593,11 @@ ], "key.bodylength" : 333, "key.bodyoffset" : 1670, + "key.doc.abstract" : [ + { + "Para" : "Evaluates the given boolean switch in the given mode." + } + ], "key.doc.column" : 21, "key.doc.comment" : "Evaluates the given boolean switch in the given mode.\n\nIf parsing command line arguments, and no value was specified on the command\nline, the option's `defaultValue` is used.", "key.doc.declaration" : "public static func <| (mode: CommandMode, option: Switch) -> Result>", diff --git a/Tests/SourceKittenFrameworkTests/Fixtures/Subscript@swift-5.0.json b/Tests/SourceKittenFrameworkTests/Fixtures/Subscript@swift-5.0.json index 267f18e4e..47ea578bf 100644 --- a/Tests/SourceKittenFrameworkTests/Fixtures/Subscript@swift-5.0.json +++ b/Tests/SourceKittenFrameworkTests/Fixtures/Subscript@swift-5.0.json @@ -26,6 +26,11 @@ "key.annotated_decl" : "subscript(key: String<\/Type>) -> () { get set }<\/Declaration>", "key.bodylength" : 46, "key.bodyoffset" : 84, + "key.doc.abstract" : [ + { + "Para" : "Returns or sets Void." + } + ], "key.doc.column" : 5, "key.doc.comment" : "Returns or sets Void.", "key.doc.declaration" : "subscript(key: String) -> () { get set }", diff --git a/Tests/SourceKittenFrameworkTests/SwiftDocMarkupDelimiterTests.swift b/Tests/SourceKittenFrameworkTests/SwiftDocMarkupDelimiterTests.swift new file mode 100644 index 000000000..26d9c33c2 --- /dev/null +++ b/Tests/SourceKittenFrameworkTests/SwiftDocMarkupDelimiterTests.swift @@ -0,0 +1,352 @@ +// +// SwiftDocMarkupDelimiterTests.swift +// SourceKittenFrameworkTests +// +// Created by Eneko Alonso on 5/28/20. +// Copyright Ā© 2020 SourceKitten. All rights reserved. +// + +import SourceKittenFramework +import XCTest + +let markupDelmitersXML = """ +\ +hello(name:)\ +s:14SourceDocsDemo10FullMarkupV5hello4nameS2S_tKF\ +public func hello(name: String) throws -> String\ +\ +\ +Method to say hello to a person or thing\ +\ +\ +\ +name\ +in\ +\ +Name of the person or thing to salute\ +\ +\ +\ +name\ +in\ +\ +Name of the person or thing to salute\ +\ +\ +\ +\ +\ +String with salute (eg. ā€œHello, Kelly!ā€)\ +\ +\ +\ +Error.noName when name is empty\ +\ +\ +This should be the discussion, where we can ellaborate what the method does, providing details and examples.\ +\ +]]>\ +\ +\ +]]>\ +Heading 1\ +]]>\ +\ +Foo\ +\ +]]>\ +Heading 2\ +]]>\ +\ +Bar\ +\ +]]>\ +Heading 3\ +]]>\ +\ +Baz\ +\ +\ +\ +\ +\ +\ +\ +This should be blockquoted text\ +\ +\ +\ +\ +\ +\ +\ +An ordered list of elements:\ +\ +\ +Foo\ +\ +\ +Bar\ +\ +\ +Baz\ +\ +\ +A bulleted list:\ +\ +\ +Foo\ +\ +\ +Bar\ +\ +\ +Baz\ +\ +\ +\ +Italics and italics Bold and bold\ +\ +* This is not a bullet item\ +\ +]]>\ +\ +\ +Use the callout to highlight information for the user of the symbol.\ +\ +\ +Use the callout to display the author of the code for a symbol.\ +\ +\ + A\ +List\ +Of Authors\ +\ +\ +Use the callout to display a bug for a symbol.\ +\ +\ +Use the callout to display the algorithmic complexity of a method or function.\ +\ +\ +Use the callout to display copyright information for a symbol.\ +\ +\ +May 28, 2020\ +\ +\ +Here is some example code:\ +\ +\ +\ +\ +\ +\ +\ +\ +\ +Use the callout to highlight information that can have adverse effects on the tasks a user is trying to accomplish.\ +\ +\ +Use the callout to display a condition that is guaranteed to be true during the execution of the documented symbol.\ +\ +\ +This is a note, that Iā€™m sure of\ +\ +\ +Use the callout to document conditions which have guaranteed values upon completion of the execution of the symbol.\ +\ +\ +Use the callout to document any conditions that are held for the documented symbol to work.\ +\ +\ +This is remarkable\ +\ +\ +\ +Non-empty name\ +\ +\ +Use the callout to add references to other information.\ +\ +\ +Use the callout to add information about when the symbol became available. Some example of the types of information include dates, \ +framework versions, and operating system versions.\ +\ +\ +Use the callout to add tasks required to complete or update the functionality of the symbol.\ +\ +\ +v1.2.3\ +\ +\ +So many delimiters\ +\ +\ +\ +Foo: Custom unsuported delimiters, appear as bulleted list items\ +\ +\ +This is more text after all the delimiters list. Still part of the main discussion.\ +\ +\ + +""" + +class SwiftDocMarkupDelimiterTests: XCTestCase { + + func testAbstract() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Method to say hello to a person or thing"]] + XCTAssertEqual(dictionary?.get(.docAbstract), expectation) + } + + func testThrowsDiscussion() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "`Error.noName` when name is empty"]] + XCTAssertEqual(dictionary?.get(.docThrowsDiscussion), expectation) + } + + func testAttentionDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to highlight information for the user of the symbol."]] + XCTAssertEqual(dictionary?.get(.docAttention), expectation) + } + + func testAuthorDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to display the author of the code for a symbol."]] + XCTAssertEqual(dictionary?.get(.docAuthor), expectation) + } + + func testAuthorsDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [ + ["Para": " A"], + ["Para": "List"], + ["Para": "Of Authors"] + ] + XCTAssertEqual(dictionary?.get(.docAuthors), expectation) + } + + func testBugDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to display a bug for a symbol."]] + XCTAssertEqual(dictionary?.get(.docBug), expectation) + } + + func testComplexityDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to display the algorithmic complexity of a method or function."]] + XCTAssertEqual(dictionary?.get(.docComplexity), expectation) + } + + func testCopyrightDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to display copyright information for a symbol."]] + XCTAssertEqual(dictionary?.get(.docCopyright), expectation) + } + + func testDateDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "May 28, 2020"]] + XCTAssertEqual(dictionary?.get(.docDate), expectation) + } + + /// - toDo: Figure out a way to extract paragraphs and any other type of nested elements (lists, code blocks, etc) + func testExperimentDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [ + ["Para": "Here is some example code:"], + ["CodeListing": ""] + ] + XCTAssertEqual(dictionary?.get(.docExperiment), expectation) + } + + func testImportantDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [ + ["Para": "Use the callout to highlight information that can have adverse effects on the tasks a user is trying to accomplish."] + ] + XCTAssertEqual(dictionary?.get(.docImportant), expectation) + } + + func testInvariantDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [ + ["Para": "Use the callout to display a condition that is guaranteed to be true during the execution of the documented symbol."] + ] + XCTAssertEqual(dictionary?.get(.docInvariant), expectation) + } + + func testNoteDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "This is a note, that Iā€™m sure of"]] + XCTAssertEqual(dictionary?.get(.docNote), expectation) + } + + func testPostconditionDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to document conditions which have guaranteed values upon completion of the execution of the symbol."]] + XCTAssertEqual(dictionary?.get(.docPostcondition), expectation) + } + + func testPreconditionDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to document any conditions that are held for the documented symbol to work."]] + XCTAssertEqual(dictionary?.get(.docPrecondition), expectation) + } + + func testRemarkDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "This is _remarkable_"]] + XCTAssertEqual(dictionary?.get(.docRemark), expectation) + } + + func testRequiresDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Non-empty name"]] + XCTAssertEqual(dictionary?.get(.docRequires), expectation) + } + + func testSeeAlsoDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to add references to other information."]] + XCTAssertEqual(dictionary?.get(.docSeeAlso), expectation) + } + + func testSinceDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": """ + Use the callout to add information about when the symbol became available. \ + Some example of the types of information include dates, \ + framework versions, and operating system versions. + """] + ] + XCTAssertEqual(dictionary?.get(.docSince), expectation) + } + + func testToDoDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "Use the callout to add tasks required to complete or update the functionality of the symbol."]] + XCTAssertEqual(dictionary?.get(.docToDo), expectation) + } + + func testVersionDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "v1.2.3"]] + XCTAssertEqual(dictionary?.get(.docVersion), expectation) + } + + func testWarningDelimiter() { + let dictionary = parseFullXMLDocs(markupDelmitersXML) + let expectation = [["Para": "So many delimiters"]] + XCTAssertEqual(dictionary?.get(.docWarning), expectation) + } +} + +extension Dictionary where Key == String, Value == SourceKitRepresentable { + func get(_ key: SwiftDocKey) -> [[String: String]]? { + return self[key.rawValue] as? [[String: String]] + } +} diff --git a/Tests/SourceKittenFrameworkTests/SwiftDocsTests.swift b/Tests/SourceKittenFrameworkTests/SwiftDocsTests.swift index 8d25bc018..9013d01b3 100644 --- a/Tests/SourceKittenFrameworkTests/SwiftDocsTests.swift +++ b/Tests/SourceKittenFrameworkTests/SwiftDocsTests.swift @@ -144,6 +144,7 @@ class SwiftDocsTests: XCTestCase { "key.doc.name": "name", "key.usr": "usr", "key.doc.declaration": "declaration", + "key.doc.abstract": [["Para": "discussion"]], "key.doc.parameters": [[ "name": "param1", "discussion": [["Para": "param1_discussion"]] diff --git a/sourcekitten.xcodeproj/project.pbxproj b/sourcekitten.xcodeproj/project.pbxproj index 69bdd3cef..08783b9db 100644 --- a/sourcekitten.xcodeproj/project.pbxproj +++ b/sourcekitten.xcodeproj/project.pbxproj @@ -34,6 +34,7 @@ 6CCFCE8E1CFED000003239EB /* Commandant.framework in Embed Frameworks into SourceKittenFramework.framework */ = {isa = PBXBuildFile; fileRef = E8EBAA5D1A5D374B002F1B8E /* Commandant.framework */; settings = {ATTRIBUTES = (CodeSignOnCopy, RemoveHeadersOnCopy, ); }; }; 8F935B342288C05A00971070 /* File+Hashable.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8F935B332288C05A00971070 /* File+Hashable.swift */; }; 8FB50D0623BFF035004F0F2B /* Line.swift in Sources */ = {isa = PBXBuildFile; fileRef = 8FB50D0523BFF035004F0F2B /* Line.swift */; }; + 9C57920B2480C60800ADCD37 /* SwiftDocMarkupDelimiterTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 9C57920A2480C60800ADCD37 /* SwiftDocMarkupDelimiterTests.swift */; }; BCF9238E228AD94E0008C684 /* CursorInfoUSRTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = BCF9238D228AD94E0008C684 /* CursorInfoUSRTests.swift */; }; C236E84B1DFF5120003807D2 /* YamlRequestCommand.swift in Sources */ = {isa = PBXBuildFile; fileRef = C236E84A1DFF5120003807D2 /* YamlRequestCommand.swift */; }; CDB51F33203E2899007563AE /* SwiftDocKeyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = CDB51F32203E2899007563AE /* SwiftDocKeyTests.swift */; }; @@ -173,6 +174,7 @@ 6CC381621ECACB50000C6F81 /* Version.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Version.swift; sourceTree = ""; }; 8F935B332288C05A00971070 /* File+Hashable.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "File+Hashable.swift"; sourceTree = ""; }; 8FB50D0523BFF035004F0F2B /* Line.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = Line.swift; sourceTree = ""; }; + 9C57920A2480C60800ADCD37 /* SwiftDocMarkupDelimiterTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SwiftDocMarkupDelimiterTests.swift; sourceTree = ""; }; BCF9238D228AD94E0008C684 /* CursorInfoUSRTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CursorInfoUSRTests.swift; sourceTree = ""; }; C236E84A1DFF5120003807D2 /* YamlRequestCommand.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = YamlRequestCommand.swift; sourceTree = ""; }; CDB51F32203E2899007563AE /* SwiftDocKeyTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SwiftDocKeyTests.swift; sourceTree = ""; }; @@ -529,6 +531,7 @@ E8C9EA071A5C99C400A6D4D1 /* StringTests.swift */, E8C9EA031A5C986A00A6D4D1 /* StructureTests.swift */, CDB51F32203E2899007563AE /* SwiftDocKeyTests.swift */, + 9C57920A2480C60800ADCD37 /* SwiftDocMarkupDelimiterTests.swift */, E80F23661A5CADD900FD2352 /* SwiftDocsTests.swift */, D0DB09A319EA354200234B16 /* SyntaxTests.swift */, BCF9238D228AD94E0008C684 /* CursorInfoUSRTests.swift */, @@ -803,6 +806,7 @@ E8C9EA081A5C99C400A6D4D1 /* StringTests.swift in Sources */, CDB51F33203E2899007563AE /* SwiftDocKeyTests.swift in Sources */, E8C9EA041A5C986A00A6D4D1 /* StructureTests.swift in Sources */, + 9C57920B2480C60800ADCD37 /* SwiftDocMarkupDelimiterTests.swift in Sources */, E80F23671A5CADD900FD2352 /* SwiftDocsTests.swift in Sources */, D0DB09A419EA354200234B16 /* SyntaxTests.swift in Sources */, );