Add BatchGetItem sample for Swift (awsdocs#4539)

* Add BatchGetItem sample for Swift

In addition to demonstrating the use of BatchGetItem, this commit updates the
metadata and README to include this function. Also included is a `.gitignore`
file that prevents Swift's `.build` directories from being added to the
repository by accident.

.doc_gen/metadata/dynamodb_metadata.yaml

@@ -166,6 +166,14 @@ dynamodb_BatchGetItem:
             - description:
               snippet_tags:
                 - cpp.example_code.dynamodb.batch_get_item
+    Swift:
+      versions:
+        - sdk_version: 1
+          github: swift/example_code/ddb
+          excerpts:
+            - description:
+              snippet_tags:
+                - ddb.swift.batchgetitem.batchget
   services:
     dynamodb: {BatchGetItem}
 dynamodb_DescribeTable:

swift/.gitignore

@@ -0,0 +1 @@
+**/.build

swift/example_code/ddb/BatchGetItem/Package.swift

@@ -0,0 +1,64 @@
+// swift-tools-version:5.6
+// The swift-tools-version declares the minimum version of Swift required to
+// build this package.
+//
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import PackageDescription
+
+let package = Package(
+// snippet-start:[ddb.swift.batchgetitem.package.attributes]
+    name: "batchgetitem",
+    platforms: [
+        .macOS(.v11),
+        .iOS(.v13)
+    ],
+// snippet-end:[ddb.swift.batchgetitem.package.attributes]
+// snippet-start:[ddb.swift.batchgetitem.package.dependencies]
+    dependencies: [
+        // Dependencies declare other packages that this package depends on.
+        .package(
+            url: "https://github.com/awslabs/aws-sdk-swift",
+            from: "0.10.0"
+        ),
+        .package(
+            url: "https://github.com/apple/swift-argument-parser.git",
+            branch: "main"
+        ),
+        .package(
+            name: "SwiftUtilities",
+            path: "../../../modules/SwiftUtilities"
+        ),
+    ],
+// snippet-end:[ddb.swift.batchgetitem.package.dependencies]
+// snippet-start:[ddb.swift.batchgetitem.package.targets]
+    targets: [
+        // A target defines a module or a test suite. A target can depend on
+        // other targets in this package. They can also depend on products in
+        // other packages that this package depends on.
+// snippet-start:[ddb.swift.batchgetitem.package.target.executable]
+        .executableTarget(
+            name: "batchgetitem",
+            dependencies: [
+                .product(name: "AWSDynamoDB", package: "aws-sdk-swift"),
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                "SwiftUtilities",
+            ],
+            path: "./Sources"
+         ),
+// snippet-end:[ddb.swift.batchgetitem.package.target.executable]
+// snippet-start:[ddb.swift.batchgetitem.package.target.tests]
+        .testTarget(
+            name: "batchgetitem-tests",
+            dependencies: [
+                .product(name: "AWSDynamoDB", package: "aws-sdk-swift"),
+                "batchgetitem",
+                "SwiftUtilities"
+            ],
+            path: "./Tests"
+        )
+// snippet-end:[ddb.swift.batchgetitem.package.target.tests]
+    ]
+// snippet-end:[ddb.swift.batchgetitem.package.targets]
+)

swift/example_code/ddb/BatchGetItem/Sources/Movie.swift

@@ -0,0 +1,154 @@
+// A structure to represent the information about a movie.
+//
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+// snippet-start:[ddb.swift.batchgetitem.movie]
+import Foundation
+import AWSDynamoDB
+
+// snippet-start:[ddb.swift.batchgetitem.info]
+/// The optional details about a movie.
+public struct Info: Codable {
+    /// The movie's rating, if available.
+    var rating: Double?
+    /// The movie's plot, if available.
+    var plot: String?
+}
+// snippet-end:[ddb.swift.batchgetitem.info]
+
+public struct Movie: Codable {
+    /// The year in which the movie was released.
+    var year: Int
+    /// The movie's title.
+    var title: String
+    /// An `Info` object providing the optional movie rating and plot
+    /// information.
+    var info: Info
+
+    // snippet-start:[ddb.swift.batchgetitem.movie.init]
+    /// Create a `Movie` object representing a movie, given the movie's
+    /// details.
+    ///
+    /// - Parameters:
+    ///   - title: The movie's title (`String`).
+    ///   - year: The year in which the movie was released (`Int`).
+    ///   - rating: The movie's rating (optional `Double`).
+    ///   - plot: The movie's plot (optional `String`).
+    init(title: String, year: Int, rating: Double? = nil, plot: String? = nil) {
+        self.title = title
+        self.year = year
+
+        self.info = Info(rating: rating, plot: plot)
+    }
+    // snippet-end:[ddb.swift.batchgetitem.movie.init]
+
+    // snippet-start:[ddb.swift.batchgetitem.movie.init-info]
+    /// Create a `Movie` object representing a movie, given the movie's
+    /// details.
+    ///
+    /// - Parameters:
+    ///   - title: The movie's title (`String`).
+    ///   - year: The year in which the movie was released (`Int`).
+    ///   - info: The optional rating and plot information for the movie in an
+    ///     `Info` object.
+    init(title: String, year: Int, info: Info?) {
+        self.title = title
+        self.year = year
+
+        if info != nil {
+            self.info = info!
+        } else {
+            self.info = Info(rating: nil, plot: nil)
+        }
+    }
+    // snippet-end:[ddb.swift.batchgetitem.movie.init-info]
+
+    // snippet-start:[ddb.swift.batchgetitem.movie.init-withitem]
+    ///
+    /// Return a new `MovieTable` object, given an array mapping string to Amazon
+    /// DynamoDB attribute values.
+    /// 
+    /// - Parameter item: The item information provided in the form used by
+    ///   DynamoDB. This is an array of strings mapped to
+    ///   `DynamoDBClientTypes.AttributeValue` values.
+    init(withItem item: [Swift.String:DynamoDBClientTypes.AttributeValue]) throws {
+        // Read the attributes.
+
+        guard let titleAttr = item["title"],
+              let yearAttr = item["year"] else {
+            throw MovieError.ItemNotFound
+        }
+        let infoAttr = item["info"] ?? nil
+
+        // Extract the values of the title and year attributes.
+
+        if case .s(let titleVal) = titleAttr {
+            self.title = titleVal
+        } else {
+            throw MovieError.InvalidAttributes
+        }
+
+        if case .n(let yearVal) = yearAttr {
+            self.year = Int(yearVal)!
+        } else {
+            throw MovieError.InvalidAttributes
+        }
+
+        // Extract the rating and/or plot from the `info` attribute, if
+        // they're present.
+
+        var rating: Double? = nil
+        var plot: String? = nil
+
+        if case .m(let infoVal) = infoAttr {
+            let ratingAttr = infoVal["rating"] ?? nil
+            let plotAttr = infoVal["plot"] ?? nil
+
+            if ratingAttr != nil, case .n(let ratingVal) = ratingAttr {
+                rating = Double(ratingVal) ?? nil
+            }
+            if plotAttr != nil, case .s(let plotVal) = plotAttr {
+                plot = plotVal
+            }
+        }
+
+        self.info = Info(rating: rating, plot: plot)
+    }
+    // snippet-end:[ddb.swift.batchgetitem.movie.init-withitem]
+
+    // snippet-start:[ddb.swift.batchgetitem.movie.getasitem]
+    ///
+    /// Return an array mapping attribute names to Amazon DynamoDB attribute
+    /// values, representing the contents of the `Movie` record as a DynamoDB
+    /// item.
+    ///
+    /// - Returns: The movie item as an array of type
+    ///   `[Swift.String:DynamoDBClientTypes.AttributeValue]`.
+    ///
+    func getAsItem() async throws -> [Swift.String:DynamoDBClientTypes.AttributeValue]  {
+        // Build the item record, starting with the year and title, which are
+        // always present.
+
+        var item: [Swift.String:DynamoDBClientTypes.AttributeValue] = [
+            "year": .n(String(self.year)),
+            "title": .s(self.title)
+        ]
+
+        // Add the `info` field with the rating and/or plot if they're
+        // available.
+
+        var info: [Swift.String:DynamoDBClientTypes.AttributeValue] = [:]
+        if self.info.rating != nil {
+            info["rating"] = .n(String(self.info.rating!))
+        }
+        if self.info.plot != nil {
+            info["plot"] = .s(self.info.plot!)
+        }
+        item["info"] = .m(info)
+
+        return item
+    }
+    // snippet-end:[ddb.swift.batchgetitem.movie.getasitem]
+}
+// snippet-end:[ddb.swift.batchgetitem.movie]