Introduce the snippet target type

Sources/Build/BuildPlan.swift

@@ -1214,7 +1214,7 @@ public final class ProductBuildDescription {
                 let relativePath = "@rpath/\(buildParameters.binaryRelativePath(for: product).pathString)"
                 args += ["-Xlinker", "-install_name", "-Xlinker", relativePath]
             }
-        case .executable:
+        case .executable, .snippet:
             // Link the Swift stdlib statically, if requested.
             if buildParameters.shouldLinkStaticSwiftStdlib {
                 if buildParameters.triple.isDarwin() {
@@ -1256,7 +1256,7 @@ public final class ProductBuildDescription {
         if containsSwiftTargets {
           switch product.type {
           case .library, .plugin: break
-          case .test, .executable:
+          case .test, .executable, .snippet:
               if buildParameters.triple.isDarwin() {
                   let stdlib = buildParameters.toolchain.macosSwiftStdlib
                   args += ["-Xlinker", "-rpath", "-Xlinker", stdlib.pathString]
@@ -1732,7 +1732,7 @@ public class BuildPlan {
                 switch product.type {
                 case .library(.automatic), .library(.static), .plugin:
                     return product.targets.map { .target($0, conditions: []) }
-                case .library(.dynamic), .test, .executable:
+                case .library(.dynamic), .test, .executable, .snippet:
                     return []
                 }
             }
@@ -1754,7 +1754,7 @@ public class BuildPlan {
                 // In tool version .v5_5 or greater, we also include executable modules implemented in Swift in
                 // any test products... this is to allow testing of executables.  Note that they are also still
                 // built as separate products that the test can invoke as subprocesses.
-                case .executable:
+                case .executable, .snippet:
                     if product.targets.contains(target) {
                         staticTargets.append(target)
                     } else if product.type == .test && target.underlyingTarget is SwiftTarget {

Sources/Build/ManifestBuilder.swift

@@ -554,7 +554,7 @@ extension LLBuildManifestBuilder {
 
             case .product(let product, _):
                 switch product.type {
-                case .executable, .library(.dynamic):
+                case .executable, .snippet, .library(.dynamic):
                     guard let planProduct = plan.productMap[product] else {
                         throw InternalError("unknown product \(product)")
                     }
@@ -673,7 +673,7 @@ extension LLBuildManifestBuilder {
 
             case .product(let product, _):
                 switch product.type {
-                case .executable, .library(.dynamic):
+                case .executable, .snippet, .library(.dynamic):
                     guard let planProduct = plan.productMap[product] else {
                         throw InternalError("unknown product \(product)")
                     }
@@ -852,7 +852,7 @@ extension ResolvedProduct {
             return "\(name)-\(config).a"
         case .library(.automatic):
             throw InternalError("automatic library not supported")
-        case .executable:
+        case .executable, .snippet:
             return "\(name)-\(config).exe"
         case .plugin:
             throw InternalError("unexpectedly asked for the llbuild target name of a plugin product")

Sources/Commands/CMakeLists.txt

@@ -14,6 +14,13 @@ add_library(Commands
   MultiRootSupport.swift
   Options.swift
   show-dependencies.swift
+  Snippets/CardEvent.swift
+  Snippets/Cards/SnippetCard.swift
+  Snippets/Cards/SnippetGroupCard.swift
+  Snippets/Cards/TopCard.swift
+  Snippets/CardStack.swift
+  Snippets/Card.swift
+  Snippets/Colorful.swift
   SwiftBuildTool.swift
   SwiftPackageCollectionsTool.swift
   SwiftPackageTool.swift

Sources/Commands/Snippets/Card.swift

@@ -0,0 +1,35 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See http://swift.org/LICENSE.txt for license information
+ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+/// A terminal menu that takes up the whole terminal, accepting input and
+/// rendering in response.
+protocol Card {
+    /// Render the contents to be printed to the terminal.
+    func render() -> String
+
+    /// Accept a line of input from the user's terminal and provide
+    /// an optional ``CardEvent`` which can alter the card stack.
+    func acceptLineInput<S: StringProtocol>(_ line: S) -> CardEvent?
+
+    /// The input prompt to present to the user when accepting a line of input.
+    var inputPrompt: String? { get }
+}
+
+extension Card {
+    var defaultPrompt: String {
+        return "Press enter to continue."
+    }
+}
+
+extension Card {
+    var inputPrompt: String? {
+        return defaultPrompt
+    }
+}

Sources/Commands/Snippets/CardEvent.swift

@@ -0,0 +1,22 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See http://swift.org/LICENSE.txt for license information
+ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+/// An event that alters the card stack after some input from the user.
+enum CardEvent {
+    /// Pop the top card from the stack, providing an optional error that
+    /// may have occurred.
+    case pop(Swift.Error? = nil)
+
+    /// Push a new card onto the stack.
+    case push(Card)
+
+    /// Quit the program, providing an optional error that may have occurred.
+    case quit(Swift.Error? = nil)
+}

Sources/Commands/Snippets/CardStack.swift

@@ -0,0 +1,110 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See http://swift.org/LICENSE.txt for license information
+ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import PackageModel
+import TSCBasic
+import PackageGraph
+
+fileprivate extension TerminalController {
+    func clearScreen() {
+        write("\u{001b}[2J")
+        write("\u{001b}[H")
+        flush()
+    }
+}
+
+/// A stack of "cards" to display one at a time at the command line.
+struct CardStack {
+    var terminal: TerminalController
+
+    /// The representation of a stack of cards.
+    var cards = [Card]()
+
+    /// The tool used for eventually building and running a chosen snippet.
+    var swiftTool: SwiftTool
+
+    /// When true, the escape sequence for clearing the terminal should be
+    /// printed first.
+    private var needsToClearScreen = true
+
+    init(package: ResolvedPackage, snippetGroups: [SnippetGroup], swiftTool: SwiftTool) {
+        self.terminal = TerminalController(stream: stdoutStream)!
+        self.cards = [TopCard(package: package, snippetGroups: snippetGroups, swiftTool: swiftTool)]
+        self.swiftTool = swiftTool
+    }
+
+    mutating func push(_ card: Card) {
+        cards.append(card)
+    }
+
+    mutating func pop() {
+        cards.removeLast()
+    }
+
+    mutating func clear() {
+        cards.removeAll()
+    }
+
+    func askForLineInput(prompt: String?) -> String? {
+        if let prompt = prompt {
+            print(brightBlack { prompt }.terminalString())
+        }
+        terminal.write(">>> ", inColor: .green, bold: true)
+        return readLine(strippingNewline: true)
+    }
+
+    mutating func run() {
+        var inputFinished = false
+        while !inputFinished {
+            guard let top = cards.last else {
+                break
+            }
+
+            if needsToClearScreen {
+                terminal.clearScreen()
+                needsToClearScreen = false
+            }
+
+            print(top.render())
+
+            // Assume input finished until proven otherwise, i.e. when readLine returns
+            // `nil`.
+            inputFinished = true
+
+            askForLine: while let line = askForLineInput(prompt: top.inputPrompt) {
+                inputFinished = false
+                let trimmedLine = String(line.drop { $0.isWhitespace }
+                                            .reversed()
+                                            .drop { $0.isWhitespace }
+                                            .reversed())
+                let response = top.acceptLineInput(trimmedLine)
+                switch response {
+                case .none:
+                    continue askForLine
+                case .push(let card):
+                    push(card)
+                    needsToClearScreen = true
+                    break askForLine
+                case let .pop(error):
+                    cards.removeLast()
+                    if let error = error {
+                        swiftTool.diagnostics.emit(error: error.localizedDescription)
+                        needsToClearScreen = false
+                    } else {
+                        needsToClearScreen = !cards.isEmpty
+                    }
+                    break askForLine
+                case .quit:
+                    return
+                }
+            }
+        }
+    }
+}

Sources/Commands/Snippets/Cards/SnippetCard.swift

@@ -0,0 +1,98 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2014 - 2021 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See http://swift.org/LICENSE.txt for license information
+ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import PackageModel
+import TSCBasic
+
+/// A card displaying a ``Snippet`` at the terminal.
+struct SnippetCard: Card {
+    enum Error: Swift.Error, CustomStringConvertible {
+        case cantRunSnippet(reason: String)
+
+        var description: String {
+            switch self {
+            case let .cantRunSnippet(reason):
+                return "Can't run snippet: \(reason)"
+            }
+        }
+    }
+    /// The snippet to display in the terminal.
+    var snippet: Snippet
+
+    /// The snippet's index within its group.
+    var number: Int
+
+    /// The tool used for eventually building and running a chosen snippet.
+    var swiftTool: SwiftTool
+
+    func render() -> String {
+        var rendered = colorized {
+            brightYellow {
+                "# "
+                snippet.name
+            }
+            "\n\n"
+        }.terminalString()
+
+        if !snippet.explanation.isEmpty {
+            rendered += brightBlack {
+                snippet.explanation
+                .split(separator: "\n", omittingEmptySubsequences: false)
+                .map { "// " + $0 }
+                .joined(separator: "\n")
+            }.terminalString()
+
+            rendered += "\n\n"
+        }
+
+        rendered += snippet.presentationCode
+
+        return rendered
+    }
+
+    var inputPrompt: String? {
+        return "\nRun this snippet? [R: run, or press Enter to return]"
+    }
+
+    func acceptLineInput<S>(_ line: S) -> CardEvent? where S : StringProtocol {
+        let trimmed = line.drop { $0.isWhitespace }.prefix { !$0.isWhitespace }.lowercased()
+        guard !trimmed.isEmpty else {
+            return .pop()
+        }
+
+        switch trimmed {
+        case "r", "run":
+            do {
+                try runExample()
+            } catch {
+                return .pop(SnippetCard.Error.cantRunSnippet(reason: error.localizedDescription))
+            }
+            break
+        case "c", "copy":
+            print("Unimplemented")
+            break
+        default:
+            break
+        }
+
+        return .pop()
+    }
+
+    func runExample() throws {
+        print("Building '\(snippet.path)'\n")
+        let buildSystem = try swiftTool.createBuildSystem(explicitProduct: snippet.name)
+        try buildSystem.build(subset: .product(snippet.name))
+        let executablePath = try swiftTool.buildParameters().buildPath.appending(component: snippet.name)
+        if let exampleTarget = try buildSystem.getPackageGraph().allTargets.first(where: { $0.name == snippet.name }) {
+            try ProcessEnv.chdir(exampleTarget.sources.paths[0].parentDirectory)
+        }
+        try exec(path: executablePath.pathString, args: [])
+    }
+}