NAME

Devel::StringInfo - Gather information about strings

SYNOPSIS

my $string = get_string_from_somewhere();

use Devel::StringInfo qw(string_info);

# warn()s a YAML dump in void context
string_info($string);



# the above is actually shorthand for:
Devel::StringInfo->new->dump_info($string);


# you can also customize with options:
my $d = Devel::StringInfo->new(
	guess_encoding => 0,
);


# and collect data instead of formatting it as a string
my %hash = $d->gather_data( $string );

warn "it's a utf8 string" if $hash{is_utf8};

DESCRIPTION

This module is a debugging aid that helps figure out more information about strings.

Perl has two main "types" of strings, unicode strings (utf8::is_utf8 returns true), and octet strings (just a bunch of bytes).

Depending on the source of the data, what data it interacted with, as well as the fact that Perl may implicitly upgrade octet streams which represent strings in the native encoding to unicode strings, it's sometimes hard to know what exactly is going on with a string.

This module clumps together a bunch of checks you can perform on a string to figure out what's in it.

EXPORTS

This module optionally exports a string_info subroutine. It uses Sub::Exporter, so you can pass any options to the import routine, and they will be used to construct the dumper for your exported sub:

use Devel::StringInfo string_info => { guess_encoding => 0 };

ATTRIBUTES

guess_encoding

Whether or not to use Encode::Guess to guess the encoding of the data if it's not a unicode string.

encoding_suspects

The list of suspect encodings. See Encode::Guess. Defaults to the empty list, which is a special case for Encode::Guess.

include_value_info

Include some information about the string value (does it contain 0x00 chars, is it alphanumeric, does it have newlines, etc).

include_decoded

Whether to include a recursive dump of the decoded versions of a non unicode string.

include_hex

Whether to include a Data::HexDump::XXD dump in dump_info.

include_raw

Whether to include a simple interpolation of the string in dump_info.

METHODS

dump_info $string, %extra_fields

Use YAML to dump information about $string.

In void context prints, in other contexts returns the dump string.

If include_raw is set then a "raw" version (no escaping of the string) is appended with some boundry markings. This can help understand what's going on if YAML's escaping is confusing.

If include_hex is set then Data::HexDump::XXD will be required and used to dump the value as well.

gather_data $string, %opts

Gathers information about the string.

Calls various other gather_ methods internally.

Used by dump_info to dump the results.

In scalar context returns a hash reference, in list context key value pairs.

All hash references are tied to Tie::IxHash in order to be layed out logically in the dump.

%opts is not yet used but may be in the future.

AUTHOR

Yuval Kogman <nothingmuch@woobling.org>

COPYRIGHT & LICENSE

Copyright (c) 2007 Yuval Kogman. All rights reserved
This program is free software; you can redistribute it and/or modify it
under the terms of the MIT license or the same terms as Perl itself.