Merge pull request #1007 from SimplyDanny/runnable-examples

Make examples runnable

Author: ahoppen

Examples/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+/.build

Examples/AddOneToIntegerLiterals.swift

@@ -1,26 +1,27 @@
 import SwiftSyntax
-import SwiftSyntaxParser
+import SwiftParser
 import Foundation
 
 /// AddOneToIntegerLiterals will visit each token in the Syntax tree, and
 /// (if it is an integer literal token) add 1 to the integer and return the
 /// new integer literal token.
 ///
-/// For example will it turn:
+/// For example, it will turn
 /// ```
 /// let x = 2
 /// let y = 3_000
 /// ```
-/// into:
+/// into
 /// ```
 /// let x = 3
 /// let y = 3001
 /// ```
-class AddOneToIntegerLiterals: SyntaxRewriter {
-  override func visit(_ token: TokenSyntax) -> Syntax {
+///
+private class AddOneToIntegerLiterals: SyntaxRewriter {
+  override func visit(_ token: TokenSyntax) -> TokenSyntax {
     // Only transform integer literals.
     guard case .integerLiteral(let text) = token.tokenKind else {
-      return Syntax(token)
+      return token
     }
 
     // Remove underscores from the original text.
@@ -33,12 +34,18 @@ class AddOneToIntegerLiterals: SyntaxRewriter {
     let newIntegerLiteralToken = token.withKind(.integerLiteral("\(int + 1)"))
 
     // Return the new integer literal.
-    return Syntax(newIntegerLiteralToken)
+    return newIntegerLiteralToken
   }
 }
 
-let file = CommandLine.arguments[1]
-let url = URL(fileURLWithPath: file)
-let sourceFile = try SyntaxParser.parse(url)
-let incremented = AddOneToIntegerLiterals().visit(sourceFile)
-print(incremented)
+@main
+struct Main {
+  static func main() throws {
+    let file = CommandLine.arguments[1]
+    let url = URL(fileURLWithPath: file)
+    let source = try String(contentsOf: url, encoding: .utf8)
+    let sourceFile = Parser.parse(source: source)
+    let incremented = AddOneToIntegerLiterals().visit(sourceFile)
+    print(incremented)
+  }
+}

Examples/CodeGenerationUsingSwiftSyntaxBuilder.swift

@@ -1,26 +1,31 @@
 import SwiftSyntaxBuilder
 
-/// This example will print the following example:
+/// This example will print the following code:
 ///
-///```
+/// ```
 /// import Foundation
 /// import UIKit
 /// class SomeViewController{
 ///    let tableView: UITableView
 /// }
-///```
-
-let source = SourceFile {
-  ImportDecl(path: "Foundation")
-  ImportDecl(path: "UIKit")
-  ClassDecl(identifier: "SomeViewController") {
-    VariableDecl(.let, name: "tableView", type: "UITableView")
-  }
-}
+/// ```
+///
+@main
+struct Main {
+  static func main() {
+    let source = SourceFile {
+      ImportDecl(path: "Foundation")
+      ImportDecl(path: "UIKit")
+      ClassDecl(identifier: "SomeViewController") {
+        VariableDecl(.let, name: "tableView", type: "UITableView")
+      }
+    }
 
-let syntax = source.buildSyntax(format: Format())
+    let syntax = source.build()
 
-var text = ""
-syntax.write(to: &text)
+    var text = ""
+    syntax.write(to: &text)
 
-print(text)
+    print(text)
+  }
+}

Examples/MigrateToNewIfLetSyntax.swift

@@ -29,7 +29,7 @@ class MigrateToNewIfLetSyntax: SyntaxRewriter {
          let initializer = binding.initializer,
          // ... and both sides of the assignment are the same identifiers.
          binding.pattern.withoutTrivia().description == initializer.value.withoutTrivia().description {
-        // Remove the initializer ... 
+        // Remove the initializer ...
         binding.initializer = nil
         // ... and remove whitespace before the comma (in `if` statements with multiple conditions).
         if index != node.conditions.count - 1 {
@@ -41,19 +41,16 @@ class MigrateToNewIfLetSyntax: SyntaxRewriter {
     }
     return StmtSyntax(node.withConditions(ConditionElementListSyntax(newConditions)))
   }
-  
-  /// Utility function to migrate all swift files in a folder and its subfolders
-  static func migrate(folderPath: String) {
-    for case let fileURL as String in FileManager.default.enumerator(atPath: folderPath)! {
-      if fileURL.hasSuffix("swift") {
-        print("Rewriting", fileURL)
-        let fullPath = folderPath + "/" + fileURL
-        let tree = try! Parser.parse(source: String(data: FileManager.default.contents(atPath: fullPath)!, encoding: .utf8 )!)
-        let newTree = MigrateToNewIfLetSyntax().visit(tree)
-        try! newTree.description.write(toFile: fullPath, atomically: true, encoding: .utf8)
-      }
-    }
-  }
 }
 
-MigrateToNewIfLetSyntax.migrate(folderPath: "/path/to/folder")
+@main
+struct Main {
+  static func main() throws {
+    let file = CommandLine.arguments[1]
+    let url = URL(fileURLWithPath: file)
+    let source = try String(contentsOf: url, encoding: .utf8)
+    let sourceFile = Parser.parse(source: source)
+    let rewritten = MigrateToNewIfLetSyntax().visit(sourceFile)
+    print(rewritten)
+  }
+}

Examples/Package.swift

@@ -0,0 +1,46 @@
+// swift-tools-version: 5.7
+
+import PackageDescription
+
+let package = Package(
+    name: "Examples",
+    platforms: [
+        .macOS(.v10_15),
+    ],
+    products: [
+        .executable(name: "AddOneToIntegerLiterals", targets: ["AddOneToIntegerLiterals"]),
+        .executable(name: "CodeGenerationUsingSwiftSyntaxBuilder", targets: ["CodeGenerationUsingSwiftSyntaxBuilder"]),
+        .executable(name: "MigrateToNewIfLetSyntax", targets: ["MigrateToNewIfLetSyntax"]),
+    ],
+    dependencies: [
+        .package(path: "../"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "AddOneToIntegerLiterals",
+            dependencies: [
+                .product(name: "SwiftParser", package: "swift-syntax"),
+                .product(name: "SwiftSyntax", package: "swift-syntax"),
+            ],
+            path: ".",
+            exclude: ["README.md", "CodeGenerationUsingSwiftSyntaxBuilder.swift", "MigrateToNewIfLetSyntax.swift"]
+        ),
+        .executableTarget(
+            name: "CodeGenerationUsingSwiftSyntaxBuilder",
+            dependencies: [
+                .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
+            ],
+            path: ".",
+            exclude: ["README.md", "AddOneToIntegerLiterals.swift", "MigrateToNewIfLetSyntax.swift"]
+        ),
+        .executableTarget(
+            name: "MigrateToNewIfLetSyntax",
+            dependencies: [
+                .product(name: "SwiftParser", package: "swift-syntax"),
+                .product(name: "SwiftSyntax", package: "swift-syntax"),
+            ],
+            path: ".",
+            exclude: ["README.md", "CodeGenerationUsingSwiftSyntaxBuilder.swift", "AddOneToIntegerLiterals.swift"]
+        ),
+    ]
+)

Examples/README.md

@@ -1,7 +1,10 @@
-# Snippets (Examples)
+# Examples
 
-- Command line tool to add one to every integer literal in a source file [AddOneToIntegerLiterals.swift](AddOneToIntegerLiterals.swift).
-- Code-generate a simple source file using SwiftSyntaxBuilder [CodeGenerationUsingSwiftSyntaxBuilder.swift](CodeGenerationUsingSwiftSyntaxBuilder.swift)
+Each example can be executed by navigating into this folder and running `swift run <example> <arguments>`. There is the following set of examples available:
+
+- [AddOneToIntegerLiterals](AddOneToIntegerLiterals.swift): Command line tool to add 1 to every integer literal in a source file
+- [CodeGenerationUsingSwiftSyntaxBuilder](CodeGenerationUsingSwiftSyntaxBuilder.swift): Code-generate a simple source file using SwiftSyntaxBuilder
+- [MigrateToNewIfLetSyntax](MigrateToNewIfLetSyntax.swift): Command line tool to transform optional bindings in `if` statements to the new shorthand syntax
 
 ## Some Example Usages
 

build-script.py

@@ -15,6 +15,7 @@
 
 PACKAGE_DIR = os.path.dirname(os.path.realpath(__file__))
 WORKSPACE_DIR = os.path.dirname(PACKAGE_DIR)
+EXAMPLES_DIR = os.path.join(PACKAGE_DIR, "Examples")
 SOURCES_DIR = os.path.join(PACKAGE_DIR, "Sources")
 SWIFTSYNTAX_DIR = os.path.join(SOURCES_DIR, "SwiftSyntax")
 SWIFTSYNTAX_DOCUMENTATION_DIR = \
@@ -401,13 +402,13 @@ def clear_gyb_files_from_previous_run(
 
 
 def get_swiftpm_invocation(
-    toolchain: str, action: str, build_dir: Optional[str],
+    toolchain: str, action: str, package_dir: str, build_dir: Optional[str],
     multiroot_data_file: Optional[str], release: bool
 ) -> List[str]:
     swift_exec = os.path.join(toolchain, "bin", "swift")
 
     swiftpm_call = [swift_exec, action]
-    swiftpm_call.extend(["--package-path", PACKAGE_DIR])
+    swiftpm_call.extend(["--package-path", package_dir])
     if platform.system() != "Darwin":
         swiftpm_call.extend(["--enable-test-discovery"])
     if release:
@@ -421,9 +422,12 @@ def get_swiftpm_invocation(
 
 
 class Builder(object):
-    swiftpm_call: List[str]
     verbose: bool
     toolchain: str
+    build_dir: Optional[str]
+    multiroot_data_file: Optional[str]
+    release: bool
+    disable_sandbox: bool
 
     def __init__(
         self,
@@ -434,23 +438,38 @@ def __init__(
         verbose: bool,
         disable_sandbox: bool = False,
     ) -> None:
-        self.swiftpm_call = get_swiftpm_invocation(
-            toolchain=toolchain,
-            action="build",
-            build_dir=build_dir,
-            multiroot_data_file=multiroot_data_file,
-            release=release,
-        )
-        if disable_sandbox:
-            self.swiftpm_call.append("--disable-sandbox")
-        if verbose:
-            self.swiftpm_call.extend(["--verbose"])
+        self.build_dir = build_dir
+        self.multiroot_data_file = multiroot_data_file
+        self.release = release
+        self.disable_sandbox = disable_sandbox
         self.verbose = verbose
         self.toolchain = toolchain
 
-    def build(self, product_name: str) -> None:
-        print("** Building " + product_name + " **")
-        command = list(self.swiftpm_call)
+    def __get_swiftpm_invocation(self, package_dir: str) -> List[str]:
+        invocation = get_swiftpm_invocation(
+            self.toolchain,
+            "build",
+            package_dir,
+            self.build_dir,
+            self.multiroot_data_file,
+            self.release
+        )
+        if self.disable_sandbox:
+            invocation.append("--disable-sandbox")
+        if self.verbose:
+            invocation.append("--verbose")
+        return invocation
+
+    def buildProduct(self, product_name: str) -> None:
+        print("** Building product " + product_name + " **")
+        self.__build(PACKAGE_DIR, product_name)
+
+    def buildExample(self, example_name: str) -> None:
+        print("** Building example " + example_name + " **")
+        self.__build(EXAMPLES_DIR, example_name)
+
+    def __build(self, package_dir: str, product_name: str) -> None:
+        command = list(self.__get_swiftpm_invocation(package_dir))
         command.extend(["--product", product_name])
 
         env = dict(os.environ)
@@ -599,6 +618,7 @@ def find_lit_test_helper_exec(
     swiftpm_call = get_swiftpm_invocation(
         toolchain=toolchain,
         action="build",
+        package_dir=PACKAGE_DIR,
         build_dir=build_dir,
         multiroot_data_file=None,
         release=release,
@@ -651,6 +671,7 @@ def run_xctests(toolchain: str, build_dir: Optional[str],
     swiftpm_call = get_swiftpm_invocation(
         toolchain=toolchain,
         action="test",
+        package_dir=PACKAGE_DIR,
         build_dir=build_dir,
         multiroot_data_file=multiroot_data_file,
         release=release,
@@ -738,9 +759,14 @@ def build_command(args: argparse.Namespace) -> None:
         )
         # Until rdar://53881101 is implemented, we cannot request a build of multiple
         # targets simultaneously. For now, just build one product after the other.
-        builder.build("SwiftSyntax")
-        builder.build("SwiftSyntaxParser")
-        builder.build("SwiftSyntaxBuilder")
+        builder.buildProduct("SwiftSyntax")
+        builder.buildProduct("SwiftSyntaxParser")
+        builder.buildProduct("SwiftSyntaxBuilder")
+
+        # Build examples
+        builder.buildExample("AddOneToIntegerLiterals")
+        builder.buildExample("CodeGenerationUsingSwiftSyntaxBuilder")
+        builder.buildExample("MigrateToNewIfLetSyntax")
     except subprocess.CalledProcessError as e:
         fail_for_called_process_error("Building SwiftSyntax failed", e)
 
@@ -756,7 +782,7 @@ def test_command(args: argparse.Namespace) -> None:
             disable_sandbox=args.disable_sandbox,
         )
 
-        builder.build("lit-test-helper")
+        builder.buildProduct("lit-test-helper")
 
         run_tests(
             toolchain=args.toolchain,