From 279f93ed17d3cc922ddea19033bcd0fe56b9a4a1 Mon Sep 17 00:00:00 2001
From: Kent Fredric <kentfredric@gmail.com>
Date: Sat, 10 Aug 2013 08:52:49 +1200
Subject: Add a WORKING WITH VARIABLES section trying to cover all the quirks
 of assign-by-value and assign-by-reference

---
 lib/Package/Stash.pm | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/lib/Package/Stash.pm b/lib/Package/Stash.pm
index 1dc6c1b..5ab183b 100644
--- a/lib/Package/Stash.pm
+++ b/lib/Package/Stash.pm
@@ -132,6 +132,50 @@ C<$type_filter> is passed, the hash will contain every variable of that type in
 the package as values, otherwise, it will contain the typeglobs corresponding
 to the variable names (basically, a clone of the stash).
 
+=head1 WORKING WITH VARIABLES
+
+It is important to note, that when working with scalar variables, default behavior is to B<copy> values.
+
+    my $stash = Package::Stash->new('Some::Namespace');
+    my $variable = 1;
+    # $Some::Namespace::name is a copy of $variable
+    $stash->add_symbol('$name', $variable);
+    $variable++
+    # $Some::Namespace::name == 1 , $variable == 2
+
+This will likely confuse people who expect it to work the same as Perl's own stash mechanism, which simply
+creates new references to existing variables.
+
+    my $variable = 1;
+    {
+        no strict 'refs';
+        # assign $Package::Stash::name = $variable
+        *{'Package::Stash::name'} = \$variable;
+    }
+    $variable++ # affects both names
+
+If this behaviour is desired when working with C<Package::Stash>, simply pass C<Package::Stash> a C<SCALAR> C<REF>
+
+    my $stash = Package::Stash->new('Some::Namespace');
+    my $variable = 1;
+    # $Some::Namespace::name is now $variable
+    $stash->add_symbol('$name', \$variable);
+    $variable++
+    # $Some::Namespace::name == 2 , $variable == 2
+
+This will be what you want as well if you're ever working with creating C<Readonly> variables
+
+    use Readonly;
+    Readonly my $value, 'hello';
+
+    $stash->add_symbol('$name', \$value); # reference
+    print $Some::Namespace::name; # hello
+    $Some::Namespace::name .= " world"; # Tries to modify the read-only 'hello' and dies.
+
+    $stash->add_symbol('$name', $value); # copy
+    print $Some::Namespace::name; # hello
+    $Some::Namespace::name .= " world"; # No problem, modifying a copy, not the original
+
 =head1 BUGS / CAVEATS
 
 =over 4
-- 
cgit v1.2.3