# module SystemError

##
Overview

This module can be included in any `Exception` subclass that is used to wrap some system error (`Errno` or `WinError`).

It adds an `#os_error` property that contains the original system error. It provides several constructor methods that set the `#os_error` value:

- `.from_os_error` receives an OS error value and creates an instance with that.
- `.from_errno` constructs an instance with the current LibC errno value (`Errno.value`).
- `.from_winerror` constructs an instance with the current LibC winerror value (`WinError.value`).

An error message is automatically constructed based on the system error message.

For example:

    class MyError < Exception
      include SystemError
    end

    MyError.from_errno("Something happened")

##
Customization

Including classes my override several protected methods to customize the instance creation based on OS errors:

- `protected def build_message(message, **opts)` Prepares the message that goes before the system error description. By default it returns the original message unchanged. But that could be customized based on the keyword arguments passed to `from_errno` or `from_winerror`.
- `protected def new_from_os_error(message : String?, os_error, **opts)` Creates an instance of the exception that wraps a system error. This is a factory method and by default it creates an instance of the current class. It can be overridden to generate different classes based on the `#os_error` value or keyword arguments.
- `protected def os_error_message(os_error : Errno | WinError | Nil, **opts) : String?` Returns the respective error message for os_error. By default it returns the result of `Errno#message` or `WinError#message`. This method can be overridden for customization of the error message based on os_error and opts.

##
Direct including types

- IO::Error
- RuntimeError

##
Defined in:

system_error.cr

##
Instance Method Summary

- #os_error : Errno | WinError | WasiError | Nil

  The original system error wrapped by this exception

##
Instance Method Detail

def os_error : Errno | WinError | WasiError | Nil #

The original system error wrapped by this exception