—

              
#!/usr/bin/env perl
use strict ;
use warnings ;
use Carp ;
HideShow 95 lines of Pod
=head1 NAME 
 $>hdr - hexadecimal [decimal] ascii, colorizing, range dump
=head1 USAGE
 $> hdr -r range_definitions file_to_dump
  
 $> hdr file_to_dump -r 'cookie,10,yellow :padding,8 :size,4:data,100' -o ver
The integer part can of a range definition and offset values can be hexadecimal value starting with I<0x>
=head1 RANGE DEFINITION 
                  format                          range example
                   
  normal range => integer                         header, 4, bright_blue
  comment      => #                               data section start, # 
  extra header => @                               header, @, red 
  bitfield     => [XInteger][xInteger]bInteger    bitfield, X2x4b4 (offset: X byte, x bit)
  skip range   => XInteger                        boring, X256,, your comment
=head1 OPTIONS
Options can be given before or after the name of the file to dump.
 range_description|r              file name containing a description
                                  or a string description formated as:
                                           'name,size,color:name,size:name,size:...'
 dump_original_range_description  dump the un-processed range descriptions
 dump_range_description           dump the processed range descriptions
 offset                           position in the data where to start dumping
 offset_start                     value added to the offset before display
  
 maximum_size                     amount of data to dump
  
 orientation|o                    'horizontal' or 'vertical'
 display_column_names|col         display columns names
 display_ruler|rul                display horizontal ruler
 format|f                         'ANSI' or 'ASCII' or 'HTML' 
 display_command_line             make the command line part of the output
  
 color                            'cycle', 'no_cycle', or 'bw'
 colors                           file containing custom colors
 start_color                      name of the first random color to use
 start_tag/end_tag                text that is output before and after the dump
                                       see L<hdr_examples.pod>
  
 data_width|w                     number of bytes per dump line
  
 offset_format                    'hex' or 'dec' 
 display_offset                   0 == no the offset display
 display_cumulative_offset        0 == no cumulative offset display
 display_zero_size_range          0 == no display of range with size 0
 display_zero_size_range_warning  0 == no warnings about ranges with size 0
 display_comment_range            0 == no comment range display 
  
 display_range_name               1 == display of the range name
 maximum_range_name_size          truncate range name if longer
 display_range_size               1 == prepend the range size to the name
  
 display_hex_dump                 1 == display hexadecimal dump column
 display_hexascii_dump            1 == display vombined HEX and ASCII dump column
 display_dec_dump                 1 == display decimal dump column
 display_ascii_dump               1 == display ASCII dump column
 display_user_information         1 == display user information columns
 maximum_user_information_size    truncate user information if longer
  
 display_bitfields                1 == display bitfields
 display_source                   1 == display source for bitfields 
 maximum_bitfield_source_size     truncate bitfield source name if longer
  
 bit_zero_on_left                 1 == bit index zero is on the left
  
 h|help                           display this scripts help page
 generate_completion_script|bash  generates a completion script on STDOUT
  
=head1 EXAMPLES
See L<hdr_examples.pod> in the distribution.
=head1 EXIT STATUS
Non zero if an error occured.
=head1 AUTHOR
  Nadim ibn hamouda el Khemir
  CPAN ID: NKH
  mailto: nkh@cpan.org
=cut
#------------------------------------------------------------------------------------------------------------------------
use Getopt::Long ;
use English qw( -no_match_vars ) ;
use File::Slurp ;
use IO::Select ;
use Data::HexDump::Range qw() ;
use Term::Bash::Completion::Generator ;
our $VERSION = '0.05' ;
use Readonly ;
Readonly my $SIZE_IF_RANGE_ERROR=> 256 ;
Readonly my $DEFAULT_SIZE => 16 ;
Readonly my $DEFAULT_USER_INFORMATION_SIZE => 20 ;
Readonly my $DEFAULT_BITFIELD_SOURCE_SIZE => 8 ;
#------------------------------------------------------------------------------------------------------------------------
my @options = 
        (
        'range_description|r=s' => \ my $range_description,
        'dump_range_description|d' =>\my $dump_range_description,
        'dump_original_range_description' =>\my $dump_original_range_description,
         
        'offset=o' =>  \my $offset,
        'offset_start=o' => \my $offset_start,
         
        'maximum_size=o' =>  \my $maximum_size,
        'orientation|o=s' => \my $orientation,
        'display_column_names|col' => \my $display_column_names,
        'display_ruler|rul' => \my $display_ruler,
        'format|f=s' => \my $format,
        'display_command_line' => \my $display_command_line,
         
        'color=s' => \my $color,
        'colors=s' => \my $color_file,
        'start_color=s' => \my $start_color,
        'start_tag=s' => \my $start_tag,
        'end_tag=s' => \my $end_tag,
         
        'data_width=o' =>  \my $data_width,
        'offset_format=s' => \my $offset_format,
        'display_offset=i' => \my $display_offset,
        'display_cumulative_offset=i' => \my $display_cumulative_offset,
         
        'display_zero_size_range=i' => \my $display_zero_size_range,
        'display_comment_range=i' => \my $display_comment_range,
        'display_zero_size_range_warning=i' => \my $display_zero_size_range_warning,
        'display_range_name=i' => \my $display_range_name,
        'maximum_range_name_size=i' => \my$maximum_range_name_size,
        'display_range_size=i' => \my $display_range_size,
        'display_hex_dump=i' => \my $display_hex_dump,
        'display_hexascii_dump=i' => \my $display_hexascii_dump,
        'display_dec_dump=i' => \my $display_dec_dump,
        'display_ascii_dump=i' => \my $display_ascii_dump,
        'display_user_information=i' => \my $display_user_information,
        'maximum_user_information_size=i' => \my $maximum_user_information_size,
        'display_bitfields=i' => \my $display_bitfields,
        'display_bitfield_source=i' => \my $display_bitfield_source,
        'maximum_bitfield_source_size=i' => \my $maximum_bitfield_source_size,
         
        'bit_zero_on_left' => \my $bit_zero_on_left,
        'h|help' => \&display_help, 
        'generate_completion_script|bash' => \my $generatebash_completion,
        ) ;
my @ARGV_COPY = @ARGV ; # getopt removes elements
display_help() unless GetOptions(@options) ;
generate_completion_script(@options) if $generatebash_completion ;
print "\n$start_tag\n\n" if defined $start_tag ;
if($display_command_line)
        {
        use Text::Colorizer ;
        my $c= Text::Colorizer->new(FORMAT => $format || 'ANSI', JOIN => q{ }) ;
         
        print $c->color_all('bright_white', 'hdr', grep{! /-output_command_line/xsm} @ARGV_COPY) ;
        }
my $data ;
my $io_select = IO::Select->new(\*STDIN) ;
if($io_select->can_read(0))
        {
        local $INPUT_RECORD_SEPARATOR = undef ;
        $data =  <STDIN> ; ## no critic (InputOutput::ProhibitExplicitStdin)
        }
else
        {
        my $file_to_dump = shift @ARGV ;
         
        if(defined $file_to_dump)
                {
                $data = read_file  $file_to_dump;
                }
        else
                {
                croak "Error: You didn't give me anything to generate an hexdump from. Try the --help option.\n";
                }
        }
$offset ||= 0 ;
my $range ;
if(defined $range_description )
        {
        if($range_description =~ /,/xsm)
                {
                $range = $range_description ;
                }
        else
                {
                # a file
                #~ $range  = do $range_description || ["hdr: range error $@", $SIZE_IF_RANGE_ERROR ] ;
                 
                unless ($range  = do $range_description ) 
                        {
                         if($@)
                                {
                                carp "ERROR: Couldn't parse $range_description:\n\t$@";
                                }
                        elsif(! defined $range)
                                {
                                carp "ERROR: Couldn't do $range_description:\n\t$!"
                                }
                         
                        $range = ["hdr: range error", $SIZE_IF_RANGE_ERROR ] ;
                        }               
                }
        }
else
        {
        $range = ['no range definition', length($data) ] ;
        $display_range_name = 0 ;
        $display_bitfield_source = 0 ;
        }
         
         
my @color_file ;
@color_file = (COLOR_NAMES => $color_file) if(defined $color_file) ;
my $hdr = Data::HexDump::Range->new
                        (
                        INTERACTION => {WARN => sub {warn @_}}, ## no critic (ErrorHandling::RequireCarping)
                         
                        ORIENTATION => $orientation || 'horizontal',
                        DISPLAY_COLUMN_NAMES => defined $display_column_names ? $display_column_names : 0,
                        DISPLAY_RULER => defined $display_ruler ? $display_ruler : 0,
                         
                        FORMAT => $format || 'ANSI',
                        COLOR => defined $color ? $color : 'cycle',
                        START_COLOR => $start_color,
                         
                        OFFSET_FORMAT => $offset_format || 'hex',
                        OFFSET_START => $offset_start || 0,
                         
                        DATA_WIDTH => $data_width || $DEFAULT_SIZE,
                         
                        DISPLAY_RANGE_NAME => defined $display_range_name ? $display_range_name : 1 ,
                        DUMP_RANGE_DESCRIPTION => defined $dump_range_description ? $dump_range_description : 0 ,
                        DUMP_ORIGINAL_RANGE_DESCRIPTION => defined $dump_original_range_description ? $dump_original_range_description : 0 ,
                        MAXIMUM_RANGE_NAME_SIZE => defined $maximum_range_name_size ? $maximum_range_name_size : $DEFAULT_SIZE,
                        DISPLAY_RANGE_SIZE => defined $display_range_size ? $display_range_size : 0,
                         
                        DISPLAY_OFFSET  => defined $display_offset ? $display_offset : 1 ,
                        DISPLAY_CUMULATIVE_OFFSET  => defined $display_cumulative_offset ? $display_cumulative_offset : 1 ,
                        DISPLAY_HEX_DUMP => defined $display_hex_dump ? $display_hex_dump : 1,
                        DISPLAY_HEXASCII_DUMP => defined $display_hexascii_dump ? $display_hexascii_dump : 0,
                        DISPLAY_DEC_DUMP => defined $display_dec_dump ? $display_dec_dump : 0,
                        DISPLAY_ASCII_DUMP => defined $display_ascii_dump ? $display_ascii_dump :  1 ,
                        DISPLAY_USER_INFORMATION => defined $display_user_information ? $display_user_information :  0 ,
                        MAXIMUM_USER_INFORMATION_SIZE => defined $maximum_user_information_size ? $maximum_user_information_size : $DEFAULT_USER_INFORMATION_SIZE,
                 
                        DISPLAY_ZERO_SIZE_RANGE => defined $display_zero_size_range ? $display_zero_size_range : 1,
                        DISPLAY_ZERO_SIZE_RANGE_WARNING => defined  $display_zero_size_range_warning ? $display_zero_size_range_warning : 1,
                        DISPLAY_COMMENT_RANGE => defined  $display_comment_range ? $display_comment_range : 1,
                         
                        DISPLAY_BITFIELDS => $display_bitfields,
                        DISPLAY_BITFIELD_SOURCE => defined $display_bitfield_source ? $display_bitfield_source : 1,
                        MAXIMUM_BITFIELD_SOURCE_SIZE => defined $maximum_bitfield_source_size ? $maximum_bitfield_source_size: $DEFAULT_BITFIELD_SOURCE_SIZE,
                         
                        BIT_ZERO_ON_LEFT =>  defined $bit_zero_on_left ? $bit_zero_on_left : 0,
                        @color_file
                        ) ;
print $hdr->dump( $range, $data, $offset, $maximum_size) ;
print "\n$end_tag\n\n" if defined $end_tag ;
#------------------------------------------------------------------------------------------------------------------------
sub display_help
{
#~ =head2 display_help()
#~ I<Arguments> - None
#~ I<Returns> - Nothing
#~ I<Exceptions> - exits with status code B<1>
#~ =cut
my ($this_script) = ($PROGRAM_NAME =~m/(.*)/sxm ) ;
print {*STDERR} `perldoc $this_script`  or croak 'Error: Can\'t display help!' ; ## no critic (InputOutput::ProhibitBacktickOperators)
exit(1) ;
}
#------------------------------------------------------------------------------------------------------------------------
sub generate_completion_script
{
#~ =head2 generate_completion_script(@definitions)
#~ I<Arguments> - @definitions - getop options description
#~ I<Returns> - Nothing
#~ I<Exceptions> - exits with status code B<1> after emitting the completion script on stdout
#~ =cut
my (@definitions) = @_ ;
my $flip = 0 ;
my @options = grep {++$flip % 2} @definitions ;
print Term::Bash::Completion::Generator::generate_bash_completion_function('hdr', [@options], undef, 1) ;
exit(0) ;
}