Error Handling in the Practical Type System (PTS)

Fundamental Principles

A crucial principle in PTS is to distinguish between two types of errors:

• anticipated errors, for example file_not_found_error, network_connection_error, etc.

  These errors are expected to possibly occur at run-time.

• unanticipated errors, for example out_of_memory_error, stack_overflow_error, etc.

  These errors are not expected to occur at run-time. They occur only if there is a serious problem that can't usually be solved at run-time.

Both types of errors are handled differently.

Anticipated errors are governed by the following principles:

• Functions that might fail at run-time must state in their signature that an anticipated error might be returned.

• Errors returned by functions cannot be silently ignored: They must be handled in the calling code, or ignored explicitly.

• There is only one idiomatic way to return errors from functions, but there are several (well supported) ways to handle errors returned by functions.

• A dedicated set of operators and statements facilitates error-handling.

Unanticipated errors are governed by the following principles:

• Unanticipated errors can potentially occur at any time during program execution, and at any location in the source code. However, they are not expected to occur — they are unanticipated, and therefore not declared in function signatures.

• By default, unanticipated errors are handled by a global error handler. A built-in, default implementation of this handler writes error information (including stack traces) to the standard OS err device and then aborts program execution with exit code 1.

  An application can register different error handlers to customize global handling of unanticipated errors.

• Unanticipated errors can be caught explicitly anywhere in the source code, in order to provide customized error handling in specific situations.

• Unanticipated errors are usually thrown implicitly, but they can also be thrown explicitly, for example in case of an unrecoverable problem detected at run-time.

These are the fundamental design principles.

Now let's look into details.

Types

Type Hierarchy

In section Type Hierarchy of the previous article Null-Safety in the Practical Type System (PTS) we already saw the following top types in the PTS type hierarchy:

We'll now refine this type hierarchy, first by defining the sub-types of non_null:

As you can see, there is a clear separation between types that represent errors (child-types of error), and those that don't (child-types of non_error).

Now let's look at the sub-types of error:

This diagram shows the distinction between anticipated and unanticipated errors.

Taking into account the above additional types, the PTS top-types hierarchy becomes:

All types displayed in italics are non-instantiable types (aka abstract types). Their cardinality is zero.

Now let's have a closer look at these types.

type error
    inherit: non_null                                                         (1)
    child_types: anticipated_error, unanticipated_error                       (2)
    factories: none                                                           (3)

    atts
        message string                                                        (4)
        id string (pattern = "[a-zA-Z0-9_-\.]{1,100}") or null default:null   (5)
        time date_time or null default:date_time.now                          (6)
        cause error or null default:null                                      (7)
    .
.

type file_error

    inherit: IO_error

    att file_path file_path

    // Get the name of the file, without it's directory
    fn file_name -> file_name
        return file_path.name
    .
.

type file_not_found_error
    inherit file_error
.

type file_read_error
    inherit file_error
.

type file_write_error
    inherit file_error
.

Anticipated Errors

If a function be advertised to return an error code in the event of difficulties, thou shalt check for that code, yea, even though the checks triple the size of thy code and produce aches in thy typing fingers, for if thou thinkest "it cannot happen to me", the gods shall surely punish thee for thy arrogance.

— Henry Spencer, The Ten Commandments for C Programmers

In this section we'll explore anticipated errors — i.e. errors that are expected to possibly occur at run-time (e.g. file_not_found_error, user_input_error, etc.).

Section Fundamental Principles stated:

• Functions that might fail at run-time must state in their signature that an anticipated error might be returned.

• Errors returned by functions cannot be silently ignored: They must be handled in the calling code, or ignored explicitly.

The following sections explain how PTS ensures these conditions.

fn read_text_file ( file_path ) -> string
    // body
.

fn read_text_file ( file_path ) -> string or file_read_error
    // body
.

fn read_text_file ( file_path ) -> string or null or file_read_error
    // body
.

fn ask_title -> string or user_input_error

    case type of GUI_dialogs.ask_string ( prompt = "Please enter a title" )
        is string as title
            return title
        is null
            return user_input_error.create (
                message = "A title is required."
                id = "INVALID_TITLE" )
    .
.

case type of read_text_file ( file_path.create ( "example.txt" ) )
    is string as text // the string is stored in constant 'text'
        write_line ( "Content of file:" )
        write_line ( text ) // the previously defined constant 'text' is now used
    is null
        write_line ( "The file is empty." )
    is file_error as error
        write_line ( """The following error occurred: {{error.message}}""" )
.

const message = case type of read_text_file ( file_path.create ( "example.txt" ) )
    is string: "a string"
    is null: "null"
    is error: "an error"
write_line ( "The result is " + message )        

const phone_number = get_employee()?null?error \
    .get_department()?null?error \
    .get_manager()?null?error \
    .get_phone_number()

assert result is not error

const value = get_value_or_null_or_error() \
    on null : return null \
    on error as e : return e

const value = get_value_or_null_or_error() ^null ^error

fn customer_name_by_id ( id string ) -> string or inexistant_customer_error

type inexistant_customer_error
    
    inherit invalid_data_error

    att customer_id string
.

fn customer_name_by_id ( id string ) -> string or inexistant_customer_error

    // dummy implementation
    if id =v "100"
        return "Foo"
    else
        return inexistant_customer_error.create (
            message = """Customer '{{id}}' doesn't exist."""
            customer_id = id )
    .
.

fn write_customer_name ( customer_id string )

fn write_customer_name ( customer_id string )
    
    const name = customer_name_by_id ( customer_id )
    write_line ( name )
.

fn write_customer_name ( customer_id string )

    case type of customer_name_by_id ( customer_id )
        is string as name
            write_line ( name )
        is inexistant_customer_error
            write_line ( "Unknown customer" )
    .
.

fn write_customer_name ( customer_id string )

    const result = customer_name_by_id ( customer_id )
    if result is string then
        write_line ( result )
    else
        write_line ( "Unknown customer" )
    .
.

fn write_customer_name ( customer_id string )

    const name = customer_name_by_id ( customer_id ) if_is error: "Unknown customer"
    write_line ( name )
.

fn write_customer_name ( customer_id string )

    write_line ( customer_name_by_id ( customer_id ) if_is error: "Unknown customer" )
.

fn write_customer_name ( customer_id string ) -> inexistant_customer_error or null

    case type of customer_name_by_id ( customer_id )
        is string as name
            write_line ( name )
            return null
        is inexistant_customer_error as error
            return error
    .
.

fn write_customer_name ( customer_id string ) -> inexistant_customer_error or null

    const name = customer_name_by_id ( customer_id ) on error as e: return e
    write_line ( name )
.

fn write_customer_name ( customer_id string ) -> inexistant_customer_error or null

    const name = customer_name_by_id ( customer_id ) ^error
    write_line ( name )
.

fn write_customer_name ( customer_id string ) -> runtime_error or null

    case type of customer_name_by_id ( customer_id )
        is string as name
            write_line ( name )
            return null
        is inexistant_customer_error as error
            return runtime_error.create (
                message = "An error occurred."
                cause = error // can be left off for security reasons
            )
    .
.

fn write_customer_name ( customer_id string ) -> runtime_error or null

    const name = customer_name_by_id ( customer_id ) \
        on error as e: return runtime_error.create (
            "An error occurred."
            cause = e )

    write_line ( name )
.

fn write_customer_name_or_throw ( customer_id string )

    case type of customer_name_by_id ( customer_id )
        is string as name
            write_line ( name )
        is inexistant_customer_error as e
            throw program_error.create (
                message = e.message
                cause = e )
    .
.

fn write_customer_name_or_throw ( customer_id string )

    const name = customer_name_by_id ( customer_id ) \
        on error as e: throw program_error.create (
            message = e.message
            cause = e )

    write_line ( name )
.

fn write_customer_name_or_throw ( customer_id string )

    const name = customer_name_by_id ( customer_id ) \
        on error: throw

    write_line ( name )
.

fn write_customer_name ( customer_id string )

    const result = customer_name_by_id ( customer_id )
    assert result is not error
    write_line ( result ) // result is guaranteed to be a string
.

fn write_customer_name ( customer_id string )

    case type of customer_name_by_id ( customer_id )
        is string as name
            write_line ( name )
        is inexistant_customer_error
            write_line ( "Error: invalid customer id." )
            OS_process.exit ( 1 )
    .
.

fn write_customer_name ( customer_id string )

    case type of customer_name_by_id ( customer_id )
        is string as name
            write_line ( name )
        is inexistant_customer_error
            do nothing
    .
.

fn do_stuff -> stuff_error or null

    task_1() on task_error as e: return stuff_error.create (
        message = "An error occurred",
        cause = e )
    task_2()
    task_3() on task_error as e: return stuff_error.create (
        message = "An error occurred",
        cause = e )
    task_4() on task_error as e: return stuff_error.create (
        message = "An error occurred",
        cause = e )
.

fn do_stuff -> stuff_error or null

    try
        try! task_1()
        task_2()
        try! task_3()
        try! task_4()
    
    on task_error as e
        return stuff_error.create (
            message = "An error occurred",
            cause = e )
    .
.

Unanticipated Errors

An unanticipated error is an error that is not expected to occur at run-time. Unanticipated errors occur if a serious problem arises during program execution — a problem that's not supposed to occur under normal conditions: e.g. a hardware malfunction, a problem in the OS, a configuration issue (e.g. missing library), a bug in the code. These errors can potentially occur at any time during program execution, and at any location in the source code.

They often occur due to a bug in the software. For example:

• too deeply nested recursive function calls (or infinite recursions not detected by the compiler) lead to a stack_overflow_error

• an infinite loop creating new in-memory objects results in an out_of_memory_error

• violating the condition specified in an assert statement leads to an assert_violation_error (a child-type of program_error)

• violating the pre-condition of a function input parameter leads to a pre_condition_violation_error (also a child-type of program_error)

• a bug in a function can lead to a post_condition_violation_error (again, a child-type of program_error)

type unanticipated_error_handler

    fn handle_error ( error unanticipated_error )
.

fn do_stuff -> stuff_error or null

    try
        try! task_1()
        task_2()
        try! task_3()
        try! task_4()
    
    on task_error as e
        return stuff_error.create (
            message = "An error occurred",
            cause = e )
    .
.

try
    do_this()
    do_that()
catch unanticipated_error as e
    // handle the error stored in constant 'e'
finally
    // clean up (e.g. close resources)
.

try
    do_this()
    do_that()
    try! task_1()
    task_2()
    try! task_3()
    try! task_4()
on anticipated_error as e
    // handle anticipated errors
catch unanticipated_error as e
    // handle unanticipated errors
finally
    // clean up
.

"throw" <expression>

if third_party_libraries_missing then
    throw program_error.create (
        message = "Third-party libraries must be installed before using this application." )
.

Avoid Returning Many Types of Anticipated Errors!

Consider a high-level function named do_stuff that calls lower-level functions executing various read/write operations on files and directories. These low-level functions in the call tree return anticipated errors such as file_not_found_error, file_read_error, file_write_error, directory_read_error, directory_access_error. If each function in the tree propagates errors to its parent functions, then do_stuff might end up with a horrible signature like this:

fn do_stuff -> string or \
    file_not_found_error or file_read_error or file_write_error or \
    directory_read_error or directory_access_error

Worse, each time a signature in a lower-level function is changed later on (e.g. an error type is added or removed), the signatures of all parent functions (including do_stuff) need to be adapted accordingly.

While there are different solutions to avoid maintenance nightmares like this, a simple solution for higher-level functions is to just return a common parent type of all errors returned in the call tree. For example, do_stuff can be simplified as follows:

fn do_stuff -> string or directory_or_file_error

Here, we assume that directory_or_file_error is the parent type of all errors returned in the call tree.

Now suppose that, later on, database and network operations are added in the code. do_stuff needs to be adapted:

fn do_stuff -> string or directory_or_file_error or database_error or network_error

But again, we can simplify by using a common parent type:

fn do_stuff -> string or IO_error

In practice, using an appropriate parent type from the onset (e.g. IO_error) is often an acceptable solution, because:

• It facilitates code maintenance.

• Caller functions often don't care about which error occurred — they only care about whether an error occurred or not.

• It hides implementation details which are irrelevant and might change in future versions.

It's important to note that error information is not lost if a higher-level function in the call-tree returns a higher-level error in the type hierarchy. For example, if a low-level function returns file_not_found_error, then a higher-level function declared to return IO_error still returns an instance of file_not_found_error (i.e. a child-type of IO_error), which can be explored by parent functions, or used for debugging/diagnostic purposes.

As a rule of thumb (that might be ignored if there is a good reason), functions shouldn't return many error types. It is often appropriate to declare a single error type which is a common parent type of all errors returned in the call tree. This leads to simpler and more maintainable code.

Use Wrappers if Appropriate!

There is another solution to the problem of "too many error types returned" explained in the previous section: define a dedicated error type that serves as a wrapper for all low-level errors, and return this wrapper in all low-level functions.

In our example, we could define type stuff_error, a wrapper for all errors in the call tree:

type stuff_error
    inherit: runtime_error
.

The signature of do_stuff becomes:

fn do_stuff -> string or stuff_error

Lower-level functions also return stuff_error, and they store the source error (the cause) into attribute cause:

fn stuff_child -> null or stuff_error
    ...
    const text = read_text_file ( file_path ) \
        on file_read_error as e: return stuff_error.create (
            message = e.message
            cause = e )
    ...
.

To shorten the code, we could define a creator/constructor create_from_cause for stuff_error (not shown here), and then simply write:

const text = read_text_file ( file_path ) \
    on file_read_error as e: return stuff_error.create_from_cause ( e )

Again, the low-level error information isn't lost, since it's stored in attribute cause of stuff_error.

See also: section Returning a Wrapper Error.

Use Unanticipated Errors if Appropriate!

Sometimes we don't want to handle errors — we assume the code to be running in an environment where errors aren't supposed to occur at run-time. If an error still occurs despite our assumption, then an immediate termination is appropriate: the application writes an error message to STDERR, and then aborts with exit code 1.

In other words, instead of handling an error, we opt to just abort execution instead. This is also referred to as panicking — for example, in Rust the panic! macro can be used to abort the application gracefully and release resources.

Aborting program execution in case of an error (i.e. panicking) is justified in various situations: for example, when experimenting with code, writing a prototype, building a personal stamp-inventory application, or when we just want to write quick and dirty code. Even in applications designed to handle errors, there might be specific cases where an immediate termination is preferable, for example to avoid corrupt data on a long-term basis. Good advice related to this topic is provided in chapter To panic! or Not to panic! of The Rust Programming Language.

While PTS is clearly not designed to abort by default, it does offer support for "crash early" approaches. You can abort (panic) if you have a good reason to do so — you just have to be explicit about it.

The basic idea is to convert anticipated errors into unanticipated ones every time you would have to deal with an anticipated error. Thus, instead of returning an anticipated error, you throw an unanticipated one. Let's see different ways to do this.

A first technique is to use an assert statement to declare that an anticipated error isn't supposed to occur:

const result = customer_name_by_id ( customer_id )
assert result is not error
// continue with a customer object stored in 'result'

A better and less verbose technique is to use the on error: throw clause, which was introduced in section Throwing an Unanticipated Error:

const name = customer_name_by_id ( customer_id ) on error: throw

Writing lots of on error: throw clauses can be annoying. A better solution might therefore be to write utility functions that throw unanticipated errors, instead of returning anticipated errors.

For example, suppose that many functions in our quick-and-dirty throw-away prototype read non-empty text files. Under normal circumstances (i.e. where reliability matters), we would call a library function like the following:

// returns 'null' if the file is empty
fn read_text_file ( file_path ) -> string or null or file_read_error

Using this function requires checks for null and file_read_error in client code. To avoid these checks, we could define the following utility function, which assumes that file read errors don't occur and text files are never empty:

fn read_non_empty_text_file_or_throw ( file_path ) -> string      (1)

    case type of read_text_file ( file_path )
        is string as content
            return content
        is null
            throw program_error.create (                          (2)
                """File {{path.to_string}} is empty.""" )
        is file_read_error as e
            throw program_error.create (
                """Could not read file {{path.to_string}}         (3)
                Reason: {{e.message}}""" )
    .
.

(1) By convention, the function name suffix _or_throw states that an unanticipated error might be thrown. Under normal conditions, the function returns a string containing the content of the non-empty text file.

(2) An unanticipated error is thrown if the file is empty.

(3) An unanticipated error is thrown if the file can't be read.

A simpler version of the above function could be written as follows:

fn read_non_empty_text_file_or_throw ( file_path ) -> string

    const result = read_text_file ( file_path )
    assert result is not null and result is not error
    return result
.

Client code is now simple and short, because null- and error-handling is no longer needed:

const text = read_non_empty_text_file_or_throw ( file_path.create ( "example.txt" ) )

Sometimes it makes sense to use unanticipated errors in unexposed (private) parts of an application, because this can considerably simplify code and increase maintainability.

Suppose we are working on a complex parser with a main function like this:

fn parse ( string ) -> AST or syntax_error

Syntax errors are likely to be detected in low-level, private functions. Using anticipated errors in the whole call tree of function parse can easily lead to verbose code, because all errors need to be handled (e.g. propagated to the parent function) and declared in the function signatures. Whenever error types in function signatures change, a lot of refactoring might be required. To avoid this maintenance burden, it might be better to throw unanticipated errors in the functions called by parse, the root function in the call tree. Function parse uses a try statement to catch any unanticipated error, and converts it into an anticipated error which is then returned. The following simplified code illustrates this approach:

fn parse ( string ) -> AST or syntax_error

    try
        const AST = AST.create_empty
        // parse the string and populate 'AST'
        return AST
    catch unanticipated_error as ue
        return syntax_error.create ( message = ue.message )
    .
.

Don't Use null to Return Error Conditions!

Suppose you're designing the map type (aka dictionary, associated_array) in a standard library. Method get takes a key as input and returns the corresponding value stored in the map. Here's an interesting question: What should the method do if the key doesn't exist?

It's tempting to simply return null, as is done in several libraries (e.g. Java Map.get). Using PTS syntax, map could be defined as follows:

type map<key_type child_of:hashable, value_type>
    
    fn get ( key key_type ) -> value_type or null

    // more methods
.

There are two downsides to this approach:

• If the values in the map are allowed to be null (e.g. map<string, string or null>), an ambiguity arises.

  For example, if a method call like map.get ( "foo" ) returns null, it can mean two things: either there is no entry with key "foo", or there is an entry with key "foo" and value null.

• If the values in the map aren't allowed to be null (e.g. map<string, string>), there's a risk of misinterpretation.

  For example, if a method call like map.get ( "foo" ) returns null, it could erroneously be interpreted in the client code as an entry with key "foo" and value null.

  This risk for misinterpretation increases if a map with nullable values is later on changed to a map with non-null values (e.g. from map<string, string or null> to map<string, string>).

To eliminate the first problem (ambiguity when null is returned), we can add method contains_key (which is needed anyway):

type map<key_type child_of:hashable, value_type>
    
    fn contains_key ( key key_type ) -> boolean
    
    fn get ( key key_type ) -> value_type or null

    // more methods
.

This works, because we can now call contains_key to eliminate the ambiguity. But it doesn't work well. Firstly, method get is error-prone, because one has to read the docs, be careful, and not forget to call contains_key if get returns null. Secondly, calling get first, and contains_key afterward, is verbose and can result in very nasty bugs in case of race conditions caused by sharing a mutable map in concurrent or parallel processing environments.

This error-proneness vanishes if get returns an error (instead of null) whenever a key isn't contained in the map:

type map<key_type child_of:hashable, value_type>
    
    fn get ( key key_type ) -> value_type or key_not_contained_in_map_error

    // more methods
.

Client code is now required to check for key_not_contained_in_map_error, e.g.

const value = map.get ( "foo" ) on error as e: return e

We are protected from forgetting to check if the key actually exists in the map. Moreover, the fact that method get could fail is also clearly expressed in the client code.

However, being forced to check for an error can be annoying, and leads to verbose code. If a key isn't contained in the map, you might want to:

• throw an unanticipated error, because you assume that the key ought to be contained in the map

• fallback to a default value

• get null, because you don't need to differentiate between the two possible meanings of null

These use cases can easily be covered by adding variations of the get method:

type map<key_type child_of:hashable, value_type>
    
    fn get ( key key_type ) -> value_type or key_not_contained_in_map_error
    fn get_or_throw ( key key_type ) -> value_type
    fn get_or_default ( key key_type, default value_type ) -> value_type
    fn get_or_null ( key key_type ) -> value_type or null

    // more methods
.

Providing many choices is sometimes counterproductive, but in this case it is justified by the fact that map is a fundamental data structure, defined in the standard library, and used in many different ways.

Besides providing a more versatile API, we benefit from the following:

• The behavior of the four getter methods is clearly expressed by their signatures — the programmer probably doesn't need to read the docs to know which getter method to use (although he/she must still be aware of the potentially ambiguous meaning in the case of null being returned by get_or_null).

• Client code is succinct in all cases and auto-documents the behavior in case of a non-existent key. Here are a few examples:

  const value_1 = map.get ( "foo" ) ^error
  
  const value_2 = map.get_or_throw ( "foo" )
  
  const value_3 = map.get_or_default ( key = "foo", default = "bar" )
  
  const value_4 = map.get_or_null ( "foo" )
  if value_4 is null then
      // handle it
  .