/*---------------------------------------------------------------------------
  Copyright 2012-2024, Microsoft Research, Daan Leijen.

  This is free software; you can redistribute it and/or modify it under the
  terms of the Apache License, Version 2.0. A copy of the License can be
  found in the LICENSE file at the root of this distribution.
---------------------------------------------------------------------------*/

// Standard exception (`:exn`) effect.
module std/core/exnstd/core/exn

import std/core/typesstd/core/types
import std/core/hndstd/core/hnd

extern import
  c  file "inline/exn"
  js file "inline/exn.js"


// Exceptions
pubstd/core/exn/exn: (E, V) -> V effect exnstd/core/exn/exn: (E, V) -> V
  // Throw an exception
  final ctl throw-exn( exnexn: exception : exceptionstd/core/exn/exception: V ) : aa: V

// Raise a pattern match exception. This is function is used internally by the
// compiler to generate error messages on pattern match failures.
pub fun error-patternstd/core/exn/error-pattern: forall<a> (location : string, definition : string) -> exn a(locationlocation: string : stringstd/core/types/string: V, definitiondefinition: string : stringstd/core/types/string: V)result: -> exn 820 : exnstd/core/exn/exn: (E, V) -> V aa: V
  throwstd/core/exn/throw: (message : string, info : ? exception-info) -> exn $764(locationlocation: string ++std/core/types/(++): (x : string, y : string) -> exn string ": "literal: string
count= 2 ++std/core/types/(++): (x : string, y : string) -> exn string definitiondefinition: string ++std/core/types/(++): (x : string, y : string) -> exn string ": pattern match failure"literal: string
count= 23,
         ExnPatternstd/core/exn/ExnPattern: (location : string, definition : string) -> exception-info(locationlocation: string,definitiondefinition: string))

// The exception data type
pub value struct exceptionstd/core/exn/exception: V( messagestd/core/exn/exception/message: (exception : exception) -> string :stringstd/core/types/string: V, infostd/core/exn/exception/info: (exception : exception) -> exception-info :exception-infostd/core/exn/exception-info: V )

// Exception information
pub open type exception-infostd/core/exn/exception-info: V
  ExnErrorstd/core/exn/ExnError: exception-info      // Generic error
  ExnAssertstd/core/exn/ExnAssert: exception-info
  ExnTodostd/core/exn/ExnTodo: exception-info
  ExnRangestd/core/exn/ExnRange: exception-info
  ExnPatternstd/core/exn/ExnPattern: (location : string, definition : string) -> exception-info( location : stringstd/core/types/string: V, definition : stringstd/core/types/string: V )
  ExnSystemstd/core/exn/ExnSystem: (errno : int) -> exception-info( errno : intstd/core/types/int: V )
  ExnInternalstd/core/exn/ExnInternal: (name : string) -> exception-info( name : stringstd/core/types/string: V )

// Show the exception message
pub fun showstd/core/exn/show: (exn : exception) -> string( exnexn: exception : exceptionstd/core/exn/exception: V )result: -> total string : stringstd/core/types/string: V
  exnexn: exception.messagestd/core/exn/exception/message: (exception : exception) -> string

// Throw an exception with a specified message.
pub fun throwstd/core/exn/throw: forall<a> (message : string, info : ? exception-info) -> exn a( messagemessage: string: stringstd/core/types/string: V, infoinfo: ? exception-info : exception-infostd/core/exn/exception-info: V = ExnErrorstd/core/exn/ExnError: exception-info )result: -> exn 759 : exnstd/core/exn/exn: (E, V) -> V aa: V
  throw-exnstd/core/exn/throw-exn: (exn : exception) -> exn $739(Exceptionstd/core/exn/Exception: (message : string, info : exception-info) -> exception(messagemessage: string,infoinfo: exception-info))

// Catch any exception raised in `action` and handle it.
// Use `on-exn` or `on-exit` when appropriate.
pub fun exn/trystd/core/exn/exn/try: forall<a,e> (action : () -> <exn|e> a, hndl : (exception) -> e a) -> e a( actionaction: () -> <exn|$587> $586 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V, hndlhndl: (exception) -> $587 $586: exceptionstd/core/exn/exception: V -> ee: E aa: V )result: -> 662 661 : ee: E aa: V
  withhandler: (() -> <exn|$587> $586) -> $587 $586 final ctl throw-exnthrow-exn: (exn : exception) -> $587 $586(exnexn: exception) hndlhndl: (exception) -> $587 $586(exnexn: exception)
  actionaction: () -> <exn|$587> $586()

// _Deprecated_; use `try` instead. Catch an exception raised by `throw` and handle it.
// Use `on-exn` or `on-exit` when appropriate.
pub fun catchstd/core/exn/catch: forall<a,e> (action : () -> <exn|e> a, hndl : (exception) -> e a) -> e a( actionaction: () -> <exn|$714> $713 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V, hndlhndl: (exception) -> $714 $713: exceptionstd/core/exn/exception: V -> ee: E aa: V)result: -> 732 731 : ee: E aa: V
  trystd/core/exn/exn/try: (action : () -> <exn|$714> $713, hndl : (exception) -> $714 $713) -> $714 $713(actionaction: () -> <exn|$714> $713,hndlhndl: (exception) -> $714 $713)

// An `:error` type represents a first-class exception result.
pub value type errorstd/core/exn/error: V -> V<aa: V>
  Errorstd/core/exn/Error: forall<a> (exception : exception) -> error<a>( exception : exceptionstd/core/exn/exception: V )
  Okstd/core/exn/Ok: forall<a> (result : a) -> error<a>( result : aa: V )

// Transform an exception effect to an  `:error` type.
pub fun trystd/core/exn/try: forall<a,e> (action : () -> <exn|e> a) -> e error<a>( actionaction: () -> <exn|$670> $669 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V )result: -> 702 error<701> : ee: E errorstd/core/exn/error: V -> V<aa: V>
  trystd/core/exn/exn/try: (action : () -> <exn|$670> error<$669>, hndl : (exception) -> $670 error<$669>) -> $670 error<$669>({ Okstd/core/exn/Ok: forall<a> (result : a) -> error<a>(actionaction: () -> <exn|$670> $669()) }, fnfn: (exn : exception) -> $670 error<$669>(exnexn: exception){ Errorstd/core/exn/Error: forall<a> (exception : exception) -> error<a>(exnexn: exception) })

// Transform an `:error` type back to an `exn` effect.
pub fun untrystd/core/exn/untry: forall<a> (err : error<a>) -> exn a( errerr: error<$825> : errorstd/core/exn/error: V -> V<aa: V> )result: -> exn 846 : exnstd/core/exn/exn: (E, V) -> V aa: V
  match errerr: error<$825>
    Errorstd/core/exn/Error: forall<a> (exception : exception) -> error<a>(exnexn: exception) -> throw-exnstd/core/exn/throw-exn: (exn : exception) -> exn $825(exnexn: exception)
    Okstd/core/exn/Ok: forall<a> (result : a) -> error<a>(xx: $825)      -> xx: $825

// Transform an `:error` type back to an `exn` effect.
pub fun exnstd/core/exn/exn: forall<a> (err : error<a>) -> exn a( errerr: error<$851> : errorstd/core/exn/error: V -> V<aa: V> )result: -> exn 863 : exnstd/core/exn/exn: (E, V) -> V aa: V
  untrystd/core/exn/untry: (err : error<$851>) -> exn $851(errerr: error<$851>)

// Use default value `def` in case of an error.
pub fun defaultstd/core/exn/default: forall<a> (t : error<a>, def : a) -> a( tt: error<$416> : errorstd/core/exn/error: V -> V<aa: V>, defdef: $416 : aa: V )result: -> total 431 : astd/core/types/total: E
  match tt: error<$416>
    Errorstd/core/exn/Error: forall<a> (exception : exception) -> error<a>  -> defdef: $416
    Okstd/core/exn/Ok: forall<a> (result : a) -> error<a>(xx: $416)  -> xx: $416

// Transform an `:error` type to a `:maybe` value.
pub fun maybestd/core/exn/maybe: forall<a> (t : error<a>) -> maybe<a>( tt: error<$474> : errorstd/core/exn/error: V -> V<aa: V> )result: -> total maybe<497> : maybestd/core/types/maybe: V -> V<aa: V>
  match tt: error<$474>
    Errorstd/core/exn/Error: forall<a> (exception : exception) -> error<a>  -> Nothingstd/core/types/Nothing: forall<a> maybe<a>
    Okstd/core/exn/Ok: forall<a> (result : a) -> error<a>(xx: $474)  -> Juststd/core/types/Just: forall<a> (value : a) -> maybe<a>(xx: $474)

// Transform an `:error` type to an `:either` value.
pub fun eitherstd/core/exn/either: forall<a> (t : error<a>) -> either<exception,a>( tt: error<$436> : errorstd/core/exn/error: V -> V<aa: V> )result: -> total either<exception,469> : eitherstd/core/types/either: (V, V) -> V<exceptionstd/core/exn/exception: V,aa: V>
  match tt: error<$436>
    Errorstd/core/exn/Error: forall<a> (exception : exception) -> error<a>(exnexn: exception) -> Leftstd/core/types/Left: forall<a,b> (left : a) -> either<a,b>(exnexn: exception)
    Okstd/core/exn/Ok: forall<a> (result : a) -> error<a>(xx: $436)      -> Rightstd/core/types/Right: forall<a,b> (right : b) -> either<a,b>(xx: $436)

/*
// Set a `hndler` that is called only when an exception is raised in the `action` block.
pub fun on-exn( hndler : exception -> <exn|e> (), action : () -> <exn|e> a ) : <exn|e> a
  // prim-try-some( action, fn(exn){ hndler(exn); throw(exn) })
  match mask<exn>{ try(action) }
    TryOk(x)    { x
    TryExn(exn) { hndler(exn); throw(exn)
*/

// Set a `hndler` that is always called when the `action` finishes (either normally or with an exception).
pub fun on-exitstd/core/exn/on-exit: forall<a,e> (hndler : () -> e (), action : () -> e a) -> e a( hndlerhndler: () -> $503 () : () -> ee: E (std/core/types/unit: V)std/core/types/unit: V, actionaction: () -> $503 $502 : () -> ee: E aa: V )result: -> 519 518 : ee: E aa: V
  finallystd/core/hnd/finally: (fin : () -> $503 (), action : () -> $503 $502) -> $503 $502(hndlerhndler: () -> $503 (),actionaction: () -> $503 $502)

pub fun exn-error-rangestd/core/exn/exn-error-range: forall<a> () -> exn a()result: -> exn 887 : exnstd/core/exn/exn: (E, V) -> V aa: V
  throwstd/core/exn/throw: (message : string, info : ? exception-info) -> exn $868("index out-of-range"literal: string
count= 18, ExnRangestd/core/exn/ExnRange: exception-info)


// // _Unsafe_. This function removes the exception effect (`:exn`) from the effect of an action
// pub fun unsafe-no-exn( action : () -> <exn|e> a ) : e a
//   unsafe-total( action )