[perl5.git] / cpan / experimental / lib / experimental.pm

package experimental;
$experimental::VERSION = '0.028';
use strict;
use warnings;
use version ();

BEGIN { eval { require feature } };
use Carp qw/croak carp/;

my %warnings = map { $_ => 1 } grep { /^experimental::/ } keys %warnings::Offsets;
my %features = map { $_ => 1 } $] > 5.015006 ? keys %feature::feature : do {
	my @features;
	if ($] >= 5.010) {
		push @features, qw/switch say state/;
		push @features, 'unicode_strings' if $] > 5.011002;
	}
	@features;
};

my %min_version = (
	args_array_with_signatures => '5.20.0',
	array_base      => '5',
	autoderef       => '5.14.0',
	bitwise         => '5.22.0',
	builtin         => '5.35.7',
	const_attr      => '5.22.0',
	current_sub     => '5.16.0',
	declared_refs   => '5.26.0',
	defer           => '5.35.4',
	evalbytes       => '5.16.0',
        extra_paired_delims => '5.35.9',
	fc              => '5.16.0',
	for_list        => '5.35.5',
	isa             => '5.31.7',
	lexical_topic   => '5.10.0',
	lexical_subs    => '5.18.0',
	postderef       => '5.20.0',
	postderef_qq    => '5.20.0',
	refaliasing     => '5.22.0',
	regex_sets      => '5.18.0',
	say             => '5.10.0',
	smartmatch      => '5.10.0',
	signatures      => '5.20.0',
	state           => '5.10.0',
	switch          => '5.10.0',
	try             => '5.34.0',
	unicode_eval    => '5.16.0',
	unicode_strings => '5.12.0',
);
my %removed_in_version = (
	array_base      => '5.30.0',
	autoderef       => '5.24.0',
	lexical_topic   => '5.24.0',
);

$_ = version->new($_) for values %min_version;
$_ = version->new($_) for values %removed_in_version;

my %additional = (
	postderef     => ['postderef_qq'],
	switch        => ['smartmatch'],
	declared_refs => ['refaliasing'],
);

sub _enable {
	my $pragma = shift;
	if ($warnings{"experimental::$pragma"}) {
		warnings->unimport("experimental::$pragma");
		feature->import($pragma) if exists $features{$pragma};
		_enable(@{ $additional{$pragma} }) if $additional{$pragma};
	}
	elsif ($features{$pragma}) {
		feature->import($pragma);
		_enable(@{ $additional{$pragma} }) if $additional{$pragma};
	}
	elsif (not exists $min_version{$pragma}) {
		croak "Can't enable unknown feature $pragma";
	}
	elsif ($] < $min_version{$pragma}) {
		my $stable = $min_version{$pragma}->stringify;
		$stable =~ s/^ 5\. ([0-9]?[13579]) \. \d+ $/"5." . ($1 + 1) . ".0"/xe;
		croak "Need perl $stable or later for feature $pragma";
	}
	elsif ($] >= ($removed_in_version{$pragma} || 7)) {
		croak "Experimental feature $pragma has been removed from perl in version $removed_in_version{$pragma}";
	}
}

sub import {
	my ($self, @pragmas) = @_;

	for my $pragma (@pragmas) {
		_enable($pragma);
	}
	return;
}

sub _disable {
	my $pragma = shift;
	if ($warnings{"experimental::$pragma"}) {
		warnings->import("experimental::$pragma");
		feature->unimport($pragma) if exists $features{$pragma};
		_disable(@{ $additional{$pragma} }) if $additional{$pragma};
	}
	elsif ($features{$pragma}) {
		feature->unimport($pragma);
		_disable(@{ $additional{$pragma} }) if $additional{$pragma};
	}
	elsif (not exists $min_version{$pragma}) {
		carp "Can't disable unknown feature $pragma, ignoring";
	}
}

sub unimport {
	my ($self, @pragmas) = @_;

	for my $pragma (@pragmas) {
		_disable($pragma);
	}
	return;
}

1;

#ABSTRACT: Experimental features made easy

__END__

=pod

=encoding UTF-8

=head1 NAME

experimental - Experimental features made easy

=head1 VERSION

version 0.027

=head1 SYNOPSIS

 use experimental 'lexical_subs', 'signatures';
 my sub plus_one($value) { $value + 1 }

=head1 DESCRIPTION

This pragma provides an easy and convenient way to enable or disable
experimental features.

Every version of perl has some number of features present but considered
"experimental."  For much of the life of Perl 5, this was only a designation
found in the documentation.  Starting in Perl v5.10.0, and more aggressively in
v5.18.0, experimental features were placed behind pragmata used to enable the
feature and disable associated warnings.

The C<experimental> pragma exists to combine the required incantations into a
single interface stable across releases of perl.  For every experimental
feature, this should enable the feature and silence warnings for the enclosing
lexical scope:

  use experimental 'feature-name';

To disable the feature and, if applicable, re-enable any warnings, use:

  no experimental 'feature-name';

The supported features, documented further below, are:

=over 4

=item * C<args_array_with_signatures> - allow C<@_> to be used in signatured subs.

This is supported on perl 5.20.0 and above, but is likely to be removed in the future.

=item * C<array_base> - allow the use of C<$[> to change the starting index of C<@array>.

This was removed in perl 5.30.0.

=item * C<autoderef> - allow push, each, keys, and other built-ins on references.

This was added in perl 5.14.0 and removed in perl 5.24.0.

=item * C<bitwise> - allow the new stringwise bit operators

This was added in perl 5.22.0.

=item * C<builtin> - allow the use of the functions in the builtin:: namespace

This was added in perl 5.36.0

=item * C<const_attr> - allow the :const attribute on subs

This was added in perl 5.22.0.

=item * C<declared_refs> - enables aliasing via assignment to references

This was added in perl 5.26.0.

=item * C<defer> - enables the use of defer blocks

This was added in perl 5.36.0

=item * C<for_list> - allows iterating over multiple values at a time with C<for>

This was added in perl 5.36.0

=item * C<isa> - allow the use of the C<isa> infix operator

This was added in perl 5.32.0.

=item * C<lexical_topic> - allow the use of lexical C<$_> via C<my $_>.

This was added in perl 5.10.0 and removed in perl 5.24.0.

=item * C<lexical_subs> - allow the use of lexical subroutines.

This was added in 5.18.0.

=item * C<postderef> - allow the use of postfix dereferencing expressions

This was added in perl 5.20.0, and became non-experimental (and always enabled) in 5.24.0.

=item * C<postderef_qq> - allow the use of postfix dereferencing expressions inside interpolating strings

This was added in perl 5.20.0, and became non-experimental (and always enabled) in 5.24.0.

=item * C<re_strict> - enables strict mode in regular expressions

This was added in perl 5.22.0.

=item * C<refaliasing> - allow aliasing via C<\$x = \$y>

This was added in perl 5.22.0.

=item * C<regex_sets> - allow extended bracketed character classes in regexps

This was added in perl 5.18.0.

=item * C<signatures> - allow subroutine signatures (for named arguments)

This was added in perl 5.20.0.

=item * C<smartmatch> - allow the use of C<~~>

This was added in perl 5.10.0, but it should be noted there are significant
incompatibilities between 5.10.0 and 5.10.1.

=item * C<switch> - allow the use of C<~~>, given, and when

This was added in perl 5.10.0.

=item * C<try> - allow the use of C<try> and C<catch>

This was added in perl 5.34.0

=item * C<win32_perlio> - allows the use of the :win32 IO layer.

This was added on perl 5.22.0.

=back

=head2 Ordering matters

Using this pragma to 'enable an experimental feature' is another way of saying
that this pragma will disable the warnings which would result from using that
feature.  Therefore, the order in which pragmas are applied is important.  In
particular, you probably want to enable experimental features I<after> you
enable warnings:

  use warnings;
  use experimental 'smartmatch';

You also need to take care with modules that enable warnings for you.  A common
example being Moose.  In this example, warnings for the 'smartmatch' feature are
first turned on by the warnings pragma, off by the experimental pragma and back
on again by the Moose module (fix is to switch the last two lines):

  use warnings;
  use experimental 'smartmatch';
  use Moose;

=head2 Disclaimer

Because of the nature of the features it enables, forward compatibility can not
be guaranteed in any way.

=head1 SEE ALSO

L<perlexperiment|perlexperiment> contains more information about experimental features.

=head1 AUTHOR

Leon Timmermans <leont@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Leon Timmermans.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut
Commit	Line	Data
de84ff2b	1	package experimental;
9c9853e8	2	$experimental::VERSION = '0.028';
de84ff2b RS	3	use strict;
de84ff2b RS	4	use warnings;
edd0583e	5	use version ();
de84ff2b	6
62805098	7	BEGIN { eval { require feature } };
de84ff2b RS	8	use Carp qw/croak carp/;
	9
	10	my %warnings = map { $_ => 1 } grep { /^experimental::/ } keys %warnings::Offsets;
f8c3bb9c CBW	11	my %features = map { $_ => 1 } $] > 5.015006 ? keys %feature::feature : do {
	12	my @features;
	13	if ($] >= 5.010) {
	14	push @features, qw/switch say state/;
	15	push @features, 'unicode_strings' if $] > 5.011002;
	16	}
	17	@features;
	18	};
de84ff2b RS	19
de84ff2b RS	20	my %min_version = (
f7a09054	21	args_array_with_signatures => '5.20.0',
f8c3bb9c CBW	22	array_base => '5',
f8c3bb9c CBW	23	autoderef => '5.14.0',
af9caa01	24	bitwise => '5.22.0',
f7a09054	25	builtin => '5.35.7',
b065a895	26	const_attr => '5.22.0',
f8c3bb9c	27	current_sub => '5.16.0',
b4d728a5	28	declared_refs => '5.26.0',
f7a09054	29	defer => '5.35.4',
f8c3bb9c	30	evalbytes => '5.16.0',
9c9853e8	31	extra_paired_delims => '5.35.9',
f8c3bb9c	32	fc => '5.16.0',
f7a09054	33	for_list => '5.35.5',
203ad3de	34	isa => '5.31.7',
f8c3bb9c CBW	35	lexical_topic => '5.10.0',
	36	lexical_subs => '5.18.0',
	37	postderef => '5.20.0',
	38	postderef_qq => '5.20.0',
af9caa01	39	refaliasing => '5.22.0',
f8c3bb9c CBW	40	regex_sets => '5.18.0',
	41	say => '5.10.0',
	42	smartmatch => '5.10.0',
	43	signatures => '5.20.0',
	44	state => '5.10.0',
	45	switch => '5.10.0',
875873b0	46	try => '5.34.0',
f8c3bb9c CBW	47	unicode_eval => '5.16.0',
f8c3bb9c CBW	48	unicode_strings => '5.12.0',
de84ff2b	49	);
203ad3de	50	my %removed_in_version = (
f7a09054 LT	51	array_base => '5.30.0',
	52	autoderef => '5.24.0',
	53	lexical_topic => '5.24.0',
61030386 CBW	54	);
61030386 CBW	55
f8c3bb9c	56	$_ = version->new($_) for values %min_version;
203ad3de	57	$_ = version->new($_) for values %removed_in_version;
de84ff2b RS	58
de84ff2b RS	59	my %additional = (
b4d728a5 SH	60	postderef => ['postderef_qq'],
	61	switch => ['smartmatch'],
	62	declared_refs => ['refaliasing'],
de84ff2b RS	63	);
	64
	65	sub _enable {
	66	my $pragma = shift;
	67	if ($warnings{"experimental::$pragma"}) {
	68	warnings->unimport("experimental::$pragma");
	69	feature->import($pragma) if exists $features{$pragma};
	70	_enable(@{ $additional{$pragma} }) if $additional{$pragma};
	71	}
	72	elsif ($features{$pragma}) {
	73	feature->import($pragma);
	74	_enable(@{ $additional{$pragma} }) if $additional{$pragma};
	75	}
	76	elsif (not exists $min_version{$pragma}) {
	77	croak "Can't enable unknown feature $pragma";
	78	}
61030386	79	elsif ($] < $min_version{$pragma}) {
f7a09054 LT	80	my $stable = $min_version{$pragma}->stringify;
f7a09054 LT	81	$stable =~ s/^ 5\. ([0-9]?[13579]) \. \d+ $/"5." . ($1 + 1) . ".0"/xe;
9c71c2c5	82	croak "Need perl $stable or later for feature $pragma";
de84ff2b	83	}
203ad3de SH	84	elsif ($] >= ($removed_in_version{$pragma} \|\| 7)) {
203ad3de SH	85	croak "Experimental feature $pragma has been removed from perl in version $removed_in_version{$pragma}";
4fdcb09b	86	}
de84ff2b RS	87	}
	88
	89	sub import {
	90	my ($self, @pragmas) = @_;
	91
	92	for my $pragma (@pragmas) {
	93	_enable($pragma);
	94	}
	95	return;
	96	}
	97
	98	sub _disable {
	99	my $pragma = shift;
	100	if ($warnings{"experimental::$pragma"}) {
	101	warnings->import("experimental::$pragma");
	102	feature->unimport($pragma) if exists $features{$pragma};
	103	_disable(@{ $additional{$pragma} }) if $additional{$pragma};
	104	}
	105	elsif ($features{$pragma}) {
	106	feature->unimport($pragma);
	107	_disable(@{ $additional{$pragma} }) if $additional{$pragma};
	108	}
	109	elsif (not exists $min_version{$pragma}) {
	110	carp "Can't disable unknown feature $pragma, ignoring";
	111	}
	112	}
	113
	114	sub unimport {
	115	my ($self, @pragmas) = @_;
	116
	117	for my $pragma (@pragmas) {
	118	_disable($pragma);
	119	}
	120	return;
	121	}
	122
	123	1;
	124
	125	#ABSTRACT: Experimental features made easy
	126
	127	__END__
	128
	129	=pod
	130
	131	=encoding UTF-8
	132
	133	=head1 NAME
	134
	135	experimental - Experimental features made easy
	136
	137	=head1 VERSION
	138
f7a09054	139	version 0.027
de84ff2b RS	140
	141	=head1 SYNOPSIS
	142
f7a09054 LT	143	use experimental 'lexical_subs', 'signatures';
f7a09054 LT	144	my sub plus_one($value) { $value + 1 }
de84ff2b RS	145
	146	=head1 DESCRIPTION
	147
	148	This pragma provides an easy and convenient way to enable or disable
	149	experimental features.
	150
	151	Every version of perl has some number of features present but considered
	152	"experimental." For much of the life of Perl 5, this was only a designation
	153	found in the documentation. Starting in Perl v5.10.0, and more aggressively in
	154	v5.18.0, experimental features were placed behind pragmata used to enable the
	155	feature and disable associated warnings.
	156
	157	The C<experimental> pragma exists to combine the required incantations into a
	158	single interface stable across releases of perl. For every experimental
	159	feature, this should enable the feature and silence warnings for the enclosing
	160	lexical scope:
	161
	162	use experimental 'feature-name';
	163
	164	To disable the feature and, if applicable, re-enable any warnings, use:
	165
	166	no experimental 'feature-name';
	167
	168	The supported features, documented further below, are:
	169
b065a895 S	170	=over 4
b065a895 S	171
f7a09054 LT	172	=item * C<args_array_with_signatures> - allow C<@_> to be used in signatured subs.
	173
	174	This is supported on perl 5.20.0 and above, but is likely to be removed in the future.
	175
b065a895 S	176	=item * C<array_base> - allow the use of C<$[> to change the starting index of C<@array>.
b065a895 S	177
f7a09054	178	This was removed in perl 5.30.0.
b065a895 S	179
	180	=item * C<autoderef> - allow push, each, keys, and other built-ins on references.
	181
f7a09054	182	This was added in perl 5.14.0 and removed in perl 5.24.0.
b065a895 S	183
	184	=item * C<bitwise> - allow the new stringwise bit operators
	185
	186	This was added in perl 5.22.0.
	187
f7a09054 LT	188	=item * C<builtin> - allow the use of the functions in the builtin:: namespace
	189
	190	This was added in perl 5.36.0
	191
b065a895 S	192	=item * C<const_attr> - allow the :const attribute on subs
	193
	194	This was added in perl 5.22.0.
	195
203ad3de SH	196	=item * C<declared_refs> - enables aliasing via assignment to references
	197
	198	This was added in perl 5.26.0.
	199
f7a09054 LT	200	=item * C<defer> - enables the use of defer blocks
	201
	202	This was added in perl 5.36.0
	203
	204	=item * C<for_list> - allows iterating over multiple values at a time with C<for>
	205
	206	This was added in perl 5.36.0
	207
203ad3de SH	208	=item * C<isa> - allow the use of the C<isa> infix operator
	209
	210	This was added in perl 5.32.0.
	211
b065a895 S	212	=item * C<lexical_topic> - allow the use of lexical C<$_> via C<my $_>.
b065a895 S	213
f7a09054	214	This was added in perl 5.10.0 and removed in perl 5.24.0.
b065a895 S	215
	216	=item * C<lexical_subs> - allow the use of lexical subroutines.
	217
	218	This was added in 5.18.0.
	219
203ad3de	220	=item * C<postderef> - allow the use of postfix dereferencing expressions
b065a895	221
203ad3de SH	222	This was added in perl 5.20.0, and became non-experimental (and always enabled) in 5.24.0.
	223
	224	=item * C<postderef_qq> - allow the use of postfix dereferencing expressions inside interpolating strings
	225
	226	This was added in perl 5.20.0, and became non-experimental (and always enabled) in 5.24.0.
b065a895 S	227
	228	=item * C<re_strict> - enables strict mode in regular expressions
	229
	230	This was added in perl 5.22.0.
	231
	232	=item * C<refaliasing> - allow aliasing via C<\$x = \$y>
	233
	234	This was added in perl 5.22.0.
	235
	236	=item * C<regex_sets> - allow extended bracketed character classes in regexps
	237
	238	This was added in perl 5.18.0.
	239
	240	=item * C<signatures> - allow subroutine signatures (for named arguments)
	241
	242	This was added in perl 5.20.0.
	243
	244	=item * C<smartmatch> - allow the use of C<~~>
	245
	246	This was added in perl 5.10.0, but it should be noted there are significant
	247	incompatibilities between 5.10.0 and 5.10.1.
	248
	249	=item * C<switch> - allow the use of C<~~>, given, and when
	250
	251	This was added in perl 5.10.0.
	252
875873b0 LT	253	=item * C<try> - allow the use of C<try> and C<catch>
	254
	255	This was added in perl 5.34.0
	256
b065a895 S	257	=item * C<win32_perlio> - allows the use of the :win32 IO layer.
	258
	259	This was added on perl 5.22.0.
	260
	261	=back
de84ff2b	262
4177cbce CBW	263	=head2 Ordering matters
	264
	265	Using this pragma to 'enable an experimental feature' is another way of saying
	266	that this pragma will disable the warnings which would result from using that
	267	feature. Therefore, the order in which pragmas are applied is important. In
	268	particular, you probably want to enable experimental features I<after> you
	269	enable warnings:
	270
	271	use warnings;
	272	use experimental 'smartmatch';
	273
	274	You also need to take care with modules that enable warnings for you. A common
	275	example being Moose. In this example, warnings for the 'smartmatch' feature are
	276	first turned on by the warnings pragma, off by the experimental pragma and back
	277	on again by the Moose module (fix is to switch the last two lines):
	278
	279	use warnings;
	280	use experimental 'smartmatch';
	281	use Moose;
	282
de84ff2b RS	283	=head2 Disclaimer
	284
	285	Because of the nature of the features it enables, forward compatibility can not
	286	be guaranteed in any way.
	287
b065a895 S	288	=head1 SEE ALSO
b065a895 S	289
203ad3de	290	L<perlexperiment\|perlexperiment> contains more information about experimental features.
b065a895	291
de84ff2b RS	292	=head1 AUTHOR
	293
	294	Leon Timmermans <leont@cpan.org>
	295
	296	=head1 COPYRIGHT AND LICENSE
	297
	298	This software is copyright (c) 2013 by Leon Timmermans.
	299
	300	This is free software; you can redistribute it and/or modify it under
	301	the same terms as the Perl 5 programming language system itself.
	302
	303	=cut