Skip to content

Commit 833c41d

Browse files
bbrtjbbrtj
committed
Aggregate all exception subclasses docs into one place
1 parent 6c7649c commit 833c41d

20 files changed

Lines changed: 141 additions & 277 deletions

‎lib/Bitcoin/Crypto/BIP44.pm‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -255,18 +255,6 @@ indirectly by just stringifying the object.
255255
256256
Returns an object of class L<Bitcoin::Crypto::DerivationPath>.
257257
258-
=head1 EXCEPTIONS
259-
260-
This module throws an instance of L<Bitcoin::Crypto::Exception> if it
261-
encounters an error. It can produce the following error types from the
262-
L<Bitcoin::Crypto::Exception> namespace:
263-
264-
=over
265-
266-
=item * NetworkConfig - incomplete or corrupted network configuration
267-
268-
=back
269-
270258
=head1 SEE ALSO
271259
272260
L<Bitcoin::Crypto::Key::ExtPrivate>

‎lib/Bitcoin/Crypto/Base58.pm‎

Lines changed: 0 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -137,20 +137,6 @@ compatibility addresses as well as WIF strings and extended key serialization.
137137
138138
Arguments are the same as base functions mentioned above.
139139
140-
=head1 EXCEPTIONS
141-
142-
This module throws an instance of L<Bitcoin::Crypto::Exception::Base58> if it
143-
encounters an error. It can produce the following error types from the
144-
L<Bitcoin::Crypto::Exception> namespace:
145-
146-
=over
147-
148-
=item * Base58InputFormat - input was not suitable for base58 operations due to invalid format
149-
150-
=item * Base58InputChecksum - checksum validation has failed
151-
152-
=back
153-
154140
=head1 SEE ALSO
155141
156142
L<Crypt::Misc>

‎lib/Bitcoin/Crypto/Bech32.pm‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -444,22 +444,6 @@ data in bech32 strings, like so:
444444
445445
Returns the human readable part encoded in the bech32 address.
446446
447-
=head1 EXCEPTIONS
448-
449-
This module throws an instance of L<Bitcoin::Crypto::Exception::Bech32> if it
450-
encounters an error. It can produce the following error types from the
451-
L<Bitcoin::Crypto::Exception> namespace:
452-
453-
=over
454-
455-
=item * Bech32InputFormat - input was not suitable for bech32 operations due to invalid format
456-
457-
=item * Bech32InputData - input was parsed with bech32 operations but contained invalid data
458-
459-
=item * Bech32InputChecksum - checksum validation has failed
460-
461-
=back
462-
463447
=head1 SEE ALSO
464448
465449
L<Bitcoin::Crypto::Base58>

‎lib/Bitcoin/Crypto/Exception.pm‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -355,6 +355,132 @@ C<Bitcoin::Crypto::Exception::Sign> for errors in signature generation). Search
355355
individual Bitcoin::Crypto packages documentation for a list the exception
356356
classes to check for extra control flow when needed.
357357
358+
=head1 EXCEPTION SUBCLASSES
359+
360+
This module defines the following subclasses to Bitcoin::Crypto::Exception:
361+
362+
=head2 Bitcoin::Crypto::Exception::Transaction
363+
364+
Thrown when a general problem with a transaction is detected, for example:
365+
non-script verification failure, corrupted serialized transaction data.
366+
367+
=head2 Bitcoin::Crypto::Exception::UTXO
368+
369+
Thrown when a problem with UTXO is detected, most notably inability to find the UTXO.
370+
371+
=head2 Bitcoin::Crypto::Exception::Sign
372+
373+
Thrown when a problem occurs during signing a transaction or message.
374+
375+
=head2 Bitcoin::Crypto::Exception::KeyCreate
376+
377+
Thrown when a problem occurs during creation of a key.
378+
379+
=head2 Bitcoin::Crypto::Exception::KeyDerive
380+
381+
Thrown when a problem occurs during derivation of a key.
382+
383+
=head2 Bitcoin::Crypto::Exception::MnemonicCheck
384+
385+
Thrown when a mnemonic checking was unsuccessful.
386+
387+
=head2 Bitcoin::Crypto::Exception::Base58
388+
389+
Thrown when a general base58 format problem is detected.
390+
391+
=head2 Bitcoin::Crypto::Exception::Base58InputFormat
392+
393+
Thrown when input does not look like valid base58. Subclass of
394+
L</Bitcoin::Crypto::Exception::Base58>.
395+
396+
=head2 Bitcoin::Crypto::Exception::Base58InputChecksum
397+
398+
Thrown when base58check input checksum is invalid. Subclass of
399+
L</Bitcoin::Crypto::Exception::Base58>.
400+
401+
=head2 Bitcoin::Crypto::Exception::Bech32
402+
403+
Thrown when a general Bech32 format problem is detected.
404+
405+
=head2 Bitcoin::Crypto::Exception::Bech32InputFormat
406+
407+
Thrown when input does not look like valid bech32. Subclass of
408+
L</Bitcoin::Crypto::Exception::Bech32>.
409+
410+
=head2 Bitcoin::Crypto::Exception::Bech32InputData
411+
412+
Thrown when input is valid bech32, but contains invalid data. Subclass of
413+
L</Bitcoin::Crypto::Exception::Bech32>.
414+
415+
=head2 Bitcoin::Crypto::Exception::Bech32InputChecksum
416+
417+
Thrown when bech32 input checksum is invalid. Subclass of
418+
L</Bitcoin::Crypto::Exception::Bech32>.
419+
420+
=head2 Bitcoin::Crypto::Exception::SegwitProgram
421+
422+
Thrown when an issue with Segregated Witness program is detected.
423+
424+
=head2 Bitcoin::Crypto::Exception::ScriptType
425+
426+
Thrown when an unexpected script type is encountered.
427+
428+
=head2 Bitcoin::Crypto::Exception::ScriptOpcode
429+
430+
Thrown when unexpected script operation is encountered.
431+
432+
=head2 Bitcoin::Crypto::Exception::ScriptPush
433+
434+
Thrown when bad script push operation is performed.
435+
436+
=head2 Bitcoin::Crypto::Exception::Block
437+
438+
Thrown when a general problem with a block is detected.
439+
440+
=head2 Bitcoin::Crypto::Exception::ScriptTree
441+
442+
Thrown when a general problem with a script tree is detected.
443+
444+
=head2 Bitcoin::Crypto::Exception::ScriptCompilation
445+
446+
Thrown when a script compilation fails. It can only be thrown just
447+
before the script is executed.
448+
449+
=head2 Bitcoin::Crypto::Exception::ScriptRuntime
450+
451+
Thrown when an error occurs during script runtime.
452+
453+
=head2 Bitcoin::Crypto::Exception::TransactionScript
454+
455+
Thrown when an error occurs in execution of scripts during
456+
transaction validation. Subclass of
457+
L</Bitcoin::Crypto::Exception::Transaction> and
458+
L</Bitcoin::Crypto::Exception::ScriptRuntime>.
459+
460+
=head2 Bitcoin::Crypto::Exception::NetworkCheck
461+
462+
Thrown when an assumption about network is not met. This can happen
463+
in single-network mode or if a network parameter is used, but it
464+
does not match the arguments.
465+
466+
=head2 Bitcoin::Crypto::Exception::NetworkConfig
467+
468+
Thrown when network configuration is bad or insufficient to perform
469+
the operation.
470+
471+
=head2 Bitcoin::Crypto::Exception::Address
472+
473+
Thrown when a general error connected to addresses is encountered.
474+
475+
=head2 Bitcoin::Crypto::Exception::AddressGenerate
476+
477+
Thrown when an error is encountered while generating an address. Subclass of
478+
L</Bitcoin::Crypto::Exception::Address>.
479+
480+
=head2 Bitcoin::Crypto::Exception::PSBT
481+
482+
Thrown when a problem with PSBT format was encountered.
483+
358484
=head1 INTERFACE
359485
360486
=head2 Attributes

‎lib/Bitcoin/Crypto/Key/ExtPrivate.pm‎

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -369,26 +369,6 @@ configuration set in the extended key will be used.>
369369
370370
Returns a fingerprint of the extended key of C<$len> length (byte string)
371371
372-
=head1 EXCEPTIONS
373-
374-
This module throws an instance of L<Bitcoin::Crypto::Exception> if it
375-
encounters an error. It can produce the following error types from the
376-
L<Bitcoin::Crypto::Exception> namespace:
377-
378-
=over
379-
380-
=item * MnemonicGenerate - mnemonic couldn't be generated correctly
381-
382-
=item * MnemonicCheck - mnemonic didn't pass the validity check
383-
384-
=item * KeyDerive - key couldn't be derived correctly
385-
386-
=item * KeyCreate - key couldn't be created correctly
387-
388-
=item * NetworkConfig - incomplete or corrupted network configuration
389-
390-
=back
391-
392372
=head1 SEE ALSO
393373
394374
=over

‎lib/Bitcoin/Crypto/Key/ExtPublic.pm‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -200,22 +200,6 @@ account, effectively only using C<change> and C<index> attributes.
200200
201201
Returns a fingerprint of the extended key of C<$len> length (byte string)
202202
203-
=head1 EXCEPTIONS
204-
205-
This module throws an instance of L<Bitcoin::Crypto::Exception> if it
206-
encounters an error. It can produce the following error types from the
207-
L<Bitcoin::Crypto::Exception> namespace:
208-
209-
=over
210-
211-
=item * KeyDerive - key couldn't be derived correctly
212-
213-
=item * KeyCreate - key couldn't be created correctly
214-
215-
=item * NetworkConfig - incomplete or corrupted network configuration
216-
217-
=back
218-
219203
=head1 SEE ALSO
220204
221205
=over

‎lib/Bitcoin/Crypto/Key/Private.pm‎

Lines changed: 0 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -360,26 +360,6 @@ function to fail. You can encode like this (for UTF-8):
360360
use Encode qw(encode);
361361
$message = encode('UTF-8', $message);
362362
363-
=head1 EXCEPTIONS
364-
365-
This module throws an instance of L<Bitcoin::Crypto::Exception> if it
366-
encounters an error. It can produce the following error types from the
367-
L<Bitcoin::Crypto::Exception> namespace:
368-
369-
=over
370-
371-
=item * Sign - couldn't sign the message correctly
372-
373-
=item * ScriptType - couldn't automatically sign the given script type
374-
375-
=item * Verify - couldn't verify the message correctly
376-
377-
=item * KeyCreate - key couldn't be created correctly
378-
379-
=item * NetworkConfig - incomplete or corrupted network configuration
380-
381-
=back
382-
383363
=head1 SEE ALSO
384364
385365
=over

‎lib/Bitcoin/Crypto/Key/Public.pm‎

Lines changed: 0 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -405,24 +405,6 @@ B<NOTE>: The rules this function uses to choose the address type B<will>
405405
change when more up-to-date address types are implemented. Use
406406
other address functions if this is not what you want.
407407
408-
=head1 EXCEPTIONS
409-
410-
This module throws an instance of L<Bitcoin::Crypto::Exception> if it
411-
encounters an error. It can produce the following error types from the
412-
L<Bitcoin::Crypto::Exception> namespace:
413-
414-
=over
415-
416-
=item * KeyCreate - key couldn't be created correctly
417-
418-
=item * Verify - couldn't verify the message correctly
419-
420-
=item * NetworkConfig - incomplete or corrupted network configuration
421-
422-
=item * AddressGenerate - address could not be generated (see BIP44 constraint notes)
423-
424-
=back
425-
426408
=head1 SEE ALSO
427409
428410
L<Bitcoin::Crypto::Key::Private>

‎lib/Bitcoin/Crypto/Manual.pod‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -134,18 +134,20 @@ Perl. However, we reserve the right to break it in the following cases:
134134

135135
=back
136136

137-
=head3 How to read the documentation?
138-
139-
Most functions in this documentation have a code snippet showcasing the arguments
140-
used by the function. These lines are not meant to be valid Perl. They're there
141-
for you to understand what arguments the function expects.
142-
143-
Packages in this module often have types of their thrown exceptions
144-
documented near the bottom of the document. The exceptions section may be
145-
useful to understand which types of exceptions can be thrown when using
146-
functions or methods from the package and what they mean. It is not meant to be
147-
a full list of exceptions a function can throw and unblessed errors may still
148-
be raised occasionally.
137+
=head3 Exceptions
138+
139+
This module tries hard not to throw any unblessed exceptions. Most exceptions
140+
should be caught and turned into a subclass of L<Bitcoin::Crypto::Exception>,
141+
or the main class if no specific subclass exists for the exception. However,
142+
unblessed errors may still happen occasionally.
143+
144+
Refer to L<Bitcoin::Crypto::Exception/EXCEPTION SUBCLASSES> for a list of
145+
exceptions used by the module.
146+
147+
Note that removing completely subclass of exceptions is not considered
148+
backward-incompatible, as checking for non-existent class through C<isa> does
149+
no harm. Renaming an exception subclass or merging it into another subclass is
150+
an incompatibility and will be done only after a deprecation period.
149151

150152
=head3 Class shortcuts
151153

‎lib/Bitcoin/Crypto/PSBT.pm‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -750,18 +750,6 @@ B<Value data:> Array reference, where first item is an array of leaf hashes, sec
750750
751751
=back
752752
753-
=head1 EXCEPTIONS
754-
755-
This module throws an instance of L<Bitcoin::Crypto::Exception> if it
756-
encounters an error. It can produce the following error types from the
757-
L<Bitcoin::Crypto::Exception> namespace:
758-
759-
=over
760-
761-
=item * PSBT - general error with the PSBT
762-
763-
=back
764-
765753
=head1 SEE ALSO
766754
767755
=over

0 commit comments

Comments
 (0)