Add support for an initial directive argument without a name (#27)

* Add support for a leading directive argument without a name

* Update the supported years in check-source

* Add missing copyright information to Markdown.md

* Document changes to name-value argument syntax

Author: d-ronnqvist

Sources/Markdown/Base/DirectiveArgument.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -178,8 +178,11 @@ public struct DirectiveArgumentText: Equatable {
         /// Parse the line segment as name-value argument pairs separated by commas.
         ///
         /// ```
-        /// name-value-arguments -> name-value-argument name-value-arguments-rest
+        /// arguments -> first-argument name-value-arguments-rest
+        /// first-argument -> value-only-argument | name-value-argument
+        /// value-only-argument -> literal
         /// name-value-argument -> literal : literal
+        /// name-value-arguments -> name-value-argument name-value-arguments-rest
         /// name-value-arguments-rest -> , name-value-arguments | ε
         /// ```
         ///
@@ -188,6 +191,8 @@ public struct DirectiveArgumentText: Equatable {
         /// - An argument-name pair is only recognized within a single line or line segment;
         ///   that is, an argument cannot span multiple lines.
         /// - A comma is expected between name-value pairs.
+        /// - The first argument can be unnamed. An unnamed argument will have an empty ``DirectiveArgument/name`` with no ``DirectiveArgument/nameRange``.
+        ///
         /// - Parameter diagnosticEngine: the diagnostic engine to use for emitting diagnostics.
         /// - Returns: an array of successfully parsed ``DirectiveArgument`` values.
         public func parseNameValueArguments(parseErrors: inout [ParseError]) -> [DirectiveArgument] {
@@ -199,7 +204,10 @@ public struct DirectiveArgumentText: Equatable {
                                    parseIndex: parseIndex)
             line.lexWhitespace()
             while !line.isEmptyOrAllWhitespace {
-                guard let name = parseLiteral(from: &line, parseErrors: &parseErrors) else {
+                let name: TrimmedLine.Lex?
+                let value: TrimmedLine.Lex
+                
+                guard let firstLiteral = parseLiteral(from: &line, parseErrors: &parseErrors) else {
                     while parseCharacter(",", from: &line, required: true, allowEscape: false, diagnoseIfNotFound: false, parseErrors: &parseErrors) {
                         if let location = line.location {
                             parseErrors.append(.unexpectedCharacter(",", location: location))
@@ -208,22 +216,33 @@ public struct DirectiveArgumentText: Equatable {
                     _ = line.lex(untilCharacter: ",")
                     continue
                 }
-                _ = parseCharacter(":", from: &line, required: true, allowEscape: false, diagnoseIfNotFound: true,
-                                   parseErrors: &parseErrors)
-                guard let value = parseLiteral(from: &line, parseErrors: &parseErrors) else {
-                    while parseCharacter(",", from: &line, required: true, allowEscape: false, diagnoseIfNotFound: false, parseErrors: &parseErrors) {
-                        if let location = line.location {
-                            parseErrors.append(.unexpectedCharacter(",", location: location))
+                
+                // The first argument can be without a name.
+                // An argument without a name must be followed by a "," or be the only argument. Otherwise the argument will be parsed as a named argument.
+                if arguments.isEmpty && (line.isEmptyOrAllWhitespace || line.text.first == ",") {
+                    name = nil
+                    value = firstLiteral
+                } else {
+                    _ = parseCharacter(":", from: &line, required: true, allowEscape: false, diagnoseIfNotFound: true, parseErrors: &parseErrors)
+                    
+                    guard let secondLiteral = parseLiteral(from: &line, parseErrors: &parseErrors) else {
+                        while parseCharacter(",", from: &line, required: true, allowEscape: false, diagnoseIfNotFound: false, parseErrors: &parseErrors) {
+                            if let location = line.location {
+                                parseErrors.append(.unexpectedCharacter(",", location: location))
+                            }
                         }
+                        _ = line.lex(untilCharacter: ",")
+                        continue
                     }
-                    _ = line.lex(untilCharacter: ",")
-                    continue
+                    name = firstLiteral
+                    value = secondLiteral
                 }
+                
                 let nameRange: SourceRange?
                 let valueRange: SourceRange?
 
                 if let lineLocation = line.location,
-                   let range = name.range {
+                   let range = name?.range {
                     nameRange = SourceLocation(line: lineLocation.line, column: range.lowerBound.column, source: range.lowerBound.source)..<SourceLocation(line: lineLocation.line, column: range.upperBound.column, source: range.upperBound.source)
                 } else {
                     nameRange = nil
@@ -243,7 +262,7 @@ public struct DirectiveArgumentText: Equatable {
                                                       diagnoseIfNotFound: false,
                                                       parseErrors: &parseErrors)
 
-                let argument = DirectiveArgument(name: String(name.text),
+                let argument = DirectiveArgument(name: String(name?.text ?? ""),
                                                  nameRange: nameRange,
                                                  value: String(value.text),
                                                  valueRange: valueRange,
@@ -284,8 +303,11 @@ public struct DirectiveArgumentText: Equatable {
     /// Parse the line segments as name-value argument pairs separated by commas.
     ///
     /// ```
-    /// name-value-arguments -> name-value-argument name-value-arguments-rest
+    /// arguments -> first-argument name-value-arguments-rest
+    /// first-argument -> value-only-argument | name-value-argument
+    /// value-only-argument -> literal
     /// name-value-argument -> literal : literal
+    /// name-value-arguments -> name-value-argument name-value-arguments-rest
     /// name-value-arguments-rest -> , name-value-arguments | ε
     /// ```
     ///
@@ -294,6 +316,8 @@ public struct DirectiveArgumentText: Equatable {
     /// - An argument-name pair is only recognized within a single line or line segment;
     ///   that is, an argument cannot span multiple lines.
     /// - A comma is expected between name-value pairs.
+    /// - The first argument can be unnamed. An unnamed argument will have an empty ``DirectiveArgument/name`` with no ``DirectiveArgument/nameRange``.
+    ///
     /// - Parameter parseErrors: an array to collect errors while parsing arguments.
     /// - Returns: an array of successfully parsed ``DirectiveArgument`` values.
     public func parseNameValueArguments(parseErrors: inout [ParseError]) -> [DirectiveArgument] {
@@ -326,8 +350,11 @@ public struct DirectiveArgumentText: Equatable {
     /// Parse the line segments as name-value argument pairs separated by commas.
     ///
     /// ```
-    /// name-value-arguments -> name-value-argument name-value-arguments-rest
+    /// arguments -> first-argument name-value-arguments-rest
+    /// first-argument -> value-only-argument | name-value-argument
+    /// value-only-argument -> literal
     /// name-value-argument -> literal : literal
+    /// name-value-arguments -> name-value-argument name-value-arguments-rest
     /// name-value-arguments-rest -> , name-value-arguments | ε
     /// ```
     ///
@@ -336,6 +363,8 @@ public struct DirectiveArgumentText: Equatable {
     /// - An argument-name pair is only recognized within a single line or line segment;
     ///   that is, an argument cannot span multiple lines.
     /// - A comma is expected between name-value pairs.
+    /// - The first argument can be unnamed. An unnamed argument will have an empty ``DirectiveArgument/name`` with no ``DirectiveArgument/nameRange``.
+    ///
     /// - Returns: an array of successfully parsed ``DirectiveArgument`` values.
     ///
     /// This overload discards parse errors.

Sources/Markdown/Markdown.docc/Markdown.md

@@ -36,3 +36,5 @@ The markup tree provided by this package is comprised of immutable/persistent, t
 
 - <doc:VisitMarkup> 
 - <doc:FormatterAndOptions>
+
+<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/Markdown/Markdown.docc/Markdown/BlockDirectives.md

@@ -73,12 +73,18 @@ You can parse argument text segments however you like. Swift Markdown also inclu
 
 When using the name-value argument parser, this results in arguments `x` with value `1` and `y` with value `2`. Names and values are both strings; it's up to you to decide how to convert them into something more specific.
 
+When using the name-value argument parser, the first argument can be unnamed for when the directive name also describes the purpose of the first argument. This parsed name-value pair will have an empty name. All other arguments have both names and values. 
+
 Here is the grammar of name-value argument syntax:
 
 ```
-Arguments -> Argument ArgumentsRest?
-ArgumentsRest -> , Arguments
+Arguments -> FirstArgument ArgumentsRest?
+ArgumentsRest -> , NamedArguments
+NamedArguments -> Argument ArgumentsRest?
+FirstArgument -> UnnamedArgument
+               | Argument
 Argument -> Literal : Literal
+UnnamedArgument -> Literal
 Literal -> QuotedLiteral
          | UnquotedLiteral
 QuotedLiteral -> " QuotedLiteralContent "
@@ -171,4 +177,4 @@ for diagnostic in collector.diagnostics {
 }
 ```
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/MarkdownTests/Parsing/BlockDirectiveParserTests.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -394,7 +394,97 @@ class BlockDirectiveArgumentParserTests: XCTestCase {
             XCTAssertEqual(SourceLocation(line: 1, column: 11, source: nil)..<SourceLocation(line: 1, column: 16, source: nil), x.valueRange)
         }
     }
+    
+    func testUnlabeledOnlyArgument() {
+        let source = "@Outer(unlabeledArgumentValue)"
+
+        let document = Document(parsing: source, options: .parseBlockDirectives)
+
+        let directive = document.child(at: 0) as! BlockDirective
+        XCTAssertEqual(1, directive.argumentText.segments.count)
+
+        var parseErrors = [DirectiveArgumentText.ParseError]()
+        let arguments = directive.argumentText.parseNameValueArguments(parseErrors: &parseErrors)
+        XCTAssertTrue(parseErrors.isEmpty)
+
+        XCTAssertEqual(1, arguments.count)
+
+        arguments[""].map { x in
+            XCTAssertEqual("", x.name)
+            XCTAssertEqual(nil, x.nameRange)
+            XCTAssertEqual("unlabeledArgumentValue", x.value)
+            XCTAssertEqual(SourceLocation(line: 1, column: 8, source: nil)..<SourceLocation(line: 1, column: 30, source: nil), x.valueRange)
+        }
+    }
+    
+    func testUnlabeledQuotedOnlyArgument(){
+        let source = "@Outer(\"Unlabeled argument value\")"
+
+        let document = Document(parsing: source, options: .parseBlockDirectives)
+
+        let directive = document.child(at: 0) as! BlockDirective
+        XCTAssertEqual(1, directive.argumentText.segments.count)
 
+        var parseErrors = [DirectiveArgumentText.ParseError]()
+        let arguments = directive.argumentText.parseNameValueArguments(parseErrors: &parseErrors)
+        XCTAssertTrue(parseErrors.isEmpty)
+
+        XCTAssertEqual(1, arguments.count)
+
+        arguments[""].map { x in
+            XCTAssertEqual("", x.name)
+            XCTAssertEqual(nil, x.nameRange)
+            XCTAssertEqual("Unlabeled argument value", x.value)
+            XCTAssertEqual(SourceLocation(line: 1, column: 9, source: nil)..<SourceLocation(line: 1, column: 33, source: nil), x.valueRange)
+        }
+    }
+    
+    func testFirstArgumentWithoutName() {
+        let source = "@Outer(unlabeledArgumentValue, label: value)"
+
+        let document = Document(parsing: source, options: .parseBlockDirectives)
+
+        let directive = document.child(at: 0) as! BlockDirective
+        XCTAssertEqual(1, directive.argumentText.segments.count)
+
+        var parseErrors = [DirectiveArgumentText.ParseError]()
+        let arguments = directive.argumentText.parseNameValueArguments(parseErrors: &parseErrors)
+        XCTAssertTrue(parseErrors.isEmpty)
+
+        XCTAssertEqual(2, arguments.count)
+
+        arguments[""].map { x in
+            XCTAssertEqual("", x.name)
+            XCTAssertEqual(nil, x.nameRange)
+            XCTAssertEqual("unlabeledArgumentValue", x.value)
+            XCTAssertEqual(SourceLocation(line: 1, column: 8, source: nil)..<SourceLocation(line: 1, column: 30, source: nil), x.valueRange)
+        }
+    }
+    
+    func testSecondArgumentWithoutName() throws {
+        let source = "@Outer(label: value, unlabeledArgumentValue)"
+
+        let document = Document(parsing: source, options: .parseBlockDirectives)
+
+        let directive = document.child(at: 0) as! BlockDirective
+        XCTAssertEqual(1, directive.argumentText.segments.count)
+
+        var parseErrors = [DirectiveArgumentText.ParseError]()
+        let arguments = directive.argumentText.parseNameValueArguments(parseErrors: &parseErrors)
+        XCTAssertEqual(parseErrors.count, 1)
+       
+        XCTAssertEqual([.missingExpectedCharacter(":", location: .init(line: 1, column: 44, source: nil))], parseErrors)
+
+        XCTAssertEqual(1, arguments.count)
+
+        arguments["label"].map { x in
+            XCTAssertEqual("label", x.name)
+            XCTAssertEqual(SourceLocation(line: 1, column: 8, source: nil)..<SourceLocation(line: 1, column: 13, source: nil), x.nameRange)
+            XCTAssertEqual("value", x.value)
+            XCTAssertEqual(SourceLocation(line: 1, column: 15, source: nil)..<SourceLocation(line: 1, column: 20, source: nil), x.valueRange)
+        }
+    }
+    
     func testRangeAdjustment() {
         let source = """
         @Outer {

bin/check-source

@@ -18,7 +18,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
 function replace_acceptable_years() {
     # this needs to replace all acceptable forms with 'YEARS'
-    sed -e 's/20[12][78901]-20[12][8901]/YEARS/' -e 's/20[12][8901]/YEARS/'
+    sed -e 's/20[12][78901]-20[12][89012]/YEARS/' -e 's/20[12][89012]/YEARS/'
 }
 
 printf "=> Checking for unacceptable language… "