Assert::Conditional::Utils - Utility functions for conditionally-compiled assertions
use Assert::Conditional::Utils qw(panic NOT_REACHED); $big > $little || panic("Impossible for $big > $little"); chdir("/") || panic("Your root filesystem is corrupt: $!"); if ($x) { ... } elsif ($y) { ... } elsif ($z) { ... } else { NOT_REACHED }
This module is used by the Assert::Conditional module for most of the non-assert functions it needs. Because this module is still in alpha release, the two examples above should be the only guaranteed serviceable parts.
It is possible (but in alpha release, not necessarily advised) to use the botch function to write your own assertions that work like those in Assert::Conditional.
botch
The panic function is for internal errors that should never happen. Unlike its cousin botch, it is not controllable through the ASSERT_CONDITIONAL variable.
panic
ASSERT_CONDITIONAL
Use NOT_REACHED for some case that can "never" happen.
NOT_REACHED
Here is the list of the support global variables, available for import, which are normally controlled by the ASSERT_CONDITIONAL environment variable.
$Assert_Never
Set by default under ASSERT_CONDITIONAL=never.
ASSERT_CONDITIONAL=never
Assertions are never imported, and even if you somehow manage to import them, they will never never make a peep nor raise an exception.
$Assert_Always
Set by default under ASSERT_CONDITIONAL=always.
ASSERT_CONDITIONAL=always
Assertions are always imported, and even if you somehow manage to avoid importing them, they will still raise an exception on error.
$Assert_Carp
Set by default under ASSERT_CONDITIONAL=carp.
ASSERT_CONDITIONAL=carp
Assertions are always imported but they do not raise an exception if they fail; instead they all carp at you. This is true even if you manage to call an assertion you haven't imported.
A few others exist, but you should probably not pay attention to them.
Here is the list of all exported functions with their prototypes:
botch ( $ ) ; botch_argc ( $$ ) ; botch_array_length ( $$ ) ; botch_false ( ) ; botch_have_thing_wanted ( @ ) ; botch_undef ( ) ; code_of_coderef ( $ ) ; commify_series ; dump_exports ( @ ) ; dump_package_exports ( $@ ) ; Export ; FIXME ( ) ; his_args ( ;$ ) ; his_assert ( ) ; his_context ( ;$ ) ; his_filename ( ;$ ) ; his_frame ( ;$ ) ; his_is_require ( ;$ ) ; his_line ( ;$ ) ; his_package ( ;$ ) ; his_sub ( ;$ ) ; his_subroutine ( ;$ ) ; name_of_coderef ( $ ) ; NOT_REACHED ( ) ; panic ( $ ) ; sig_name2num ( $ ) ; sig_num2longname ( $ ) ; sig_num2name ( $ ) ; subname_or_code ( $ ) ; UCA ( _ ) ; UCA1 ( _ ) ; uca1_cmp ( $$ ) ; UCA2 ( _ ) ; uca2_cmp ( $$ ) ; UCA3 ( _ ) ; uca3_cmp ( $$ ) ; UCA4 ( _ ) ; uca4_cmp ( $$ ) ; uca_cmp ( $$ ) ; uca_sort ( @ ) ;
Available exports are grouped by the following tags:
:all
"$Allow_Handlers", "$Assert_Always", "$Assert_Carp", "$Assert_Debug", "$Assert_Never", "botch", "botch_argc", "botch_array_length", "botch_false", "botch_have_thing_wanted", "botch_undef", "CALLER_BITMASK", "CALLER_EVALTEXT", "CALLER_FILENAME", "CALLER_HASARGS", "CALLER_HINTHASH", "CALLER_HINTS", "CALLER_IS_REQUIRE", "CALLER_LINE", "CALLER_PACKAGE", "CALLER_SUBROUTINE", "CALLER_WANTARRAY", "code_of_coderef", "commify_and", "commify_but", "commify_nor", "commify_or", "commify_series", "dump_exports", "dump_package_exports", "FIXME", "his_args", "his_assert", "his_context", "his_filename", "his_frame", "his_is_require", "his_line", "his_package", "his_sub", "his_subroutine", "name_of_coderef", "NOT_REACHED", "%N_PLURAL", "panic", "%PLURAL", "quotify_and", "quotify_but", "quotify_nor", "quotify_or", "sig_name2num", "sig_num2longname", "sig_num2name", "subname_or_code", "UCA", "UCA1", "uca1_cmp", "UCA2", "uca2_cmp", "UCA3", "uca3_cmp", "UCA4", "uca4_cmp", "uca_cmp", and "uca_sort".
:acme_plurals
"%N_PLURAL" and "%PLURAL".
:botch
"botch", "botch_argc", "botch_array_length", "botch_false", "botch_have_thing_wanted", "botch_undef", and "panic".
:CALLER
"CALLER_BITMASK", "CALLER_EVALTEXT", "CALLER_FILENAME", "CALLER_HASARGS", "CALLER_HINTHASH", "CALLER_HINTS", "CALLER_IS_REQUIRE", "CALLER_LINE", "CALLER_PACKAGE", "CALLER_SUBROUTINE", and "CALLER_WANTARRAY".
:code
"code_of_coderef", "name_of_coderef", and "subname_or_code".
:exports
"dump_exports" and "dump_package_exports".
:frame
"CALLER_BITMASK", "CALLER_EVALTEXT", "CALLER_FILENAME", "CALLER_HASARGS", "CALLER_HINTHASH", "CALLER_HINTS", "CALLER_IS_REQUIRE", "CALLER_LINE", "CALLER_PACKAGE", "CALLER_SUBROUTINE", "CALLER_WANTARRAY", "his_args", "his_assert", "his_context", "his_filename", "his_frame", "his_is_require", "his_line", "his_package", "his_sub", and "his_subroutine".
:lint
"FIXME", "NOT_REACHED", and "panic".
:list
"commify_and", "commify_but", "commify_nor", "commify_or", "commify_series", "quotify_and", "quotify_but", "quotify_nor", "quotify_or", and "uca_sort".
:sigmappers
"sig_name2num", "sig_num2longname", and "sig_num2name".
:unicode
"UCA", "UCA1", "uca1_cmp", "UCA2", "uca2_cmp", "UCA3", "uca3_cmp", "UCA4", "uca4_cmp", "uca_cmp", and "uca_sort".
:vars
"$Allow_Handlers", "$Assert_Always", "$Assert_Carp", "$Assert_Debug", and "$Assert_Never".
About the only thing here that's "public" is "botch" and the sig* name-to-number mapping functions. The rest are internal and shouldn't be relied on.
sig*
botch($)
The main way that assertions fail. Normally it raises an exception by calling Carp::confess, but this can be controlled using the ASSERT_CONDITIONAL environment variable or its associated package variables as previously described.
Carp::confess
We crawl up the stack to find the highest function named assert_* to use for the message. That way when an assertion calls another assertion and that second one fails, the reported message uses the name of the first one.
assert_*
botch_false()
A way to panic if something is false but shouldn't be.
botch_undef()
A way to panic if something is undef but shouldn't be.
botch_argc($$)
botch_array_length($$)
botch_have_thing_wanted(@)
panic(MESSAGE)
This function is used for internal errors that should never happen. It calls Carp::confess with a prefix indicating that it is an internal error.
FIXME
Code you haven't gotten to yet.
Put this in places that you think you can never reach in your code.
his_assert()
his_args(;$)
his_frame(;$)
his_package(;$)
his_filename(;$)
his_line(;$)
his_subroutine(;$)
his_sub(;$)
his_context(;$)
his_is_require(;$)
code_of_coderef(CODEREF)
Return the code but not the name of the code reference passed.
name_of_coderef(CODEREF)
Return the name of the code reference passed.
subname_or_code(CODEREF)
Return the name of the code reference passed if it is not anonymous; otherwise return its code.
commify_series
dump_exports(@)
dump_package_exports($@)
UCA(_)
UCA1(_)
UCA2(_)
UCA3(_)
UCA4(_)
uca_cmp($$)
uca1_cmp($$)
uca2_cmp($$)
uca3_cmp($$)
uca4_cmp($$)
uca_sort(@)
Return its argument list sorted alphabetically.
sig_num2name(NUMBER)
Returns the name of the signal number, like HUP, INT, etc.
HUP
INT
sig_num2longname($)
Returns the long name of the signal number, like SIGHUP, SIGINT, etc.
SIGHUP
SIGINT
sig_name2num(NAME)
Returns the signal number corresponding to the passed in name.
The ASSERT_CONDITIONAL variable controls the behavior of the botch function, and also of the the conditional importing itself.
The ASSERT_CONDITIONAL_BUILD_POD variable is used internally.
ASSERT_CONDITIONAL_BUILD_POD
The Assert::Conditional module that uses these utilities and the Exporter::ConditionalSubs module which that module is based on.
Probably many. This is an beta release.
Tom Christiansen <tchrist@perl.com>
<tchrist@perl.com>
Copyright (c) 2015-2018 Tom Christiansen <tchrist@perl.com>. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
To install Assert::Conditional, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Assert::Conditional
CPAN shell
perl -MCPAN -e shell install Assert::Conditional
For more information on module installation, please visit the detailed CPAN module installation guide.