![]() |
![]()
| ![]() |
![]()
NAMEData::HexDump::Range - Hexadecimal Range Dumper with color, bitfields and skip rangesSYNOPSISmy $hdr = Data::HexDump::Range->new() ; print $hdr->dump([['magic cookie', 12, 'red'],['image type', 2, 'green']], $data) ; print $hdr->dump('magic cookie, 12, red :image type, 2, green', $data) ; $hdr->gather(['magic cookie', 12, 'red'], $data) ; $hdr->gather(['image type', 2, 'green'], $other_data) ; print $hdr->dump_gathered() ; $hdr->reset() ; DESCRIPTIONCreates a dump from binary data and user defined range descriptions. The goal of this module is to create an easy to understand dump of binary data.This achieved through:
DOCUMENTATIONThe shortest perl dumper is "perl -ne 'BEGIN{$/=\16} printf "%07x0: @{[unpack q{(H2)*}]}\n", $.-1'", courtesy of a golfing session with Andrew Rodland <arodland@cpan.org> aka hobbs. priodev, tm604, Khisanth and other provided valuable insight particularely with the html output.hexd from libma <http://www.ioplex.com/~miallen/libmba/> is nice tools that inspired me to write this module. This module offers many more options but hexd may be a better alternative If you need very fast dump generation. Data::HexDump::Range splits binary data according to user defined ranges and renderes them as a hex or/and decimal data dump. The data dump can be rendered in ANSI, ASCII or HTML. Rendered ColumnsYou can choose which columns are rendered by setting options when creating a Data::HexDump::Range object. The default rendering includes the followingRANGE_NAME OFFSET CUMULATIVE_OFFSET HEX_DUMP ASCII_DUMP which corresponds to the object below: Data::HexDump::Range->new ( FORMAT => 'ANSI', COLOR => 'cycle', ORIENTATION => 'horizontal', DISPLAY_RANGE_NAME => 1 , DISPLAY_OFFSET => 1 , OFFSET_FORMAT => 'hex', DISPLAY_HEX_DUMP => 1, DISPLAY_ASCII_DUMP => 1, DATA_WIDTH => 16, ) ; If you decided that you wanted the binary data to be showed in decimal instead for hexadecimal, you' set DISPLAY_HEX_DUMP => 0 and DISPLAY_DEC_DUMP => 1. See new for all the possible options. Most option are also available from the command line utility hdr. OrientationThe examples below show the output of the following command:$>hdr -r 'magic cookie,12:padding, 32:header,5:data, 20:extra data,#:header,5:data,40:footer,4' -col -o ver -display_ruler lib/Data/HexDump/Range.pm Vertical orientation In this orientation mode, each range displayed on a separate line. RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345 magic cookie 00000000 00000000 0a 70 61 63 6b 61 67 65 20 44 61 74 .package Dat padding 0000000c 00000000 61 3a 3a 48 a::H padding 00000010 00000004 65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a exDump::Range ;. padding 00000020 00000014 0a 75 73 65 20 73 74 72 69 63 74 3b .use strict; header 0000002c 00000000 0a 75 73 65 .use header 00000030 00000004 20 data 00000031 00000000 77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 warnings ;.use data 00000040 0000000f 43 61 72 70 20 Carp "extra data" header 00000045 00000000 3b 0a 0a 42 45 ;..BE data 0000004a 00000000 47 49 4e 20 0a 7b GIN .{ data 00000050 00000006 0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 ..use Sub::Expor data 00000060 00000016 74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 ter -setup => .. data 00000070 00000026 7b 0a {. footer 00000072 00000000 09 65 78 70 .exp In colors: Horizontal orientation In this mode, the data are packed together in the dump OFFSET HEX_DUMP ASCII_DUMP RANGE_NAME 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345 00000000 0a 70 61 63 6b 61 67 65 20 44 61 74 61 3a 3a 48 .package Data::H magic cookie, padding, 00000020 65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a exDump::Range ;. padding, 00000030 0a 75 73 65 20 73 74 72 69 63 74 3b 0a 75 73 65 .use strict;.use padding, header, 00000050 20 77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 warnings ;.use header, data, 00000070 43 61 72 70 20 3b 0a 0a 42 45 47 49 4e 20 0a 7b Carp ;..BEGIN .{ data, "extra data", header, data, 000000a0 0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 ..use Sub::Expor data, 000000b0 74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 ter -setup => .. data, 000000c0 7b 0a 09 65 78 70 {..exp data, footer, In colors: Range definitionmy $simple_range = ['magic cookie', 12, 'red'] ; Ranges are Array references containing two to four elements:
Any of the elements can be replaced by a subroutine reference. See "Dynamic range definition" below. You can also pass the ranges as a string. The hdr command line range dumper that was installed by this module uses the string format. Example: $>hdr --col -display_ruler -o ver -r 'header,12:name,10:magic,2:offset,4:BITMAP,4,bright_yellow:ff,x2b2:fx,b32:f0,b16:field,x8b8:field2, b17:footer,20' my_binary Size field format The size field is used to defined if the range is a normal range, a comment, a bitfield or a skip range. The formats are a s follows: format range example normal range => integer header, 4, bright_blue comment => # data section start, # extra header => @ header, @, red bitfield => [XInteger][xInteger]bInteger bitfield, X2x4b4 # X is byte offset, x is bit offset skip range => xInteger boring, X256,, comment Note that the integer part can be a hexadecimal value starting with 0x Coloring Ranges and ranges names are displayed according to the color field in the range definition. The color definition is one of:
Linear ranges For simple data formats, your can put all the your range descriptions in a array: my $image_ranges = [ ['magic cookie', 12, 'red'], ['size', 10, 'yellow'], ['data', 10, 'blue on_yellow'], ['timestamp', 5, 'green'], ] ; Structured Ranges my $data_range = # definition to re-use [ ['data header', 5, 'blue on_yellow'], ['data', 100, 'blue'], ] ; my $structured_range = [ [ ['magic cookie', 12, 'red'], ['padding', 88, 'yellow'], $data_range, ], [ ['extra data', 12, undef], [ $data_range, ['footer', 4, 'yellow on_red'], ] ], ] Comment ranges If the size of a range is the string '#', the whole range is considered a comment my $range_defintion_with_comments = [ ['comment text', '#', 'optional color for meta range'], ['magic cookie', 12, 'red'], ['padding', 88, 'yellow'], [ ['another comment', '#'], ['data header', 5, 'blue on_yellow'], ['data', 100, 'blue'], ], ] ; Extra header If the size of a range is the string '@', and extra header is inserted in the output. This is useful when you have very long output and want an extra header. Bitfields Bitfields can be up to 32 bits long and can overlap each other. Bitfields are applied on the previously defined range. In the example below, bitfields ff, fx, f0 are extracted form the data defined by the BITMAP range. .------------. .--------------. .---. | data range | | data hexdump | | b | '------------' '--------------' | i | | | | t | BITMAP <----' 00000000 00000000 0a 70 61 63 <--' .pac | f | ^ .ff 02 .. 03 -- -- -- 00 ----------------------------00-- .bitfield: ---. | i |---> .fx 00 .. 31 0a 70 61 63 00001010011100000110000101100011 .bitfield: .pac | e | v .f0 00 .. 15 -- -- 61 63 ----------------0110000101100011 .bitfield: --ac | l | ^ ^ ^ ^ | d | | | | | | s | .----------------------.-------------------.----------------------. .---------------------. '---' | start bit .. end bit | bitfields hexdump | bitfield binary dump | | bitfield ascci dump | '----------------------'-------------------'----------------------' '---------------------' The the format definiton is: an optional "x (for offset) + offset" + "b (for bits) + number of bits". Eg: x8b8 second byte in MYDATA. An example output containing normal data and bifields dumps using the comand below. $>hdr -r 'header,12:BITMAP,4,bright_yellow:ff,x2b2:fx,b32:f0,b16:footer,16' -o ver file_name By default bitfields are not displayed in horizontal mode. Skip ranges If the size format is 'X' + number, that number of bytes is skipped from the data. Data::HexDump::Range will display the skip range in the dump but not the data. In the command below, the range 'skip' removes 32 bytes from the display. '>>' is prepended to the range name. Command: hdr -r 'magic cookie, 5 :other,37 :bf,b8 :skip,X32,, I skipped :more, 20' -rul -col -o ver RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345 magic cookie 00000000 00000000 44 61 74 61 3a Data: other 00000005 00000000 3a 48 65 78 44 75 6d 70 3a 3a 52 :HexDump::R other 00000010 0000000b 61 6e 67 65 0a 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d ange.=========== other 00000020 0000001b 3d 3d 3d 3d 3d 3d 3d 3d 3d 0a =========. .bf 00 .. 07 -- -- -- 0a ------------------------00001010 .bitfield: ---. >>skip 0000002a 00000049 00 00 00 20 bytes skipped more 0000004a 00000000 20 63 6f 6c 6f 72 color more 00000050 00000006 2c 20 62 69 74 66 69 65 6c 64 73 20 61 6e , bitfields an in color: Dynamic range definition The whole range can be replaced by a subroutine reference or elements of the range can be replaced by a subroutine definition. my $dynamic_range = [ [\&name, \&size, \&color, \&comment ], [\&define_range] # returns a range definition ] ; sub cloth_size { my ($self, $data, $used_data, $size, $range) = @_ ; my %types = (O => 'S', 1 => 'M', 2 => 'L',) ; return 'size:' . ($types{$data} // '?') ; } $hdr->dump([\&cloth_size, 1, 'yellow'], $data) ; sub cloth_size { my ($self, $data, $used_data, $size, $range) = @_ ; return unpack "a", $data ; } $hdr->dump(['data', \&get_size, 'yellow'], $data) ; my $flip_flop = 1 ; my @colors = ('green', 'red') ; sub alternate_color {$flip_flop ^= 1 ; return $colors[$flip_flop] } $hdr->dump(['data', 100, \&alternate_color], $data) ; sub define_range(['whole range', 5, 'on_yellow']} $hdr->dump([\&define_range], $data) ; define_range($data, $offset)Returns a range description for the next range to dumpArguments - See gather
Returns -
Note this is, very, different from "User defined range generator" below. User defined range generator A subroutine reference can be passed as a range definition. The subroutine will be called repetitively till the data is exhausted or the subroutine returns undef. sub my_parser { my ($data, $offset) = @_ ; my $first_byte = unpack ("x$offset C", $data) ; $offset < length($data) ? $first_byte == ord(0) ? ['from odd', 5, 'blue on_yellow'] : ['from even', 3, 'green'] : undef ; } my $hdr = Data::HexDump::Range->new() ; print $hdr->dump(\&my_parser, '01' x 50) ; my_parser($data, $offset)Returns a range description for the next range to dumpArguments - See gather
Returns -
EXAMPLESSee hdr_examples.pod in the distribution.SUBROUTINES/METHODSnew(NAMED_ARGUMENTS)Create a Data::HexDump::Range object.my $hdr = Data::HexDump::Range->new() ; # use default setup my $hdr = Data::HexDump::Range->new ( FORMAT => 'ANSI'|'ASCII'|'HTML', COLOR => 'bw' | 'cycle', OFFSET_FORMAT => 'hex' | 'dec', DATA_WIDTH => 16 | 20 | ... , DISPLAY_RANGE_NAME => 1 , MAXIMUM_RANGE_NAME_SIZE => 16, DISPLAY_COLUMN_NAMES => 0, DISPLAY_RULER => 0, DISPLAY_OFFSET => 1 , DISPLAY_CUMULATIVE_OFFSET => 1 , DISPLAY_ZERO_SIZE_RANGE_WARNING => 1, DISPLAY_ZERO_SIZE_RANGE => 1, DISPLAY_RANGE_SIZE => 1, DISPLAY_ASCII_DUMP => 1 , DISPLAY_HEX_DUMP => 1, DISPLAY_DEC_DUMP => 1, COLOR_NAMES => {}, ORIENTATION => 'horizontal', ) ; Arguments - All arguments are optional. Default values are listed below.
Returns - Nothing Exceptions - Dies if an unsupported option is passed. gather($range_description, $data, $offset, $size)Dump the data, up to $size, according to the description. The data dump is kept in the object so you can merge multiple gathered dumps and get a single rendering.$hdr->gather($range_description, $data, $offset, $size) $hdr->gather($range_description, $more_data) print $hdr->dump_gathered() ; Arguments
Returns - An integer - the number of processed bytes Exceptions - See _gather dump_gathered()Returns the dump string for the gathered data.$hdr->gather($range_description, $data, $size) $hdr->gather($range_description, $data, $size) print $hdr->dump_gathered() ; Arguments - None Returns - A string - the binary data formated according to the rnage descriptions Exceptions - None dump($range_description, $data, $offset, $size)Dump the data, up to $size, according to the descriptionArguments - See gather Returns - A string - the formated dump Exceptions - dies if the range description is invalid get_dump_and_consumed_data_size($range_description, $data, $offset, $size)Dump the data, from $offset up to $size, according to the $range_descriptionArguments - See gather Returns -
Exceptions - dies if the range description is invalid reset()Clear the gathered dumpArguments - None Returns - Nothing Exceptions - None BUGS AND LIMITATIONSNone so far.AUTHORNadim ibn hamouda el Khemir CPAN ID: NKH mailto: nadim@cpan.org COPYRIGHT AND LICENSECopyright Nadim Khemir 2010.This program is free software; you can redistribute it and/or modify it under the terms of either:
SUPPORTYou can find documentation for this module with the perldoc command.perldoc Data::HexDump::Range You can also look for information at:
SEE ALSOData::Hexdumper, Data::ParseBinary, Convert::Binary::C, Parse::Binary
|