/ 
Exception-FFI-ErrorCode-0.01
River stage zero No dependents
/ Exception::FFI::ErrorCode

NAME

Exception::FFI::ErrorCode - Exception class based on integer error codes common in C code

VERSION

version 0.01

SYNOPSIS

Throwing:

# realish world example for use with libcurl
package Curl::Error {
  use Exception::FFI::ErrorCode
    code => {
      CURLE_OK                   => 0,
      CURLE_UNKNOWN_OPTION       => 48
      ...
    };
  $ffi->attach( [ curl_easy_strerror => strerror ] => ['enum'] => 'string' => sub {
    my($xsub, $self, $code) = @_;
    $xsub->($code);
  });
}

# foo is an unknown option, so this will return 48
my $code = $curl->setopt( "foo" => "bar" );
# throw as an exception
Curl::Error->throw( code => $code ) if $code != Curl::Error::CURLE_OK;

Defining error class without a strerror

package Curl::<Error {
  use Exception::FFI::ErrorCode
    code => {
      CURLE_OK                   => [ 0,  'no error'                        ],
      CURLE_UNKNOWN_OPTION       => [ 48, 'unknown option passed to setopt' ],
      ...
    };
}
...

Catching:

try {
  might_die;
}
catch ($ex) {
  if($ex isa Curl::Error) {
    my $package  = $ex->package;   # the package where thrown
    my $filename = $ex->filename;  # the filename where thrown
    my $line     = $ex->line;      # the linenumber where thrown
    my $code     = $ex->code;      # the error code
    my $human    = $ex->strerror;  # human readable error
    my $diag     = $ex->as_string; # human readable error at filename.pl line xxx
    my $diag     = "$ex";          # same as $ex->as_string

    if($ex->code == Curl::Error::UNKNOWN_OPTION) {
      # handle the unknown option variant of this error
    }
  }
}

DESCRIPTION

A common pattern in C libraries is to return an integer error code to classify an error. When translating those APIs to Perl you often want to instead throw an exception. This class provides an interface for building exception classes that help with that pattern.

For APIs that provide a strerror or similar function that converts the error code into a human readable diagnostic, you can simply attach it. If not you can provide human readable diagnostics for each error code using an array reference, as shown above.

The base class for your exception class will be set to Exception::FFI::ErrorCode::Base. The base class handles determining the location of where the exception was thrown and will stringify in a way to look like a regular Perl string exception with the filename and line number you would expect.

METHODS

import

use Exception::FFI::ErrorCode
  %options;

The import method will set the base class, and set up any specific error codes. Options include:

class

The exception class. If not provided this will be determined using caller.

codes

The error codes. This is a hash reference. The keys are the constant names, in C and Perl these are usually all upper case like FOO_BAD_FILENAME. The values can be either an integer constant, or an array reference with the integer constant and human readable diagnostic. The former is intended for when there is a strerror type function that will convert the error code into a diagnostic for you.

const_class

Where to put the constants. If not provided, these will be be the same as class.

Exception::FFI::ErrorCode::Base

The base class uses Class::Tiny, so feel free to add additional attributes. The base class provides these attributes and methods:

throw

Exception::FFI::ErrorCode::Base->throw( code => $code );

Throws the exception with the given code. Obviously you would throw the subclass, not the base class.

strerror

my $string = $ex->strerror;

Returns a human readable message for the exception. If available this should be overridden by attaching the appropriate C function.

as_string

my $string = $ex->as_string;
my $string = "$ex";

Returns a human readable diagnostic. This is in the form of a familiar Perl warning or string exception, including the filename and line number where the exception was thrown. If you stringify the exception it will use this method.

package

my $package = $ex->package;

The package where the exception happened.

filename

my $filename = $ex->filename;

The filename where the exception happened.

line

my $line = $ex->line;

The line number where the exception happened.

code

my $code = $ex->code;

The integer error code.

SEE ALSO

FFI::Platypus
Exception::Class
Class:Tiny

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.