<commit_before>A `recover` expression let's you "lift" the reference capability of the result. A mutable reference capability (`iso`, `trn`, or `ref`) can become _any_ reference capability, and an immutable reference capability (`val` or `box`) can become any immutable or opaque reference capability.

# Why is this useful?

This most straightforward use of `recover` is to get an `iso` that you can pass to another actor. But it can be used for many other things as well, such as:

* Creating a cyclic immutable data structure. That is, you can create a complex mutable data structure inside a `recover` expression, "lift" the resulting `ref` to a `val`.
* "Borrow" an `iso` as a `ref`, do a series of complex mutable operations on it, and return it as an `iso` again.
* "Extract" a mutable field from an `iso` and return it as an `iso`.

# What does this look like?

```pony
recover Array[String] end
```

That's a simple one: it returns an `Array[String] iso`, instead of the usual `Array[String] ref` you would get.

Here's a more complicate example from the standard library:

```pony
recover
  var s = String((prec' + 1).max(width.max(31)))
  var value = x

  try
    if value == 0 then
      s.push(table(0))
    else
      while value != 0 do
        let index = (value = value / base) - (value * base)
        s.push(table(index))
      end
    end
  end

  s.append(typestring)<commit_msg>Grammar fix.<commit_after>A `recover` expression let's you "lift" the reference capability of the result. A mutable reference capability (`iso`, `trn`, or `ref`) can become _any_ reference capability, and an immutable reference capability (`val` or `box`) can become any immutable or opaque reference capability.

# Why is this useful?

This most straightforward use of `recover` is to get an `iso` that you can pass to another actor. But it can be used for many other things as well, such as:

* Creating a cyclic immutable data structure. That is, you can create a complex mutable data structure inside a `recover` expression, "lift" the resulting `ref` to a `val`.
* "Borrow" an `iso` as a `ref`, do a series of complex mutable operations on it, and return it as an `iso` again.
* "Extract" a mutable field from an `iso` and return it as an `iso`.

# What does this look like?

```pony
recover Array[String] end
```

That's a simple one: it returns an `Array[String] iso`, instead of the usual `Array[String] ref` you would get.

Here's a more complicated example from the standard library:

```pony
recover
  var s = String((prec' + 1).max(width.max(31)))
  var value = x

  try
    if value == 0 then
      s.push(table(0))
    else
      while value != 0 do
        let index = (value = value / base) - (value * base)
        s.push(table(index))
      end
    end
  end

  s.append(typestring)
{'fraction_non_alphanumeric': 0.0975, 'fraction_numerical': 0.004285714285714286, 'mean_word_length': 3.614497528830313, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4322671', 'n_tokens_mistral': 857, 'n_tokens_neox': 817, 'n_words': 412}