stx_fail

Usage

The convenience functions for this library are found in stx_nano as that library introduces the wildcard system.

  using stx.Pico;//Wildcard 
  using stx.Fail;
  function method(){
    final fault = __.f
    final error : Error<String> = __.fault().of("my error");
    trace(error.blame)//List({value: 'my error',pos : ${pos}});
  }

see more detail

How Does it Work?

This library distinguishes between three sorts of error:

digest -> Fatal errors meant to report to the user/developer
ingest -> To pattern match from supersystems except -> Specified Haxe exceptions.

stx.fail.Blame.BlameDef

typedef BlameDef<E> = {
  /** Typed value  */
  public final ?value   : E;
  /** label */
  public final ?label   : String;
  /** Underlying exception, if it exists */
  public final ?crack   : Exception;  
  /** Error number to pass up to sys, or httpCode */
  public final ?canon   : Int;
  /** Captured location, if available. */
  public final ?loc     : Loc;
}

concat

Concat allows you to accumulate errors in order.

final a : Error<String> = __.fault().of("first error");
final b : Error<String> = __.fault().of("second error");
final c : Error<String> = a.concat(b);//{ blame : List(a,b) }

loc

Loc contains various ways of showing location information.

Detailed Usage

  using stx.Pico;
  /**
    switch over errors 
  **/
  enum ErrorVal{
    E_SomeError;
    E_SomeOther_Error;
  }
  /**
    switch over errors containing subsystem error
  **/
  enum SuperErrorVal{
    E_SuperError;
    E_SubsytemError(v:ErrorVal);
  }
  static function main(){
    //                v--`haxe.PosInfos` injected here as `stx.Loc`
    var e0 = __.fault( ).of(E_SomeError);//Error<ErrorVal>
    var e1 = __.fault( ).of(E_SomeOtherError);//Error<ErrorVal>

    var e2 = e0.concat(e1);//both of these errors now available downstream.
    var e3 = __.fault().digest(d -> e_resource_not_found());//Error<Unknown>;

    var e4 = e2.concat(e3);//Type compatible

    var e5 = __.fault().of(E_SuperError);

    var report0 = Report.pure(e4);//Report<ErrorVal>
    var report1 = Report.pure(e5);//Report<SuperErrorVal>

    var report2 = report0.errata(E_SubsystemError);//Report<SuperErrorVal>

    var report3 = report1.concat(report2);

    if(!report3.ok()){
      report3.crack();//throws if defined
    }
  }

see here for Wildcard methods

Difficult Type Compositions.

If there's issues of error values being impossible to pass because of complicated type relations, you can provide a stash for the error to use to elide the type variable for reconstruction later.

Constructors

@see stx.fail.Error.ErrorCtr for details

using stx.Error;
function use(){
final ctr = ErrorCtr.instance;
}

public inline function Make<E>(blame:CTR<BlameCtr,() -> Complaint<E>>):Error<E>;
//Typed Error
public inline function Value<E>(value:E,?loc:CTR<LocCtr,Loc>):Error<E>;
//Untyped Error
public inline function Label<E>(label:String,?loc:CTR<LocCtr,Loc>):Error<E>;
//Lazy Exception
public inline function Crack<E>(crack:() -> Exception,?loc:CTR<LocCtr,Loc>):Error<E>;
//Process return Value
public inline function Canon<E>(canon:Int,?loc:CTR<LocCtr,Loc>):Error<E>;
public inline function Unit<E>():Error<E>;
//Transport Error type incognito
public inline function Stash<E,EE>(self:Error<E>,stash:Stash<Blame<E>>):Error<EE>;
//Framework errors
public inline function Digest<E>(l : DigestCls):Error<E>;
//Typed, with a label.
public inline function Ingest<E>(l : Ingest<E>):Error<E>;

Functional Errors

In functional programming, it is common to consider an error part of a return type and pass it along, rather than to throw it.

This is particularly useful in multithreaded environments where it is necessary to make sure the error makes it back to the main thread to be reported correctly.

In the stx libraries, the Error type value is denoted E and each library has it's own enumeration found in stx.fail.${LIBRARY_NAME}Failure.

How to use Digest

using stx.Pico;
using stx.Fail;

using MyDigest;

//extend DigestCls
class MyDigest extends{
  public function new(?loc:Loc){
    super(UUid.of("unique_string_here"),"My sort of error",pos,-1);
  }
  //Use the `Digests` static extention
  static public function e_my_digest<E>(self:Digests):CTR<Loc,Digest>{
    return (loc:Loc) -> new MyDigest(pos);
  }
}
function use(){
  final my_digest_error = __.fault().digest((d:Digests) -> d.e_my_digest());
}