https://github.com/arnetheduck/nim-results

Friendly value-or-error type
https://github.com/arnetheduck/nim-results

error-handling nim result

Last synced: 26 days ago
JSON representation

Friendly value-or-error type

• Host: GitHub
• URL: https://github.com/arnetheduck/nim-results
• Owner: arnetheduck
• License: other
• Created: 2018-05-20T03:44:24.000Z (over 6 years ago)
• Default Branch: master
• Last Pushed: 2024-08-22T07:56:43.000Z (3 months ago)
• Last Synced: 2024-10-10T20:05:59.519Z (29 days ago)
• Topics: error-handling, nim, result
• Language: Nim
• Homepage:
• Size: 135 KB
• Stars: 147
• Watchers: 7
• Forks: 10
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • License: LICENSE-APACHEv2

Awesome Lists containing this project

• awesome-nim - result - Friendly, exception-free value-or-error returns, similar to Option[T]. (Language Features / Error Handling)

README

        
# Introduction

Result type that can hold either a value or an error, but not both

## Usage

Add the following to your `.nimble` file:

```

requires "results"

```

or just drop the file in your project!

## Example

```nim

import results

# Re-export `results` so that API is always available to users of your module!

export results

# It's convenient to create an alias - most likely, you'll do just fine

# with strings or cstrings as error for a start

type R = Result[int, string]

# Once you have a type, use `ok` and `err`:

func works(): R =

  # ok says it went... ok!

  R.ok 42

func fails(): R =

  # or type it like this, to not repeat the type:

  result.err "bad luck"

func alsoWorks(): R =

  # or just use the shortcut - auto-deduced from the return type!

  ok(24)

if (let w = works(); w.isOk):

  echo w[], " or use value: ", w.value

# In case you think your callers want to differentiate between errors:

type

  Error = enum

    a, b, c

  type RE[T] = Result[T, Error]

# You can use the question mark operator to pass errors up the call stack

func f(): R =

  let x = ?works() - ?fails()

  assert false, "will never reach"

# If you provide this exception converter, this exception will be raised on

# `tryGet`:

func toException(v: Error): ref CatchableError = (ref CatchableError)(msg: $v)

try:

  RE[int].err(a).tryGet()

except CatchableError:

  echo "in here!"

# You can use `Opt[T]` as a replacement for `Option` = `Opt` is an alias for

# `Result[T, void]`, meaning you can use the full `Result` API on it:

let x = Opt[int].ok(42)

echo x.get()

# ... or `Result[void, E]` as a replacement for `bool`, providing extra error

# information!

let y = Result[void, string].err("computation failed")

echo y.error()

```

See [results.nim](./results.nim) for more in-depth documentation - specially

towards the end where there are plenty of examples!

## License

MIT license, just like Nim, or Apache, if you prefer that