Bracket docs #1134
Bracket docs #1134
Conversation
JorgeCastilloPrz
requested review from
raulraja,
pakoito,
Tylos and
nomisRev
Codecov Report
@@ Coverage Diff @@
## master #1134 +/- ##
============================================
- Coverage 42.78% 42.77% -0.01%
Complexity 813 813
============================================
Files 400 400
Lines 11000 11000
Branches 1256 1256
============================================
- Hits 4706 4705 -1
Misses 5927 5927
- Partials 367 368 +1
Continue to review full report at Codecov.
|
| ```kotlin:ank | ||
| import arrow.effects.IO | ||
|
|
||
| openFile("data.json").bracket(release = { closeFile(it) }) { file -> |
There was a problem hiding this comment.
Nitpick: use named lambdas for both functions
|
|
||
| The `Bracket` Type class abstracts the ability to safely **acquire**, **use**, and then **release** a resource. | ||
|
|
||
| Essentially, it could be considered the functional programming equivalent to the well known imperative |
There was a problem hiding this comment.
Something worth noticing here is that Bracket, unlike try/catch/finally works in all contexts when powered with an async capable data type such as Deferred, Observable or IO. Since it targets Kinds and not just the current thread environment like try/catch/finallydo, it can be relied upon with the same semantics in synchronous and async computations.
There was a problem hiding this comment.
Fixed. I've just added an additional example clarifying that and showcasing a polymorphic program using Bracket<F, Throwable> as a constraint, and running over the 3 mentioned data types.
| It ensures that the acquired resource is released at the end after using it, **even if the using action throws an error**. | ||
| That ensures that no errors are swallowed. | ||
|
|
||
| Another key point of `Bracket` would be the ability to abstract over whether the resource is going to be used |
There was a problem hiding this comment.
I guess this is in line with my point above but it does not spread the gospel comparing it to try/catch/finally and showing how it's a superior abstraction
There was a problem hiding this comment.
Fixed, explained above.
|
|
||
| `fun <A, B> Kind<F, A>.bracketCase(release: (A, ExitCase<Throwable>) -> Kind<F, Unit>, use: (A) -> Kind<F, B>): Kind<F, B>` | ||
|
|
||
| ```kotlin:ank |
There was a problem hiding this comment.
Can we make all these snippets executable like in the AQL docs, please? These are API examples more than a tutorial and as a user I'd like to play with it right in the browser
There was a problem hiding this comment.
Sure, I'll take a look tomorrow. Leaving now!
There was a problem hiding this comment.
@raulraja is there a policy about which snippets should be executable? Should we aim for as much as possible executable snippets?
|
Yes but this should work because try arrow is supposed to pull the latest snapshot out of master. Which means that once you run the snippets in the live site they will work since try arrow is supposed to automatically deploy the latest snapshot |
|
I think the problem is not related with the Arrow version, but with some changes needed to be made on the compiler config as the error some of those snippets are facing is the following:
|
fixes #1129