I agree with Tanktalus' comments. I wanted to read the code but it is quite hard to find the code with the POD all mixed up with it. Please consider making the code easier to read and the POD easier to read (and both easier to maintain) by keeping them separate.

I would rename the get() method to something very distinctive. It would be useful to be able to search for all instances of, for example, unhide_string() to audit the places where the sensitive data is being exposed to ensure they are all appropriate.

I can see the motivation for auto_get() but I also don't think it will be enough of a solution.

I'd probably go for a more direct approach at preventing specific leakage. The first thing is to prevent the sensitive string from being logged.

So provide a class that you can tie the log file handle to such that any uses of the file handle set a global "unsecure" flag:

sub Text::Hidden::Handle::PRINT {
    local( $Text::Hidden::SECURE ) = 0;
    ...
}

sub Text::Hidden::as_string {
    my( $self ) = @_;
    return $self->{value}
        if  $SECURE;
    return $self->get_obscured_value();
}
[download]

Another place you don't want to leak such information is into a database. I'd be tempted to walk caller() information looking for DBI or DBD::* modules, though I somewhat worry about the efficiency of that. Perhaps one only need walk a couple of levels up for such a check, though.

So, there will be some situations where you can unhide the sensitive string only a couple of places where it is actually used. There will be other situations where the value is used in in a bunch of code, some of which you have no control over and you just want to identify the few places where information can escape the process and block those exits. auto_get() may be sufficient for many of these second cases but I also think it will be harder to get working that way.

And that last point means that you should provide a debug option that logs the places where the string value was asked for and whether a hidden or unhidden version was provided.