Merge pull request swiftlang#214 from google/cleanup

Remove some dead rules; refactor format/lint logic into an API.

Author: dabelknap

Package.swift

@@ -19,6 +19,7 @@ let package = Package(
   name: "swift-format",
   products: [
     .executable(name: "swift-format", targets: ["swift-format"]),
+    .library(name: "SwiftFormat", targets: ["SwiftFormat"]),
   ],
   dependencies: [
     .package(url: "https://github.com/apple/swift-package-manager.git", from: "0.1.0"),
@@ -35,6 +36,16 @@ let package = Package(
       ]
     ),
     .target(name: "CommonMark", dependencies: ["CCommonMark"]),
+    .target(
+      name: "SwiftFormat",
+      dependencies: [
+        "SwiftFormatConfiguration",
+        "SwiftFormatCore",
+        "SwiftFormatPrettyPrint",
+        "SwiftFormatRules",
+        "SwiftSyntax",
+      ]
+    ),
     .target(name: "SwiftFormatConfiguration"),
     .target(name: "SwiftFormatCore", dependencies: ["SwiftFormatConfiguration", "SwiftSyntax"]),
     .target(
@@ -49,10 +60,9 @@ let package = Package(
     .target(
       name: "swift-format",
       dependencies: [
+        "SwiftFormat",
         "SwiftFormatConfiguration",
         "SwiftFormatCore",
-        "SwiftFormatPrettyPrint",
-        "SwiftFormatRules",
         "SwiftSyntax",
         "Utility",
       ]

Sources/swift-format/DebugOptions.swift renamed to Sources/SwiftFormat/DebugOptions.swift

@@ -12,21 +12,21 @@
 
 /// Advanced options that are useful when debugging and developing the formatter, but are otherwise
 /// not meant for general use.
-struct DebugOptions: OptionSet {
+public struct DebugOptions: OptionSet {
 
   /// Disables the pretty-printer pass entirely, executing only the syntax-transforming rules in the
   /// pipeline.
-  static let disablePrettyPrint = DebugOptions(rawValue: 1 << 0)
+  public static let disablePrettyPrint = DebugOptions(rawValue: 1 << 0)
 
   /// Dumps a verbose representation of the raw pretty-printer token stream.
-  static let dumpTokenStream = DebugOptions(rawValue: 1 << 1)
+  public static let dumpTokenStream = DebugOptions(rawValue: 1 << 1)
 
-  let rawValue: Int
+  public let rawValue: Int
 
-  init(rawValue: Int) { self.rawValue = rawValue }
+  public init(rawValue: Int) { self.rawValue = rawValue }
 
   /// Inserts or removes the given element from the option set, based on the value of `enabled`.
-  mutating func set(_ element: Element, enabled: Bool) {
+  public mutating func set(_ element: Element, enabled: Bool) {
     if enabled { insert(element) } else { remove(element) }
   }
 }

Sources/swift-format/PopulatePipeline.swift renamed to Sources/SwiftFormat/PopulatePipeline.swift

@@ -20,10 +20,8 @@ import SwiftSyntax
 /// - Parameter pipeline: The pipeline to populate with passes.
 func populate(_ pipeline: Pipeline) {
   /// MARK: File Passes
-  pipeline.addFileRule(UseOnlySpaces.self)
   pipeline.addFileRule(UseOnlyUTF8.self)
   pipeline.addFileRule(UseSpecialEscapeSequences.self)
-  pipeline.addFileRule(ValidFilename.self)
 
   /// MARK: Formatting Passes
 
@@ -263,6 +261,7 @@ func populate(_ pipeline: Pipeline) {
   pipeline.addLinter(
     BeginDocumentationCommentWithOneLineSummary.self,
     for:
+      AssociatedtypeDeclSyntax.self,
       ClassDeclSyntax.self,
       DeinitializerDeclSyntax.self,
       EnumDeclSyntax.self,

Sources/SwiftFormat/SwiftFormatter.swift

@@ -0,0 +1,88 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import SwiftFormatConfiguration
+import SwiftFormatCore
+import SwiftFormatPrettyPrint
+import SwiftSyntax
+
+/// Formats Swift source code or syntax trees according to the Swift style guidelines.
+public final class SwiftFormatter {
+
+  /// The configuration settings that control the formatter's behavior.
+  public let configuration: Configuration
+
+  /// A diagnostic engine to which non-fatal errors will be reported.
+  public let diagnosticEngine: DiagnosticEngine?
+
+  /// Advanced options that are useful when debugging the formatter's behavior but are not meant for
+  /// general use.
+  public var debugOptions: DebugOptions = []
+
+  /// Creates a new Swift code formatter with the given configuration.
+  ///
+  /// - Parameters:
+  ///   - configuration: The configuration settings that control the formatter's behavior.
+  ///   - diagnosticEngine: The diagnostic engine to which non-fatal errors will be reported.
+  ///     Defaults to nil.
+  public init(configuration: Configuration, diagnosticEngine: DiagnosticEngine? = nil) {
+    self.configuration = configuration
+    self.diagnosticEngine = diagnosticEngine
+  }
+
+  /// Formats the Swift code at the given file URL and writes the result to an output stream.
+  ///
+  /// - Parameters:
+  ///   - url: The URL of the file containing the code to format.
+  ///   - outputStream: A value conforming to `TextOutputStream` to which the formatted output will
+  ///     be written.
+  /// - Throws: If an unrecoverable error occurs when formatting the code.
+  public func format<Output: TextOutputStream>(
+    contentsOf url: URL, to outputStream: inout Output
+  ) throws {
+    let sourceFile = try SyntaxTreeParser.parse(url)
+    try format(syntax: sourceFile, assumingFileURL: url, to: &outputStream)
+  }
+
+  /// Formats the given Swift syntax tree and writes the result to an output stream.
+  ///
+  /// - Parameters:
+  ///   - syntax: The Swift syntax tree to be converted to source code and formatted.
+  ///   - url: A file URL denoting the filename/path that should be assumed for this syntax tree.
+  ///   - outputStream: A value conforming to `TextOutputStream` to which the formatted output will
+  ///     be written.
+  /// - Throws: If an unrecoverable error occurs when formatting the code.
+  public func format<Output: TextOutputStream>(
+    syntax: Syntax, assumingFileURL url: URL, to outputStream: inout Output
+  ) throws {
+    let context
+      = Context(configuration: configuration, diagnosticEngine: diagnosticEngine, fileURL: url)
+    let pipeline = FormatPipeline(context: context)
+    populate(pipeline)
+
+    let transformedSyntax = pipeline.visit(syntax)
+
+    if debugOptions.contains(.disablePrettyPrint) {
+      outputStream.write(transformedSyntax.description)
+      return
+    }
+
+    let printer = PrettyPrinter(
+      context: context,
+      node: transformedSyntax,
+      printTokenStream: debugOptions.contains(.dumpTokenStream))
+    outputStream.write(printer.prettyPrint())
+  }
+
+  // TODO: Add an overload of `format` that takes the source text directly.
+}

Sources/SwiftFormat/SwiftLinter.swift

@@ -0,0 +1,71 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2018 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import SwiftFormatConfiguration
+import SwiftFormatCore
+import SwiftSyntax
+
+/// Diagnoses and reports problems in Swift source code or syntax trees according to the Swift style
+/// guidelines.
+public final class SwiftLinter {
+
+  /// The configuration settings that control the linter's behavior.
+  public let configuration: Configuration
+
+  /// A diagnostic engine to which lint findings will be reported.
+  public let diagnosticEngine: DiagnosticEngine
+
+  /// Advanced options that are useful when debugging the linter's behavior but are not meant for
+  /// general use.
+  public var debugOptions: DebugOptions = []
+
+  /// Creates a new Swift code linter with the given configuration.
+  ///
+  /// - Parameters:
+  ///   - configuration: The configuration settings that control the linter's behavior.
+  ///   - diagnosticEngine: The diagnostic engine to which lint findings will be reported.
+  public init(configuration: Configuration, diagnosticEngine: DiagnosticEngine) {
+    self.configuration = configuration
+    self.diagnosticEngine = diagnosticEngine
+  }
+
+  /// Lints the Swift code at the given file URL.
+  ///
+  /// - Parameters url: The URL of the file containing the code to format.
+  /// - Throws: If an unrecoverable error occurs when formatting the code.
+  public func lint(contentsOf url: URL) throws {
+    let sourceFile = try SyntaxTreeParser.parse(url)
+    try lint(syntax: sourceFile, assumingFileURL: url)
+  }
+
+  /// Lints the given Swift syntax tree.
+  ///
+  /// - Parameters:
+  ///   - syntax: The Swift syntax tree to be converted to be linted.
+  ///   - url: A file URL denoting the filename/path that should be assumed for this syntax tree.
+  ///   - outputStream: A value conforming to `TextOutputStream` to which the formatted output will
+  ///     be written.
+  /// - Throws: If an unrecoverable error occurs when formatting the code.
+  public func lint(syntax: Syntax, assumingFileURL url: URL) throws {
+    let context
+      = Context(configuration: configuration, diagnosticEngine: diagnosticEngine, fileURL: url)
+    let pipeline = LintPipeline(context: context)
+    populate(pipeline)
+
+    pipeline.visit(syntax as Syntax)
+
+    // TODO: Extend the pretty printer to make it possible to lint spacing and breaking issues.
+  }
+
+  // TODO: Add an overload of `lint` that takes the source text directly.
+}

Sources/SwiftFormatConfiguration/Configuration.swift

@@ -65,9 +65,6 @@ public class Configuration: Codable {
   /// Rules for limiting blank lines between members.
   public var blankLineBetweenMembers = BlankLineBetweenMembersConfiguration()
 
-  /// Rules for adding backticks around special symbols in documentation comments.
-  public var surroundSymbolsWithBackticks = SurroundSymbolsWithBackticksConfiguration()
-
   /// Constructs a Configuration with all default values.
   public init() {
     self.version = highestSupportedConfigurationVersion
@@ -104,9 +101,6 @@ public class Configuration: Codable {
     self.blankLineBetweenMembers = try container.decodeIfPresent(
       BlankLineBetweenMembersConfiguration.self, forKey: .blankLineBetweenMembers)
       ?? BlankLineBetweenMembersConfiguration()
-    self.surroundSymbolsWithBackticks = try container.decodeIfPresent(
-      SurroundSymbolsWithBackticksConfiguration.self, forKey: .surroundSymbolsWithBackticks)
-      ?? SurroundSymbolsWithBackticksConfiguration()
   }
 
   public func encode(to encoder: Encoder) throws {
@@ -119,7 +113,6 @@ public class Configuration: Codable {
     try container.encode(indentation, forKey: .indentation)
     try container.encode(respectsExistingLineBreaks, forKey: .respectsExistingLineBreaks)
     try container.encode(blankLineBetweenMembers, forKey: .blankLineBetweenMembers)
-    try container.encode(surroundSymbolsWithBackticks, forKey: .surroundSymbolsWithBackticks)
   }
 }
 
@@ -129,18 +122,6 @@ public struct BlankLineBetweenMembersConfiguration: Codable {
   public let ignoreSingleLineProperties = true
 }
 
-// TODO(abl): Expand the whitelist and blacklist.
-/// Configuration for the SurroundSymbolsWithBackticks rule.
-public struct SurroundSymbolsWithBackticksConfiguration: Codable {
-  /// List of global symbols; added to the list of file-local symbols. Case-sensitive.
-  public let symbolWhitelist = ["String"]
-
-  /// List of symbols to ignore. Case-sensitive.
-  public let symbolBlacklist = [
-    "URL", // symbol name and capitalization is the same as the term.
-  ]
-}
-
 /// Configuration for the NoPlaygroundLiterals rule.
 public struct NoPlaygroundLiteralsConfiguration: Codable {
   public enum ResolveBehavior: String, Codable {