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.

cpanm Exception::FFI::ErrorCode

perl -MCPAN -e shell
install Exception::FFI::ErrorCode