You’re already using a dualvar without knowing it. The $! variable, which holds the value of the last system error, is most often used in its string form:

open my $fh, '>', $filename or die "Error: $!";

If something goes wrong with that open, you’ll get an error such as these:

No such file or directory
Permission denied

Both of those error messages have numbers associated with them. You can output their numeric value

open my $fh, '>', $filename or die $! + 0;

Now the errors are numbers, which correspond to the errno value for the system call:

2
13

These numbers are keys in the %!, and the value for that key is true if that was the last system error.

Perl, on its own, doesn’t give you a way to create this sort of variable yourself. When you assign a new value to a scalar, whether string or number, Perl clears the previous values it has. When you use a number as a string, Perl converts it to a string, and the same the other way around.

You can watch this with Devel::Peek. Here’s a program that sets a string value:

use Devel::Peek;

my $value = 'abc';

Dump( $value );

In the scalar record, the POK flag is set, indicating the variable has a string form, and the PV slot has a value (see perlguts for more details):

SV = PV(0x100801070) at 0x100827810
  REFCNT = 1
  FLAGS = (PADMY,POK,pPOK)
  PV = 0x100202870 "abc"\0
  CUR = 3
  LEN = 16

If you set a numeric value, the flags are different:

use Devel::Peek;

my $value = 137;

Dump( $value );

Now there’s an IOK flag, and one of the numeric slots, in this case the IV, is set:

SV = IV(0x100827800) at 0x100827810
  REFCNT = 1
  FLAGS = (PADMY,IOK,pIOK)
  IV = 137

However, if you take the numeric value and use it in a string context, Perl also creates a string version. Now the scalar has both the IOK and POK flags, and both the IV and PV slots have values:

137
SV = PVIV(0x100809208) at 0x100827840
  REFCNT = 1
  FLAGS = (PADMY,IOK,POK,pIOK,pPOK)
  IV = 137
  PV = 0x100202870 "137"\0
  CUR = 3
  LEN = 16

If you change the variable, some of those flags disappear, even though the values don’t necessarily disappear:

use v5.10;
use Devel::Peek;

my $value = 137;

$value = 'Buster';

Dump( $value );

Now the scalar’s value should be just Buster, but the IV slot still has the old 137. However, the IOK flag is gone:

SV = PVIV(0x100809208) at 0x100827840
  REFCNT = 1
  FLAGS = (PADMY,POK,pPOK)
  IV = 137
  PV = 0x100202870 "Buster"\0
  CUR = 6
  LEN = 16

When you set the new value, and Perl hadn’t used it in a numeric context yet, there was no need to go through the work to translate the string value to the number value. Instead, it just unset the flag that denotes its okay to use the value as a number. You have to use it as a number to again:

use v5.10;
use Devel::Peek;

my $value = 137;

$value = 'Buster';

say $value + 0;

Dump( $value );

Now Perl converts it to a number and sets the numeric flags again:

0
SV = PVNV(0x100801e30) at 0x100827840
  REFCNT = 1
  FLAGS = (PADMY,POK,pIOK,pNOK,pPOK)
  IV = 0
  NV = 0
  PV = 0x100202870 "Buster"\0
  CUR = 6
  LEN = 16

That’s how it works if you go through the Perl interface, but if you play it a scalar through the XS interface, you can set whatever flags and values that you like. That’s exactly what Scalar::Util‘s dualvar does that for you:

use v5.10;
use Devel::Peek;
use Scalar::Util qw(dualvar);

my $value = dualvar 137, 'Buster';

Dump( $value );

say "$value";
say $value + 0;

Now you have a scalar which has unrelated numeric and string values, and the flags for both values are set:

SV = PVNV(0x100802010) at 0x1008277c8
  REFCNT = 1
  FLAGS = (PADMY,IOK,POK,pIOK,pPOK)
  IV = 137
  NV = 0
  PV = 0x100202870 "Buster"\0
  CUR = 6
  LEN = 16
Buster
137

Things to remember

• Scalars can have both numeric and string values at the same time
• Those two values can be unrelated
• You can create your own dualvar with Scalar::Util

The autovivification pragma, which you can get from CPAN, lets you decide how autovivification works, or doesn’t work. As you saw in Understand autovivification, there are several ways that autovivification comes into play, specifically when you dereference an undefined value to:

• fetch a value
• store a value
• test an undefined value with exists
• delete an element

The pragma lets you control each of these independently.

The simplest use is simply unimport the module with no. This gets a bit tricky because this pragma is more interesting for what you disallow rather than enable:

no autovivification;

With no arguments, this turns off autovivification for fetching a value, or using delete or exists. This does not turn off autovivification for storing a value. You’re more likely to make mistakes with those first three, and most likely to get what you want with the last one.

None of these work, in that they don’t create any more of the data structure:

no autovivification;

my $cats;
delete $cats{'Buster'};
my $foo = $cats{'Buster'}; 

if( exists $cats{'Buster'} ) { 1 }

use Data::Dumper;
print Dumper( $cats );

You don’t get an error or a warning, but nothing happens to $cats, which is still undefined at the end. The pragma just leaves the undefined value as it is and your program continues. In those cases, you still get the answers that expect. When the element isn’t there, you still get undef when you try to access it. It stills returns false when you try exists and the element isn’t there after a exists. Your program continues without a warning.

If you want to know when you’ve skipped at possible autovivification, you can also tell autovivification to warn you, or if you’re really paranoid, kill your program.

Including the warn option gives you warnings. As with any import list, when you specify something you override all defaults. If you still want those defaults, you have to list them explicitly:

no autovivification qw(fetch delete exists warn);

use Data::Dumper;

my $cats;

delete $cats->{Buster};

print Dumper( $cats );

Now you get a warning:

Reference was vivified at auto.pl line 7.
$VAR1 = undef;

If you want to stop the program, you use strict instead of warn:

no autovivification qw(fetch delete exists strict);

use Data::Dumper;

my $cats;

delete $cats->{Buster};

print Dumper( $cats );

Your program stops at the point that Perl tries to autovivify something and gives you an file and line where autovivification stopped your program:

Reference vivification forbidden at auto.pl line 7.

When you store a value, however, autovivification doesn’t get in your way, even if you create a deep one:

no autovivification;

use Data::Dumper;

my $cats;

$cats->{Buster}{count} = 9;

print Dumper( $cats );

You still autovivified the structure:

$VAR1 = {
          'Buster' => {
                        'count' => 9
                      }
        };

If you want to turn off autovification for storing a variable, you have to explicitly disallow it. As before, you have to provide the other default options that you’d like to keep:

no autovivification qw(fetch delete exists store strict);

use Data::Dumper;

my $cats;

$cats->{Buster}++;

print Dumper( $cats );

Now, when you try to autovivify a hash reference to store a value in the Buster key, your program stops (because you are also using strict:

Reference vivification forbidden at auto.pl line 7.

Lexical scope

You can limit the effect of autovivification pragma to part of your program by using it in only in the scope where you need it. There are two ways that you can do this, depending on what you need.

First, you can turn off all autovivification for the entire file (which is itself a scope, see Know what creates a scope), but re-enable it for the bits where you need it:

no autovivification qw(fetch delete exists store strict);

# can't do it in here

{
use autovivification qw(store);

...; # allow some of it in here
}

# can't do it in here, either

Second, you can leave Perl’s normal autovivification features in place for the entire file, but turn it off in the sensitive parts of the program, just as in Item 100. Use lexical warnings to selectively turn on or off complaints (but in this case, engaging safety features):

...; # program with possible autovivification

{
# can't do it in here
no autovivification qw(fetch delete exists store strict);

}

...; # program with possible autovivification

Things to remember

• The autovivification pragma lets you disable Perl’s automatic data structure creation
• The defaults do not prevent you from assigning to an autovivified reference
• You can enable warnings or errors to catch autovivification events

In general, a string eval is a dangerous and tricky feature, and most good Perl programmers will tell you not to use it (see Know the two different forms of eval). That, in general, is good advice. If you can reasonably get the job done without the string eval, you’re probably better off. Sometimes, however, you need the string eval, and for the rest of this Item I’ll assume you have a good reason.

Consider this bit of code that issues a warning and has a fatal error that the eval catches:

use v5.14;
use warnings;
say 'Hello';

eval q(
	my $string;
	print $string;

	die 'Dying in eval';
	);
print $@;

The output shows the warning and the error, and each has a line number. However, there’s no filename and the line number doesn’t correspond either to the actual line of the statement of the line of the eval:

Hello
Use of uninitialized value $string in say at (eval 1) line 3.
Dying in eval at (eval 1) line 5.

You can solve this with a preprocessor comment. Few people know that Perl looks for a couple of special pre-processor commands, but it’s right there in perlsyn. You can change what perl thinks the line number and filename are with a line that starts with # line. You follow that with the line number and the filename (optionally in double quotes):

use warnings;

my $string; # no value there!

print $string; # gets right line and file in warning

# line 58976 "Buster.pm"
print $string;

# line 65783 "Mimi.pm"
print $string;

# line 137
print $string;

Now, the warnings make it look like there are at least two modules having problems even though there is a single file. Without a filename in the command, perl uses the previous filename, as in the last line of this output:

Use of uninitialized value $string in print at line.pl line 5.
Use of uninitialized value $string in print at Buster.pm line 58976.
Use of uninitialized value $string in print at Mimi.pm line 65783.
Use of uninitialized value $string in print at Mimi.pm line 137.

You should do this only when Perl expects a new statement. If you place one of those pre-processor commands in the middle of a statement, odd things can happen:

use warnings;

my $string; # no value there!

print $string; # gets right line and file in warning

print
# line 58976 "Buster.pm"
	$string;

# line 65783 "Mimi.pm"
print $string;

# line 137
print $string;

The output shows that perl changed the current filename to Buster.pm but did not change the line number. For that warning, the line number is the actual line number:

Use of uninitialized value $string in print at line.pl line 5.
Use of uninitialized value $string in print at Buster.pm line 7.
Use of uninitialized value $string in print at Mimi.pm line 65783.
Use of uninitialized value $string in print at Mimi.pm line 137.

Once you know that, you can use this in your string eval, which perl compiles just like any other Perl code, including this pre-processor command. You can use the special literals __FILE__ and __LINE__ (documented in perldata) to get the current values instead of hard-coding them. You can only use those as separate tokens, which makes their use a bit messy.

This code is the same as the first example in this Item, put with the addition of a pre-processor line as the first line in the eval string:

use v5.14;
use warnings;
say 'Hello';

eval '# line '. __LINE__ . ' "' . __FILE__ . qq("\n) . q(
	my $string;
	print $string;

	die 'Dying in eval';
	);
say $@;

Now the eval warnings and error messages show a filename and line number, and the line number corresponds to its actual location in the file:

Hello
Use of uninitialized value $string in print at eval.pl line 7.
Dying in eval at eval.pl line 9.

Note that changing the line number and filename also change __LINE__ and __FILE__, meaning there’s no way to get back to the actual line number and filename. As such, you probably only want to use these to represent the actual values:

use v5.14;
use warnings;

# line 58976 "Buster.pm"
say "line ", __LINE__, " file ", __FILE__

line 58976 file Buster.pm

Things to remember

• String eval act like their own virtual file for line numbering
• You can modify the current line number and filename with the # line pre-processor command
• You can use # line in your string eval
• The special literals __LINE__ and __FILE__ report the line number and filename.

You handle these special signals by setting values in the %SIG hash just like you would for any other signal. Since these are internal to perl, the signal names have underscores around them to distinguish them from external signal names:

$SIG{__WARN__} = \&some_Sub;
$SIG{__DIE__} = sub { ... };

I’ll treat the __WARN__ in a different Item, because even though these look like they should do the same sort of thing, they really don’t. The warn prints a message and lets the program continue. The die is designed to kill the program (hence, it’s morbid name) by starting a sequence of events that leads to the program’s shutdown. However, die became Perl’s fake exception mechanism, now used more to signal an error but without the intent to stop the program. Most of what die is supposed to do is discarded by catching it in an eval now:

eval {
	...;
	die( ... );
	...;
	};
if( $@ ) { ... }

This still triggers the __DIE__ signal even though Perl knows that you aren’t going to exit the program. This means that if you want to handle __DIE__ on your own, you need to distinguish between those cases where you should shut down the program, which seem to be the rare uses now, and the ones inside an eval that should not shutdown the program. You don’t want to, for instance, start cleaning up database connections, logging, and other resources if the program is going to magically recover saying “I’m not dead yet!”.

There’s a Perl special variable that can help. The documentation for die recommends that you start your __DIE__ handler by checking $^S before you continue. Inside the handler, the special handler is turned off so die inside $SIG{__DIE__} is the real die. The value of $^S will be true if it came from within an eval, so this just re-throws the exception without handling it:

$SIG{__DIE__} = sub {
	die @_ if $^S;
	...;
	};

This way, you’ll skip anything you might want to do to handle during a real shutdown.

There’s an additional twist. Perl might throw the __DIE__ signal if there’s a problem during parsing. That is, you can actaully catch compilation errors:

use strict;
use warnings;
use 5.010;

BEGIN { $SIG{__DIE__} = sub { print "Caught error: [@_]\n" } }

while( <> ) {
	next if m/(/; # compile-time error
	}

Now you get a double error message. You might not have meant to catch those sorts of errors, but you might.

Caught error: [Unmatched ( in regex; marked by <-- HERE in m/( <-- HERE / at test line 8.
]
Unmatched ( in regex; marked by <-- HERE in m/( <-- HERE / at test line 8.

The problem with these errors is that the parser might not have done everything you thought it should have done by tht point. Relying on anything, such as a subroutine definition is dangerous. The value of $^S will be undefined in this case, so your handler might now become:

$SIG{__DIE__} = sub {
	die @_ if( $^S or not defined $^S );
	...;
	};

Skipping those two cases, the eval and compile-time parsing, leaves you just with the case of actually exiting the program. However, there's another mechanism that might work better for you: the END block, which I covered in Know the phases of a Perl program’s execution. Anything in the END block executes as the program shuts down:

END {
	...
	}

However, if you really need to catch calls to die, you can define CORE::GLOBAL::die (see Use CORE when you need the real thing). This won't catch parsing errors, and will only affect calls to die (even in an eval). To use it, you need to declare it before perl parses any of the die statements that you want to replace. You can do this in a BEGIN block:

use strict;
use warnings;
use 5.010;

BEGIN { *CORE::GLOBAL::die = sub { say "In CORE::GLOBAL::die: [@_]" } }

eval {
	say "Inside eval";
	die 'Die-ing in eval';
	say "Past die in eval";
	};

die "This is the real die";

say "I got to the end!";

This version of die merely outputs a message, but without stopping the program. Thus, you see the message from the last say in the eval:

Inside eval
In CORE::GLOBAL::die: [Die-ing in eval]
Past die in eval
In CORE::GLOBAL::die: [This is the real die]
I got to the end!

Your new die doesn't stop the program, so you might put in an exit:

use strict;
use warnings;
use 5.010;

BEGIN {
*CORE::GLOBAL::die = sub {
	say "In CORE::GLOBAL::die: [@_]";
	exit(1);
	}
	}

eval {
	say "Inside eval";
	die 'Die-ing in eval';
	say "Past die in eval";
	};
if( $@ ) {
	say "Caught [$@]";
	}

die "This is the real die";

say "I got to the end!";

Now your program stops in the eval because you call exit, but notice that it actually exits. That means there is no $@ to catch. eval does not catch an exit:

Inside eval
In CORE::GLOBAL::die: [Die-ing in eval]

If you want to get back to the real die, you can use CORE::die. For instance, you can die only if you are in an eval, making it catchable, and exit otherwise:

use strict;
use warnings;
use 5.010;

BEGIN {
*CORE::GLOBAL::die = sub {
	say "In CORE::GLOBAL::die: [@_]";
	CORE::die( @_ ) if $^S;
	exit(1);
	}
	}

eval {
	say "Inside eval";
	die 'Die-ing in eval';
	say "Past die in eval";
	};
if( $@ ) {
	say "Caught: [$@]";
	}

die "This is the real die";

say "I got to the end!";

Now the program behavior is almost back to what you expect from the real die:

Inside eval
In CORE::GLOBAL::die: [Die-ing in eval]
Caught: [Die-ing in eval at test line 8.
]
In CORE::GLOBAL::die: [This is the real die]

Now that you are this far, there are a few more tricks that you can play. For instance, you might want to catch all string arguments to die and turn them into objects. If they are already objects, you propagate them with some extra information.

Here's an example with a MyError class you can use as an error object. It knows how to stringify its object and it defines its own special PROPAGATE method to carry a message through several layers of eval:

use strict;
use warnings;
use Scalar::Util qw(blessed);
use 5.014;

package MyError {
	use overload '""' => \&as_string;

	sub new {
		bless { message => $_[1] }, $_[0];
		}

	sub PROPAGATE {
		$_[0]->{message} .= "Passed through at file $_[1] line $_[2]\n";
		}

	sub as_string { "Stringified: <$_[0]->{message}>" }
	}

BEGIN {
*CORE::GLOBAL::die = sub {
	say "In CORE::GLOBAL::die: [@_]";
	$@ = do {
		if( blessed $@ and $@->can('PROPAGATE') ) {
			$@->PROPAGATE(__FILE__, __LINE__);
			}
		elsif( not blessed $@ ) {
			MyError->new( 'Made object: [' . join( ' ', @_) . "]\n" );
			}
		};
	CORE::die( $@ );
	}
	}

eval {
	eval {
		say "Inside eval";
		die 'Die-ing in eval';
		say "Past die in eval";
		};
	if( $@ ) {
		die $@;
		}
	};
if( $@ ) {
	say "Caught: [$@]";
	}

die "This is the real die";

say "I got to the end!";

Now the output is a layered mess of error messages within error messages, but you had quite a bit of control over those messages:

Inside eval
In CORE::GLOBAL::die: [Die-ing in eval]
In CORE::GLOBAL::die: [Stringified: <Made object: [Die-ing in eval]
>]
In CORE::GLOBAL::die: [Caught: [Made object: [Die-ing in eval]
Passed through at file test line 25
]]
Stringified: <Made object: [Caught: [Made object: [Die-ing in eval]
Passed through at file test line 25
]]
>

Things to remember

• $SIG{__DIE__} catches much more than a program's death
• Use END blocks for end-of-program cleanups if you can
• Override CORE::GLOBAL::die if you really need to replace die.

Git has many nice features, some of which people consider advantages over other source control paradigms. As a distributed system, you don’t need anyone’s permission to use it. You don’t have to ask anyone to set up a repository for you, and you can install the client software yourself. This isn’t a Git tutorial. You’ll find enough of those on the interwebs, especially by Scott Chacon.

Create your first repository

Creating a git repository is easy. The repo itself carries everything that you need (that’s part of its distributed nature), so you don’t need to do much to create and use a repository. You don’t need anyone’s permission and you don’t need net access. Everything the repository needs is directly in the repositories directory, so once you are done with it, you can simply delete the directory without any additional cleanup.

Suppose that you wanted to start using Git with one of your Perl distributions. Change into its directory and create the repo:

$ cd Some-Module-Distribution-Directory
$ git init
$ git add .
$ git commit -m 'initial import'

That’s it. Now you have a Git repository. The init creates the repository, the add tracks files (and the . works on the current directory, tracking the directory and everything below). The commit makes it official.

The next step is to work on your Perl distribution. Isn't working on the Perl the point, anyway? You need to makes some changes to track changes. From that point, it's the basic Git workflow. You can add individual files and commit their changes:

$ git add lib/Foo.pm
$ git commit -m 'Made things work'

You'll get some output:

[master 3663fe3] Made things work
 1 files changed, 1 insertions(+), 0 deletions(-)

That number after master is the first part of the commit ID, a SHA-1 digest that not only identifies the particular commit, but everything that led up to it. Again, the Git tutorials will explain these things.

You just keep doing that until your software rules the world.

Work on other distributions

But you can use Git with Perl distributions that aren't yours. Since you don't have to do much work to create the repository, it makes sense to make temporary repositories for other people's distributions when you want to make a patch. IF you like, you can download the distribution, unpack it, and create the repository just like you did before:

$ curl -O  http://www.cpan.org/authors/id/T/TU/TURNSTEP/Net-SSH-Perl-1.34.tar.gz
$ tar -xzf Net-SSH-Perl-1.34.tar.gz
$ cd Net-SSH-Perl-1.34
$ git init
$ git add .
$ git commit -m 'initial import of Net-SSH-Perl-1.34'

Now you have the module you want to patch in a Git repository, and you've saved the initial state of the repository. Make your changes, commiting as many times as you like along the way.

After you do your work, you can easily create patches. Check your log to find the commit where you want to start. The --oneline log format is useful just to see the commit digests and the short messages:

$ git log --oneline
5cbbf58 Make delete part of the pipeline
33268fc Removed keyword
5efbedd Initial import of Net-SSH-Perl-1.34

Since you want to create the patches for the work you've done since the initial import, you tell git to create those patch files by specify where it should start by giving it the commit digest. There are many ways to specify how you want to create the patch, but this is easy enough:

$ git format-patch 5efbedd
0001-Removed-keyword.patch
0002-Make-delete-part-of-the-pipeline.patch

There you are. You have one file per change (although you can do that differently as well). Those are the files you need to send off. If you're used to doing with with the diff tool, notice that you don't have to keep two copies of the distribution for comparison and you don't have to remember if the original directory comes first or second. Git does all of that work for you.

That's the basic idea, and that's easy, but it gets even easier.

git-cpan

Yanick Champoux created the Git::CPAN::Patch distribution so you can easily interact with CPAN distributions with git, but especially so you can download the latest version, create a patch, and submit it while doing as little work as possible. Yanick first mentioned his work in a Use.perl post after he wrote an artile about it for The Perl Review 5.1.

His Git::CPAN::Patch distribution installs several Perl programs that you'll use as regular git commands. You can even make your own git commands; installed in the right place (somewhere in PATH), a script named git-foo becomes the git foo you type at the command line.

Suppose that you wanted to make a patch to Module::Build. Create a directory to hold your repository, change into it, then call git cpan-init:

$ mkdir module-build
$ cd module-build
$ git cpan-init Module::Build

Now you have the latest version of Module::Build in a Git repository, making it easy for you to do work and later create the patch. So, do that. Perhaps you can fix one of the outstanding bugs in its RT queue. As you go along, commit as normal.

After many commits, perhaps you're ready to submit a patch. Instead of creating a patch for each commit, you can combine them into one big commit. The git cpan-squash command takes your commits and turns them into a single commit in a new branch:

$ git cpan-squash some_branch

After you do that, git cpan-squash leaves you on the branch that it created for you so you can do the final step: sending the patch to the RT queue. You don't even need to know anything about RT:

$ git cpan-send-path

That's it. Now that you are done, you can keep the repository or get rid of it.

Things to remember

• You can use Git for lightweight, short term repositories.
• You can use Git to make quick patches to other people's distributions
• Git::CPAN::Patch installs git commands that interact with CPAN for you.