Introduce the snippet target type (#3694)

Snippets are small, focused pieces of example code for packages. They are meant
for current and potential package clients to read and try when exploring a
package.

Snippets build with the rest of a package so they don't get stale and
can run as an executable target with hidden "demo code" to illustrate and prove
that the snippets work (this does not mean that snippets are tests!).

Summary of changes:

- Add a `.snippet` product and target type
- Add the `Snippet` and `SnippetGroup` model to PackageModel
- When building a package in `PackageBuilder`, look for snippets in the
  `Snippets` subdirectory.
- Add the "card stack" terminal UIs for browsing a package's snippets
  - "Top" card: The top level menu that displays products and snippet groups
  - "Snippet Group" card: The menu that shows the snippets in a group
  - "Snippet" card: Displays a snippet's presentation code and offers
    to build and run the snippet.

Author: bitjammer

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
   SwiftPackageRegistryTool.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: [])
+    }
+}