view release on metacpan or  search on metacpan

lib/App/Open/Backend.pm  view on Meta::CPAN

this detail, it is expected to use the exact same semantics as
lookup_file().

=back

=head2 Exceptions

For this document, exceptions are triggered by calling die() with a
specific argument string. Some exceptions take optional arguments, which are
delimited by spaces in the die string.

Example:

    die "INVALID_CONFIGURATION"; # exception for invalid configuration
    die "ANOTHER_EXCEPTION that has four arguments"; # an exception with arguments

While there's nothing stopping you from processing exceptions this way
in your own backends, these exceptions are mainly for the benefit of
the App::Open core. The core uses these exceptions to provide useful
output to the user when there's an error running the `openit` command.

Anyways, on to the list of recognized exceptions.

=over 4

=item MISSING_ARGUMENT

=item INVALID_ARGUMENT

=item FILE_NOT_FOUND

=item INVALID_CONFIGURATION

I hope these are self-explanatory.

=item NO_PROGRAM

This is generally thrown by App::Open itself, when no matches for a
given extension/scheme are found. However, if your backend depends on
a program to perform lookups and can't find it, it would be
appropriate to throw this.

=item NO_BACKEND_FOUND backend_name

Used by App::Open::Config when initializing backends, and one cannot
be loaded. It's unlikely you will ever need this.

=item BACKEND_CONFIG_ERROR

This is what you will most often use; if you require arguments or
merely get garbage arguments, this is what you throw, and the `openit`
program will direct the user to your backend documentation. Obviously,
this can be used in less obvious cases.

=back

=head1 EXAMPLES

Please look at App::Open::Backend::Dummy for a very basic rundown of
the API. This is what's used to test the backend interface
functionality, and as such will remain updated along with this
document concerning any changes to the API.

If you'd like something with more meat, App:;Open::Backend::YAML is
fully functional and relatively simple to understand.

=head1 CONTRIBUTING BACKENDS

It is the author's desire that backends released be packaged
separately from App::Open and available via CPAN.

However, he will gladly consider backends for inclusion in this
package that:

=over 4

=item Do not add dependencies

=item Do not make assumptions about the operating system or installed tools

=item Are fully tested and documented

=back

In other words, you're better off just releasing it yourself.

=cut