Handling plan function results

Each execution function, or a function you use to operate on one or more targets, returns a ResultSet. Each target you executed on returns a Result. The apply action returns a ResultSet containing ApplyResult objects.

You can iterate on an instance of ResultSet as if it were an Array[Variant[Result, ApplyResult]]. This means iterative functions like each, map, reduce, or filter work directly on the ResultSet returning each result.

A ResultSet may contain these functions:

Function	Definition
`names()`	Names all targets in the set as an `Array`.
`empty()`	Returns `Boolean` if the execution result set is empty.
`count()`	Returns an `Integer` count of targets.
`first()`	Specifies the first `Result` object, useful to unwrap single results.
`find(String $target_name)`	Specifies the `Result` for a specific target.
`error_set()`	Returns a `ResultSet` containing only the results of failed targets.
`ok_set()`	Returns a `ResultSet` containing only the successful results.
`filter_set(block)`	Filters a `ResultSet` with the given block and returns a `ResultSet` object (where the filter function returns an array or hash).
`targets()`	Specifies an array of all the `Target` objects from every `Result` in the set.
`ok()`	Specifies a `Boolean` that is the same as `error_set.empty`.
`to_data()`	Returns an array of hashes representing either `Result` or `ApplyResults`.

A Result may contain these functions:

Function	Definition
`value()`	Specifies the hash containing the value of the `Result`.
`target()`	Specifies the `Target` object that the `Result` is from.
`error()`	Returns an `Error` object constructed from the `_error` in the value.
`message()`	Specifies the `_output` key from the value.
`ok()`	Returns `true` if the `Result` was successful.
`[]`	Accesses the value hash directly.
`to_data()`	Returns a hash representation of `Result`.
`action()`	Returns a string representation of result type (task, command, etc.).

An ApplyResult may contain these functions.

Function	Definition
`report()`	Returns the hash containing the Puppet report from the application.
`target()`	Returns the `Target` object that the `Result` is from.
`error()`	Returnsn `Error` object constructed from the `_error` in the value.
`ok()`	Returns `true` if the `Result` was successful.
`to_data()`	Returns a hash representation of `ApplyResult`.
`action()`	Returns a string representation of result type (apply).

For example, to check if a task ran correctly on all targets, and the check fails if the task fails:

$r = run_task('sometask', ..., '_catch_errors' => true)
unless $r.ok {
  fail("Running sometask failed on the targets ${r.error_set.names}")
}

You can do iteration and check if the result is an error. This example outputs feedback about the result of a task.

$r = run_task('sometask', ..., '_catch_errors' => true)
$r.each |$result| {
  $target = $result.target.name
  if $result.ok {
    out::message("${target} returned a value: ${result.value}")
  } else {
    out::message("${target} errored with a message: ${result.error.message}")
  }
}

Similarly, you can iterate over the array of hashes returned by calling to_data on a ResultSet and access hash values. For example,

$r = run_command('whoami')
$r.to_data.each |$result_hash| { notice($result_hash['result']['stdout']) }

You can also use filter_set to filter a ResultSet and apply a ResultSet function such as targets to the output:

$filtered = $result.filter_set |$r| {
  $r['tag'] == "you're it"
}.targets