Add `result.guard` and `option.guard` functions

[chuckberrypi]

I propose that there be result.guard and option.guard functions similar to bool.guard. I think these would be useful convenience functions and would provide a consistent api in the standard library. My proposed functions are:

fn option.guard(
  when requirement: Option(a),
  return consequence: b,
  otherwise alternative: fn(a) -> b,
) -> b {
  case requirement {
    Some(o) -> alternative(o)
    None -> consequence
  }
}

fn result.guard(
  when requirement: Result(a, b),
  return consequence: c,
  otherwise alternative: fn(a) -> c,
) -> b {
  case requirement {
    Ok(r) -> alternative(r)
    Error(_) -> consequence
  }
}

fn result.guard_map(
  when requirement: Result(a, b),
  return consequence: fn(b) -> c,
  otherwise alternative: fn(a) -> c,
) -> b {
  case requirement {
    Ok(r) -> alternative(r)
    Error(e) -> consequence(e)
  }
}

These functions would provide a consistent way of using the use syntax across bool, result, and option libraries, and allow clearer code when the function you are writing does not itself Return a result. For example:

fn handler(req: Request, ctx: Context, maybe_user: Option(User)) -> Response(String) {
  let unauthorized_request = Response("Not authorized")
  let internal_server_error = Response("Status 400")
  use user <- option.guard(maybe_user, unauthorized_request)
  let db_res = get_info_from_db(req, ctx) 
  use db_info <- result.guard(db_res, internal_server_error)
  Response("Successful response" <> user.name <> ": " <> db_info.success_message)
}

This is a familiar gleam pattern that is available from result.try, but works in situations where the function you are writing always returns a Response rather than a Result type.

[lpil]

Hello! These functions are very close to the result.try etc functions, and it seems they would encourage the check-and-assert antipattern, so it's not clear they belong in the standard library.

To evidence their value please gather a body of real-world code that demonstrates how these functions substantially improve the code in a way that the existing function cannot. Thank you

[yoshi-monster]

I think the labels are very confusing, I would expect the otherwise branch to be taken in the Error / None case, not on the happy path.

I use a similar function in crew to early-out return the next state in case one step of the pipeline fails:

fn on_message(state: State) -> actor.Next(State, Message) {
  // let next_state = case message { .... 

  use caller_pid <- result.guard(process.subject_owner(respond), or: state)
  use channel <- result.guard(dict.get(state.channels, receive), or: state)

  let channels = dict.delete(state.channels, receive)
 
  use caller <- result.guard(
    dict.get(state.callers, caller_pid),
    or: State(..state, channels:),
  )

  // ...

  actor.continue(next_state)
}

I can see how it would encourage bad patterns in http handlers though, as it makes early-returning responses instead of the recommended error pattern easier.

[shunjilin]

I have a use case which results in large nested case statements:

fn handle_create_board(
  board_registry: Subject(board_registry.Message),
  req: Request(Connection),
) -> Response(ResponseData) {
  case mist.read_body(req, 102_400) {
    Ok(req_with_body) -> {
      case parse_board_form(req_with_body.body, generate_board_id()) {
        Error(Nil) ->
          response.new(422)
          |> response.set_body(
            mist.Bytes(bytes_tree.from_string(
              "Failed to create board due to invalid input.",
            )),
          )
        Ok(board) -> {
          case board_registry.create_board(board_registry, board) {
            Ok(_) -> {
              response.new(303)
              |> response.set_header("location", "/board/" <> board.id(board))
              |> response.set_body(mist.Bytes(bytes_tree.new()))
            }
            Error(board_registry.BoardAlreadyExist) -> {
              response.new(409)
              |> response.set_body(
                mist.Bytes(bytes_tree.from_string(
                  "Failed to create board as it already exists.",
                )),
              )
            }
          }
        }
      }
    }
    Error(error) -> {
      case error {
        mist.ExcessBody -> {
          response.new(413)
          |> response.set_body(
            mist.Bytes(bytes_tree.from_string("Request body too large.")),
          )
        }
        mist.MalformedBody -> {
          response.new(400)
          |> response.set_body(
            mist.Bytes(bytes_tree.from_string("Malformed request body.")),
          )
        }
      }
    }
  }
}

I can see how it would encourage bad patterns in http handlers though, as it makes early-returning responses instead of the recommended error pattern easier.

In my example, I could also be tempted to early return by using catch all Error(_) instead of handling errors explicitly, so I am not sure if the added API will encourage more bad patterns. However I do see the concern that maybe the example function design is bad, and that it may be preferably to only have the function return something like Result(Board, CreateBoardFailure), and pipe this into a separate function that converts the result into an appropriate response in a single case statement?