NAME

Assert::Refute::Build - tool for extending Assert::Refute suite

DESCRIPTION

Although arbitrary checks may be created using just the refute function, they may be cumbersome to use and especially share.

This module takes care of some boilerplate as well as maintains parity between functional and object-oriented interfaces of Assert::Refute.

SYNOPSIS

Extending the test suite goes as follows:

    package My::Package;
    use Assert::Refute::Build;
    use parent qw(Exporter);

    build_refute is_everything => sub {
        return if $_[0] == 42;
        return "$_[0] is not answer to life, universe, and everything";
    }, export => 1, args => 1;

    1;

This can be later used inside production code to check a condition:

    use Assert::Refute qw(:all);
    use My::Package;
    my $fun_check = contract {
        is_everything( shift );
    };
    my $oo_check = contract {
        $_[0]->is_everything( $_[1] );
    }, need_object => 1;
    # ditto

    # apply $fun_check or $oo_check to a variable, get result

    my $log = $oo_check->apply(137);
    $log->is_passing; # nope
    $log->get_tap;    # get details

This call will create a prototyped function is_everything(...) in the calling package, with args positional parameters and an optional human-readable message. (Think ok 1, ok 1 'test passed').

FUNCTIONS

All functions are exportable.

build_refute name => \&CODE, %options

This function

• accepts a subroutine reference that returns a false value on success and a brief description of the discrepancy on failure (e.g. "$got != $expected");

  Note that this function does not need to know anything about the testing environment it is in, it just cares about its arguments (think pure function).

• builds an exportable wrapper around it that would talk to the most recent Assert::Refute::Exec instance;

• adds a method with the same name to Assert::Refute::Exec so that object-oriented and functional interfaces are as close to each other as possible.

As a side effect, Assert::Refute's internals are added to the caller's @CARP_NOT array so that carp/croak points to where the built function is actually used.

NOTE One needs to use Exporter explicitly if either export or export_ok option is in use. This MAY change in the future.

Options may include:

• export => 1 - add function to @EXPORT (Exporter still has to be used by target module explicitly).

• export_ok => 1 - add function to @EXPORT_OK (don't export by default).

• no_create => 1 - don't generate a function at all, just add to Assert::Refute's methods.

• manual => 1 - don't generate any code. Instead, assume that user has already done that and just add a method to Assert::Refute::Exec and a prototyped exportable wrapper.

  This may be useful to create refutations based on subcontract or such.

  [EXPERIMENTAL].

• args => nnn - number of arguments. This will generate a prototyped function accepting nnn scalars + optional description.

• list => 1 - create a list prototype instead. Mutually exclusive with args.

• block => 1 - create a block function.

• no_proto => 1 - skip prototype, function will have to be called with parentheses.

The name must not start with set_, get_, or do_. Also colliding with a previously defined name would case an exception.

current_contract

Returns a Assert::Refute::Exec object. Dies if no contract is being executed at the time.

to_scalar

Convert an arbitrary data structure to a human-readable string.

• to_scalar( undef ) # returns '(undef)'

• to_scalar( string ) # returns the string as is in quotes

• to_scalar( \%ref || \@array, $depth )

  Only goes $depth levels deep. Default depth is 1.

Hashes/arrays are only penetrated 1 level deep by default.

undef is returned as "(undef)" so it can't be confused with other types.

Strings are quoted unless numeric or depth is omitted.

Refs are returned as My::Module/1a2c3f (NOT in perl's own format My::Module=HASH(0x20f9190)). This MAY change in the future.

LICENSE AND COPYRIGHT

This module is part of Assert::Refute suite.

Copyright 2017 Konstantin S. Uvarin. <khedin at gmail.com>

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cpanm Assert::Refute

perl -MCPAN -e shell
install Assert::Refute