implement snippet slice de-indentation, and better organize the SnippetParser code

Author: tayloraswift

Sources/MarkdownPluginSwift/MarkdownCodeLanguage.Swift.Highlighter.swift

@@ -0,0 +1,58 @@
+extension SnippetParser
+{
+    /// A snippet slice is an arbitrary collection of text ranges within a snippet’s source
+    /// file. Snippet slices are not contiguous, but they should never overlap.
+    ///
+    /// The individual ranges can span multiple lines, but de-indentation (via ``punch(hole:)``)
+    /// may further break multiline ranges into multiple single-line ranges.
+    struct Slice
+    {
+        let id:String
+        var ranges:[Range<Int>]
+
+        init(id:String, ranges:[Range<Int>])
+        {
+            self.id = id
+            self.ranges = ranges
+        }
+    }
+}
+extension SnippetParser.Slice
+{
+    mutating
+    func punch(hole:Range<Int>)
+    {
+        guard
+        let last:Int = self.ranges.indices.last
+        else
+        {
+            preconditionFailure("Punching a hole in an empty slice!")
+        }
+
+        let next:Range<Int>? =
+        {
+            if  $0.lowerBound < hole.lowerBound
+            {
+                let next:Range<Int>? = hole.upperBound < $0.upperBound
+                    ? hole.upperBound ..< $0.upperBound
+                    : nil
+
+                $0 = $0.lowerBound ..< hole.lowerBound
+                return next
+            }
+            else
+            {
+                precondition(hole.upperBound <= $0.upperBound,
+                    "Punching a hole that is not inside the slice!")
+
+                $0 = hole.upperBound ..< $0.upperBound
+                return nil
+            }
+        } (&self.ranges[last])
+
+        if  let next:Range<Int>
+        {
+            self.ranges.append(next)
+        }
+    }
+}

Sources/MarkdownPluginSwift/Snippets/SnippetParser.Slice.swift

@@ -0,0 +1,128 @@
+import SwiftSyntax
+
+extension SnippetParser
+{
+    /// A `SliceBounds` is the precursor to a ``Slice``. It describes the vertical dimensions of
+    /// a snippet slice, and the indentation of its first marker statement.
+    struct SliceBounds
+    {
+        let id:String
+        var indent:Int
+        var ranges:[Range<AbsolutePosition>]
+
+        init(id:String, indent:Int)
+        {
+            self.id = id
+            self.indent = indent
+            self.ranges = []
+        }
+    }
+}
+extension SnippetParser.SliceBounds
+{
+    func viewbox(in utf8:[UInt8]) -> SnippetParser.Slice
+    {
+        //  We need to do two passes over the source ranges, as indentation is computed across
+        //  the entire slice, and not just one subslice.
+        let ranges:[Range<Int>] = self.ranges.compactMap
+        {
+            let start:Int = $0.lowerBound.utf8Offset
+            if  start >= utf8.endIndex
+            {
+                //  This could happen if the file ends with a control comment and no
+                //  final newline.
+                return nil
+            }
+
+            let end:Int = min($0.upperBound.utf8Offset, utf8.endIndex)
+            if  end <= start
+            {
+                //  Also possible due to missing final newlines.
+                return nil
+            }
+            else
+            {
+                return start ..< end
+            }
+        }
+
+        //  Compute maximum removable indentation.
+        var indent:Int = self.indent
+        for range:Range<Int> in ranges
+        {
+            /// We initialize this to 0 and not nil because we assume the range starts at the
+            /// beginning of a line.
+            var spaces:Int? = 0
+            for byte:UInt8 in utf8[range]
+            {
+                switch (byte, spaces)
+                {
+                //  '\n'
+                case    (0x0A, _):
+                    spaces = 0
+
+                //  '\r'
+                case    (0x0D, _):
+                    continue
+
+                //  '\t', ' '
+                //  Tabs and spaces both count as one space. This will work correctly as long as
+                //  people are not mixing tabs and spaces, which no one should be doing anyway.
+                case    (0x09, let count?),
+                        (0x20, let count?):
+                    spaces = count + 1
+
+                case    (_,    let count?):
+                    indent = min(indent, count)
+                    spaces = nil
+
+                case    (_,    nil):
+                    continue
+                }
+            }
+        }
+
+
+        if  self.indent == 0
+        {
+            return .init(id: self.id, ranges: ranges)
+        }
+
+        var slice:SnippetParser.Slice = .init(id: self.id, ranges: [])
+            slice.ranges.reserveCapacity(ranges.count)
+
+        for range:Range<Int> in ranges
+        {
+            slice.ranges.append(range)
+
+            print(slice.ranges)
+
+            var start:Int? = range.lowerBound
+            for j:Int in range
+            {
+                switch (utf8[j], start)
+                {
+                //  '\n'
+                case    (0x0A, _):
+                    start = j + 1
+
+                //  '\r'
+                //  '\t', ' '
+                case    (0x0D, _),
+                        (0x09, _),
+                        (0x20, _):
+                    continue
+
+                case    (_, let i?):
+                    slice.punch(hole: (i ..< j).prefix(self.indent))
+                    start = nil
+
+                case    (_, nil):
+                    continue
+                }
+            }
+        }
+
+        return slice
+    }
+}

Sources/MarkdownPluginSwift/Snippets/SnippetParser.SliceBounds.swift

@@ -0,0 +1,62 @@
+import SwiftSyntax
+
+extension SnippetParser
+{
+    /// A `SliceFetus` is the precursor to a ``SliceBounds``.
+    struct SliceFetus
+    {
+        private
+        var slice:SliceBounds
+        private
+        var start:AbsolutePosition?
+
+        init(id:String, at position:AbsolutePosition, indent:Int = 0)
+        {
+            self.slice = .init(id: id, indent: indent)
+            self.start = position
+        }
+    }
+}
+extension SnippetParser.SliceFetus
+{
+    mutating
+    func show(at position:AbsolutePosition)
+    {
+        if  case nil = self.start
+        {
+            self.start = position
+        }
+        else
+        {
+            //  TODO: Emit a warning.
+        }
+    }
+
+    mutating
+    func hide(at position:AbsolutePosition)
+    {
+        guard
+        let start:AbsolutePosition = self.start
+        else
+        {
+            //  TODO: Emit a warning.
+            return
+        }
+        //  Two ways this check can fail:
+        //
+        //  1.  Something resembling a control comment appears in the snippet abstract.
+        //  2.  A snippet slice is hidden instantly after it is shown.
+        if  start < position
+        {
+            self.slice.ranges.append(start ..< position)
+            self.start = nil
+        }
+    }
+
+    consuming
+    func end(at position:AbsolutePosition) -> SnippetParser.SliceBounds
+    {
+        self.hide(at: position)
+        return self.slice
+    }
+}

Sources/MarkdownPluginSwift/Snippets/SnippetParser.SliceFetus.swift

@@ -0,0 +1,62 @@
+extension SnippetParser.SliceMarker
+{
+    enum Statement
+    {
+        case end
+        case hide
+        case show
+        case slice(String)
+    }
+}
+extension SnippetParser.SliceMarker.Statement
+{
+    private
+    init(_ text:Substring)
+    {
+        switch text
+        {
+        case "end":     self = .end
+        case "hide":    self = .hide
+        case "show":    self = .show
+        default:        self = .slice(String.init(text))
+        }
+    }
+
+    init?(lineComment text:borrowing String, skip:Int)
+    {
+        guard
+        let i:String.Index = text.index(text.startIndex,
+            offsetBy: skip,
+            limitedBy: text.endIndex)
+        else
+        {
+            fatalError("Encountered a line comment with no leading slashes!")
+        }
+
+        let text:Substring = (copy text)[i...].drop(while: \.isWhitespace)
+
+        guard
+        let j:String.Index = text.firstIndex(of: "."),
+        case "snippet" = text[..<j]
+        else
+        {
+            return nil
+        }
+
+        let k:String.Index = text.index(after: j)
+        if  let space:String.Index = text[k...].firstIndex(where: \.isWhitespace)
+        {
+            guard text[text.index(after: space)...].allSatisfy(\.isWhitespace)
+            else
+            {
+                return nil
+            }
+
+            self.init(text[k ..< space])
+        }
+        else
+        {
+            self.init(text[k...])
+        }
+    }
+}

Sources/MarkdownPluginSwift/Snippets/SnippetParser.SliceMarker.Statement.swift

@@ -0,0 +1,16 @@
+import SwiftSyntax
+
+extension SnippetParser
+{
+    struct SliceMarker
+    {
+        let statement:Statement
+        /// The number of leading spaces before the control comment.
+        let indent:Int
+        /// The UTF-8 offset of the (first) newline before the control comment, or the beginning
+        /// of the file if the control comment is at the beginning of the file.
+        let before:AbsolutePosition
+        /// The UTF-8 offset of the newline after the control comment, assuming it exists.
+        let after:AbsolutePosition
+    }
+}