/ 
Assert-Conditional-v0.010
River stage one • 1 direct dependent • 1 total dependent
/ Assert::Conditional::Utils

NAME

Assert::Conditional::Utils - Utility functions for conditionally-compiled assertions

SYNOPSIS

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 }

DESCRIPTION

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.

The panic function is for internal errors that should never happen. Unlike its cousin botch, it is not controllable through the ASSERT_CONDITIONAL variable.

Use NOT_REACHED for some case that can "never" happen.

Exported Variables

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.

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.

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.

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.

Exported Functions

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                (  @  ) ;

Export Tags

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".

Exported Functions

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.

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.

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.

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.

NOT_REACHED

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.

sig_num2longname($)

Returns the long name of the signal number, like SIGHUP, SIGINT, etc.

sub sig_name2num(NAME)

Returns the signal number corresponding to the passed in name.

ENVIRONMENT

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.

SEE ALSO

The Assert::Conditional module that uses these utilities and the Exporter::ConditionalSubs module which that module is based on.

BUGS AND LIMITATIONS

Probably many. This is an beta release.

AUTHOR

Tom Christiansen <tchrist@perl.com>

LICENCE AND COPYRIGHT

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.