diff options
author | Kent Fredric <kentfredric@gmail.com> | 2013-08-10 08:52:49 +1200 |
---|---|---|
committer | Kent Fredric <kentfredric@gmail.com> | 2013-08-10 08:52:49 +1200 |
commit | 279f93ed17d3cc922ddea19033bcd0fe56b9a4a1 (patch) | |
tree | 5c86113d4f4490863bafc0dd42e4da60c9f25a46 /lib/Package | |
parent | e565af54b1ebba7c6c9e69a984e739f57c12135a (diff) | |
download | package-stash-279f93ed17d3cc922ddea19033bcd0fe56b9a4a1.tar.gz package-stash-279f93ed17d3cc922ddea19033bcd0fe56b9a4a1.zip |
Add a WORKING WITH VARIABLES section trying to cover all the quirks of assign-by-value and assign-by-reference
Diffstat (limited to 'lib/Package')
-rw-r--r-- | lib/Package/Stash.pm | 44 |
1 files changed, 44 insertions, 0 deletions
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 |