/*---------------------------------------------------------------------------
  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 487 : exnstd/core/exn/exn: (E, V) -> V aa: V
  throwstd/core/exn/throw: (message : string, info : ? exception-info) -> exn $435(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 430 : exnstd/core/exn/exn: (E, V) -> V aa: V
  throw-exnstd/core/exn/throw-exn: (exn : exception) -> exn $406(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-exit` when appropriate.
pub fun handle/trystd/core/exn/handle/try: forall<a,e> (hndl : (exception) -> e a, action : () -> <exn|e> a) -> e a( hndlhndl: (exception) -> $581 $580: exceptionstd/core/exn/exception: V -> ee: E aa: V, actionaction: () -> <exn|$581> $580 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V )result: -> 667 666 : ee: E aa: V
  withwith: () -> <exn|$581> $580 final ctl throw-exnhandler: (() -> <exn|$581> $580) -> $581 $580(exnexn: exception) hndlhndl: (exception) -> $581 $580(exnexn: exception)
  actionaction: () -> <exn|$581> $580()

// _deprecated_. Catch an exception raised by `throw` and handle it.
pub fun catchstd/core/exn/catch: forall<a,e> (hndl : (exception) -> e a, action : () -> <exn|e> a) -> e a(hndlhndl: (exception) -> $729 $728: exceptionstd/core/exn/exception: V -> ee: E aa: V, actionaction: () -> <exn|$729> $728 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V)result: -> 752 751 : ee: E aa: V
  trystd/core/exn/handle/try: (hndl : (exception) -> $729 $728, action : () -> <exn|$729> $728) -> $729 $728(hndlhndl: (exception) -> $729 $728,actionaction: () -> <exn|$729> $728)

// An `:error<a>` type represents a first-class exception result as a `:result<a,exception>`.
pub alias errorstd/core/exn/error: V -> V<aa: V> = resultstd/core/types/result: (V, V) -> V<aa: V,exceptionstd/core/exn/exception: V>

// Transform an exception effect to an  `:error` type.
pub fun error/trystd/core/exn/error/try: forall<a,e> (action : () -> <exn|e> a) -> e error<a>( actionaction: () -> <exn|$675> $674 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V )result: -> 721 error<720> : ee: E errorstd/core/exn/error: V -> V<aa: V>
  withwith: () -> <exn|$675> result<$674,exception> trystd/core/exn/handle/try: (hndl : (exception) -> $675 error<$674>, action : () -> <exn|$675> error<$674>) -> $675 error<$674> fnfn: (exn : exception) -> $675 result<$674,exception>(exnexn: exception)
    Errorstd/core/types/Error: forall<a,b> (error : b) -> result<a,b>(exnexn: exception) 
  Okstd/core/types/Ok: forall<a,b> (value : a) -> result<a,b>(actionaction: () -> <exn|$675> $674())

// Transform an exception result type back to an `exn` effect (by throwing on an `Error`)
pub fun untrystd/core/exn/untry: forall<a> (err : error<a>) -> exn a( errerr: error<$759> : errorstd/core/exn/error: V -> V<aa: V> )result: -> exn 789 : exnstd/core/exn/exn: (E, V) -> V aa: V
  match errerr: error<$759>
    Errorstd/core/types/Error: forall<a,b> (error : b) -> result<a,b>(exnexn: exception) -> throw-exnstd/core/exn/throw-exn: (exn : exception) -> exn $759(exnexn: exception)
    Okstd/core/types/Ok: forall<a,b> (value : a) -> result<a,b>(xx: $759)      -> xx: $759

pub fun error/mapstd/core/exn/error/map: forall<a,b,e> (err : error<a>, f : (a) -> e b) -> e error<b>( errerr: error<$794> : errorstd/core/exn/error: V -> V<aa: V>, ff: ($794) -> $796 $795 : aa: V -> ee: E bb: V )result: -> 850 error<849> : ee: E errorstd/core/exn/error: V -> V<bb: V>
  match errerr: error<$794>
    Errorstd/core/types/Error: forall<a,b> (error : b) -> result<a,b>(exnexn: exception) -> Errorstd/core/types/Error: forall<a,b> (error : b) -> result<a,b>(exnexn: exception)
    Okstd/core/types/Ok: forall<a,b> (value : a) -> result<a,b>(xx: $794)      -> Okstd/core/types/Ok: forall<a,b> (value : a) -> result<a,b>(ff: ($794) -> $796 $795(xx: $794))

// 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: () -> $861 () : () -> ee: E (std/core/types/unit: V)std/core/types/unit: V, actionaction: () -> $861 $860 : () -> ee: E aa: V )result: -> 882 881 : ee: E aa: V
  finallystd/core/hnd/finally: (fin : () -> $861 (), action : () -> $861 $860) -> $861 $860(hndlerhndler: () -> $861 (),actionaction: () -> $861 $860)

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

// Prepend `exn`'s message with `pre`.
pub fun prependstd/core/exn/prepend: (exn : exception, pre : string) -> exception( exnexn: exception : exceptionstd/core/exn/exception: V, prepre: string : stringstd/core/types/string: V )result: -> total exception : exceptionstd/core/exn/exception: V
  Exceptionstd/core/exn/Exception: (message : string, info : exception-info) -> exception(prepre: string ++std/core/types/(++): (x : string, y : string) -> string ": "literal: string
count= 2 ++std/core/types/(++): (x : string, y : string) -> string exnexn: exception.messagestd/core/exn/exception/message: (exception : exception) -> string, exnexn: exception.infostd/core/exn/exception/info: (exception : exception) -> exception-info)

pub fun try-exn-prependstd/core/exn/try-exn-prepend: forall<a,e> (pre : string, action : () -> <exn|e> a) -> <exn|e> a( prepre: string : stringstd/core/types/string: V, actionaction: () -> <exn|$1073> $1072 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V)result: -> <exn|1101> 1100 : <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V
  try-exn-mapstd/core/exn/try-exn-map: (f : (exception) -> exception, action : () -> <exn|$1073> $1072) -> <exn|$1073> $1072( fnfn: (exn : exception) -> exception(exnexn: exception) exnexn: exception.prependstd/core/exn/prepend: (exn : exception, pre : string) -> exception(prepre: string), actionaction: () -> <exn|$1073> $1072 )

pub fun try-exn-mapstd/core/exn/try-exn-map: forall<a,e> (f : (exception) -> exception, action : () -> <exn|e> a) -> <exn|e> a( ff: (exception) -> exception : exceptionstd/core/exn/exception: V -> exceptionstd/core/exn/exception: V, actionaction: () -> <exn|$951> $950 : () -> <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V)result: -> <exn|1065> 1064 : <exnstd/core/exn/exn: (E, V) -> V|std/core/types/effect-extend: (X, E) -> Eee: E> aa: V
  withwith: () -> <exn|$951> $950 overridehandler: (() -> <exn,exn|$951> $950) -> <exn|$951> $950 final ctl throw-exnthrow-exn: (exn : exception) -> <exn|$951> $950(exnexn: exception)
    ff: (exception) -> <exn|$951> exception(exnexn: exception).throw-exnstd/core/exn/throw-exn: (exn : exception) -> <exn|$951> $950
  actionaction: () -> <exn|$951> $950()