From 821361b63ca5bf477eebc88759d8f3e7f69a93e3 Mon Sep 17 00:00:00 2001
From: Ricardo Signes <rjbs@cpan.org>
Date: Thu, 26 Sep 2013 22:44:00 -0400
Subject: [PATCH] preliminary postfix dereference docs

This commit adds an overview of the feature to perlref and a pointer
to the section in perlref to perlop's documentation of the arrow.

If/when this feature becomes non-experimental, the documentation
should be merged upward into Using References.

This documentation was written against a previous state of the
branch.  Is should be fact-checked before any merge.
---
 pod/perlop.pod  |  4 ++++
 pod/perlref.pod | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 4c26fe7..b968144 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -153,6 +153,10 @@ variable containing either the method name or a subroutine reference,
 and the left side must be either an object (a blessed reference)
 or a class name (that is, a package name).  See L<perlobj>.
 
+The dereferencing cases (as opposed to method-calling cases) are
+somewhat extended by the experimental C<postderef> feature.  For the
+details of that feature, consult L<perlref/Postfix Dereference Syntax>.
+
 =head2 Auto-increment and Auto-decrement
 X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
 
diff --git a/pod/perlref.pod b/pod/perlref.pod
index 4ed7e95..e9f7974 100644
--- a/pod/perlref.pod
+++ b/pod/perlref.pod
@@ -744,6 +744,60 @@ real refs, instead of the keys(), which won't.
 
 The standard Tie::RefHash module provides a convenient workaround to this.
 
+=head1 Postfix Dereference Syntax
+
+Beginning in v5.20.0, a postfix syntax for using references is
+available.  It behaves as described in L</Using References>, but instead
+of a prefixed sigil, a postfixed sigil-and-star is used.
+
+For example:
+
+    $r = \@a;
+    @b = $r->@*; # equivalent to @$r or @{ $r }
+
+    $r = [ 1, [ 2, 3 ], 4 ];
+    $r->[1]->@*;  # equivalent to @{ $r->[1] }
+
+This syntax must be enabled with C<use feature 'postderef'>.  It is
+experimental, and will warn by default unless C<no warnings
+'experimental::postderef'> is in effect.
+
+Postfix dereference should work in all circumstances where block
+(circumfix) dereference worked, and should be entirely equivalent.  This
+syntax allows dereferencing to be written and read entirely
+left-to-right.  The following equivalencies are defined:
+
+  $sref->$*;  # same as ${ $sref }
+  $aref->@*;  # same as @{ $aref }
+  $href->%*;  # same as %{ $href }
+  $cref->&*;  # same as &{ $cref }
+
+Note especially that C<< $cref->&* >> is I<not> equivalent to C<<
+$cref->() >>, and can serve different purposes.  C<< $gref->** >> is not
+(yet?) implemented.
+
+Postfix array and scalar dereferencing I<can> be used in interpolating
+strings (double quotes or the C<qq> operator), but only if the
+additional C<postderef_qq> feature is enabled.
+
+=head2 Postfix Reference Slicing
+
+Value slices of arrays and hashes may also be taken with postfix
+dereferencing notation, with the following equivalencies:
+
+  $aref->@[ ... ];  # same as @$aref[ ... ]
+  $href->@{ ... };  # same as @$href{ ... }
+
+Postfix key/value pair slicing is not I<yet> implemented, but will
+behave as expected:
+
+  $aref->%[ ... ];  # same as %$aref[ ... ]
+  $href->%{ ... };  # same as %$href{ ... }
+
+As with postfix array, postfix value slice dereferencing I<can> be used
+in interpolating strings (double quotes or the C<qq> operator), but only
+if the additional C<postderef_qq> feature is enabled.
+
 =head1 SEE ALSO
 
 Besides the obvious documents, source code can be instructive.
-- 
2.7.4