NAME Exception::FFI::ErrorCode - Exception class based on integer error codes common in C code VERSION version 0.03 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) = @_; $xsub->($self->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. A stack trace can be generated, either on a per-subclass basis, or globally via an environment variable. This is not done by default due to the overhead involved. See the trace method for details. This class will attempt to detect if Carp::Always is running and produce a long message when stringified, as it already does for regular string exceptions. By default it will only do this if Carp::Always is running when this module is loaded. Since typically Carp::Always is loaded via the command line -MCarp::Always or via PERL5OPT environment variable this should cover all of the typical use cases, but if for some reason Carp::Always does get loaded after this module, you can force redetection by calling the detect method. METHODS detect Exception::FFI::ErrorCode->detect; This will redetect if Carp::Always has been loaded yet. You do not need to call this method if Carp::Always has been enabled or disabled (we check for that when the exception is thrown and stringified), just if the module has been loaded. 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, %attr ); Exception::FFI::ErrorCode::Base->throw( code => $code, frame => $frame, %attr ); Throws the exception with the given code. Obviously you would throw the subclass, not the base class. If you have added additional attributes via Class::Tiny you can provide them as %attr. If you want the exception to appear to happen from a different frame then you can specify it with $frame. 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, adding a new line. 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. trace my $trace = $ex->trace; This will return a Devel::StackTrace trace, if it was recorded when the exception was thrown. Generally the trace will only be generated if EXCEPTION_FFI_ERROR_CODE_STACK_TRACE set to a true value. Individual subclasses may also choose to always generate a stack trace. get_stack_trace my $trace = $ex->get_stack_trace; This is the method that is called internally to generate a stack trace. By default this is only done if EXCEPTION_FFI_ERROR_CODE_STACK_TRACE is set to true. If you want a stack trace to always be generated, you can override this method in your subclass. CAVEATS The Carp::Always detection is pretty solid, but if Carp::Always is off when the exception is thrown but on when it is stringified then strange things might happen. ENVIRONMENT EXCEPTION_FFI_ERROR_CODE_STACK_TRACE If this environment variable is set to a true value, then a stack trace will be generated and attached to all exceptions managed by Exception::FFI::ErrorCode. SEE ALSO FFI::Platypus Exception::Class Class:Tiny AUTHOR Graham Ollis 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.