The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Assert-Conditional-0.004
River stage one • 1 direct dependent • 1 total dependent
3 ++
/ Assert::Conditional::Utils

NAME

Assert::Conditional::Utils - Utility functions for conditionally compiling 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 old 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

%N_PLURAL, %PLURAL, $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_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, panic, sig_name2num, sig_num2longname, sig_num2name, subname_or_code, UCA, uca_cmp, uca_sort, UCA1, uca1_cmp, UCA2, uca2_cmp, UCA3, uca3_cmp, UCA4, and uca4_cmp.

: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_series and uca_sort.

:sigmappers

sig_name2num, sig_num2longname, and sig_num2name.

:unicode

UCA, uca_cmp, uca_sort, UCA1, uca1_cmp, UCA2, uca2_cmp, UCA3, uca3_cmp, UCA4, and uca4_cmp.

:vars

$Assert_Always, $Assert_Carp, $Assert_Debug, and $Assert_Never.

Exported Functions

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.

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.

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 alpha release.

AUTHOR

Tom Christiansen <tchrist@perl.com>

LICENCE AND COPYRIGHT

Copyright (c) 2015, 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.

__DATA__