Perl: Experimental Features and Perldoc

Question

I was inadvertently using Perl 5.14's experimental autoderef feature in Perl 5.20 and of course getting warnings about its use. The diagnostics pragma explains how to suppress these warning messages if need be; however, I wanted to learn more about the root cause of this warning (and really the feature overall), so I turned to perldoc to learn more about autoderef.

The perldoc experimental command lists the autoderef feature with a high-level statement about its purpose, but nothing more.

The perldoc perlexperiment command provides greater detail about other experimental features, but autoderef is not mentioned at all.

I've tried various other perldoc options (e.g., -v,-f,etc), but to no avail.

What is an effective way to traceback such warning / diagnostics messages using perldoc? Are experimental features not covered in perldoc?

UPDATE: Please see @ThisSuitIsBlackNot's EXCELLENT answer below.

For further clarity and reference: it seems odd that the autoderef namespace did not hold throughout all the various documentation (i.e., perlexperiment, perldelta, perldoc etc.). perldoc experiment called it autoderef, perldelta5140 referred to it as auto-deref. perldoc perlexperiment used some language from the perldelta page, but not autoderef or the like.

Since diagnostics stated the associated warnings could be suppressed using no warnings "experimental::autoderef". It would be nice to use that as a starting point in perldoc. That is, find relative documentation with perldoc experimental::autoderef, matching the syntax and semantics provided by diagnostics and/or warnings.

Answer 1

When features are added to or removed from the Perl core, they are documented in perldelta, so if you get a warning about a feature being experimental, that's a good place to look.

If you know the feature was added in Perl 5.14.0:

perldoc perl5140delta

If not:

grep -lr autoderef $(dirname $(perldoc -l perldelta))

The description you linked to in perl5140delta is pretty thorough on its own, but notice that it gives a list of built-in functions that autoderef applies to. Run perldoc -f <function> to see the documentation for built-in functions, e.g. perldoc -f push:

Starting with Perl 5.14, push can take a scalar EXPR, which must hold a reference to an unblessed array. The argument will be dereferenced automatically. This aspect of push is considered highly experimental. The exact behaviour may change in a future version of Perl.

The reason for the warning is documented in perl5200delta:

The "auto-deref" feature is experimental.

Starting in v5.14.0, it was possible to use push, pop, keys, and other built-in functions not only on aggregate types, but on references to them. The feature was not deployed to its original intended specification, and now may become redundant to postfix dereferencing. It has always been categorized as an experimental feature, and in v5.20.0 is carries a warning as such.

And actually, autoderef is mentioned in perlexperiment, although it's under the heading "Array and hash container functions accept references" (the same heading used in perl5140delta):

• Array and hash container functions accept references

  Introduced in Perl 5.14.0

  The ticket for this feature is [perl #119437].

If you view the online documentation, you can follow the link to issue #119437 in Perl's issue tracker, where you can follow development details related to the feature.

---

In case you were curious, it looks like autoderef is getting axed in the next release:

The autoderef feature has been removed

The experimental autoderef feature (which allowed calling push, pop, shift, unshift, splice, keys, values, and each on a scalar argument) has been deemed unsuccessful. It has now been removed; trying to use the feature (or to disable the experimental::autoderef warning it previously triggered) now yields an exception.