perform some path sanitization over the generated names (#258)

* perform some path sanitization over the generated names

The current scheme for the file generation uses the function label,
which uses ':' as a parameter separator.  However, this character is not
valid on all file systems.  This results in partial content generation
on Windows.  Add a sanitization step which replaces "invalid" characters
with `_` instead.  This does not impact the rendering, only the
filenames and the generated URL references between the pages.  With
this, we can generate and link function documentation on Windows.

* Apply suggestion from code review

Co-authored-by: Mattt <[email protected]>

Author: compnerd

Sources/SwiftDoc/Helpers.swift

@@ -14,10 +14,20 @@ public func path(for symbol: Symbol, with baseURL: String) -> String {
 }
 
 public func path(for identifier: CustomStringConvertible, with baseURL: String) -> String {
-    let url = URL(string: baseURL)?.appendingPathComponent("\(identifier)") ?? URL(string: "\(identifier)")
+    let tail: String = path(for: "\(identifier)")
+    let url = URL(string: baseURL)?.appendingPathComponent(tail) ?? URL(string: tail)
     guard let string = url?.absoluteString else {
         fatalError("Unable to construct path for \(identifier) with baseURL \(baseURL)")
     }
 
     return string
 }
+
+private let reservedCharacters: CharacterSet = [
+    // Windows Reserved Characters
+    "<", ">", ":", "\"", "/", "\\", "|", "?", "*",
+]
+
+public func path(for identifier: String) -> String {
+    return identifier.components(separatedBy: reservedCharacters).joined(separator: "_")
+}

Sources/swift-doc/Subcommands/Generate.swift

@@ -134,11 +134,11 @@ extension SwiftDoc {
             let filename: String
             switch format {
             case .commonmark:
-              filename = "\($0.key).md"
+              filename = "\(path(for: $0.key)).md"
             case .html where $0.key == "Home":
               filename = "index.html"
             case .html:
-              filename = "\($0.key)/index.html"
+              filename = "\(path(for: $0.key))/index.html"
             }
 
             let url = outputDirectoryURL.appendingPathComponent(filename)

Tests/SwiftDocTests/PathTests.swift

@@ -6,42 +6,42 @@ final class PathTests: XCTestCase {
     func testEmptyBaseURL() {
         XCTAssertEqual(path(for: "Class", with: ""), "Class")
 
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: ""), "(lhs:rhs:)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: ""), "(lhs_rhs_)")
     }
 
     func testRootDirectoryBaseURL() {
         XCTAssertEqual(path(for: "Class", with: "/"), "/Class")
 
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/"), "/(lhs:rhs:)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/"), "/(lhs_rhs_)")
     }
 
     func testCurrentDirectoryBaseURL() {
         XCTAssertEqual(path(for: "Class", with: "./"), "./Class")
 
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "./"), "./(lhs:rhs:)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "./"), "./(lhs_rhs_)")
     }
 
     func testNestedSubdirectoryBaseURL() {
         XCTAssertEqual(path(for: "Class", with: "/path/to/directory"), "/path/to/directory/Class")
         XCTAssertEqual(path(for: "Class", with: "/path/to/directory/"), "/path/to/directory/Class")
 
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/path/to/directory"), "/path/to/directory/(lhs:rhs:)")
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/path/to/directory/"), "/path/to/directory/(lhs:rhs:)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/path/to/directory"), "/path/to/directory/(lhs_rhs_)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/path/to/directory/"), "/path/to/directory/(lhs_rhs_)")
     }
 
     func testDomainBaseURL() {
         XCTAssertEqual(path(for: "Class", with: "https://example.com"), "https://example.com/Class")
         XCTAssertEqual(path(for: "Class", with: "https://example.com/"), "https://example.com/Class")
 
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com"), "https://example.com/(lhs:rhs:)")
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/"), "https://example.com/(lhs:rhs:)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com"), "https://example.com/(lhs_rhs_)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/"), "https://example.com/(lhs_rhs_)")
     }
 
     func testDomainSubdirectoryBaseURL() {
         XCTAssertEqual(path(for: "Class", with: "https://example.com/docs"), "https://example.com/docs/Class")
         XCTAssertEqual(path(for: "Class", with: "https://example.com/docs/"), "https://example.com/docs/Class")
 
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/docs"), "https://example.com/docs/(lhs:rhs:)")
-        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/docs/"), "https://example.com/docs/(lhs:rhs:)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/docs"), "https://example.com/docs/(lhs_rhs_)")
+        XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/docs/"), "https://example.com/docs/(lhs_rhs_)")
     }
 }