PR feedback

Author: Jesse Haigh

Sources/SwiftDocC/Checker/Checkers/InvalidCodeBlockOption.swift

@@ -19,7 +19,7 @@ public struct InvalidCodeBlockOption: Checker {
     public var problems = [Problem]()
 
     /// Parsing options for code blocks
-    private let knownOptions = RenderBlockContent.CodeListing.knownOptions
+    private let knownOptions = RenderBlockContent.CodeBlockOptions.knownOptions
 
     private var sourceFile: URL?
 
@@ -31,9 +31,9 @@ public struct InvalidCodeBlockOption: Checker {
     }
 
     public mutating func visitCodeBlock(_ codeBlock: CodeBlock) {
-        let (lang, tokens) = tokenizeLanguageString(codeBlock.language)
+        let (lang, tokens) = RenderBlockContent.CodeBlockOptions.tokenizeLanguageString(codeBlock.language)
 
-        func matches(token: RenderBlockContent.CodeListing.OptionName, value: String?) {
+        func matches(token: RenderBlockContent.CodeBlockOptions.OptionName, value: String?) {
             guard token == .unknown, let value = value else { return }
 
             let matches = NearMiss.bestMatches(for: knownOptions, against: value)
@@ -58,12 +58,12 @@ public struct InvalidCodeBlockOption: Checker {
             }
         }
 
-        func validateArrayIndices(token: RenderBlockContent.CodeListing.OptionName, value: String?) {
+        func validateArrayIndices(token: RenderBlockContent.CodeBlockOptions.OptionName, value: String?) {
             guard token == .highlight || token == .strikeout, let value = value else { return }
             // code property ends in a newline. this gives us a bogus extra line.
             let lineCount: Int = codeBlock.code.split(omittingEmptySubsequences: false, whereSeparator: { $0.isNewline }).count - 1
 
-            guard let indices = parseCodeBlockOptionArray(value) else {
+            guard let indices = RenderBlockContent.CodeBlockOptions.parseCodeBlockOptionsArray(value) else {
                 let diagnostic = Diagnostic(source: sourceFile, severity: .warning, range: codeBlock.range, identifier: "org.swift.docc.InvalidCodeBlockOption", summary: "Could not parse \(token.rawValue.singleQuoted) indices from \(value.singleQuoted). Expected an integer (e.g. 3) or an array (e.g. [1, 3, 5])")
                 problems.append(Problem(diagnostic: diagnostic, possibleSolutions: []))
                 return

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -124,21 +124,36 @@ public enum RenderBlockContent: Equatable {
         public var code: [String]
         /// Additional metadata for this code block.
         public var metadata: RenderContentMetadata?
+        /// Annotations for code blocks
+        public var options: CodeBlockOptions?
+
+        /// Make a new `CodeListing` with the given data.
+        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, options: CodeBlockOptions?) {
+            self.syntax = syntax
+            self.code = code
+            self.metadata = metadata
+            self.options = options
+        }
+    }
+
+    public struct CodeBlockOptions: Equatable {
+        public var language: String?
         public var copyToClipboard: Bool = true
-        public var wrap: Int = 100
+        public var wrap: Int = 0
         public var highlight: [Int] = [Int]()
         public var showLineNumbers: Bool = false
         public var strikeout: [Int] = [Int]()
 
         public enum OptionName: String, CaseIterable {
+            case _nonFrozenEnum_useDefaultCase
             case nocopy
             case wrap
             case highlight
             case showLineNumbers
             case strikeout
             case unknown
 
-            init?<S: StringProtocol>(caseInsensitive raw: S) {
+            init?(caseInsensitive raw: some StringProtocol) {
                 self.init(rawValue: raw.lowercased())
             }
         }
@@ -147,17 +162,141 @@ public enum RenderBlockContent: Equatable {
             Set(OptionName.allCases.map(\.rawValue))
         }
 
-        /// Make a new `CodeListing` with the given data.
-        public init(syntax: String?, code: [String], metadata: RenderContentMetadata?, copyToClipboard: Bool, wrap: Int, highlight: [Int], strikeout: [Int], showLineNumbers: Bool) {
-            self.syntax = syntax
-            self.code = code
-            self.metadata = metadata
+        // empty initializer with default values
+        public init() {
+            self.language = ""
+            self.copyToClipboard = true
+            self.wrap = 0
+            self.highlight = [Int]()
+            self.showLineNumbers = false
+            self.strikeout = [Int]()
+        }
+
+        public init(parsingLanguageString language: String?) {
+            let (lang, tokens) = Self.tokenizeLanguageString(language)
+
+            self.language = lang
+            self.copyToClipboard = !tokens.contains { $0.name == .nocopy }
+            self.showLineNumbers = tokens.contains { $0.name == .showLineNumbers }
+
+            if let wrapString = tokens.first(where: { $0.name == .wrap })?.value,
+               let wrapValue = Int(wrapString) {
+                self.wrap = wrapValue
+            } else {
+                self.wrap = 0
+            }
+
+            if let highlightString = tokens.first(where: { $0.name == .highlight })?.value,
+               let highlightValue = Self.parseCodeBlockOptionsArray(highlightString) {
+                self.highlight = highlightValue
+            } else {
+                self.highlight = []
+            }
+
+            if let strikeoutString = tokens.first(where: { $0.name == .strikeout })?.value,
+               let strikeoutValue = Self.parseCodeBlockOptionsArray(strikeoutString) {
+                self.strikeout = strikeoutValue
+            } else {
+                self.strikeout = []
+            }
+        }
+
+        public init(copyToClipboard: Bool, wrap: Int, highlight: [Int], strikeout: [Int], showLineNumbers: Bool) {
             self.copyToClipboard = copyToClipboard
             self.wrap = wrap
             self.highlight = highlight
             self.showLineNumbers = showLineNumbers
             self.strikeout = strikeout
         }
+
+        /// A function that parses array values on code block options from the language line string
+        static internal func parseCodeBlockOptionsArray(_ value: String?) -> [Int]? {
+            guard var s = value?.trimmingCharacters(in: .whitespaces), !s.isEmpty else { return [] }
+
+            if s.hasPrefix("[") && s.hasSuffix("]") {
+                s.removeFirst()
+                s.removeLast()
+            }
+
+            return s.split(separator: ",").compactMap { Int($0.trimmingCharacters(in: .whitespaces)) }
+        }
+
+        /// A function that parses the language line options on code blocks, returning the language and tokens, an array of OptionName and option values
+        static internal func tokenizeLanguageString(_ input: String?) -> (lang: String?, tokens: [(name: OptionName, value: String?)]) {
+            guard let input else { return (lang: nil, tokens: []) }
+
+            let parts = parseLanguageString(input)
+            var tokens: [(OptionName, String?)] = []
+            var lang: String? = nil
+
+            for (index, part) in parts.enumerated() {
+                if let eq = part.firstIndex(of: "=") {
+                    let key = part[..<eq].trimmingCharacters(in: .whitespaces).lowercased()
+                    let value = part[part.index(after: eq)...].trimmingCharacters(in: .whitespaces)
+                    if key == "wrap" {
+                        tokens.append((.wrap, value))
+                    } else if key == "highlight" {
+                        tokens.append((.highlight, value))
+                    } else if key == "strikeout" {
+                        tokens.append((.strikeout, value))
+                    } else {
+                        tokens.append((.unknown, key))
+                    }
+                } else {
+                    let key = part.trimmingCharacters(in: .whitespaces).lowercased()
+                    if key == "nocopy" {
+                        tokens.append((.nocopy, nil as String?))
+                    } else if key == "showlinenumbers" {
+                        tokens.append((.showLineNumbers, nil as String?))
+                    } else if key == "wrap" {
+                        tokens.append((.wrap, nil as String?))
+                    } else if key == "highlight" {
+                        tokens.append((.highlight, nil as String?))
+                    } else if key == "strikeout" {
+                        tokens.append((.strikeout, nil as String?))
+                    } else if index == 0 && !key.contains("[") && !key.contains("]") {
+                        lang = key
+                    } else {
+                        tokens.append((.unknown, key))
+                    }
+                }
+            }
+            return (lang, tokens)
+        }
+
+        // helper function for tokenizeLanguageString to parse the language line
+        static func parseLanguageString(_ input: String?) -> [Substring] {
+
+            guard let input else { return [] }
+            var parts: [Substring] = []
+            var start = input.startIndex
+            var i = input.startIndex
+
+            var bracketDepth = 0
+
+            while i < input.endIndex {
+                let c = input[i]
+
+                if c == "[" { bracketDepth += 1 }
+                else if c == "]" { bracketDepth = max(0, bracketDepth - 1) }
+                else if c == "," && bracketDepth == 0 {
+                    let seq = input[start..<i]
+                    if !seq.isEmpty {
+                        parts.append(seq)
+                    }
+                    input.formIndex(after: &i)
+                    start = i
+                    continue
+                }
+                input.formIndex(after: &i)
+            }
+            let tail = input[start..<input.endIndex]
+            if !tail.isEmpty {
+                parts.append(tail)
+            }
+
+            return parts
+        }
     }
 
     /// A heading with the given level.
@@ -747,15 +886,23 @@ extension RenderBlockContent: Codable {
             self = try .aside(.init(style: style, content: container.decode([RenderBlockContent].self, forKey: .content)))
         case .codeListing:
             let copy = FeatureFlags.current.isExperimentalCodeBlockEnabled
+            let options: CodeBlockOptions?
+            if !Set(container.allKeys).isDisjoint(with: [.copyToClipboard, .wrap, .highlight, .strikeout, .showLineNumbers]) {
+                options = try CodeBlockOptions(
+                    copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy,
+                    wrap: container.decodeIfPresent(Int.self, forKey: .wrap) ?? 0,
+                    highlight: container.decodeIfPresent([Int].self, forKey: .highlight) ?? [],
+                    strikeout: container.decodeIfPresent([Int].self, forKey: .strikeout) ?? [],
+                    showLineNumbers: container.decodeIfPresent(Bool.self, forKey: .showLineNumbers) ?? false
+                )
+            } else {
+                options = nil
+            }
             self = try .codeListing(.init(
                 syntax: container.decodeIfPresent(String.self, forKey: .syntax),
                 code: container.decode([String].self, forKey: .code),
                 metadata: container.decodeIfPresent(RenderContentMetadata.self, forKey: .metadata),
-                copyToClipboard: container.decodeIfPresent(Bool.self, forKey: .copyToClipboard) ?? copy,
-                wrap: container.decodeIfPresent(Int.self, forKey: .wrap) ?? 0,
-                highlight: container.decodeIfPresent([Int].self, forKey: .highlight) ?? [Int](),
-                strikeout: container.decodeIfPresent([Int].self, forKey: .strikeout) ?? [Int](),
-                showLineNumbers: container.decodeIfPresent(Bool.self, forKey: .showLineNumbers) ?? false
+                options: options
             ))
         case .heading:
             self = try .heading(.init(level: container.decode(Int.self, forKey: .level), text: container.decode(String.self, forKey: .text), anchor: container.decodeIfPresent(String.self, forKey: .anchor)))
@@ -859,11 +1006,11 @@ extension RenderBlockContent: Codable {
             try container.encode(l.syntax, forKey: .syntax)
             try container.encode(l.code, forKey: .code)
             try container.encodeIfPresent(l.metadata, forKey: .metadata)
-            try container.encode(l.copyToClipboard, forKey: .copyToClipboard)
-            try container.encode(l.wrap, forKey: .wrap)
-            try container.encode(l.highlight, forKey: .highlight)
-            try container.encode(l.strikeout, forKey: .strikeout)
-            try container.encode(l.showLineNumbers, forKey: .showLineNumbers)
+            try container.encodeIfPresent(l.options?.copyToClipboard, forKey: .copyToClipboard)
+            try container.encodeIfPresent(l.options?.wrap, forKey: .wrap)
+            try container.encodeIfPresent(l.options?.highlight, forKey: .highlight)
+            try container.encodeIfPresent(l.options?.strikeout, forKey: .strikeout)
+            try container.encodeIfPresent(l.options?.showLineNumbers, forKey: .showLineNumbers)
         case .heading(let h):
             try container.encode(h.level, forKey: .level)
             try container.encode(h.text, forKey: .text)

Sources/SwiftDocC/Model/Rendering/RenderContentCompiler.swift

@@ -49,45 +49,18 @@ struct RenderContentCompiler: MarkupVisitor {
         // Default to the bundle's code listing syntax if one is not explicitly declared in the code block.
 
         if FeatureFlags.current.isExperimentalCodeBlockEnabled {
-            let (lang, tokens) = tokenizeLanguageString(codeBlock.language)
-
-            var listing = RenderBlockContent.CodeListing(
-                syntax: lang ?? bundle.info.defaultCodeListingLanguage,
+            let codeBlockOptions = RenderBlockContent.CodeBlockOptions(parsingLanguageString: codeBlock.language)
+            let listing = RenderBlockContent.CodeListing(
+                syntax: codeBlockOptions.language ?? bundle.info.defaultCodeListingLanguage,
                 code: codeBlock.code.splitByNewlines,
                 metadata: nil,
-                copyToClipboard: true, // default value
-                wrap: 0, // default value
-                highlight: [Int](), // default value
-                strikeout: [Int](), // default value
-                showLineNumbers: false // default value
+                options: codeBlockOptions
             )
 
-            // apply code block options
-            for (option, value) in tokens {
-                switch option {
-                case .nocopy:
-                    listing.copyToClipboard = false
-                case .wrap:
-                    if let value, let intValue = Int(value) {
-                        listing.wrap = intValue
-                    } else {
-                        listing.wrap = 0
-                    }
-                case .highlight:
-                    listing.highlight = parseCodeBlockOptionArray(value) ?? []
-                case .strikeout:
-                    listing.strikeout = parseCodeBlockOptionArray(value) ?? []
-                case .showLineNumbers:
-                    listing.showLineNumbers = true
-                case .unknown:
-                    break
-                }
-            }
-
             return [RenderBlockContent.codeListing(listing)]
 
         } else {
-            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, copyToClipboard: false, wrap: 0, highlight: [Int](), strikeout: [Int](), showLineNumbers: false))]
+            return [RenderBlockContent.codeListing(.init(syntax: codeBlock.language ?? bundle.info.defaultCodeListingLanguage, code: codeBlock.code.splitByNewlines, metadata: nil, options: nil))]
         }
     }
 

Sources/SwiftDocC/Semantics/Snippets/Snippet.swift

@@ -83,13 +83,23 @@ extension Snippet: RenderableDirectiveConvertible {
                 let lines = snippetMixin.lines[lineRange]
                 let minimumIndentation = lines.map { $0.prefix { $0.isWhitespace }.count }.min() ?? 0
                 let trimmedLines = lines.map { String($0.dropFirst(minimumIndentation)) }
-                let copy = FeatureFlags.current.isExperimentalCodeBlockEnabled
-                return [RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: trimmedLines, metadata: nil, copyToClipboard: copy, wrap: 0, highlight: [Int](), strikeout: [Int](), showLineNumbers: false))]
+                let codeBlockOptions: RenderBlockContent.CodeBlockOptions?
+                if FeatureFlags.current.isExperimentalCodeBlockEnabled {
+                    codeBlockOptions = .init()
+                } else {
+                    codeBlockOptions = nil
+                }
+                return [RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: trimmedLines, metadata: nil, options: codeBlockOptions))]
             } else {
                 // Render the whole snippet with its explanation content.
                 let docCommentContent = snippetEntity.markup.children.flatMap { contentCompiler.visit($0) }
-                let copy = FeatureFlags.current.isExperimentalCodeBlockEnabled
-                let code = RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: snippetMixin.lines, metadata: nil, copyToClipboard: copy, wrap: 0, highlight: [Int](), strikeout: [Int](), showLineNumbers: false))
+                let codeBlockOptions: RenderBlockContent.CodeBlockOptions?
+                if FeatureFlags.current.isExperimentalCodeBlockEnabled {
+                    codeBlockOptions = .init()
+                } else {
+                    codeBlockOptions = nil
+                }
+                let code = RenderBlockContent.codeListing(.init(syntax: snippetMixin.language, code: snippetMixin.lines, metadata: nil, options: codeBlockOptions))
                 return docCommentContent + [code]
             }
     }