# Capture

Capture values while matching templates.

Using an instance of this class within a Matcher will capture the matching value.
The `as*()` APIs on the instance can be used to get the captured value.

Extends: [Matcher](/cdk/api/v2/docs/aws-cdk-lib.assertions.Matcher.html) › Capture

- Source: [`matching/lib/capture.ts`](https://github.com/aws/aws-cdk/blob/v2.277.0/packages/aws-cdk-lib/matching/lib/capture.ts#L12)
- Type last changed: v2.1.0 · 8 Dec 2021

## Example

TypeScript:

```ts
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Flob",
//       }
//     },
//     "MyBaz": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Quib",
//       }
//     }
//   }
// }

const fredCapture = new Capture();
template.hasResourceProperties('Foo::Bar', {
  Fred: fredCapture,
});

fredCapture.asString(); // returns "Flob"
fredCapture.next();     // returns true
fredCapture.asString(); // returns "Quib"
```

Python:

```python
# Given a template -
# {
#   "Resources": {
#     "MyBar": {
#       "Type": "Foo::Bar",
#       "Properties": {
#         "Fred": "Flob",
#       }
#     },
#     "MyBaz": {
#       "Type": "Foo::Bar",
#       "Properties": {
#         "Fred": "Quib",
#       }
#     }
#   }
# }

fred_capture = Capture()
template.has_resource_properties("Foo::Bar", {
    "Fred": fred_capture
})

fred_capture.as_string() # returns "Flob"
fred_capture.next() # returns true
fred_capture.as_string()
```

Java:

```java
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Flob",
//       }
//     },
//     "MyBaz": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Quib",
//       }
//     }
//   }
// }

Capture fredCapture = new Capture();
template.hasResourceProperties("Foo::Bar", Map.of(
        "Fred", fredCapture));

fredCapture.asString(); // returns "Flob"
fredCapture.next(); // returns true
fredCapture.asString();
```

C# / .NET:

```csharp
// Install: dotnet add package Amazon.CDK.Lib
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Flob",
//       }
//     },
//     "MyBaz": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Quib",
//       }
//     }
//   }
// }

var fredCapture = new Capture();
template.HasResourceProperties("Foo::Bar", new Dictionary<string, Capture> {
    { "Fred", fredCapture }
});

fredCapture.AsString(); // returns "Flob"
fredCapture.Next(); // returns true
fredCapture.AsString();
```

Golang:

```go
// Install: go get github.com/aws/aws-cdk-go/awscdk/v2
// Given a template -
// {
//   "Resources": {
//     "MyBar": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Flob",
//       }
//     },
//     "MyBaz": {
//       "Type": "Foo::Bar",
//       "Properties": {
//         "Fred": "Quib",
//       }
//     }
//   }
// }

fredCapture := awscdk.NewCapture()
template.HasResourceProperties(jsii.String("Foo::Bar"), map[string]Capture{
	"Fred": fredCapture,
})

fredCapture.AsString() // returns "Flob"
fredCapture.Next() // returns true
fredCapture.AsString()
```

## Initializer

TypeScript:

```ts
new Capture(pattern?: any)
```

Python:

```python
Capture(pattern: typing.Optional[Any] = None)
```

Java:

```java
new Capture(Object pattern)
```

C# / .NET:

```csharp
new Capture(object? pattern = null)
```

Golang:

```go
NewCapture(Pattern interface{})
```

## Properties

- `name`: string — A name for the matcher.

  This is collected as part of the result and may be presented to the user.

## Methods

- `asArray(): any[]` — Retrieve the captured value as an array.

  An error is generated if no value is captured or if the value is not an array.

- `asBoolean(): boolean` — Retrieve the captured value as a boolean.

  An error is generated if no value is captured or if the value is not a boolean.

- `asNumber(): number` — Retrieve the captured value as a number.

  An error is generated if no value is captured or if the value is not a number.

- `asObject(): { [key: string]: any }` — Retrieve the captured value as a JSON object.

  An error is generated if no value is captured or if the value is not an object.

- `asString(): string` — Retrieve the captured value as a string.

  An error is generated if no value is captured or if the value is not a string.

- `isMatcher(x: any): boolean` (static) — Check whether the provided object is a subtype of the `IMatcher`.

- `next(): boolean` — When multiple results are captured, move the iterator to the next result.

  **Returns:** true if another capture is present, false otherwise

- `test(actual: any): MatchResult` — Test whether a target matches the provided pattern.

  Every Matcher must implement this method.
  This method will be invoked by the assertions framework. Do not call this method directly.
