From c61010aafbd9317870eeb7f3fd2f1baca88d873c Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Mon, 31 May 2010 12:59:10 -0500 Subject: update docs for add_package_symbol --- lib/Package/Stash.pm | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'lib') diff --git a/lib/Package/Stash.pm b/lib/Package/Stash.pm index d632c37..6f0910c 100644 --- a/lib/Package/Stash.pm +++ b/lib/Package/Stash.pm @@ -98,7 +98,7 @@ sub namespace { } } -=head2 add_package_symbol $variable $value $filename $firstlinenum $lastlinenum +=head2 add_package_symbol $variable $value %opts Adds a new package symbol, for the symbol given as C<$variable>, and optionally gives it an initial value of C<$value>. C<$variable> should be the name of @@ -108,12 +108,16 @@ variable including the sigil, so will create C<%Foo::foo>. -The optional $filename, $firstlinenum, and $lastlinenum arguments can be used -to indicate where the symbol should be regarded as having been defined. +Valid options (all optional) are C, C, and +C. + +C<$opts{filename}>, C<$opts{first_line_num}>, and C<$opts{last_line_num}> can +be used to indicate where the symbol should be regarded as having been defined. Currently these values are only used if the symbol is a subroutine ('C<&>' -sigil) and only if C<$^P & 0x10> is true. In which case the special -C<%DB::sub> hash is updated to record the values of $filename, $firstlinenum, -and $lastlinenum for the subroutine. +sigil) and only if C<$^P & 0x10> is true, in which case the special C<%DB::sub> +hash is updated to record the values of C, C, and +C for the subroutine. If these are not passed, their values are +inferred (as much as possible) from C information. This is especially useful for debuggers and profilers, which use C<%DB::sub> to determine where the source code for a subroutine can be found. See -- cgit v1.2.3-54-g00ecf