Merge pull request #375 from tayloraswift/ucf-signature-patterns

add a quick-and-dirty implementation of DocC signature pattern syntax

Author: tayloraswift

Sources/LinkResolution/UCF.ResolvableOverload.swift

@@ -19,7 +19,7 @@ extension UCF.ResolvableOverload
     {
         if  case nil = predicate.seal
         {
-            //  Macros are currently the only kind of declaration that *must* be spelled with 
+            //  Macros are currently the only kind of declaration that *must* be spelled with
             //  trailing parentheses.
             switch self.phylum
             {
@@ -40,7 +40,7 @@ extension UCF.ResolvableOverload
             case .var:                      break
             }
         }
-        else 
+        else
         {
             switch self.phylum
             {
@@ -62,7 +62,7 @@ extension UCF.ResolvableOverload
             }
         }
 
-        guard 
+        guard
         let suffix:UCF.Selector.Suffix = predicate.suffix
         else
         {
@@ -75,6 +75,8 @@ extension UCF.ResolvableOverload
         case .legacy(_, let hash?):         return hash == self.hash
         case .hash(let hash):               return hash == self.hash
         case .filter(let filter):           return filter ~= self.phylum
+        //  TODO: unimplemented
+        case .pattern:                      return true
         }
     }
 }

Sources/UCF/Codelinks/UCF.PatternFilter.Identifier.swift

@@ -0,0 +1,42 @@
+extension UCF.PatternFilter
+{
+    @frozen public
+    struct Identifier:Equatable, Hashable, Sendable
+    {
+        @usableFromInline
+        let suffix:String
+
+        @inlinable
+        init(suffix:String)
+        {
+            self.suffix = suffix
+        }
+    }
+}
+extension UCF.PatternFilter.Identifier:CustomStringConvertible
+{
+    @inlinable public
+    var description:String
+    {
+        self.suffix.isEmpty ? "_" : self.suffix
+    }
+}
+extension UCF.PatternFilter.Identifier
+{
+    @inlinable public
+    init?(_ pattern:some StringProtocol)
+    {
+        if  pattern.isEmpty
+        {
+            return nil
+        }
+        if  pattern == "_"
+        {
+            self.init(suffix: "")
+        }
+        else
+        {
+            self.init(suffix: String.init(pattern))
+        }
+    }
+}

Sources/UCF/Codelinks/UCF.PatternFilter.Output.swift

@@ -0,0 +1,60 @@
+extension UCF.PatternFilter
+{
+    @frozen public
+    enum Output:Equatable, Hashable, Sendable
+    {
+        case single(Identifier)
+        case tuple([Identifier])
+    }
+}
+extension UCF.PatternFilter.Output
+{
+    static func parse(_ string:Substring) -> Self?
+    {
+        guard
+        let i:String.Index = string.firstIndex(of: "("),
+        let k:String.Index = string.lastIndex(of: ")")
+        else
+        {
+            guard
+            let identifier:UCF.PatternFilter.Identifier = .init(string)
+            else
+            {
+                return nil
+            }
+
+            return .single(identifier)
+        }
+
+        guard i < k
+        else
+        {
+            return nil
+        }
+
+        let j:String.Index = string.index(after: i)
+
+        //  If we do not check for this, ``BidirectionalCollection.split`` will emit a single
+        //  empty substring due to `omitEmptySubsequences`.
+        if  j == k
+        {
+            return .tuple([])
+        }
+
+        var outputs:[UCF.PatternFilter.Identifier] = []
+        for output:Substring in string[j ..< k].split(separator: ",",
+            omittingEmptySubsequences: false)
+        {
+            guard
+            let output:UCF.PatternFilter.Identifier = .init(output)
+            else
+            {
+                return nil
+            }
+
+            outputs.append(output)
+        }
+
+        return outputs.count == 1 ? .single(outputs[0]) : .tuple(outputs)
+    }
+}

Sources/UCF/Codelinks/UCF.PatternFilter.swift

@@ -0,0 +1,177 @@
+extension UCF
+{
+    @frozen public
+    enum PatternFilter:Equatable, Hashable, Sendable
+    {
+        case fullSignature([Identifier], Output)
+        case inputs([Identifier])
+        case output(Output)
+    }
+}
+extension UCF.PatternFilter
+{
+    @inlinable public
+    var inputs:[Identifier]?
+    {
+        switch self
+        {
+        case .fullSignature(let inputs, _): inputs
+        case .inputs(let inputs):           inputs
+        case .output:                       nil
+        }
+    }
+
+    @inlinable public
+    var output:Output?
+    {
+        switch self
+        {
+        case .fullSignature(_, let output): output
+        case .inputs:                       nil
+        case .output(let output):           output
+        }
+    }
+}
+extension UCF.PatternFilter:CustomStringConvertible
+{
+    public
+    var description:String
+    {
+        var string:String = ""
+
+        if  let inputs:[UCF.PatternFilter.Identifier] = self.inputs
+        {
+            string.append("(")
+
+            var first:Bool = true
+            for input:UCF.PatternFilter.Identifier in inputs
+            {
+                if  first
+                {
+                    first = false
+                }
+                else
+                {
+                    string.append(",")
+                }
+
+                string.append("\(input)")
+            }
+
+            string.append(")")
+        }
+
+        guard
+        let output:UCF.PatternFilter.Output = self.output
+        else
+        {
+            return string
+        }
+
+        if !string.isEmpty
+        {
+            string.append("-")
+        }
+
+        string.append(">")
+
+        switch output
+        {
+        case .single(let output):
+            string.append("\(output)")
+
+        case .tuple(let outputs):
+            string.append("(")
+
+            var first:Bool = true
+            for output:UCF.PatternFilter.Identifier in outputs
+            {
+                if  first
+                {
+                    first = false
+                }
+                else
+                {
+                    string.append(",")
+                }
+
+                string.append("\(output)")
+            }
+
+            string.append(")")
+        }
+
+        return string
+    }
+}
+extension UCF.PatternFilter
+{
+    static func parse(_ string:Substring) -> Self?
+    {
+        guard
+        let first:Character = string.first
+        else
+        {
+            return nil
+        }
+
+        switch first
+        {
+        case "(":
+            let i:String.Index = string.index(after: string.startIndex)
+
+            guard
+            let j:String.Index = string[i...].firstIndex(of: ")")
+            else
+            {
+                return nil
+            }
+
+            var inputs:[UCF.PatternFilter.Identifier] = []
+            for input:Substring in string[i ..< j].split(separator: ",",
+                omittingEmptySubsequences: false)
+            {
+                guard
+                let input:UCF.PatternFilter.Identifier = .init(input)
+                else
+                {
+                    return nil
+                }
+
+                inputs.append(input)
+            }
+
+            let k:String.Index = string.index(after: j)
+
+            if  let l:String.Index = string.index(k, offsetBy: 2, limitedBy: string.endIndex),
+                string[k ..< l] == "->"
+            {
+                guard
+                let output:UCF.PatternFilter.Output = .parse(string[l...])
+                else
+                {
+                    return nil
+                }
+
+                return .fullSignature(inputs, output)
+            }
+
+            return .inputs(inputs)
+
+        case ">":
+            //  This pattern contains an output only.
+            let i:String.Index = string.index(after: string.startIndex)
+            guard
+            let output:UCF.PatternFilter.Output = .parse(string[i...])
+            else
+            {
+                return nil
+            }
+
+            return .output(output)
+
+        default:
+            return nil
+        }
+    }
+}