Small improvements to the new payload changes to steer users in the right direction

Author: migueldeicaza

Sources/SwiftTerm/CharData.swift

@@ -200,7 +200,10 @@ public struct TinyAtom {
         self.code = code
     }
 
-    /// Returns the TinyAtom associated with the specified url, or nil if we ran out of space
+    /// Creates a caller-owned TinyAtom for the specified value, or returns nil if no codes remain.
+    ///
+    /// The caller must call ``release()`` when the atom is no longer in use. Use
+    /// ``Terminal/makePayload(value:)`` for an atom whose lifetime is managed by a terminal.
     public static func lookup (value: Any) -> TinyAtom? {
         lock.lock()
         defer { lock.unlock() }
@@ -219,6 +222,13 @@ public struct TinyAtom {
         release(codes: [code])
     }
 
+    /// Releases a caller-owned atom.
+    ///
+    /// After this call, ``target`` returns nil for this atom and for all copies of it.
+    public func release() {
+        TinyAtom.release(code: code)
+    }
+
     static func release<S: Sequence>(codes: S) where S.Element == UInt16 {
         lock.lock()
         defer { lock.unlock() }

Sources/SwiftTerm/Documentation.docc/Extensions/Terminal.md

@@ -127,6 +127,7 @@ queue and the terminal will synchronize internally.
 - ``makeCharData(attribute:scalar:size:)``
 - ``updateCharData(_:char:size:)``
 - ``updateCharData(_:code:size:)``
+- ``makePayload(value:)``
 
 ### Housekeeping
 

Sources/SwiftTerm/Terminal.swift

@@ -1800,15 +1800,27 @@ open class Terminal {
     var hyperLinkTracking: (start: Position, payload: String)? = nil
     private var payloadCodes = Set<UInt16>()
 
+    /// Creates a payload atom whose lifetime is managed by this terminal.
+    ///
+    /// ``garbageCollectPayload()`` releases the atom after it is no longer present in
+    /// either terminal buffer. The terminal also releases its remaining atoms when it
+    /// is deinitialized.
+    public func makePayload(value: Any) -> TinyAtom? {
+        guard let atom = TinyAtom.lookup(value: value) else {
+            return nil
+        }
+        payloadCodes.insert(atom.code)
+        return atom
+    }
+
     func oscHyperlink (_ data: ArraySlice<UInt8>)
     {
         let buffer = self.buffer
         if data.count == 1 && data [data.startIndex] == UInt8 (ascii: ";") {
             // We only had the terminator, so we can close ";"
             if let hlt = hyperLinkTracking {
                 let str = hlt.payload
-                if let urlToken = TinyAtom.lookup (value: str) {
-                    payloadCodes.insert(urlToken.code)
+                if let urlToken = makePayload(value: str) {
                     //print ("Setting the text from \(hlt.start) to \(buffer.x) on line \(buffer.y+buffer.yBase) to \(str)")
 
                     // Between the time the flag was set, and now `y` might have changed negatively,

Tests/SwiftTermTests/LinkLookupTests.swift

@@ -32,7 +32,7 @@ final class LinkLookupTests: TerminalDelegate {
         terminal.feed(text: "abc")
 
         let payload = "id;https://example.com"
-        let atom = TinyAtom.lookup(value: payload)!
+        let atom = terminal.makePayload(value: payload)!
         let line = terminal.displayBuffer.lines[0]
         var cd = line[1]
         cd.setPayload(atom: atom)
@@ -69,7 +69,7 @@ final class LinkLookupTests: TerminalDelegate {
                         return false
                     }
                     let matched = atom.target as? Int == value
-                    TinyAtom.release(code: atom.code)
+                    atom.release()
                     return matched
                 }
             }
@@ -84,6 +84,30 @@ final class LinkLookupTests: TerminalDelegate {
         #expect(allValuesMatched)
     }
 
+    @Test func testTerminalOwnedPayloadIsGarbageCollected() throws {
+        let terminal = Terminal(delegate: self, options: TerminalOptions(cols: 10, rows: 1))
+        terminal.feed(text: "abc")
+
+        let atom = try #require(terminal.makePayload(value: "https://example.com"))
+        let line = try #require(terminal.getLine(row: 0))
+        var cell = line[0]
+        cell.setPayload(atom: atom)
+        line[0] = cell
+
+        terminal.feed(text: "\u{1b}[2J")
+        terminal.garbageCollectPayload()
+
+        #expect(atom.target == nil)
+    }
+
+    @Test func testCallerOwnedPayloadCanBeReleased() throws {
+        let atom = try #require(TinyAtom.lookup(value: "https://example.com"))
+
+        atom.release()
+
+        #expect(atom.target == nil)
+    }
+
     @Test func testImplicitUrlLookup() {
         let terminal = Terminal(delegate: self, options: TerminalOptions(cols: 40, rows: 1))
         terminal.feed(text: "https://example.com tail")