package Test::Builder;

use 5.004;

# $^C was only introduced in 5.005-ish.  We do this to prevent

# use of uninitialized value warnings in older perls.

$^C ||= 0;

use strict;

use vars qw($VERSION);

$VERSION = '0.30';

$VERSION = eval $VERSION;    # make the alpha version come out as a number

# Make Test::Builder thread-safe for ithreads.

BEGIN {

    use Config;

    # Load threads::shared when threads are turned on

    if( $] >= 5.008 && $Config{useithreads} && $INC{'threads.pm'}) {

        require threads::shared;

        # Hack around YET ANOTHER threads::shared bug.  It would 

        # occassionally forget the contents of the variable when sharing it.

        # So we first copy the data, then share, then put our copy back.

        *share = sub (\[$@%]) {

            my $type = ref $_[0];

            my $data;

            if( $type eq 'HASH' ) {

                %$data = %{$_[0]};

            }

            elsif( $type eq 'ARRAY' ) {

                @$data = @{$_[0]};

            }

            elsif( $type eq 'SCALAR' ) {

                $$data = ${$_[0]};

            }

            else {

                die "Unknown type: ".$type;

            }

            $_[0] = &threads::shared::share($_[0]);

            if( $type eq 'HASH' ) {

                %{$_[0]} = %$data;

            }

            elsif( $type eq 'ARRAY' ) {

                @{$_[0]} = @$data;

            }

            elsif( $type eq 'SCALAR' ) {

                ${$_[0]} = $$data;

            }

            else {

                die "Unknown type: ".$type;

            }

            return $_[0];

        };

    }

    # 5.8.0's threads::shared is busted when threads are off.

    # We emulate it here.

    else {

        *share = sub { return $_[0] };

        *lock  = sub { 0 };

    }

}

=head1 NAME

Test::Builder - Backend for building test libraries

=head1 SYNOPSIS

  package My::Test::Module;

  use Test::Builder;

  require Exporter;

  @ISA = qw(Exporter);

  @EXPORT = qw(ok);

  my $Test = Test::Builder->new;

  $Test->output('my_logfile');

  sub import {

      my($self) = shift;

      my $pack = caller;

      $Test->exported_to($pack);

      $Test->plan(@_);

      $self->export_to_level(1, $self, 'ok');

  }

  sub ok {

      my($test, $name) = @_;

      $Test->ok($test, $name);

  }

=head1 DESCRIPTION

Test::Simple and Test::More have proven to be popular testing modules,

but they're not always flexible enough.  Test::Builder provides the a

building block upon which to write your own test libraries I

work together>.

=head2 Construction

=over 4

=item B<new>

  my $Test = Test::Builder->new;

Returns a Test::Builder object representing the current state of the

test.

Since you only run one test per program C<new> always returns the same

Test::Builder object.  No matter how many times you call new(), you're

getting the same object.  This is called a singleton.  This is done so that

multiple modules share such global information as the test counter and

where test output is going.

If you want a completely new Test::Builder object different from the

singleton, use C<create>.

=cut

my $Test = Test::Builder->new;

sub new {

    my($class) = shift;

    $Test ||= $class->create;

    return $Test;

}

=item B<create>

  my $Test = Test::Builder->create;

Ok, so there can be more than one Test::Builder object and this is how

you get it.  You might use this instead of C<new()> if you're testing

a Test::Builder based module, but otherwise you probably want C<new>.

B<NOTE>: the implementation is not complete.  C<level>, for example, is

still shared amongst B<all> Test::Builder objects, even ones created using

this method.  Also, the method name may change in the future.

=cut

sub create {

    my $class = shift;

    my $self = bless {}, $class;

    $self->reset;

    return $self;

}

=item B<reset>

  $Test->reset;

Reinitializes the Test::Builder singleton to its original state.

Mostly useful for tests run in persistent environments where the same

test might be run multiple times in the same process.

=cut

use vars qw($Level);

sub reset {

    my ($self) = @_;

    # We leave this a global because it has to be localized and localizing

    # hash keys is just asking for pain.  Also, it was documented.

    $Level = 1;

    $self->{Test_Died}    = 0;

    $self->{Have_Plan}    = 0;

    $self->{No_Plan}      = 0;

    $self->{Original_Pid} = $$;

    share($self->{Curr_Test});

    $self->{Curr_Test}    = 0;

    $self->{Test_Results} = &share([]);

    $self->{Exported_To}    = undef;

    $self->{Expected_Tests} = 0;

    $self->{Skip_All}   = 0;

    $self->{Use_Nums}   = 1;

    $self->{No_Header}  = 0;

    $self->{No_Ending}  = 0;

    $self->_dup_stdhandles unless $^C;

    return undef;

}

=back

=head2 Setting up tests

These methods are for setting up tests and declaring how many there

are.  You usually only want to call one of these methods.

=over 4

=item B<exported_to>

  my $pack = $Test->exported_to;

  $Test->exported_to($pack);

Tells Test::Builder what package you exported your functions to.

This is important for getting TODO tests right.

=cut

sub exported_to {

    my($self, $pack) = @_;

    if( defined $pack ) {

        $self->{Exported_To} = $pack;

    }

    return $self->{Exported_To};

}

=item B<plan>

  $Test->plan('no_plan');

  $Test->plan( skip_all => $reason );

  $Test->plan( tests => $num_tests );

A convenient way to set up your tests.  Call this and Test::Builder

will print the appropriate headers and take the appropriate actions.

If you call plan(), don't call any of the other methods below.

=cut

sub plan {

    my($self, $cmd, $arg) = @_;

    return unless $cmd;

    if( $self->{Have_Plan} ) {

        die sprintf "You tried to plan twice!  Second plan at %s line %d\n",

          ($self->caller)[1,2];

    }

    if( $cmd eq 'no_plan' ) {

        $self->no_plan;

    }

    elsif( $cmd eq 'skip_all' ) {

        return $self->skip_all($arg);

    }

    elsif( $cmd eq 'tests' ) {

        if( $arg ) {

            return $self->expected_tests($arg);

        }

        elsif( !defined $arg ) {

            die "Got an undefined number of tests.  Looks like you tried to ".

                "say how many tests you plan to run but made a mistake.\n";

        }

        elsif( !$arg ) {

            die "You said to run 0 tests!  You've got to run something.\n";

        }

    }

    else {

        require Carp;

        my @args = grep { defined } ($cmd, $arg);

        Carp::croak("plan() doesn't understand @args");

    }

    return 1;

}

=item B<expected_tests>

    my $max = $Test->expected_tests;

    $Test->expected_tests($max);

Gets/sets the # of tests we expect this test to run and prints out

the appropriate headers.

=cut

sub expected_tests {

    my $self = shift;

    my($max) = @_;

    if( @_ ) {

        die "Number of tests must be a postive integer.  You gave it '$max'.\n"

          unless $max =~ /^\+?\d+$/ and $max > 0;

        $self->{Expected_Tests} = $max;

        $self->{Have_Plan}      = 1;

        $self->_print("1..$max\n") unless $self->no_header;

    }

    return $self->{Expected_Tests};

}

=item B<no_plan>

  $Test->no_plan;

Declares that this test will run an indeterminate # of tests.

=cut

sub no_plan {

    my $self = shift;

    $self->{No_Plan}   = 1;

    $self->{Have_Plan} = 1;

}

=item B<has_plan>

  $plan = $Test->has_plan

Find out whether a plan has been defined. $plan is either C<undef> (no plan has been set), C<no_plan> (indeterminate # of tests) or an integer (the number of expected tests).

=cut

sub has_plan {

    my $self = shift;

    return($self->{Expected_Tests}) if $self->{Expected_Tests};

    return('no_plan') if $self->{No_Plan};

    return(undef);

};

=item B<skip_all>

  $Test->skip_all;

  $Test->skip_all($reason);

Skips all the tests, using the given $reason.  Exits immediately with 0.

=cut

sub skip_all {

    my($self, $reason) = @_;

    my $out = "1..0";

    $out .= " # Skip $reason" if $reason;

    $out .= "\n";

    $self->{Skip_All} = 1;

    $self->_print($out) unless $self->no_header;

    exit(0);

}

=back

=head2 Running tests

These actually run the tests, analogous to the functions in

Test::More.

$name is always optional.

=over 4

=item B<ok>

  $Test->ok($test, $name);

Your basic test.  Pass if $test is true, fail if $test is false.  Just

like Test::Simple's ok().

=cut

sub ok {

    my($self, $test, $name) = @_;

    # $test might contain an object which we don't want to accidentally

    # store, so we turn it into a boolean.

    $test = $test ? 1 : 0;

    unless( $self->{Have_Plan} ) {

        require Carp;

        Carp::croak("You tried to run a test without a plan!  Gotta have a plan.");

    }

    lock $self->{Curr_Test};

    $self->{Curr_Test}++;

    # In case $name is a string overloaded object, force it to stringify.

    $self->_unoverload(\$name);

    $self->diag(<

    You named your test '$name'.  You shouldn't use numbers for your test names.

    Very confusing.

ERR

    my($pack, $file, $line) = $self->caller;

    my $todo = $self->todo($pack);

    $self->_unoverload(\$todo);

    my $out;

    my $result = &share({});

    unless( $test ) {

        $out .= "not ";

        @$result{ 'ok', 'actual_ok' } = ( ( $todo ? 1 : 0 ), 0 );

    }

    else {

        @$result{ 'ok', 'actual_ok' } = ( 1, $test );

    }

    $out .= "ok";

    $out .= " $self->{Curr_Test}" if $self->use_numbers;

    if( defined $name ) {

        $name =~ s|#|\\#|g;     # # in a name can confuse Test::Harness.

        $out   .= " - $name";

        $result->{name} = $name;

    }

    else {

        $result->{name} = '';

    }

    if( $todo ) {

        $out   .= " # TODO $todo";

        $result->{reason} = $todo;

        $result->{type}   = 'todo';

    }

    else {

        $result->{reason} = '';

        $result->{type}   = '';

    }

    $self->{Test_Results}[$self->{Curr_Test}-1] = $result;

    $out .= "\n";

    $self->_print($out);

    unless( $test ) {

        my $msg = $todo ? "Failed (TODO)" : "Failed";

        $self->_print_diag("\n") if $ENV{HARNESS_ACTIVE};

        $self->diag("    $msg test ($file at line $line)\n");

    } 

    return $test ? 1 : 0;

}

sub _unoverload {

    my $self  = shift;

    local($@,$!);

    eval { require overload } || return;

    foreach my $thing (@_) {

        eval { 

            if( defined $$thing ) {

                if( my $string_meth = overload::Method($$thing, '""') ) {

                    $$thing = $$thing->$string_meth();

                }

            }

        };

    }

}

=item B<is_eq>

  $Test->is_eq($got, $expected, $name);

Like Test::More's is().  Checks if $got eq $expected.  This is the

string version.

=item B<is_num>

  $Test->is_num($got, $expected, $name);

Like Test::More's is().  Checks if $got == $expected.  This is the

numeric version.

=cut

sub is_eq {

    my($self, $got, $expect, $name) = @_;

    local $Level = $Level + 1;

    if( !defined $got || !defined $expect ) {

        # undef only matches undef and nothing else

        my $test = !defined $got && !defined $expect;

        $self->ok($test, $name);

        $self->_is_diag($got, 'eq', $expect) unless $test;

        return $test;

    }

    return $self->cmp_ok($got, 'eq', $expect, $name);

}

sub is_num {

    my($self, $got, $expect, $name) = @_;

    local $Level = $Level + 1;

    if( !defined $got || !defined $expect ) {

        # undef only matches undef and nothing else

        my $test = !defined $got && !defined $expect;

        $self->ok($test, $name);

        $self->_is_diag($got, '==', $expect) unless $test;

        return $test;

    }

    return $self->cmp_ok($got, '==', $expect, $name);

}

sub _is_diag {

    my($self, $got, $type, $expect) = @_;

    foreach my $val (\$got, \$expect) {

        if( defined $$val ) {

            if( $type eq 'eq' ) {

                # quote and force string context

                $$val = "'$$val'"

            }

            else {

                # force numeric context

                $$val = $$val+0;

            }

        }

        else {

            $$val = 'undef';

        }

    }

    return $self->diag(sprintf <

         got: %s

    expected: %s

DIAGNOSTIC

}    

=item B<isnt_eq>

  $Test->isnt_eq($got, $dont_expect, $name);

Like Test::More's isnt().  Checks if $got ne $dont_expect.  This is

the string version.

=item B<isnt_num>

  $Test->is_num($got, $dont_expect, $name);

Like Test::More's isnt().  Checks if $got ne $dont_expect.  This is

the numeric version.

=cut

sub isnt_eq {

    my($self, $got, $dont_expect, $name) = @_;

    local $Level = $Level + 1;

    if( !defined $got || !defined $dont_expect ) {

        # undef only matches undef and nothing else

        my $test = defined $got || defined $dont_expect;

        $self->ok($test, $name);

        $self->_cmp_diag($got, 'ne', $dont_expect) unless $test;

        return $test;

    }

    return $self->cmp_ok($got, 'ne', $dont_expect, $name);

}

sub isnt_num {

    my($self, $got, $dont_expect, $name) = @_;

    local $Level = $Level + 1;

    if( !defined $got || !defined $dont_expect ) {

        # undef only matches undef and nothing else

        my $test = defined $got || defined $dont_expect;

        $self->ok($test, $name);

        $self->_cmp_diag($got, '!=', $dont_expect) unless $test;

        return $test;

    }

    return $self->cmp_ok($got, '!=', $dont_expect, $name);

}

=item B<like>

  $Test->like($this, qr/$regex/, $name);

  $Test->like($this, '/$regex/', $name);

Like Test::More's like().  Checks if $this matches the given $regex.

You'll want to avoid qr// if you want your tests to work before 5.005.

=item B<unlike>

  $Test->unlike($this, qr/$regex/, $name);

  $Test->unlike($this, '/$regex/', $name);

Like Test::More's unlike().  Checks if $this B<does not match> the

given $regex.

=cut

sub like {

    my($self, $this, $regex, $name) = @_;

    local $Level = $Level + 1;

    $self->_regex_ok($this, $regex, '=~', $name);

}

sub unlike {

    my($self, $this, $regex, $name) = @_;

    local $Level = $Level + 1;

    $self->_regex_ok($this, $regex, '!~', $name);

}

=item B<maybe_regex>

  $Test->maybe_regex(qr/$regex/);

  $Test->maybe_regex('/$regex/');

Convenience method for building testing functions that take regular

expressions as arguments, but need to work before perl 5.005.

Takes a quoted regular expression produced by qr//, or a string

representing a regular expression.

Returns a Perl value which may be used instead of the corresponding

regular expression, or undef if it's argument is not recognised.

For example, a version of like(), sans the useful diagnostic messages,

could be written as:

  sub laconic_like {

      my ($self, $this, $regex, $name) = @_;

      my $usable_regex = $self->maybe_regex($regex);

      die "expecting regex, found '$regex'\n"

          unless $usable_regex;

      $self->ok($this =~ m/$usable_regex/, $name);

  }

=cut

sub maybe_regex {

    my ($self, $regex) = @_;

    my $usable_regex = undef;

    return $usable_regex unless defined $regex;

    my($re, $opts);

    # Check for qr/foo/

    if( ref $regex eq 'Regexp' ) {

        $usable_regex = $regex;

    }

    # Check for '/foo/' or 'm,foo,'

    elsif( ($re, $opts)        = $regex =~ m{^ /(.*)/ (\w*) $ }sx           or

           (undef, $re, $opts) = $regex =~ m,^ m([^\w\s]) (.+) \1 (\w*) $,sx

         )

    {

        $usable_regex = length $opts ? "(?$opts)$re" : $re;

    }

    return $usable_regex;

};

sub _regex_ok {

    my($self, $this, $regex, $cmp, $name) = @_;

    local $Level = $Level + 1;

    my $ok = 0;

    my $usable_regex = $self->maybe_regex($regex);

    unless (defined $usable_regex) {

        $ok = $self->ok( 0, $name );

        $self->diag("    '$regex' doesn't look much like a regex to me.");

        return $ok;

    }

    {

        local $^W = 0;

        my $test = $this =~ /$usable_regex/ ? 1 : 0;

        $test = !$test if $cmp eq '!~';

        $ok = $self->ok( $test, $name );

    }

    unless( $ok ) {

        $this = defined $this ? "'$this'" : 'undef';

        my $match = $cmp eq '=~' ? "doesn't match" : "matches";

        $self->diag(sprintf <

                  %s

    %13s '%s'

DIAGNOSTIC

    }

    return $ok;

}

=item B<cmp_ok>

  $Test->cmp_ok($this, $type, $that, $name);

Works just like Test::More's cmp_ok().

    $Test->cmp_ok($big_num, '!=', $other_big_num);

=cut

sub cmp_ok {

    my($self, $got, $type, $expect, $name) = @_;

    my $test;

    {

        local $^W = 0;

        local($@,$!);   # don't interfere with $@

                        # eval() sometimes resets $!

        $test = eval "\$got $type \$expect";

    }

    local $Level = $Level + 1;

    my $ok = $self->ok($test, $name);

    unless( $ok ) {

        if( $type =~ /^(eq|==)$/ ) {

            $self->_is_diag($got, $type, $expect);

        }

        else {

            $self->_cmp_diag($got, $type, $expect);

        }

    }

    return $ok;

}

sub _cmp_diag {

    my($self, $got, $type, $expect) = @_;

    $got    = defined $got    ? "'$got'"    : 'undef';

    $expect = defined $expect ? "'$expect'" : 'undef';

    return $self->diag(sprintf <

    %s

        %s

    %s

DIAGNOSTIC

}

=item B<BAILOUT>

    $Test->BAILOUT($reason);

Indicates to the Test::Harness that things are going so badly all

testing should terminate.  This includes running any additional test

scripts.

It will exit with 255.

=cut

sub BAILOUT {

    my($self, $reason) = @_;

    $self->_print("Bail out!  $reason");

    exit 255;

}

=item B<skip>

    $Test->skip;

    $Test->skip($why);

Skips the current test, reporting $why.

=cut

sub skip {

    my($self, $why) = @_;

    $why ||= '';

    $self->_unoverload(\$why);

    unless( $self->{Have_Plan} ) {

        require Carp;

        Carp::croak("You tried to run tests without a plan!  Gotta have a plan.");

    }

    lock($self->{Curr_Test});

    $self->{Curr_Test}++;

    $self->{Test_Results}[$self->{Curr_Test}-1] = &share({

        'ok'      => 1,

        actual_ok => 1,

        name      => '',

        type      => 'skip',

        reason    => $why,

    });

    my $out = "ok";

    $out   .= " $self->{Curr_Test}" if $self->use_numbers;

    $out   .= " # skip";

    $out   .= " $why"       if length $why;

    $out   .= "\n";

    $self->_print($out);

    return 1;

}

=item B<todo_skip>

  $Test->todo_skip;

  $Test->todo_skip($why);

Like skip(), only it will declare the test as failing and TODO.  Similar

to

    print "not ok $tnum # TODO $why\n";

=cut

sub todo_skip {

    my($self, $why) = @_;

    $why ||= '';

    unless( $self->{Have_Plan} ) {

        require Carp;

        Carp::croak("You tried to run tests without a plan!  Gotta have a plan.");

    }

    lock($self->{Curr_Test});

    $self->{Curr_Test}++;

    $self->{Test_Results}[$self->{Curr_Test}-1] = &share({

        'ok'      => 1,

        actual_ok => 0,

        name      => '',

        type      => 'todo_skip',

        reason    => $why,

    });

    my $out = "not ok";

    $out   .= " $self->{Curr_Test}" if $self->use_numbers;

    $out   .= " # TODO & SKIP $why\n";

    $self->_print($out);

    return 1;

}

=begin _unimplemented

=item B<skip_rest>

  $Test->skip_rest;

  $Test->skip_rest($reason);

Like skip(), only it skips all the rest of the tests you plan to run

and terminates the test.

If you're running under no_plan, it skips once and terminates the

test.

=end _unimplemented