kotlin-result/README.md

83 lines
3.5 KiB
Markdown
Raw Normal View History

2017-10-21 16:44:55 +00:00
# kotlin-result
2017-10-22 00:12:50 +00:00
[![Release](https://jitpack.io/v/michaelbull/kotlin-result.svg)](https://jitpack.io/#michaelbull/kotlin-result) [![Build Status](https://travis-ci.org/michaelbull/kotlin-result.svg?branch=master)](https://travis-ci.org/michaelbull/kotlin-result) [![License](https://img.shields.io/github/license/michaelbull/kotlin-result.svg)](https://github.com/michaelbull/kotlin-result/blob/master/LICENSE)
2017-10-21 23:59:16 +00:00
2017-10-21 21:07:07 +00:00
[`Result<V, E>`][result] is a monad for modelling success ([`Ok`][result-ok]) or
failure ([`Err`][result-err]) operations.
2017-10-21 16:44:55 +00:00
## Inspiration
Inspiration for this library has been drawn from other languages in which the
Result monad is present, including:
- [Elm](http://package.elm-lang.org/packages/elm-lang/core/latest/Result)
- [Haskell](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html)
- [Rust](https://doc.rust-lang.org/std/result/)
2017-10-21 18:44:58 +00:00
It also iterates on other Result libraries written in Kotlin, namely:
2017-10-21 16:44:55 +00:00
2017-10-21 18:44:58 +00:00
- [danneu/kotlin-result](https://github.com/danneu/kotlin-result)
- [kittinunf/Result](https://github.com/kittinunf/Result)
- [npryce/result4k](https://github.com/npryce/result4k)
2017-10-21 16:44:55 +00:00
Improvements on the existing solutions include:
2017-10-21 21:33:59 +00:00
- Feature parity with Result types from other languages including Elm, Haskell,
& Rust
2017-12-16 22:34:06 +00:00
- [Multiplatform][multiplatform] project support
2017-10-21 18:44:58 +00:00
- Lax constraints on `value`/`error` nullability
2017-10-21 18:46:14 +00:00
- Lax constraints on the `error` type's inheritance (does not inherit from
2017-10-21 18:46:44 +00:00
`Exception`)
- Top level `Ok` and `Err` classes avoids qualifying usages with
`Result.Ok`/`Result.Err` respectively
2017-10-21 16:44:55 +00:00
- Higher-order functions marked with the `inline` keyword for reduced runtime
overhead
- Extension functions on `Iterable` & `List` for folding, combining, partitioning
- Consistent naming with existing Result libraries from other languages (e.g.
`map`, `mapError`, `mapBoth`, `mapEither`, `and`, `andThen`, `or`, `orElse`,
`unwrap`)
2017-10-22 00:14:01 +00:00
- Extensive test suite with over 50 unit tests covering every library method
2017-10-21 16:44:55 +00:00
## Installation
```groovy
repositories {
2017-10-21 23:59:16 +00:00
maven { url "https://jitpack.io" }
2017-10-21 16:44:55 +00:00
}
dependencies {
2018-01-10 17:44:12 +00:00
compile 'com.github.michaelbull:kotlin-result:1.0.6'
2017-10-21 16:44:55 +00:00
}
```
2017-10-21 18:44:58 +00:00
## Getting Started
The [unit tests][unit-tests] are a good source of examples for using the library
2017-10-21 21:07:07 +00:00
as they cover every available method.
2017-10-21 18:44:58 +00:00
Mappings from common Result libraries are available on the [wiki][wiki]:
- [Elm][wiki-elm]
- [Haskell][wiki-haskell]
- [Rust][wiki-rust]
2017-10-21 19:03:51 +00:00
## Contributing
Bug reports and pull requests are welcome on [GitHub][github].
## License
This project is available under the terms of the ISC license. See the
[`LICENSE`](LICENSE) file for the copyright information and licensing terms.
2017-10-22 00:02:27 +00:00
[result]: https://github.com/michaelbull/kotlin-result/blob/master/src/main/kotlin/com/github/michaelbull/result/Result.kt#L10
2017-10-22 14:31:54 +00:00
[result-ok]: https://github.com/michaelbull/kotlin-result/blob/master/src/main/kotlin/com/github/michaelbull/result/Result.kt#L27
[result-err]: https://github.com/michaelbull/kotlin-result/blob/master/src/main/kotlin/com/github/michaelbull/result/Result.kt#L28
2017-12-16 22:34:06 +00:00
[multiplatform]: https://kotlinlang.org/docs/reference/multiplatform.html
2017-10-22 00:02:27 +00:00
[unit-tests]: https://github.com/michaelbull/kotlin-result/tree/master/src/test/kotlin/com/github/michaelbull/result
2017-10-21 18:44:58 +00:00
[wiki]: https://github.com/michaelbull/kotlin-result/wiki
[wiki-elm]: https://github.com/michaelbull/kotlin-result/wiki/Elm
[wiki-haskell]: https://github.com/michaelbull/kotlin-result/wiki/Haskell
[wiki-rust]: https://github.com/michaelbull/kotlin-result/wiki/Rust
2017-10-21 19:03:51 +00:00
[github]: https://github.com/michaelbull/kotlin-result