[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / _Util.pm

package # hide from PAUSE
  DBIx::Class::_Util;

use DBIx::Class::StartupCheck;  # load es early as we can, usually a noop

use warnings;
use strict;

use constant SPURIOUS_VERSION_CHECK_WARNINGS => ( "$]" < 5.010 ? 1 : 0);

BEGIN {
  package # hide from pause
    DBIx::Class::_ENV_;

  use Config;

  use constant {

    # but of course
    BROKEN_FORK => ($^O eq 'MSWin32') ? 1 : 0,

    BROKEN_GOTO => ( "$]" < 5.008003 ) ? 1 : 0,

    HAS_ITHREADS => $Config{useithreads} ? 1 : 0,

    UNSTABLE_DOLLARAT => ( "$]" < 5.013002 ) ? 1 : 0,

    ( map
      #
      # the "DBIC_" prefix below is crucial - this is what makes CI pick up
      # all envvars without further adjusting its scripts
      # DO NOT CHANGE to the more logical { $_ => !!( $ENV{"DBIC_$_"} ) }
      #
      { substr($_, 5) => !!( $ENV{$_} ) }
      qw(
        DBIC_SHUFFLE_UNORDERED_RESULTSETS
        DBIC_ASSERT_NO_INTERNAL_WANTARRAY
        DBIC_ASSERT_NO_INTERNAL_INDIRECT_CALLS
        DBIC_STRESSTEST_UTF8_UPGRADE_GENERATED_COLLAPSER_SOURCE
        DBIC_STRESSTEST_COLUMN_INFO_UNAWARE_STORAGE
      )
    ),

    IV_SIZE => $Config{ivsize},

    OS_NAME => $^O,
  };

  if ( "$]" < 5.009_005) {
    require MRO::Compat;
    constant->import( OLD_MRO => 1 );
  }
  else {
    require mro;
    constant->import( OLD_MRO => 0 );
  }

  # Both of these are no longer used for anything. However bring
  # them back after they were purged in 08a8d8f1, as there appear
  # to be outfits with *COPY PASTED* pieces of lib/DBIx/Class/Storage/*
  # in their production codebases. There is no point in breaking these
  # if whatever they used actually continues to work
  my $warned;
  my $sigh = sub {

    require Carp;
    my $cluck = "The @{[ (caller(1))[3] ]} constant is no more - adjust your code" . Carp::longmess();

    warn $cluck unless $warned->{$cluck}++;

    0;
  };
  sub DBICTEST () { &$sigh }
  sub PEEPEENESS () { &$sigh }
}

# FIXME - this is not supposed to be here
# Carp::Skip to the rescue soon
use DBIx::Class::Carp '^DBIx::Class|^DBICTest';

use B ();
use Carp 'croak';
use Storable 'nfreeze';
use Scalar::Util qw(weaken blessed reftype refaddr);
use Sub::Quote qw(qsub quote_sub);
use Sub::Name ();

# Already correctly prototyped: perlbrew exec perl -MStorable -e 'warn prototype \&Storable::dclone'
BEGIN { *deep_clone = \&Storable::dclone }

use base 'Exporter';
our @EXPORT_OK = qw(
  sigwarn_silencer modver_gt_or_eq modver_gt_or_eq_and_lt
  fail_on_internal_wantarray fail_on_internal_call
  refdesc refcount hrefaddr set_subname
  scope_guard detected_reinvoked_destructor
  is_exception dbic_internal_try
  quote_sub qsub perlstring serialize deep_clone dump_value
  parent_dir mkdir_p
  UNRESOLVABLE_CONDITION
);

use constant UNRESOLVABLE_CONDITION => \ '1 = 0';

sub sigwarn_silencer ($) {
  my $pattern = shift;

  croak "Expecting a regexp" if ref $pattern ne 'Regexp';

  my $orig_sig_warn = $SIG{__WARN__} || sub { CORE::warn(@_) };

  return sub { &$orig_sig_warn unless $_[0] =~ $pattern };
}

sub perlstring ($) { q{"}. quotemeta( shift ). q{"} };

sub hrefaddr ($) { sprintf '0x%x', &refaddr||0 }

sub refdesc ($) {
  croak "Expecting a reference" if ! length ref $_[0];

  # be careful not to trigger stringification,
  # reuse @_ as a scratch-pad
  sprintf '%s%s(0x%x)',
    ( defined( $_[1] = blessed $_[0]) ? "$_[1]=" : '' ),
    reftype $_[0],
    refaddr($_[0]),
  ;
}

sub refcount ($) {
  croak "Expecting a reference" if ! length ref $_[0];

  # No tempvars - must operate on $_[0], otherwise the pad
  # will count as an extra ref
  B::svref_2object($_[0])->REFCNT;
}

# FIXME In another life switch this to a polyfill like the one in namespace::clean
sub set_subname ($$) {

  # fully qualify name
  splice @_, 0, 1, caller(0) . "::$_[0]"
    if $_[0] !~ /::|'/;

  &Sub::Name::subname;
}

sub serialize ($) {
  local $Storable::canonical = 1;
  nfreeze($_[0]);
}

my $dd_obj;
sub dump_value ($) {
  local $Data::Dumper::Indent = 1
    unless defined $Data::Dumper::Indent;

  my $dump_str = (
    $dd_obj
      ||=
    do {
      require Data::Dumper;
      my $d = Data::Dumper->new([])
        ->Purity(0)
        ->Pad('')
        ->Useqq(1)
        ->Terse(1)
        ->Freezer('')
        ->Quotekeys(0)
        ->Bless('bless')
        ->Pair(' => ')
        ->Sortkeys(1)
        ->Deparse(1)
      ;

      $d->Sparseseen(1) if modver_gt_or_eq (
        'Data::Dumper', '2.136'
      );

      $d;
    }
  )->Values([$_[0]])->Dump;

  $dd_obj->Reset->Values([]);

  $dump_str;
}

sub scope_guard (&) {
  croak 'Calling scope_guard() in void context makes no sense'
    if ! defined wantarray;

  # no direct blessing of coderefs - DESTROY is buggy on those
  bless [ $_[0] ], 'DBIx::Class::_Util::ScopeGuard';
}
{
  package #
    DBIx::Class::_Util::ScopeGuard;

  sub DESTROY {
    &DBIx::Class::_Util::detected_reinvoked_destructor;

    local $@ if DBIx::Class::_ENV_::UNSTABLE_DOLLARAT;

    eval {
      $_[0]->[0]->();
      1;
    }
      or
    Carp::cluck(
      "Execution of scope guard $_[0] resulted in the non-trappable exception:\n\n$@"
    );
  }
}


sub is_exception ($) {
  my $e = $_[0];

  # FIXME
  # this is not strictly correct - an eval setting $@ to undef
  # is *not* the same as an eval setting $@ to ''
  # but for the sake of simplicity assume the following for
  # the time being
  return 0 unless defined $e;

  my ($not_blank, $suberror);
  {
    local $SIG{__DIE__} if $SIG{__DIE__};
    local $@;
    eval {
      # The ne() here is deliberate - a plain length($e), or worse "$e" ne
      # will entirely obviate the need for the encolsing eval{}, as the
      # condition we guard against is a missing fallback overload
      $not_blank = ( $e ne '' );
      1;
    } or $suberror = $@;
  }

  if (defined $suberror) {
    if (length (my $class = blessed($e) )) {
      carp_unique( sprintf(
        'External exception class %s implements partial (broken) overloading '
      . 'preventing its instances from being used in simple ($x eq $y) '
      . 'comparisons. Given Perl\'s "globally cooperative" exception '
      . 'handling this type of brokenness is extremely dangerous on '
      . 'exception objects, as it may (and often does) result in silent '
      . '"exception substitution". DBIx::Class tries to work around this '
      . 'as much as possible, but other parts of your software stack may '
      . 'not be even aware of this. Please submit a bugreport against the '
      . 'distribution containing %s and in the meantime apply a fix similar '
      . 'to the one shown at %s, in order to ensure your exception handling '
      . 'is saner application-wide. What follows is the actual error text '
      . "as generated by Perl itself:\n\n%s\n ",
        $class,
        $class,
        'http://v.gd/DBIC_overload_tempfix/',
        $suberror,
      ));

      # workaround, keeps spice flowing
      $not_blank = !!( length $e );
    }
    else {
      # not blessed yet failed the 'ne'... this makes 0 sense...
      # just throw further
      die $suberror
    }
  }
  elsif (
    # a ref evaluating to '' is definitively a "null object"
    ( not $not_blank )
      and
    length( my $class = ref $e )
  ) {
    carp_unique( sprintf(
      "Objects of external exception class '%s' stringify to '' (the "
    . 'empty string), implementing the so called null-object-pattern. '
    . 'Given Perl\'s "globally cooperative" exception handling using this '
    . 'class of exceptions is extremely dangerous, as it may (and often '
    . 'does) result in silent discarding of errors. DBIx::Class tries to '
    . 'work around this as much as possible, but other parts of your '
    . 'software stack may not be even aware of the problem. Please submit '
    . 'a bugreport against the distribution containing %s',

      ($class) x 2,
    ));

    $not_blank = 1;
  }

  return $not_blank;
}

{
  my $callstack_state;

  # Recreate the logic of try(), while reusing the catch()/finally() as-is
  #
  # FIXME: We need to move away from Try::Tiny entirely (way too heavy and
  # yes, shows up ON TOP of profiles) but this is a batle for another maint
  sub dbic_internal_try (&;@) {

    my $try_cref = shift;
    my $catch_cref = undef;  # apparently this is a thing... https://rt.perl.org/Public/Bug/Display.html?id=119311

    for my $arg (@_) {

      if( ref($arg) eq 'Try::Tiny::Catch' ) {

        croak 'dbic_internal_try() may not be followed by multiple catch() blocks'
          if $catch_cref;

        $catch_cref = $$arg;
      }
      elsif ( ref($arg) eq 'Try::Tiny::Finally' ) {
        croak 'dbic_internal_try() does not support finally{}';
      }
      else {
        croak(
          'dbic_internal_try() encountered an unexpected argument '
        . "'@{[ defined $arg ? $arg : 'UNDEF' ]}' - perhaps "
        . 'a missing semi-colon before or ' # trailing space important
        );
      }
    }

    my $wantarray = wantarray;
    my $preexisting_exception = $@;

    my @ret;
    my $all_good = eval {
      $@ = $preexisting_exception;

      local $callstack_state->{in_internal_try} = 1
        unless $callstack_state->{in_internal_try};

      # always unset - someone may have snuck it in
      local $SIG{__DIE__} if $SIG{__DIE__};

      if( $wantarray ) {
        @ret = $try_cref->();
      }
      elsif( defined $wantarray ) {
        $ret[0] = $try_cref->();
      }
      else {
        $try_cref->();
      }

      1;
    };

    my $exception = $@;
    $@ = $preexisting_exception;

    if ( $all_good ) {
      return $wantarray ? @ret : $ret[0]
    }
    elsif ( $catch_cref ) {
      for ( $exception ) {
        return $catch_cref->($exception);
      }
    }

    return;
  }

  sub in_internal_try { !! $callstack_state->{in_internal_try} }
}

{
  my $destruction_registry = {};

  sub CLONE {
    %$destruction_registry = map {
      (defined $_)
        ? ( refaddr($_) => $_ )
        : ()
    } values %$destruction_registry;

    weaken($_) for values %$destruction_registry;

    # Dummy NEXTSTATE ensuring the all temporaries on the stack are garbage
    # collected before leaving this scope. Depending on the code above, this
    # may very well be just a preventive measure guarding future modifications
    undef;
  }

  # This is almost invariably invoked from within DESTROY
  # throwing exceptions won't work
  sub detected_reinvoked_destructor {

    # quick "garbage collection" pass - prevents the registry
    # from slowly growing with a bunch of undef-valued keys
    defined $destruction_registry->{$_} or delete $destruction_registry->{$_}
      for keys %$destruction_registry;

    if (! length ref $_[0]) {
      printf STDERR '%s() expects a blessed reference %s',
        (caller(0))[3],
        Carp::longmess,
      ;
      return undef; # don't know wtf to do
    }
    elsif (! defined $destruction_registry->{ my $addr = refaddr($_[0]) } ) {
      weaken( $destruction_registry->{$addr} = $_[0] );
      return 0;
    }
    else {
      carp_unique ( sprintf (
        'Preventing *MULTIPLE* DESTROY() invocations on %s - an *EXTREMELY '
      . 'DANGEROUS* condition which is *ALMOST CERTAINLY GLOBAL* within your '
      . 'application, affecting *ALL* classes without active protection against '
      . 'this. Diagnose and fix the root cause ASAP!!!%s',
      refdesc $_[0],
        ( ( $INC{'Devel/StackTrace.pm'} and ! do { local $@; eval { Devel::StackTrace->VERSION(2) } } )
          ? " (likely culprit Devel::StackTrace\@@{[ Devel::StackTrace->VERSION ]} found in %INC, http://is.gd/D_ST_refcap)"
          : ''
        )
      ));

      return 1;
    }
  }
}

my $module_name_rx = qr/ \A [A-Z_a-z] [0-9A-Z_a-z]* (?: :: [0-9A-Z_a-z]+ )* \z /x;
my $ver_rx =         qr/ \A [0-9]+ (?: \. [0-9]+ )* (?: \_ [0-9]+ )*        \z /x;

sub modver_gt_or_eq ($$) {
  my ($mod, $ver) = @_;

  croak "Nonsensical module name supplied"
    if ! defined $mod or $mod !~ $module_name_rx;

  croak "Nonsensical minimum version supplied"
    if ! defined $ver or $ver !~ $ver_rx;

  no strict 'refs';
  my $ver_cache = ${"${mod}::__DBIC_MODULE_VERSION_CHECKS__"} ||= ( $mod->VERSION
    ? {}
    : croak "$mod does not seem to provide a version (perhaps it never loaded)"
  );

  ! defined $ver_cache->{$ver}
    and
  $ver_cache->{$ver} = do {

    local $SIG{__WARN__} = sigwarn_silencer( qr/\Qisn't numeric in subroutine entry/ )
      if SPURIOUS_VERSION_CHECK_WARNINGS;

    local $SIG{__DIE__} if $SIG{__DIE__};
    local $@;
    eval { $mod->VERSION($ver) } ? 1 : 0;
  };

  $ver_cache->{$ver};
}

sub modver_gt_or_eq_and_lt ($$$) {
  my ($mod, $v_ge, $v_lt) = @_;

  croak "Nonsensical maximum version supplied"
    if ! defined $v_lt or $v_lt !~ $ver_rx;

  return (
    modver_gt_or_eq($mod, $v_ge)
      and
    ! modver_gt_or_eq($mod, $v_lt)
  ) ? 1 : 0;
}


#
# Why not just use some higher-level module or at least File::Spec here?
# Because:
# 1)  This is a *very* rarely used function, and the deptree is large
#     enough already as it is
#
# 2)  (more importantly) Our tooling is utter shit in this area. There
#     is no comprehensive support for UNC paths in PathTools and there
#     are also various small bugs in representation across different
#     path-manipulation CPAN offerings.
#
# Since this routine is strictly used for logical path processing (it
# *must* be able to work with not-yet-existing paths), use this seemingly
# simple but I *think* complete implementation to feed to other consumers
#
# If bugs are ever uncovered in this routine, *YOU ARE URGED TO RESIST*
# the impulse to bring in an external dependency. During runtime there
# is exactly one spot that could potentially maybe once in a blue moon
# use this function. Keep it lean.
#
sub parent_dir ($) {
  ( $_[0] =~ m{  [\/\\]  ( \.{0,2} ) ( [\/\\]* ) \z }x )
    ? (
      $_[0]
        .
      ( ( length($1) and ! length($2) ) ? '/' : '' )
        .
      '../'
    )
    : (
      require File::Spec
        and
      File::Spec->catpath (
        ( File::Spec->splitpath( "$_[0]" ) )[0,1],
        '/',
      )
    )
  ;
}

sub mkdir_p ($) {
  require File::Path;
  # do not ask for a recent version, use 1.x API calls
  File::Path::mkpath([ "$_[0]" ]);  # File::Path does not like objects
}


{
  my $list_ctx_ok_stack_marker;

  sub fail_on_internal_wantarray () {
    return if $list_ctx_ok_stack_marker;

    if (! defined wantarray) {
      croak('fail_on_internal_wantarray() needs a tempvar to save the stack marker guard');
    }

    my $cf = 1;
    while ( ( (CORE::caller($cf+1))[3] || '' ) =~ / :: (?:

      # these are public API parts that alter behavior on wantarray
      search | search_related | slice | search_literal

        |

      # these are explicitly prefixed, since we only recognize them as valid
      # escapes when they come from the guts of CDBICompat
      CDBICompat .*? :: (?: search_where | retrieve_from_sql | retrieve_all )

    ) $/x ) {
      $cf++;
    }

    my ($fr, $want, $argdesc);
    {
      package DB;
      $fr = [ CORE::caller($cf) ];
      $want = ( CORE::caller($cf-1) )[5];
      $argdesc = ref $DB::args[0]
        ? DBIx::Class::_Util::refdesc($DB::args[0])
        : 'non '
      ;
    };

    if (
      $want and $fr->[0] =~ /^(?:DBIx::Class|DBICx::)/
    ) {
      DBIx::Class::Exception->throw( sprintf (
        "Improper use of %s instance in list context at %s line %d\n\n    Stacktrace starts",
        $argdesc, @{$fr}[1,2]
      ), 'with_stacktrace');
    }

    weaken( $list_ctx_ok_stack_marker = my $mark = [] );

    $mark;
  }
}

sub fail_on_internal_call {
  my ($fr, $argdesc);
  {
    package DB;
    $fr = [ CORE::caller(1) ];
    $argdesc = ref $DB::args[0]
      ? DBIx::Class::_Util::refdesc($DB::args[0])
      : ( $DB::args[0] . '' )
    ;
  };

  if (
    $argdesc
      and
    $fr->[0] =~ /^(?:DBIx::Class|DBICx::)/
      and
    $fr->[1] !~ /\b(?:CDBICompat|ResultSetProxy)\b/  # no point touching there
  ) {
    DBIx::Class::Exception->throw( sprintf (
      "Illegal internal call of indirect proxy-method %s() with argument '%s': examine the last lines of the proxy method deparse below to determine what to call directly instead at %s on line %d\n\n%s\n\n    Stacktrace starts",
      $fr->[3], $argdesc, @{$fr}[1,2], ( $fr->[6] || do {
        require B::Deparse;
        no strict 'refs';
        B::Deparse->new->coderef2text(\&{$fr->[3]})
      }),
    ), 'with_stacktrace');
  }
}

1;
Commit	Line	Data
b1dbf716	1	package # hide from PAUSE
	2	DBIx::Class::_Util;
	3
399b9455	4	use DBIx::Class::StartupCheck; # load es early as we can, usually a noop
399b9455	5
b1dbf716	6	use warnings;
	7	use strict;
	8
750a4ad2	9	use constant SPURIOUS_VERSION_CHECK_WARNINGS => ( "$]" < 5.010 ? 1 : 0);
b1dbf716	10
37873f78	11	BEGIN {
	12	package # hide from pause
	13	DBIx::Class::_ENV_;
	14
	15	use Config;
	16
	17	use constant {
	18
	19	# but of course
	20	BROKEN_FORK => ($^O eq 'MSWin32') ? 1 : 0,
	21
750a4ad2	22	BROKEN_GOTO => ( "$]" < 5.008003 ) ? 1 : 0,
8d73fcd4	23
37873f78	24	HAS_ITHREADS => $Config{useithreads} ? 1 : 0,
37873f78	25
bbf6a9a5	26	UNSTABLE_DOLLARAT => ( "$]" < 5.013002 ) ? 1 : 0,
bbf6a9a5	27
db83437e	28	( map
	29	#
	30	# the "DBIC_" prefix below is crucial - this is what makes CI pick up
	31	# all envvars without further adjusting its scripts
	32	# DO NOT CHANGE to the more logical { $_ => !!( $ENV{"DBIC_$_"} ) }
	33	#
	34	{ substr($_, 5) => !!( $ENV{$_} ) }
	35	qw(
	36	DBIC_SHUFFLE_UNORDERED_RESULTSETS
	37	DBIC_ASSERT_NO_INTERNAL_WANTARRAY
	38	DBIC_ASSERT_NO_INTERNAL_INDIRECT_CALLS
	39	DBIC_STRESSTEST_UTF8_UPGRADE_GENERATED_COLLAPSER_SOURCE
	40	DBIC_STRESSTEST_COLUMN_INFO_UNAWARE_STORAGE
	41	)
	42	),
f45dc928	43
37873f78	44	IV_SIZE => $Config{ivsize},
00882d2c	45
00882d2c	46	OS_NAME => $^O,
37873f78	47	};
37873f78	48
750a4ad2	49	if ( "$]" < 5.009_005) {
37873f78	50	require MRO::Compat;
	51	constant->import( OLD_MRO => 1 );
	52	}
	53	else {
	54	require mro;
	55	constant->import( OLD_MRO => 0 );
	56	}
4b1b44c1	57
	58	# Both of these are no longer used for anything. However bring
	59	# them back after they were purged in 08a8d8f1, as there appear
	60	# to be outfits with COPY PASTED pieces of lib/DBIx/Class/Storage/*
	61	# in their production codebases. There is no point in breaking these
	62	# if whatever they used actually continues to work
	63	my $warned;
	64	my $sigh = sub {
	65
	66	require Carp;
	67	my $cluck = "The @{[ (caller(1))[3] ]} constant is no more - adjust your code" . Carp::longmess();
	68
	69	warn $cluck unless $warned->{$cluck}++;
	70
	71	0;
	72	};
	73	sub DBICTEST () { &$sigh }
	74	sub PEEPEENESS () { &$sigh }
37873f78	75	}
37873f78	76
841efcb3	77	# FIXME - this is not supposed to be here
	78	# Carp::Skip to the rescue soon
	79	use DBIx::Class::Carp '^DBIx::Class\|^DBICTest';
	80
d7d45bdc	81	use B ();
841efcb3	82	use Carp 'croak';
d7d45bdc	83	use Storable 'nfreeze';
3d56e026	84	use Scalar::Util qw(weaken blessed reftype refaddr);
0020e364	85	use Sub::Quote qw(qsub quote_sub);
514b84f6	86	use Sub::Name ();
7f9a3f70	87
1c30a2e4	88	# Already correctly prototyped: perlbrew exec perl -MStorable -e 'warn prototype \&Storable::dclone'
	89	BEGIN { *deep_clone = \&Storable::dclone }
	90
b1dbf716	91	use base 'Exporter';
3705e3b2	92	our @EXPORT_OK = qw(
d634850b	93	sigwarn_silencer modver_gt_or_eq modver_gt_or_eq_and_lt
77c3a5dc	94	fail_on_internal_wantarray fail_on_internal_call
514b84f6	95	refdesc refcount hrefaddr set_subname
ddcc02d1	96	scope_guard detected_reinvoked_destructor
ddcc02d1	97	is_exception dbic_internal_try
8fc4291e	98	quote_sub qsub perlstring serialize deep_clone dump_value
439a7283	99	parent_dir mkdir_p
facd0e8e	100	UNRESOLVABLE_CONDITION
3705e3b2	101	);
052a832c	102
facd0e8e	103	use constant UNRESOLVABLE_CONDITION => \ '1 = 0';
facd0e8e	104
bf302897	105	sub sigwarn_silencer ($) {
052a832c	106	my $pattern = shift;
	107
	108	croak "Expecting a regexp" if ref $pattern ne 'Regexp';
	109
	110	my $orig_sig_warn = $SIG{__WARN__} \|\| sub { CORE::warn(@_) };
	111
	112	return sub { &$orig_sig_warn unless $_[0] =~ $pattern };
	113	}
b1dbf716	114
01b25f12	115	sub perlstring ($) { q{"}. quotemeta( shift ). q{"} };
01b25f12	116
3d56e026	117	sub hrefaddr ($) { sprintf '0x%x', &refaddr\|\|0 }
8433421f	118
	119	sub refdesc ($) {
	120	croak "Expecting a reference" if ! length ref $_[0];
	121
	122	# be careful not to trigger stringification,
	123	# reuse @_ as a scratch-pad
	124	sprintf '%s%s(0x%x)',
	125	( defined( $_[1] = blessed $_[0]) ? "$_[1]=" : '' ),
	126	reftype $_[0],
3d56e026	127	refaddr($_[0]),
8433421f	128	;
8433421f	129	}
bf302897	130
bf302897	131	sub refcount ($) {
dac7972a	132	croak "Expecting a reference" if ! length ref $_[0];
dac7972a	133
dac7972a	134	# No tempvars - must operate on $_[0], otherwise the pad
	135	# will count as an extra ref
	136	B::svref_2object($_[0])->REFCNT;
	137	}
	138
514b84f6	139	# FIXME In another life switch this to a polyfill like the one in namespace::clean
	140	sub set_subname ($$) {
	141
	142	# fully qualify name
	143	splice @_, 0, 1, caller(0) . "::$_[0]"
	144	if $_[0] !~ /::\|'/;
	145
	146	&Sub::Name::subname;
	147	}
	148
b34d9331	149	sub serialize ($) {
b34d9331	150	local $Storable::canonical = 1;
d7d45bdc	151	nfreeze($_[0]);
b34d9331	152	}
b34d9331	153
2d5ac3cf	154	my $dd_obj;
8fc4291e	155	sub dump_value ($) {
	156	local $Data::Dumper::Indent = 1
	157	unless defined $Data::Dumper::Indent;
	158
2d5ac3cf	159	my $dump_str = (
8fc4291e	160	$dd_obj
	161	\|\|=
	162	do {
	163	require Data::Dumper;
	164	my $d = Data::Dumper->new([])
	165	->Purity(0)
	166	->Pad('')
	167	->Useqq(1)
	168	->Terse(1)
	169	->Freezer('')
	170	->Quotekeys(0)
	171	->Bless('bless')
	172	->Pair(' => ')
	173	->Sortkeys(1)
	174	->Deparse(1)
	175	;
	176
	177	$d->Sparseseen(1) if modver_gt_or_eq (
	178	'Data::Dumper', '2.136'
	179	);
	180
	181	$d;
	182	}
	183	)->Values([$_[0]])->Dump;
	184
	185	$dd_obj->Reset->Values([]);
	186
	187	$dump_str;
	188	}
	189
bbf6a9a5	190	sub scope_guard (&) {
	191	croak 'Calling scope_guard() in void context makes no sense'
	192	if ! defined wantarray;
	193
	194	# no direct blessing of coderefs - DESTROY is buggy on those
	195	bless [ $_[0] ], 'DBIx::Class::_Util::ScopeGuard';
	196	}
	197	{
	198	package #
	199	DBIx::Class::_Util::ScopeGuard;
	200
	201	sub DESTROY {
	202	&DBIx::Class::_Util::detected_reinvoked_destructor;
	203
	204	local $@ if DBIx::Class::_ENV_::UNSTABLE_DOLLARAT;
	205
	206	eval {
	207	$_[0]->[0]->();
	208	1;
118b2c36	209	}
	210	or
	211	Carp::cluck(
	212	"Execution of scope guard $_[0] resulted in the non-trappable exception:\n\n$@"
	213	);
bbf6a9a5	214	}
	215	}
	216
	217
841efcb3	218	sub is_exception ($) {
	219	my $e = $_[0];
	220
35cf7d1a	221	# FIXME
a0414138	222	# this is not strictly correct - an eval setting $@ to undef
	223	# is not the same as an eval setting $@ to ''
	224	# but for the sake of simplicity assume the following for
	225	# the time being
	226	return 0 unless defined $e;
	227
841efcb3	228	my ($not_blank, $suberror);
841efcb3	229	{
5c33c8be	230	local $SIG{__DIE__} if $SIG{__DIE__};
841efcb3	231	local $@;
841efcb3	232	eval {
d52c4a75	233	# The ne() here is deliberate - a plain length($e), or worse "$e" ne
	234	# will entirely obviate the need for the encolsing eval{}, as the
	235	# condition we guard against is a missing fallback overload
	236	$not_blank = ( $e ne '' );
841efcb3	237	1;
	238	} or $suberror = $@;
	239	}
	240
	241	if (defined $suberror) {
	242	if (length (my $class = blessed($e) )) {
	243	carp_unique( sprintf(
9bea2000	244	'External exception class %s implements partial (broken) overloading '
9bea2000	245	. 'preventing its instances from being used in simple ($x eq $y) '
841efcb3	246	. 'comparisons. Given Perl\'s "globally cooperative" exception '
	247	. 'handling this type of brokenness is extremely dangerous on '
	248	. 'exception objects, as it may (and often does) result in silent '
	249	. '"exception substitution". DBIx::Class tries to work around this '
	250	. 'as much as possible, but other parts of your software stack may '
	251	. 'not be even aware of this. Please submit a bugreport against the '
	252	. 'distribution containing %s and in the meantime apply a fix similar '
	253	. 'to the one shown at %s, in order to ensure your exception handling '
	254	. 'is saner application-wide. What follows is the actual error text '
	255	. "as generated by Perl itself:\n\n%s\n ",
9bea2000	256	$class,
841efcb3	257	$class,
	258	'http://v.gd/DBIC_overload_tempfix/',
	259	$suberror,
	260	));
	261
	262	# workaround, keeps spice flowing
d52c4a75	263	$not_blank = !!( length $e );
841efcb3	264	}
	265	else {
	266	# not blessed yet failed the 'ne'... this makes 0 sense...
	267	# just throw further
	268	die $suberror
	269	}
	270	}
84e4e006	271	elsif (
	272	# a ref evaluating to '' is definitively a "null object"
	273	( not $not_blank )
	274	and
	275	length( my $class = ref $e )
	276	) {
	277	carp_unique( sprintf(
	278	"Objects of external exception class '%s' stringify to '' (the "
	279	. 'empty string), implementing the so called null-object-pattern. '
	280	. 'Given Perl\'s "globally cooperative" exception handling using this '
	281	. 'class of exceptions is extremely dangerous, as it may (and often '
	282	. 'does) result in silent discarding of errors. DBIx::Class tries to '
	283	. 'work around this as much as possible, but other parts of your '
	284	. 'software stack may not be even aware of the problem. Please submit '
35cf7d1a	285	. 'a bugreport against the distribution containing %s',
84e4e006	286
	287	($class) x 2,
	288	));
	289
	290	$not_blank = 1;
	291	}
841efcb3	292
	293	return $not_blank;
	294	}
	295
3d56e026	296	{
ddcc02d1	297	my $callstack_state;
	298
	299	# Recreate the logic of try(), while reusing the catch()/finally() as-is
	300	#
	301	# FIXME: We need to move away from Try::Tiny entirely (way too heavy and
	302	# yes, shows up ON TOP of profiles) but this is a batle for another maint
	303	sub dbic_internal_try (&;@) {
	304
	305	my $try_cref = shift;
	306	my $catch_cref = undef; # apparently this is a thing... https://rt.perl.org/Public/Bug/Display.html?id=119311
	307
	308	for my $arg (@_) {
	309
	310	if( ref($arg) eq 'Try::Tiny::Catch' ) {
	311
	312	croak 'dbic_internal_try() may not be followed by multiple catch() blocks'
	313	if $catch_cref;
	314
	315	$catch_cref = $$arg;
	316	}
	317	elsif ( ref($arg) eq 'Try::Tiny::Finally' ) {
	318	croak 'dbic_internal_try() does not support finally{}';
	319	}
	320	else {
	321	croak(
	322	'dbic_internal_try() encountered an unexpected argument '
	323	. "'@{[ defined $arg ? $arg : 'UNDEF' ]}' - perhaps "
	324	. 'a missing semi-colon before or ' # trailing space important
	325	);
	326	}
	327	}
	328
	329	my $wantarray = wantarray;
	330	my $preexisting_exception = $@;
	331
	332	my @ret;
	333	my $all_good = eval {
	334	$@ = $preexisting_exception;
	335
	336	local $callstack_state->{in_internal_try} = 1
	337	unless $callstack_state->{in_internal_try};
	338
	339	# always unset - someone may have snuck it in
5c33c8be	340	local $SIG{__DIE__} if $SIG{__DIE__};
ddcc02d1	341
	342	if( $wantarray ) {
	343	@ret = $try_cref->();
	344	}
	345	elsif( defined $wantarray ) {
	346	$ret[0] = $try_cref->();
	347	}
	348	else {
	349	$try_cref->();
	350	}
	351
	352	1;
	353	};
	354
	355	my $exception = $@;
	356	$@ = $preexisting_exception;
	357
	358	if ( $all_good ) {
	359	return $wantarray ? @ret : $ret[0]
	360	}
	361	elsif ( $catch_cref ) {
	362	for ( $exception ) {
	363	return $catch_cref->($exception);
	364	}
	365	}
	366
	367	return;
	368	}
	369
	370	sub in_internal_try { !! $callstack_state->{in_internal_try} }
	371	}
	372
	373	{
3d56e026	374	my $destruction_registry = {};
	375
	376	sub CLONE {
d098704f	377	%$destruction_registry = map {
	378	(defined $_)
	379	? ( refaddr($_) => $_ )
	380	: ()
	381	} values %$destruction_registry;
d52fc26d	382
d098704f	383	weaken($_) for values %$destruction_registry;
29211e03	384
d52fc26d	385	# Dummy NEXTSTATE ensuring the all temporaries on the stack are garbage
	386	# collected before leaving this scope. Depending on the code above, this
	387	# may very well be just a preventive measure guarding future modifications
	388	undef;
3d56e026	389	}
	390
	391	# This is almost invariably invoked from within DESTROY
	392	# throwing exceptions won't work
e1d9e578	393	sub detected_reinvoked_destructor {
3d56e026	394
	395	# quick "garbage collection" pass - prevents the registry
	396	# from slowly growing with a bunch of undef-valued keys
	397	defined $destruction_registry->{$_} or delete $destruction_registry->{$_}
	398	for keys %$destruction_registry;
	399
e1d9e578	400	if (! length ref $_[0]) {
e1d9e578	401	printf STDERR '%s() expects a blessed reference %s',
3d56e026	402	(caller(0))[3],
	403	Carp::longmess,
	404	;
	405	return undef; # don't know wtf to do
	406	}
e1d9e578	407	elsif (! defined $destruction_registry->{ my $addr = refaddr($_[0]) } ) {
3d56e026	408	weaken( $destruction_registry->{$addr} = $_[0] );
	409	return 0;
	410	}
	411	else {
	412	carp_unique ( sprintf (
	413	'Preventing MULTIPLE DESTROY() invocations on %s - an *EXTREMELY '
	414	. 'DANGEROUS* condition which is ALMOST CERTAINLY GLOBAL within your '
	415	. 'application, affecting ALL classes without active protection against '
	416	. 'this. Diagnose and fix the root cause ASAP!!!%s',
	417	refdesc $_[0],
	418	( ( $INC{'Devel/StackTrace.pm'} and ! do { local $@; eval { Devel::StackTrace->VERSION(2) } } )
	419	? " (likely culprit Devel::StackTrace\@@{[ Devel::StackTrace->VERSION ]} found in %INC, http://is.gd/D_ST_refcap)"
	420	: ''
	421	)
	422	));
	423
	424	return 1;
	425	}
	426	}
	427	}
	428
7302b3e0	429	my $module_name_rx = qr/ \A [A-Z_a-z] [0-9A-Z_a-z]* (?: :: [0-9A-Z_a-z]+ )* \z /x;
	430	my $ver_rx = qr/ \A [0-9]+ (?: \. [0-9]+ )* (?: \_ [0-9]+ )* \z /x;
	431
bf302897	432	sub modver_gt_or_eq ($$) {
b1dbf716	433	my ($mod, $ver) = @_;
	434
	435	croak "Nonsensical module name supplied"
7302b3e0	436	if ! defined $mod or $mod !~ $module_name_rx;
b1dbf716	437
b1dbf716	438	croak "Nonsensical minimum version supplied"
7302b3e0	439	if ! defined $ver or $ver !~ $ver_rx;
	440
	441	no strict 'refs';
	442	my $ver_cache = ${"${mod}::__DBIC_MODULE_VERSION_CHECKS__"} \|\|= ( $mod->VERSION
	443	? {}
	444	: croak "$mod does not seem to provide a version (perhaps it never loaded)"
	445	);
	446
	447	! defined $ver_cache->{$ver}
	448	and
	449	$ver_cache->{$ver} = do {
b1dbf716	450
7302b3e0	451	local $SIG{__WARN__} = sigwarn_silencer( qr/\Qisn't numeric in subroutine entry/ )
7302b3e0	452	if SPURIOUS_VERSION_CHECK_WARNINGS;
b1dbf716	453
5c33c8be	454	local $SIG{__DIE__} if $SIG{__DIE__};
7302b3e0	455	local $@;
7302b3e0	456	eval { $mod->VERSION($ver) } ? 1 : 0;
7302b3e0	457	};
56270bba	458
7302b3e0	459	$ver_cache->{$ver};
b1dbf716	460	}
b1dbf716	461
d634850b	462	sub modver_gt_or_eq_and_lt ($$$) {
	463	my ($mod, $v_ge, $v_lt) = @_;
	464
	465	croak "Nonsensical maximum version supplied"
7302b3e0	466	if ! defined $v_lt or $v_lt !~ $ver_rx;
d634850b	467
	468	return (
	469	modver_gt_or_eq($mod, $v_ge)
	470	and
	471	! modver_gt_or_eq($mod, $v_lt)
	472	) ? 1 : 0;
	473	}
	474
e3be2b6f	475
	476	#
	477	# Why not just use some higher-level module or at least File::Spec here?
	478	# Because:
	479	# 1) This is a very rarely used function, and the deptree is large
	480	# enough already as it is
	481	#
	482	# 2) (more importantly) Our tooling is utter shit in this area. There
	483	# is no comprehensive support for UNC paths in PathTools and there
	484	# are also various small bugs in representation across different
	485	# path-manipulation CPAN offerings.
	486	#
	487	# Since this routine is strictly used for logical path processing (it
	488	# must be able to work with not-yet-existing paths), use this seemingly
	489	# simple but I think complete implementation to feed to other consumers
	490	#
	491	# If bugs are ever uncovered in this routine, YOU ARE URGED TO RESIST
	492	# the impulse to bring in an external dependency. During runtime there
	493	# is exactly one spot that could potentially maybe once in a blue moon
	494	# use this function. Keep it lean.
	495	#
	496	sub parent_dir ($) {
	497	( $_[0] =~ m{ [\/\\] ( \.{0,2} ) ( [\/\\]* ) \z }x )
	498	? (
	499	$_[0]
	500	.
	501	( ( length($1) and ! length($2) ) ? '/' : '' )
	502	.
	503	'../'
	504	)
	505	: (
	506	require File::Spec
	507	and
	508	File::Spec->catpath (
	509	( File::Spec->splitpath( "$_[0]" ) )[0,1],
	510	'/',
	511	)
	512	)
	513	;
	514	}
	515
439a7283	516	sub mkdir_p ($) {
	517	require File::Path;
	518	# do not ask for a recent version, use 1.x API calls
	519	File::Path::mkpath([ "$_[0]" ]); # File::Path does not like objects
	520	}
	521
e3be2b6f	522
a9da9b6a	523	{
	524	my $list_ctx_ok_stack_marker;
	525
e89c7968	526	sub fail_on_internal_wantarray () {
a9da9b6a	527	return if $list_ctx_ok_stack_marker;
	528
	529	if (! defined wantarray) {
	530	croak('fail_on_internal_wantarray() needs a tempvar to save the stack marker guard');
	531	}
	532
	533	my $cf = 1;
821edc09	534	while ( ( (CORE::caller($cf+1))[3] \|\| '' ) =~ / :: (?:
a9da9b6a	535
	536	# these are public API parts that alter behavior on wantarray
	537	search \| search_related \| slice \| search_literal
	538
	539	\|
	540
	541	# these are explicitly prefixed, since we only recognize them as valid
	542	# escapes when they come from the guts of CDBICompat
	543	CDBICompat .*? :: (?: search_where \| retrieve_from_sql \| retrieve_all )
	544
	545	) $/x ) {
	546	$cf++;
	547	}
	548
e89c7968	549	my ($fr, $want, $argdesc);
	550	{
	551	package DB;
821edc09	552	$fr = [ CORE::caller($cf) ];
821edc09	553	$want = ( CORE::caller($cf-1) )[5];
e89c7968	554	$argdesc = ref $DB::args[0]
	555	? DBIx::Class::_Util::refdesc($DB::args[0])
	556	: 'non '
	557	;
	558	};
	559
a9da9b6a	560	if (
e89c7968	561	$want and $fr->[0] =~ /^(?:DBIx::Class\|DBICx::)/
a9da9b6a	562	) {
a9da9b6a	563	DBIx::Class::Exception->throw( sprintf (
e89c7968	564	"Improper use of %s instance in list context at %s line %d\n\n Stacktrace starts",
e89c7968	565	$argdesc, @{$fr}[1,2]
a9da9b6a	566	), 'with_stacktrace');
	567	}
	568
d098704f	569	weaken( $list_ctx_ok_stack_marker = my $mark = [] );
d098704f	570
a9da9b6a	571	$mark;
	572	}
	573	}
	574
77c3a5dc	575	sub fail_on_internal_call {
	576	my ($fr, $argdesc);
	577	{
	578	package DB;
821edc09	579	$fr = [ CORE::caller(1) ];
77c3a5dc	580	$argdesc = ref $DB::args[0]
77c3a5dc	581	? DBIx::Class::_Util::refdesc($DB::args[0])
e5053694	582	: ( $DB::args[0] . '' )
77c3a5dc	583	;
	584	};
	585
	586	if (
	587	$argdesc
	588	and
	589	$fr->[0] =~ /^(?:DBIx::Class\|DBICx::)/
	590	and
	591	$fr->[1] !~ /\b(?:CDBICompat\|ResultSetProxy)\b/ # no point touching there
	592	) {
	593	DBIx::Class::Exception->throw( sprintf (
e5053694	594	"Illegal internal call of indirect proxy-method %s() with argument '%s': examine the last lines of the proxy method deparse below to determine what to call directly instead at %s on line %d\n\n%s\n\n Stacktrace starts",
77c3a5dc	595	$fr->[3], $argdesc, @{$fr}[1,2], ( $fr->[6] \|\| do {
	596	require B::Deparse;
	597	no strict 'refs';
	598	B::Deparse->new->coderef2text(\&{$fr->[3]})
	599	}),
	600	), 'with_stacktrace');
	601	}
	602	}
	603
b1dbf716	604	1;