Use extension methods.

Author: dabrahams

.cursorrules

@@ -44,12 +44,19 @@ When invoking `swiftc`, pass `-module-cache-path` with a temporary directory to
 
 Avoid putting type information in non-type names. Variable names should reflect the role of the value, if at all possible. If you can't find a better name for a variable than one that reflects its type, use a single letter name.
 
+Extension property and method names must be clear about what they return. Use gerunds (verbs ending in -ing) for transformations (e.g., `normalizingLineEndings()` not `normalizedLineEndings`).
+
+Avoid computed properties that aren't O(1). Any operation that scans or transforms the entire collection should be a method, not a property.
+
+Only use intermediate variables where they reduce nesting or significantly reduce code size. Variables used only once should be avoided.
+
 ## Documentation Guidelines
 
 - Every declaration outside a function body needs a doc comment except for tests and declarations that satisfy protocol requirements.
 - Capture the complete contract in concise summaries following better-code contracts principles
 - Avoid verbose parameter blocks when good naming and a clear summary suffice
 - Name parameters in summary (e.g., "`nodes`'s text") to show their roles precisely
+- Use `self` rather than "this T" where T is the type of `self` (e.g., "`self` decoded as UTF-8" not "This data decoded as UTF-8")
 - Raise the level of abstraction - focus on semantic meaning rather than implementation details
 - Doc comments describe the contract (what, not how). Implementation details and rationale belong in regular comments inside the function body.
 - When multiple sentences are needed, separate them with a blank line

Sources/gyb-swift/AST.swift

@@ -50,13 +50,16 @@ struct SubstitutionNode: ASTNode {
 /// Note: Nesting is handled by Swift's compiler, not by the parser.
 typealias AST = [ASTNode]
 
-// MARK: - Helper Functions
-
-/// Extracts code content from a gybBlockOpen token (%{...}%).
-/// Removes the %{ prefix, }% suffix, and optional trailing newline.
-private func extractCodeFromBlockToken(_ token: Substring) -> Substring {
-  let suffixLength = token.last?.isNewline == true ? 3 : 2  // }%\n or }%
-  return token.dropFirst(2).dropLast(suffixLength)
+// MARK: - Helper Extensions
+
+extension StringProtocol {
+  /// The code content from a gyb block (%{...}%).
+  ///
+  /// Removes the %{ prefix, }% suffix, and optional trailing newline.
+  var codeBlockContent: SubSequence {
+    let suffixLength = last?.isNewline == true ? 3 : 2  // }%\n or }%
+    return dropFirst(2).dropLast(suffixLength)
+  }
 }
 
 // MARK: - Parse Context
@@ -93,7 +96,7 @@ struct ParseContext {
       case .gybBlock:
         // Extract code between %{ and }%
         return CodeNode(
-          code: extractCodeFromBlockToken(token.text),
+          code: token.text.codeBlockContent,
           sourcePosition: token.text.startIndex)
 
       case .symbol:

Sources/gyb-swift/ExecutionContext.swift

@@ -38,8 +38,8 @@ struct CodeGenerator {
   /// Whether to emit line directives in the template output.
   let emitLineDirectives: Bool
 
-  /// Precomputed line start positions for efficient line number calculation.
-  private let lineStarts: [String.Index]
+  /// Precomputed line boundaries for efficient line number calculation.
+  private let lineBounds: [String.Index]
 
   init(
     templateText: String,
@@ -51,7 +51,7 @@ struct CodeGenerator {
     self.filename = filename
     self.lineDirective = lineDirective
     self.emitLineDirectives = emitLineDirectives
-    self.lineStarts = getLineStarts(templateText)
+    self.lineBounds = templateText.lineBounds()
   }
 
   /// Returns Swift code executing `nodes`, batching consecutive nodes of the same type.
@@ -64,9 +64,8 @@ struct CodeGenerator {
     let lines = chunks.map { chunk -> String in
       // Code nodes: emit with source location directive at the start
       if let firstCode = chunk.first as? CodeNode {
-        let lineNumber =
-          getLineNumber(
-            for: firstCode.sourcePosition, in: templateText, lineStarts: lineStarts)
+        let lineNumber = templateText.lineNumber(
+          at: firstCode.sourcePosition, lineBounds: lineBounds)
         let sourceLocationDirective = formatSourceLocation(
           #"#sourceLocation(file: "\(file)", line: \(line))"#,
           filename: filename,
@@ -147,7 +146,7 @@ struct CodeGenerator {
       throw GYBError.executionFailed(filename: filename, errorOutput: result.stderr)
     }
 
-    return normalizeLineEndings(result.stdout)
+    return result.stdout.normalizingLineEndings()
   }
 
   /// Executes `swiftCode` by compiling and running the executable.
@@ -203,7 +202,8 @@ struct CodeGenerator {
   /// Compiles Swift source file to executable.
   private func compileSwiftCode(source: URL, output: URL, moduleCache: URL) throws {
     let result = try resultsOfRunning(
-      ["swiftc",
+      [
+        "swiftc",
         source.platformString,
         "-o", output.platformString,
         "-module-cache-path", moduleCache.platformString,
@@ -222,7 +222,7 @@ struct CodeGenerator {
       throw GYBError.executionFailed(filename: filename, errorOutput: result.stderr)
     }
 
-    return normalizeLineEndings(result.stdout)
+    return result.stdout.normalizingLineEndings()
   }
 
   /// Returns the start position of `nodes`'s first element.
@@ -259,7 +259,7 @@ struct CodeGenerator {
 
     // Always emit #sourceLocation in the intermediate Swift code for error reporting
     let index = sourceLocationIndex(for: nodes)
-    let lineNumber = getLineNumber(for: index, in: templateText, lineStarts: lineStarts)
+    let lineNumber = templateText.lineNumber(at: index, lineBounds: lineBounds)
     let sourceLocationDirective = formatSourceLocation(
       #"#sourceLocation(file: "\(file)", line: \(line))"#,
       filename: filename,
@@ -275,7 +275,7 @@ struct CodeGenerator {
       output = outputDirective + "\n" + output
     }
 
-    let escaped = escapeForSwiftMultilineString(output)
+    let escaped = output.escapedForSwiftMultilineString()
     swiftCode.append(
       #"print(""""#
         + "\n\(escaped)\n"
@@ -290,14 +290,21 @@ struct CodeGenerator {
   }
 }
 
-/// Returns `text` escaped for Swift multiline string literals, preserving `\(...)` interpolations.
-private func escapeForSwiftMultilineString(_ text: String) -> String {
-  return
-    text
-    .replacingOccurrences(of: #"\"#, with: #"\\"#)
-    .replacingOccurrences(of: #"""""#, with: #"\"\"\""#)
-    // Undo escaping for interpolations so \(expr) is undisturbed.
-    .replacingOccurrences(of: #"\\("#, with: #"\("#)
+extension String {
+  /// Returns `self` escaped for Swift multiline string literals, preserving `\(...)` interpolations.
+  func escapedForSwiftMultilineString() -> String {
+    replacingOccurrences(of: #"\"#, with: #"\\"#)
+      .replacingOccurrences(of: #"""""#, with: #"\"\"\""#)
+      // Undo escaping for interpolations so \(expr) is undisturbed.
+      .replacingOccurrences(of: #"\\("#, with: #"\("#)
+  }
+
+  /// Returns `self` with line endings normalized to Unix style (`\n`) for cross-platform consistency.
+  ///
+  /// On Windows, Swift's print() outputs `\r\n` line endings, but our tests expect `\n`.
+  func normalizingLineEndings() -> String {
+    replacingOccurrences(of: "\r\n", with: "\n")
+  }
 }
 
 /// Returns `template`'s `\(file)` and `\(line)` placeholders replaced by `filename` and `line`.
@@ -307,10 +314,3 @@ private func formatSourceLocation(_ template: String, filename: String, line: In
     .replacingOccurrences(of: #"\(file)"#, with: filename)
     .replacingOccurrences(of: #"\(line)"#, with: "\(line)")
 }
-
-/// Normalizes line endings to Unix style (`\n`) for cross-platform consistency.
-///
-/// On Windows, Swift's print() outputs `\r\n` line endings, but our tests expect `\n`.
-private func normalizeLineEndings(_ text: String) -> String {
-  return text.replacingOccurrences(of: "\r\n", with: "\n")
-}

Sources/gyb-swift/ProcessUtilities.swift

@@ -178,8 +178,8 @@ func resultsOfRunning(_ commandLine: [String], setSDKRoot: Bool = true) throws -
   p.waitUntilExit()
 
   // Retrieve the data (blocks until background reads complete)
-  let stdout = try decodeUTF8(stdoutData(), as: "\(command) stdout")
-  let stderr = try decodeUTF8(stderrData(), as: "\(command) stderr")
+  let stdout = try stdoutData().asUTF8(source: "\(command) stdout")
+  let stderr = try stderrData().asUTF8(source: "\(command) stderr")
 
   return ProcessResults(
     stdout: stdout,
@@ -218,10 +218,12 @@ private func readPipeInBackground(_ pipe: Pipe) -> () -> Data {
   }
 }
 
-/// Decodes `data` as UTF-8, throwing `Failure` with `source` name if it fails.
-private func decodeUTF8(_ data: Data, as source: String) throws -> String {
-  guard let result = String(data: data, encoding: .utf8) else {
-    throw Failure("\(source) not UTF-8 encoded")
+extension Data {
+  /// `self` decoded as UTF-8.
+  func asUTF8(source: String) throws -> String {
+    guard let result = String(data: self, encoding: .utf8) else {
+      throw Failure("\(source) not UTF-8 encoded")
+    }
+    return result
   }
-  return result
 }

Sources/gyb-swift/StringUtilities.swift

@@ -3,15 +3,17 @@ import Foundation
 
 // MARK: - String Utilities
 
-/// Returns the start of each line in `text` followed by `text.endIndex`.
-func getLineStarts(_ text: String) -> [String.Index] {
-  text.split(omittingEmptySubsequences: false) { $0.isNewline }
-    .map(\.startIndex) + [text.endIndex]
-}
+extension String {
+  /// Returns the start of each line followed by `endIndex`.
+  func lineBounds() -> [String.Index] {
+    split(omittingEmptySubsequences: false) { $0.isNewline }
+      .map(\.startIndex) + [endIndex]
+  }
 
-/// Returns the 1-based line number for a given index in the text.
-func getLineNumber(for index: String.Index, in text: String, lineStarts: [String.Index]) -> Int {
-  // Use binary search to find the first line start that is after the given index
-  // lineStarts is sorted, so partitioningIndex performs O(log N) binary search
-  return lineStarts.partitioningIndex { $0 > index }
+  /// Returns the 1-based line number for `index`.
+  func lineNumber(at index: String.Index, lineBounds: [String.Index]) -> Int {
+    // Use binary search to find the first line boundary that is after the given index
+    // lineBounds is sorted, so partitioningIndex performs O(log N) binary search
+    return lineBounds.partitioningIndex { $0 > index }
+  }
 }

Sources/gyb-swift/Tokenization.swift

@@ -116,7 +116,7 @@ struct TemplateTokens: Sequence, IteratorProtocol {
     let codePart = remainingText.dropFirst(2)
 
     // Use Swift tokenizer to find the real closing }
-    let closeIndex = tokenizeSwiftToUnmatchedCloseCurly(codePart)
+    let closeIndex = codePart.indexOfFirstSwiftUnmatchedCloseCurly()
 
     if closeIndex < codePart.endIndex {
       // Include ${ + code + }
@@ -138,7 +138,7 @@ struct TemplateTokens: Sequence, IteratorProtocol {
     let codePart = remainingText.dropFirst(2)
 
     // Use Swift tokenizer to find the real closing }
-    let closeIndex = tokenizeSwiftToUnmatchedCloseCurly(codePart)
+    let closeIndex = codePart.indexOfFirstSwiftUnmatchedCloseCurly()
 
     if closeIndex < codePart.endIndex {
       let afterClose = codePart.index(after: closeIndex)
@@ -190,30 +190,32 @@ struct TemplateTokens: Sequence, IteratorProtocol {
 
 // MARK: - Swift Tokenization
 
-/// Returns the index of the first unmatched `}` in Swift code,
-/// or `code.endIndex` if none exists.
-func tokenizeSwiftToUnmatchedCloseCurly(_ code: Substring) -> String.Index {
-  // Parse to get tokens, which automatically handles braces within strings and comments.
-  let parsed = Parser.parse(source: String(code))
-
-  var nesting = 0
-  for token in parsed.tokens(viewMode: .sourceAccurate) {
-    if token.tokenKind == .leftBrace {
-      nesting += 1
-    } else if token.tokenKind == .rightBrace {
-      nesting -= 1
-      if nesting < 0 {
-        return convertUTF8OffsetToIndex(
-          token.positionAfterSkippingLeadingTrivia.utf8Offset, in: code)
+extension StringProtocol {
+  /// The index of the first unmatched `}` when parsed as Swift code, or `endIndex` if none exists.
+  ///
+  /// Uses SwiftSyntax to properly handle braces within strings and comments.
+  func indexOfFirstSwiftUnmatchedCloseCurly() -> String.Index {
+    // Parse to get tokens, which automatically handles braces within strings and comments.
+    let parsed = Parser.parse(source: String(self))
+
+    var nesting = 0
+    for token in parsed.tokens(viewMode: .sourceAccurate) {
+      if token.tokenKind == .leftBrace {
+        nesting += 1
+      } else if token.tokenKind == .rightBrace {
+        nesting -= 1
+        if nesting < 0 {
+          return indexFromUTF8Offset(token.positionAfterSkippingLeadingTrivia.utf8Offset)
+        }
       }
     }
-  }
 
-  return code.endIndex
-}
+    return endIndex
+  }
 
-/// Converts a UTF-8 byte offset to a `String.Index` within the given substring.
-private func convertUTF8OffsetToIndex(_ utf8Offset: Int, in code: Substring) -> String.Index {
-  let utf8Index = code.utf8.index(code.utf8.startIndex, offsetBy: utf8Offset)
-  return String.Index(utf8Index, within: code) ?? code.endIndex
+  /// Converts a UTF-8 byte offset to a `String.Index`.
+  func indexFromUTF8Offset(_ utf8Offset: Int) -> String.Index {
+    let utf8Index = utf8.index(utf8.startIndex, offsetBy: utf8Offset)
+    return String.Index(utf8Index, within: self) ?? endIndex
+  }
 }

Tests/gyb-swiftTests/ExecutionTests.swift

@@ -4,49 +4,33 @@ import Testing
 
 @Test("execute simple literal template")
 func execute_literalTemplate() throws {
-  let text = "Hello, World!"
-  let result = try execute(text)
-
-  #expect(result == "Hello, World!")
+  #expect(try execute("Hello, World!") == "Hello, World!")
 }
 
 @Test("execute template with escaped symbols")
 func execute_templateWithEscapedSymbols() throws {
-  let text = "Price: $$50"
-  let result = try execute(text)
-
-  #expect(result == "Price: $50")
+  #expect(try execute("Price: $$50") == "Price: $50")
 }
 
 @Test("substitution with bound variable")
 func substitution_withSimpleBinding() throws {
-  let text = "x = ${x}"
-  let result = try execute(text, bindings: ["x": "42"])
-  #expect(result == "x = 42")
+  #expect(try execute("x = ${x}", bindings: ["x": "42"]) == "x = 42")
 }
 
 @Test("empty template")
 func execute_emptyTemplate() throws {
-  let text = ""
-  let result = try execute(text)
-
-  #expect(result == "")
+  #expect(try execute("") == "")
 }
 
 @Test("template with only whitespace")
 func execute_whitespaceOnly() throws {
   let text = "   \n\t\n   "
-  let result = try execute(text)
-
-  #expect(result == text)
+  #expect(try execute(text) == text)
 }
 
 @Test("mixed literal and symbols")
 func execute_mixedLiteralsAndSymbols() throws {
-  let text = "Regular $$text with %%symbols"
-  let result = try execute(text)
-
-  #expect(result == "Regular $text with %symbols")
+  #expect(try execute("Regular $$text with %%symbols") == "Regular $text with %symbols")
 }
 
 @Test("malformed substitutions handled gracefully")
@@ -64,9 +48,7 @@ func parse_malformedSubstitution() {
 @Test("multiple literals in sequence")
 func execute_multipleLiterals() throws {
   let text = "First line\nSecond line\nThird line"
-  let result = try execute(text)
-
-  #expect(result == text)
+  #expect(try execute(text) == text)
 }
 
 @Test("line directive generation")