Add Expr.init(literal:)

Adds an `Expr.init(literal:)` which functions similarly to `appendInterpolation(literal:format:)` but works outside of interpolations. Also rewrite and reformat related documentation.

Author: beccadax

Sources/SwiftSyntaxBuilder/ConvenienceInitializers.swift

@@ -90,6 +90,42 @@ extension DictionaryExpr {
   }
 }
 
+// MARK: - Expr
+
+extension Expr {
+  /// Returns a syntax tree for an expression that represents the value of the
+  /// provided instance. For example, passing an `Array<String>` will result in
+  /// an array literal containing string literals:
+  ///
+  ///     let arrayExpr = Expr(literal: ["a", "b", "c"])
+  ///     // `arrayExpr` is a syntax tree like `["a", "b", "c"]`
+  ///
+  /// This initializer is compatible with types that conform to
+  /// ``ExpressibleByLiteralSyntax``. These include:
+  ///
+  /// * `String` and `Substring`
+  /// * `Int` and other integer types
+  /// * `Double` and other floating-point types
+  /// * `Bool`
+  /// * `Array` and `Set` of conforming elements
+  /// * `Dictionary` and `KeyValuePairs` of conforming keys and values
+  /// * `Optional` of conforming wrapped value
+  ///
+  /// Conformances will generally handle edge cases sensibly: `String` will
+  /// use raw literals and escapes as needed, `Optional` will wrap a nested
+  /// `nil` in `.some`, `Double` wil represent special values like infinities
+  /// as code sequences like `.infinity`, etc. `Set` and `Dictionary` sort
+  /// thier elements to improve stability.
+  ///
+  /// Because of that intelligent behavior, this initializer is not guaranteed
+  /// to produce a literal as the outermost syntax node, or even to have a
+  /// literal anywhere in its syntax tree. Use a convenience initializer on a
+  /// specific type if you need that exact type in the syntax tree.
+  public init<Literal: ExpressibleByLiteralSyntax>(literal: Literal) {
+    self.init(fromProtocol: literal.makeLiteralSyntax())
+  }
+}
+
 // MARK: - FloatLiteralExprSyntax
 
 extension FloatLiteralExprSyntax: ExpressibleByFloatLiteral {

Sources/SwiftSyntaxBuilder/Syntax+StringInterpolation.swift

@@ -110,26 +110,26 @@ extension SyntaxStringInterpolation: StringInterpolationProtocol {
     self.appendInterpolation(buildable.formatted(using: format))
   }
 
+  /// Interpolates a literal or similar expression syntax equivalent to `value`.
+  ///
+  /// - SeeAlso: ``Expr.init(literal:)``
   public mutating func appendInterpolation<Literal: ExpressibleByLiteralSyntax>(
     literal value: Literal,
     format: BasicFormat = BasicFormat()
   ) {
-    self.appendInterpolation(
-      ExprSyntax(fromProtocol: value.makeLiteralSyntax()),
-      format: format
-    )
+    self.appendInterpolation(Expr(literal: value), format: format)
   }
 
   // This overload is technically redundant with the previous one, except that
   // it silences a warning about interpolating Optionals.
+  /// Interpolates a literal or similar expression syntax equivalent to `value`.
+  ///
+  /// - SeeAlso: ``Expr.init(literal:)``
   public mutating func appendInterpolation<Literal: ExpressibleByLiteralSyntax>(
     literal value: Literal?,
     format: BasicFormat = BasicFormat()
   ) {
-    self.appendInterpolation(
-      ExprSyntax(fromProtocol: value.makeLiteralSyntax()),
-      format: format
-    )
+    self.appendInterpolation(Expr(literal: value), format: format)
   }
 }
 
@@ -157,23 +157,55 @@ enum SyntaxStringInterpolationError: Error, CustomStringConvertible {
   }
 }
 
-/// A Swift type whose value can be represented directly in source code by a Swift literal.
+/// A Swift type whose value can be represented directly in source code by a
+/// Swift literal.
+///
+/// Conforming types do not *contain* Swift source code; rather, they can be
+/// *expressed* in Swift source code, and this protocol can be used to get
+/// whatever source code would do that. For example, `String` is
+/// `ExpressibleByLiteralSyntax` but `StringLiteralExprSyntax` is not.
+///
+/// This protocol is usually not used directly. Instead, conforming types can
+/// be turned into syntax trees using ``Expr.init(literal:)``:
 ///
-/// Conforming types do not *contain* Swift source code; rather, they can be *expressed* in Swift source code, and this protocol can be used to get whatever source code would do that. For example, `String` is `ExpressibleByLiteralSyntax` but `StringLiteralExprSyntax` is not.
+///     let expr2 = Expr(literal: [0+1, 1+1, 2+1])
+///     // `expr2` is a syntax tree for `[1, 2, 3]`.
 ///
-/// Conforming types can be interpolated into a Swift source code literal with the syntax `\(literal: <value>)`:
+/// Or interpolated into a Swift source code literal with the syntax
+/// `\(literal: <value>)`:
 ///
-///      let greeting = "Hello, world!"
-///      let expr1 = ExprSyntax("print(\(literal: greeting))")
-///      // `expr1` is a syntax tree for `print("Hello, world!")`
+///     let greeting = "Hello, world!"
+///     let expr1 = ExprSyntax("print(\(literal: greeting))")
+///     // `expr1` is a syntax tree for `print("Hello, world!")`
 ///
-/// Note that quote marks are automatically added around the contents; you don't have to write them yourself. The conformance will automatically ensure the contents are correctly escaped, possibly by using raw literals or other language features:
+/// Note that quote marks are automatically added around the contents of string
+/// literals; you don't have to write them yourself. The conformance for
+/// `String` will automatically ensure the contents are correctly escaped,
+/// possibly by using raw literals or other language features:
 ///
-///      let msPath = "c:\\windows\\system32"
-///      let expr2 = ExprSyntax("open(\(literal: msPath))")
-///      // `expr2` might be a syntax tree for `open(#"c:\windows\system32"#)`
-///      // or for `open("c:\\windows\\system32")`.
+///     let msPath = "c:\\windows\\system32"
+///     let expr3 = ExprSyntax("open(\(literal: msPath))")
+///     // `expr3` might be a syntax tree for `open(#"c:\windows\system32"#)`
+///     // or for `open("c:\\windows\\system32")`.
+///
+/// Other conformances have similar intelligent behaviors: floating-point types
+/// produce correct syntax trees for infinities and NaNs, nested optionals
+/// produce `.some(nil)` where appropriate, etc.
 public protocol ExpressibleByLiteralSyntax {
+  /// Returns a syntax tree that represents the value of this instance.
+  ///
+  /// This method is usually not called directly. Instead, conforming types can
+  /// be turned into syntax trees using ``Expr.init(literal:)``:
+  ///
+  ///     let expr2 = Expr(literal: [0+1, 1+1, 2+1])
+  ///     // `expr2` is a syntax tree for `[1, 2, 3]`.
+  ///
+  /// Or interpolated into a Swift source code literal with the syntax
+  /// `\(literal: <value>)`:
+  ///
+  ///     let greeting = "Hello, world!"
+  ///     let expr1 = ExprSyntax("print(\(literal: greeting))")
+  ///     // `expr1` is a syntax tree for `print("Hello, world!")`
   func makeLiteralSyntax() -> ExprSyntaxProtocol
 }