Merge branch 'swiftlang:main' into main

Author: hanny-ph

CODE_OF_CONDUCT.md

@@ -1,4 +1,4 @@
-// swift-tools-version:5.5
+// swift-tools-version:5.7
 /*
  This source file is part of the Swift.org open source project
 
@@ -28,6 +28,9 @@ let package = Package(
                 "CAtomic",
                 .product(name: "cmark-gfm", package: cmarkPackageName),
                 .product(name: "cmark-gfm-extensions", package: cmarkPackageName),
+            ], 
+            exclude: [
+                "CMakeLists.txt"
             ]),
         .testTarget(
             name: "MarkdownTests",
@@ -43,7 +46,7 @@ let package = Package(
 if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
     // Building standalone, so fetch all dependencies remotely.
     package.dependencies += [
-        .package(url: "https://github.com/apple/swift-cmark.git", branch: "gfm"),
+        .package(url: "https://github.com/swiftlang/swift-cmark.git", branch: "gfm"),
     ]
 
     // SwiftPM command plugins are only supported by Swift version 5.6 and later.

Package.swift

@@ -4,7 +4,7 @@ Swift `Markdown` is a Swift package for parsing, building, editing, and analyzin
 
 The parser is powered by GitHub-flavored Markdown's [cmark-gfm](https://github.com/github/cmark-gfm) implementation, so it follows the spec closely. As the needs of the community change, the effective dialect implemented by this library may change.
 
-The markup tree provided by this package is comprised of immutable/persistent, thread-safe, copy-on-write value types that only copy substructure that has changed. Other examples of the main strategy behind this library can be seen in [SwiftSyntax](https://github.com/apple/swift-syntax).
+The markup tree provided by this package is comprised of immutable/persistent, thread-safe, copy-on-write value types that only copy substructure that has changed. Other examples of the main strategy behind this library can be seen in [SwiftSyntax](https://github.com/swiftlang/swift-syntax).
 
 ## Getting Started Using Markup
 
@@ -41,10 +41,12 @@ print(document.debugDescription())
 //    └─ Text "."
 ```
 
-Please see Swift `Markdown`'s [documentation site](https://apple.github.io/swift-markdown/documentation/markdown/)
+Please see Swift `Markdown`'s [documentation site](https://swiftlang.github.io/swift-markdown/documentation/markdown/)
 for more detailed information about the library.
 
-## Getting Involved
+## Contributing to Swift Markdown
+
+Please see the [contributing guide](https://swift.org/contributing/#contributing-code) for more information.
 
 ### Submitting a Bug Report
 
@@ -62,8 +64,6 @@ or start a discussion on the [Swift Forums](https://forums.swift.org/c/developme
 Don't hesitate to submit a feature request if you see a way
 Swift Markdown can be improved to better meet your needs.
 
-### Contributing to Swift Markdown
 
-Please see the [contributing guide](https://swift.org/contributing/#contributing-code) for more information.
 
 <!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

README.md

@@ -6,7 +6,7 @@ Swift `Markdown` is a Swift package for parsing, building, editing, and analyzin
 
 The parser is powered by GitHub-flavored Markdown's [cmark-gfm](https://github.com/github/cmark-gfm) implementation, so it follows the spec closely. As the needs of the community change, the effective dialect implemented by this library may change.
 
-The markup tree provided by this package is comprised of immutable/persistent, thread-safe, copy-on-write value types that only copy substructure that has changed. Other examples of the main strategy behind this library can be seen in [SwiftSyntax](https://github.com/apple/swift-syntax).
+The markup tree provided by this package is comprised of immutable/persistent, thread-safe, copy-on-write value types that only copy substructure that has changed. Other examples of the main strategy behind this library can be seen in [SwiftSyntax](https://github.com/swiftlang/swift-syntax).
 
 ## Topics
 

Sources/Markdown/Markdown.docc/Markdown.md

@@ -44,6 +44,8 @@ Doxygen commands are not parsed within code blocks or block directive content.
 
 ### Commands
 
+- ``DoxygenDiscussion``
+- ``DoxygenNote``
 - ``DoxygenParam``
 - ``DoxygenReturns``
 

Sources/Markdown/Markdown.docc/Markdown/DoxygenCommands.md

@@ -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-2023 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
@@ -13,7 +13,7 @@
 /// - note: This interface only provides requirements for visiting each kind of element. It does not require each visit method to descend into child elements.
 ///
 /// Generally, ``MarkupWalker`` is best for walking a ``Markup`` tree if the ``Result`` type is `Void` or is built up some other way, or ``MarkupRewriter`` for recursively changing a tree's structure. This type serves as a common interface to both. However, for building up other structured result types you can implement ``MarkupVisitor`` directly.
-public protocol MarkupVisitor {
+public protocol MarkupVisitor<Result> {
 
     /**
      The result type returned when visiting a element.

Sources/Markdown/Visitor/MarkupVisitor.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -463,7 +463,8 @@ public struct MarkupFormatter: MarkupWalker {
                 } else if let numeralPrefix = numeralPrefix(for: parentListItem) {
                     prefix += String(repeating: " ", count: numeralPrefix.count)
                 }
-            } else if element is BlockDirective {
+            }
+            if element.parent is BlockDirective {
                 prefix += "    "
             }
         }
@@ -1105,7 +1106,9 @@ public struct MarkupFormatter: MarkupWalker {
     }
 
     public mutating func visitBlockDirective(_ blockDirective: BlockDirective) {
-        ensurePrecedingNewlineCount(atLeast: 1)
+        if blockDirective.indexInParent > 0 {
+            ensurePrecedingNewlineCount(atLeast: 2)
+        }
         print("@", for: blockDirective)
         print(blockDirective.name, for: blockDirective)
 
@@ -1124,13 +1127,13 @@ public struct MarkupFormatter: MarkupWalker {
 
         if blockDirective.childCount > 0 {
             print(" {", for: blockDirective)
+            queueNewline()
         }
 
         descendInto(blockDirective)
 
-        queueNewline()
-
         if blockDirective.childCount > 0 {
+            queueNewline()
             print("}", for: blockDirective)
         }
     }
@@ -1165,15 +1168,29 @@ public struct MarkupFormatter: MarkupWalker {
         }
     }
 
-    public mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) -> () {
-        print("\(formattingOptions.doxygenCommandPrefix.rawValue)param", for: doxygenParam)
-        print(" \(doxygenParam.name) ", for: doxygenParam)
+    private mutating func printDoxygenStart(_ name: String, for element: Markup) {
+        print(formattingOptions.doxygenCommandPrefix.rawValue + name + " ", for: element)
+    }
+
+    public mutating func visitDoxygenDiscussion(_ doxygenDiscussion: DoxygenDiscussion) {
+        printDoxygenStart("discussion", for: doxygenDiscussion)
+        descendInto(doxygenDiscussion)
+    }
+
+    public mutating func visitDoxygenNote(_ doxygenNote: DoxygenNote) {
+        printDoxygenStart("note", for: doxygenNote)
+        descendInto(doxygenNote)
+    }
+
+    public mutating func visitDoxygenParameter(_ doxygenParam: DoxygenParameter) {
+        printDoxygenStart("param", for: doxygenParam)
+        print("\(doxygenParam.name) ", for: doxygenParam)
         descendInto(doxygenParam)
     }
 
-    public mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) -> () {
+    public mutating func visitDoxygenReturns(_ doxygenReturns: DoxygenReturns) {
         // FIXME: store the actual command name used in the original markup
-        print("\(formattingOptions.doxygenCommandPrefix.rawValue)returns ", for: doxygenReturns)
+        printDoxygenStart("returns", for: doxygenReturns)
         descendInto(doxygenReturns)
     }
 }

Sources/Markdown/Walker/Walkers/MarkupFormatter.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -289,6 +289,56 @@ class MarkupFormatterSingleElementTests: XCTestCase {
         XCTAssertEqual(expected, printed)
     }
 
+    func testPrintDoxygenPrefix() {
+        let expectedSlash = #"\discussion Discussion"#
+        let printedSlash = DoxygenDiscussion(children: Paragraph(Text("Discussion")))
+            .format(options: .init(doxygenCommandPrefix: .backslash))
+        XCTAssertEqual(expectedSlash, printedSlash)
+
+        let expectedAt = "@discussion Discussion"
+        let printedAt = DoxygenDiscussion(children: Paragraph(Text("Discussion")))
+            .format(options: .init(doxygenCommandPrefix: .at))
+        XCTAssertEqual(expectedAt, printedAt)
+    }
+
+    func testPrintDoxygenDiscussion() {
+        let expected = #"\discussion Another thing."#
+        let printed = DoxygenDiscussion(children: Paragraph(Text("Another thing."))).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenDiscussionMultiline() {
+        let expected = #"""
+        \discussion Another thing.
+        This is an extended discussion.
+        """#
+        let printed = DoxygenDiscussion(children: Paragraph(
+            Text("Another thing."),
+            SoftBreak(),
+            Text("This is an extended discussion.")
+        )).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenNote() {
+        let expected = #"\note Another thing."#
+        let printed = DoxygenNote(children: Paragraph(Text("Another thing."))).format()
+        XCTAssertEqual(expected, printed)
+    }
+
+    func testPrintDoxygenNoteMultiline() {
+        let expected = #"""
+        \note Another thing.
+        This is an extended discussion.
+        """#
+        let printed = DoxygenNote(children: Paragraph(
+            Text("Another thing."),
+            SoftBreak(),
+            Text("This is an extended discussion.")
+        )).format()
+        XCTAssertEqual(expected, printed)
+    }
+
     func testPrintDoxygenParameter() {
         let expected = #"\param thing The thing."#
         let printed = DoxygenParameter(name: "thing", children: Paragraph(Text("The thing."))).format()
@@ -326,6 +376,18 @@ class MarkupFormatterSingleElementTests: XCTestCase {
         )).format()
         XCTAssertEqual(expected, printed)
     }
+
+    func testPrintBlockDirective() {
+        let expected = #"""
+        @Metadata {
+            @TitleHeading(Example)
+        }
+        """#
+        let printed = BlockDirective(name: "Metadata", children: [
+            BlockDirective(name: "TitleHeading", argumentText: "Example"),
+        ]).format()
+        XCTAssertEqual(expected, printed)
+    }
 }
 
 /// Tests that formatting options work correctly.
@@ -1483,10 +1545,65 @@ class MarkupFormatterTableTests: XCTestCase {
         """
 
         XCTAssertEqual(expected, formatted)
-        print(formatted)
 
         let reparsed = Document(parsing: formatted)
-        print(reparsed.debugDescription())
         XCTAssertTrue(document.hasSameStructure(as: reparsed))
     }
 }
+
+class MarkupFormatterMixedContentTests: XCTestCase {
+    func testMixedContentWithBlockDirectives() {
+        let expected = [
+            #"""
+            # Example title
+
+            @Metadata {
+                @TitleHeading(example)
+            }
+            """#,
+            #"""
+            @Tutorials(name: Foo) {
+                @Intro(title: Bar) {
+                    Foobar
+                    
+                    @Image(source: foo, alt: bar)
+                }
+            }
+            """#,
+            #"""
+            # Example title
+
+            @Links(visualStyle: list) {
+                - ``Foo``
+                - ``Bar``
+            }
+            """#,
+        ]
+        let printed = [
+            Document(
+                Heading(level: 1, Text("Example title")),
+                BlockDirective(name: "Metadata", children: [
+                    BlockDirective(name: "TitleHeading", argumentText: "example"),
+                ])
+            ).format(),
+            Document(
+                BlockDirective(name: "Tutorials", argumentText: "name: Foo", children: [
+                    BlockDirective(name: "Intro", argumentText: "title: Bar", children: [
+                        Paragraph(Text("Foobar")) as BlockMarkup,
+                        BlockDirective(name: "Image", argumentText: "source: foo, alt: bar") as BlockMarkup,
+                    ]),
+                ])
+            ).format(),
+            Document(
+                Heading(level: 1, Text("Example title")),
+                BlockDirective(name: "Links", argumentText: "visualStyle: list", children: [
+                    UnorderedList([
+                        ListItem(Paragraph(SymbolLink(destination: "Foo"))),
+                        ListItem(Paragraph(SymbolLink(destination: "Bar"))),
+                    ]),
+                ])
+            ).format(),
+        ]
+        zip(expected, printed).forEach { XCTAssertEqual($0, $1) }
+    }
+}

Tests/MarkdownTests/Visitors/MarkupFormatterTests.swift

@@ -95,7 +95,6 @@ final class MarkupTreeDumperTests: XCTestCase {
         └─ HTMLBlock @42:1-42:90 #71
            <!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
         """
-        print(everythingDocument.debugDescription(options: [.printEverything]))
         XCTAssertEqual(expectedDump, everythingDocument.debugDescription(options: [.printEverything]))
     }
 }

Tests/MarkdownTests/Visitors/MarkupTreeDumperTests.swift

@@ -0,0 +1,56 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 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
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import XCTest
+import Markdown
+
+class MarkupVisitorTests: XCTestCase {
+    struct IntegerConverter: MarkupVisitor {
+        var value: Int
+        
+        mutating func defaultVisit(_: Markdown.Markup) -> Int {
+            defer { value += 1 }
+            return value
+        }
+    }
+    
+    
+    // A compile time check for PAT support
+    func testMarkupVisitorPrimaryAssociatedType() {
+        var visitor: some MarkupVisitor<Int> = IntegerConverter(value: 1)
+        let markup = Text("")
+        XCTAssertEqual(visitor.visit(markup), 1)
+        XCTAssertEqual(visitor.visit(markup), 2)
+        var mappedVisitor: some MarkupVisitor<Int> = visitor.map { $0 * $0 }  
+        XCTAssertEqual(mappedVisitor.visit(markup), 9)
+        XCTAssertEqual(mappedVisitor.visit(markup), 16)
+        XCTAssertEqual(visitor.visit(markup), 3)
+    }
+}
+
+struct _MappVisitor<A: MarkupVisitor, B>: MarkupVisitor {
+    typealias Result = B
+    init(visitor: A, _ transform: @escaping (A.Result) -> B) {
+        self.visitor = visitor
+        self.transform = transform
+    }
+    private var visitor: A
+    private let transform: (A.Result) -> B
+    
+    mutating func defaultVisit(_ markup: Markdown.Markup) -> B {
+        transform(visitor.defaultVisit(markup))
+    }
+}
+
+extension MarkupVisitor {
+    func map<U>(_ transform: @escaping (Self.Result) -> U) -> some MarkupVisitor<U> {
+        _MappVisitor(visitor: self, transform)
+    }
+}