xyerror

README

Introduction

Package xyerror supports to define and compare errors conveniently.

The error is inspired by Python Exception.

Features

Package xyerror defined an error type used to create other errors called Exception, it is equivalent to Exception class in Python.

Exception creates Error objects by using New or Newf method. It looks like Exception class creates Exception instances. Example:

// xyerror
var err xyerror.Error = xyerror.ValueError.New("value is invalid")
fmt.Println(err)

# python
print(ValueError("value is invalid"))

An Exception can "inherits" from another Exception. Example:

// xyerror
var ZeroDivisionError = xyerror.ValueError.NewException("ZeroDivisionError")
fmt.Println(ZeroDivisionError.New("do not divide by zero"))

# python
class ZeroDivisionError(ValueError):
    ...
print(ZeroDivisionError("do not divide by zero"))

An Exception also "inherits" from many Exception instances. Example:

// xyerror
var ValueTypeError = xyerror.
    Combine(xyerror.ValueError, xyerror.TypeError).
    NewException("ValueTypeError")

# python
class ValueTypeError(ValueError, TypeError):
    ...

An Error created by an Exception can compare to that Exception.

// xyerror
func foo() error {
    return xyerror.ValueError.New("value is invalid")
}

func bar() error {
    if err := foo(); errors.Is(err, xyerror.ValueError) {
        fmt.Println(err)
    } else {
        return err
    }
    return nil
}

# python
def foo():
    raise ValueError("value is invalid")

def bar():
    try:
        foo()
    except ValueError as e:
        print(e)

Example

package xyerror_test

import (
    "errors"
    "fmt"

    "github.com/xybor-x/xyerror"
)

func ExampleException() {
    // To create a root Exception, call xyerror.NewException with the its name.
    var RootError = xyerror.NewException("RootError")

    // You can create an Exception by inheriting from another one.
    var ChildError = RootError.NewException("ChildError")

    fmt.Println(RootError)
    fmt.Println(ChildError)

    // Output:
    // RootError
    // ChildError
}

func ExampleError() {
    // You can compare an Error with an Exception by using the built-in method
    // errors.Is.
    var NegativeIndexError = xyerror.IndexError.NewException("NegativeIndexError")

    var err1 = xyerror.ValueError.New("some value error")
    if errors.Is(err1, xyerror.ValueError) {
        fmt.Println("err1 is a ValueError")
    }
    if !errors.Is(err1, NegativeIndexError) {
        fmt.Println("err1 is not a NegativeIndexError")
    }

    var err2 = NegativeIndexError.Newf("some negative index error %d", -1)
    if errors.Is(err2, NegativeIndexError) {
        fmt.Println("err2 is a NegativeIndexError")
    }
    if errors.Is(err2, xyerror.IndexError) {
        fmt.Println("err2 is a IndexError")
    }
    if !errors.Is(err2, xyerror.ValueError) {
        fmt.Println("err2 is not a ValueError")
    }

    // Output:
    // err1 is a ValueError
    // err1 is not a NegativeIndexError
    // err2 is a NegativeIndexError
    // err2 is a IndexError
    // err2 is not a ValueError
}

func ExampleCombinedException() {
    // CombinedException allows you to create an Exception with multiparents.
    var KeyValueError = xyerror.
        Combine(xyerror.KeyError, xyerror.ValueError).
        NewException("KeyValueError")

    var err = KeyValueError.New("something is wrong")

    if errors.Is(err, xyerror.KeyError) {
        fmt.Println("err is a KeyError")
    }

    if errors.Is(err, xyerror.ValueError) {
        fmt.Println("err is a ValueError")
    }

    // Output:
    // err is a KeyError
    // err is a ValueError
}

Documentation

Overview

Package xyerror supports to define and compare errors conveniently.

Index

• Variables
• func Message(e error) string
• func Or(errs ...error) error
• type CombinedException
  • func Combine(cs ...Exception) CombinedException
  • func (combined CombinedException) NewException(name string) Exception
• type Error
  • func (err Error) Error() string
  • func (err Error) Is(target error) bool
• type Exception
  • func NewException(name string) Exception
  • func (exc Exception) Error() string
  • func (exc Exception) Is(target error) bool
  • func (exc Exception) New(a ...any) Error
  • func (exc Exception) NewException(name string) Exception
  • func (exc Exception) Newf(msg string, a ...any) Error

Examples

• CombinedException
• Error
• Exception

Variables

var (
	BaseException      = Exception{/* contains filtered or unexported fields */}
	IOError            = BaseException.NewException("IOError")
	FloatingPointError = BaseException.NewException("FloatingPointError")
	IndexError         = BaseException.NewException("IndexError")
	KeyError           = BaseException.NewException("KeyError")
	ValueError         = BaseException.NewException("ValueError")
	ParameterError     = BaseException.NewException("ParameterError")
	TypeError          = BaseException.NewException("TypeError")
	AssertionError     = BaseException.NewException("AssertionError")
)

Predefined Exceptions.

Functions

func Message

func Message(e error) string

Message returns only the error message.

func Or

func Or(errs ...error) error

Or returns the first not-nil error. If all errors are nil, return nil.

Types

type CombinedException

type CombinedException []Exception

CombinedException is an array of Exception. It supports to creates an Exception inherited from many parents.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/xybor-x/xyerror"
)

func main() {
	// CombinedException allows you to create an Exception with multiparents.
	var KeyValueError = xyerror.
		Combine(xyerror.KeyError, xyerror.ValueError).
		NewException("KeyValueError")

	var err = KeyValueError.New("something is wrong")

	if errors.Is(err, xyerror.KeyError) {
		fmt.Println("err is a KeyError")
	}

	if errors.Is(err, xyerror.ValueError) {
		fmt.Println("err is a ValueError")
	}

}

Output:

err is a KeyError
err is a ValueError

func Combine

func Combine(cs ...Exception) CombinedException

Combine supports creating a group of Exceptions. This group can be used to create the Exception with multiparents.

func (CombinedException) NewException

func (combined CombinedException) NewException(name string) Exception

NewException creates an Exception with multiparents.

type Error

type Error struct {
	// contains filtered or unexported fields
}

Error is a special error belongs to a generic error class.

Example

package main

import (
	"errors"
	"fmt"

	"github.com/xybor-x/xyerror"
)

func main() {
	// You can compare an Error with an Exception by using the built-in method
	// errors.Is.
	var NegativeIndexError = xyerror.IndexError.NewException("NegativeIndexError")

	var err1 = xyerror.ValueError.New("some value error")
	if errors.Is(err1, xyerror.ValueError) {
		fmt.Println("err1 is a ValueError")
	}
	if !errors.Is(err1, NegativeIndexError) {
		fmt.Println("err1 is not a NegativeIndexError")
	}

	var err2 = NegativeIndexError.Newf("some negative index error %d", -1)
	if errors.Is(err2, NegativeIndexError) {
		fmt.Println("err2 is a NegativeIndexError")
	}
	if errors.Is(err2, xyerror.IndexError) {
		fmt.Println("err2 is a IndexError")
	}
	if !errors.Is(err2, xyerror.ValueError) {
		fmt.Println("err2 is not a ValueError")
	}

}

Output:

err1 is a ValueError
err1 is not a NegativeIndexError
err2 is a NegativeIndexError
err2 is a IndexError
err2 is not a ValueError

func (Error) Error

func (err Error) Error() string

Error returns the Exception name along with the Error message.

func (Error) Is

func (err Error) Is(target error) bool

Is returns true if Error is created by the target Exception.

type Exception

type Exception struct {
	// contains filtered or unexported fields
}

Exception is the generic type of Errors. It does not contain the error message. You should use an Error by creating from Exception, instead of using Exception directly.

Example

package main

import (
	"fmt"

	"github.com/xybor-x/xyerror"
)

func main() {
	// To create a root Exception, call xyerror.NewException with the its name.
	var RootError = xyerror.NewException("RootError")

	// You can create an Exception by inheriting from another one.
	var ChildError = RootError.NewException("ChildError")

	fmt.Println(RootError)
	fmt.Println(ChildError)

}

Output:

RootError
ChildError

func NewException

func NewException(name string) Exception

NewException creates an Exception inherited from the BaseException.

func (Exception) Error

func (exc Exception) Error() string

Error returns the Exception name.

func (Exception) Is

func (exc Exception) Is(target error) bool

Is returns true if the Exception is inherited from the target.

func (Exception) New

func (exc Exception) New(a ...any) Error

New creates an Error with default formatting objects.

func (Exception) NewException

func (exc Exception) NewException(name string) Exception

NewException creates a new Exception by inheriting the called Exception.

func (Exception) Newf

func (exc Exception) Newf(msg string, a ...any) Error

Newf creates an Error with a formatting message.