diff options
-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 |