/usr/lib/perl5/Glib/Error.pod is in libglib-perl 3:1.260-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 | =head1 NAME
Glib::Error - Exception Objects based on GError
=cut
=for position SYNOPSIS
=head1 SYNOPSIS
eval {
my $pixbuf = Gtk2::Gdk::Pixbuf->new_from_file ($filename);
$image->set_from_pixbuf ($pixbuf);
};
if ($@) {
print "$@\n";
if (Glib::Error::matches ($@, 'Gtk2::Gdk::Pixbuf::Error',
'unknown-format')) {
change_format_and_try_again ();
} elsif (Glib::Error::matches ($@, 'Glib::File::Error', 'noent')) {
change_source_dir_and_try_again ();
} else {
# don't know how to handle this
die $@;
}
}
=cut
=for position DESCRIPTION
=head1 DESCRIPTION
Gtk2-Perl translates GLib's GError runtime errors into Perl exceptions, by
creating exception objects based on Glib::Error. Glib::Error overloads the
stringification operator, so a Glib::Error object will act like a string if
used with print() or warn(), so most code using $@ will not even know the
difference.
The point of having exception objects, however, is that the error messages
in GErrors are often localized with NLS translation. Thus, it's not good
for your code to attempt to handle errors by string matching on the the
error message. Glib::Error provides a way to get to the deterministic
error code.
You will typically deal with objects that inherit from Glib::Error, such as
Glib::Convert::Error, Glib::File::Error, Gtk2::Gdk::Pixbuf::Error, etc; these
classes are provided by the libraries that define the error domains. However,
it is possible to get a base Glib::Error when the bindings encounter an unknown
or unbound error domain. The interface used here degrades nicely in such a
situation, but in general you should submit a bug report to the binding
maintainer if you get such an exception.
=cut
=for object Glib::Error Exception Objects based on GError
=cut
=head1 METHODS
=head2 scalar = Glib::Error::new ($class, $code, $message)
=head2 scalar = $class->B<new> ($code, $message)
=over
=item * $code (Glib::Enum) an enumeration value, depends on I<$class>
=item * $message (string)
=back
Create a new exception object of type I<$class>, where I<$class> is associated
with a GError domain. I<$code> should be a value from the enumeration type
associated with this error domain. I<$message> can be anything you like, but
should explain what happened from the point of view of a user.
=head2 integer = $error-E<gt>B<code>
This is the numeric error code. Normally, you'll want to use C<value> instead,
for readability.
=head2 string = $error-E<gt>B<domain>
The error domain. You normally do not need this, as the object will be blessed
into a corresponding class.
=head2 string = $error-E<gt>B<location>
The source line and file closest to the emission of the exception, in the same
format that you'd get from croak() or die().
If there's non-ascii characters in the filename Perl leaves them as
raw bytes, so you may have to put the string through
Glib::filename_display_name for a wide-char form.
=head2 boolean = $error-E<gt>B<matches> ($domain, $code)
=over
=item * $domain (string)
=item * $code (scalar)
=back
Returns true if the exception in I<$error> matches the given I<$domain> and
I<$code>. I<$domain> may be a class name or domain quark (that is, the real
string used in C). I<$code> may be an integer value or an enum nickname;
the enum type depends on the value of I<$domain>.
=head2 string = $error-E<gt>B<message>
The error message. This may be localized, as it is intended to be shown to a
user.
=head2 Glib::Error::register ($package, $enum_package)
=over
=item * $package (string) class name to register as a Glib::Error.
=item * $enum_package (string) class name of the enum type to use for this domain's error codes.
=back
Register a new error domain. Glib::Error will be added @I<package>::ISA for
you. I<enum_package> must be a valid Glib::Enum type, either from a C library
or registered with C<< Glib::Type::register_enum >>. After registering an
error domain, you can create or throw exceptions of this type.
=head2 scalar = Glib::Error::throw ($class, $code, $message)
=head2 scalar = $class->B<throw> ($code, $message)
=over
=item * $code (Glib::Enum) an enumeration value, depends on I<$class>
=item * $message (string)
=back
Throw an exception with a Glib::Error exception object.
Equivalent to C<< croak (Glib::Error::new ($class, $code, $message)); >>.
=head2 string = $error-E<gt>B<value>
The enumeration value nickname of the integer value in C<< $error->code >>,
according to this error domain. This will not be available if the error
object is a base Glib::Error, because the bindings will have no idea how to
get to the correct nickname.
=cut
=head1 SEE ALSO
L<Glib>
=cut
=head1 COPYRIGHT
Copyright (C) 2003-2011 by the gtk2-perl team.
This software is licensed under the LGPL. See L<Glib> for a full notice.
=cut
|