Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

docs restructured a bit

  • Loading branch information...
commit a645d081f10b7d80bfd282039e6c1af404dfba75 1 parent b3d34ae
Kent Fredric authored
Showing with 294 additions and 218 deletions.
  1. +182 −119 lib/ELF/Extract/Sections.pm
  2. +112 −99 lib/ELF/Extract/Sections/Section.pm
301 lib/ELF/Extract/Sections.pm
View
@@ -8,6 +8,48 @@ use MooseX::Declare;
class ELF::Extract::Sections with MooseX::Log::Log4perl {
+=head1 CAVEATS
+
+=over 4
+
+=item 1. Beta Software
+
+This code is relatively new. It exists only as a best attempt at present until further notice. It
+has proven practical for at least one application, and this is why the module exists. However, it can't be
+guaranteed it will work for whatever you want it to in all cases. Please report any bugs you find.
+
+=item 2. Feature Incomplete
+
+This only presently has a very barebones functionality, which should however prove practical for most purposes.
+If you have any suggestions, please tell me via "report bugs". If you never seek, you'll never find.
+
+=item 3. Humans
+
+This code is written by a human, and like all human code, it sucks. There will be bugs. Please report them.
+
+=back
+
+=head1 SYNOPSIS
+
+ use ELF::Extract::Sections;
+
+ # Create an extractor object for foo.so
+ my $extractor = ELF::Extract::Sections->new( file => '/path/to/foo.so' );
+
+ # Scan file for section data, returns a hash
+ my %sections = ${ $extractor->sections };
+
+ # Retreive the section object for the comment section
+ my $data = $sections{.comment};
+
+ # Print the stringified explanation of the section
+ print "$data";
+
+ # Get the raw bytes out of the section.
+ print $data->contents # returns bytes
+
+=cut
+
use MooseX::Has::Sugar 0.0300;
use MooseX::Types::Moose ( ':all', );
use MooseX::Types::Path::Class ( 'File', );
@@ -15,16 +57,86 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
require ELF::Extract::Sections::Section;
- has '_scanner_package' => ( isa => ClassName, ro, lazy_build, );
- has '_scanner_instance' => ( isa => Object, ro, lazy_build, );
+=head1 PUBLIC ATTRIBUTES
+=cut
+
+=head2 -> file
+
+Returns the file the section data is being created for.
+
+=cut
- has 'scanner' => ( isa => Str, ro, default => 'Objdump', );
- has 'sections' => ( isa => HashRef [ElfSection], ro, lazy_build, );
has 'file' => ( isa => File, ro, required, coerce, );
- #
- # Public Interfaces
- #
+=head2 -> sections
+
+Returns a HashRef of the available sections.
+
+=cut
+
+ has 'sections' => ( isa => HashRef [ElfSection], ro, lazy_build, );
+
+=head2 -> scanner
+
+Returns the name of the default scanner plugin
+
+=cut
+
+ has 'scanner' => ( isa => Str, ro, default => 'Objdump', );
+
+=head1 PUBLIC METHODS
+
+=cut
+
+=head2 -> new ( file => FILENAME )
+
+=head2 -> new ( file => FILENAME , scanner => 'Objdump' )
+
+Creates A new Section Extractor object
+
+=cut
+
+ method BUILD( $args ) {
+ if ( not $self->file->stat ) {
+ $self->log->logconfess(q{File Specifed could not be found.});
+ }
+ };
+
+=head2 -> sorted_sections ( field => SORT_BY )
+
+=head2 -> sorted_sections ( field => SORT_BY, descending => DESCENDING )
+
+Returns an ArrayRef sorted by the SORT_BY field. May be Ascending or Descending depending on requirements.
+
+=over 4
+
+=item DESCENDING
+
+Optional parameters. True for descending, False or absensent for ascending.
+
+=item SORT_BY
+
+A String of the field to sort by. Valid options at present are
+
+=over 6
+
+=item name
+
+The Section Name
+
+=item offset
+
+The Sections offset relative to the start of the file.
+
+=item size
+
+The Size of the section.
+
+=back
+
+=back
+
+=cut
method sorted_sections( FilterField :$field!, Bool :$descending? ) {
my $m = 1;
@@ -32,21 +144,15 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
return [ sort { $m * ( $a->compare( other => $b, field => $field ) ) } values %{ $self->sections } ];
};
- #
- # Moose Builders
- #
+=head1 PUBLIC ATTRIBUTE BUILDERS
- method _build__scanner_package {
- my $pkg = 'ELF::Extract::Sections::Scanner::' . $self->scanner;
- eval "use $pkg; 1"
- or $self->log->logconfess( "The Scanner " . $self->scanner . " could not be found as $pkg. >$! >$@ " );
- return $pkg;
- };
+These aren't really user servicable, but they make your front end work.
- method _build__scanner_instance {
- my $instance = $self->_scanner_package->new();
- return $instance;
- };
+=cut
+
+=head2 -> _build_sections
+
+=cut
method _build_sections {
$self->log->debug('Building Section List');
@@ -58,15 +164,48 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
}
};
- method BUILD( $args ) {
- if ( not $self->file->stat ) {
- $self->log->logconfess(q{File Specifed could not be found.});
- }
+
+=head1 PRIVATE ATTRIBUTES
+=cut
+
+=head2 -> _scanner_package
+=cut
+
+ has '_scanner_package' => ( isa => ClassName, ro, lazy_build, );
+
+=head2 -> _scanner_instance
+=cut
+
+ has '_scanner_instance' => ( isa => Object, ro, lazy_build, );
+
+=head1 PRIVATE ATTRIBUTE BUILDERS
+=cut
+
+=head2 -> _build__scanner_package
+=cut
+
+ method _build__scanner_package {
+ my $pkg = 'ELF::Extract::Sections::Scanner::' . $self->scanner;
+ eval "use $pkg; 1"
+ or $self->log->logconfess( "The Scanner " . $self->scanner . " could not be found as $pkg. >$! >$@ " );
+ return $pkg;
+ };
+
+=head2 -> _build__scanner_instance
+=cut
+
+ method _build__scanner_instance {
+ my $instance = $self->_scanner_package->new();
+ return $instance;
};
- #
- # Internals
- #
+
+=head1 PRIVATE_METHODS
+=cut
+
+=head2 -> _stash_record( HashRef, Str, Str )
+=cut
+
method _stash_record ( HashRef $stash! , Str $header!, Str $offset! ){
if ( exists $stash->{$offset} ) {
$self->log->logcluck(
@@ -83,6 +222,9 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
$stash->{$offset} = $header;
};
+=head2 -> _build_section_section( Str, Int, Int, File )
+=cut
+
method _build_section_section( Str $stashName, Int $start, Int $stop , File $file ){
$self->log->info(" Section ${stashName} , ${start} -> ${stop} ");
return ELF::Extract::Sections::Section->new(
@@ -93,6 +235,9 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
);
};
+=head2 -> _build_section_table( HashRef )
+=cut
+
method _build_section_table ( HashRef $ob! ){
my %dataStash = ();
my @k = sort { $a <=> $b } keys %{$ob};
@@ -104,6 +249,9 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
return \%dataStash;
};
+=head2 -> _scan_guess_size
+=cut
+
method _scan_guess_size {
$self->_scanner_instance->open_file( file => $self->file );
my %offsets = ();
@@ -115,6 +263,9 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
return $self->_build_section_table( \%offsets );
};
+=head2 -> _scan_with_size
+=cut
+
method _scan_with_size {
my %dataStash = ();
$self->_scanner_instance->open_file( file => $self->file );
@@ -135,95 +286,8 @@ class ELF::Extract::Sections with MooseX::Log::Log4perl {
__END__
-=head1 Caveats
-
-=over 4
-
-=item 1. Beta Software
-
-This code is relatively new. It exists only as a best attempt at present until further notice. It
-has proven practical for at least one application, and this is why the module exists. However, it can't be
-guaranteed it will work for whatever you want it to in all cases. Please report any bugs you find.
-
-=item 2. Feature Incomplete
-
-This only presently has a very barebones functionality, which should however prove practical for most purposes.
-If you have any suggestions, please tell me via "report bugs". If you never seek, you'll never find.
-=item 3. Humans
-
-This code is written by a human, and like all human code, it sucks. There will be bugs. Please report them.
-
-=back
-
-=head1 Synopsis
-
- use ELF::Extract::Sections;
-
- # Create an extractor object for foo.so
- my $extractor = ELF::Extract::Sections->new( file => '/path/to/foo.so' );
-
- # Scan file for section data, returns a hash
- my %sections = ${ $extractor->sections };
-
- # Retreive the section object for the comment section
- my $data = $sections{.comment};
-
- # Print the stringified explanation of the section
- print "$data";
-
- # Get the raw bytes out of the section.
- print $data->contents # returns bytes
-
-=head1 Methods
-
-=head2 -> new ( file => FILENAME )
-
-Creates A new Section Extractor object
-
-=head2 -> file
-
-Returns the file the section data is being created for.
-
-=head2 -> sections
-
-Returns a HashRef of the available sections.
-
-=head2 -> sorted_sections ( field => SORT_BY )
-
-=head2 -> sorted_sections ( field => SORT_BY, descending => DESCENDING )
-
-Returns an ArrayRef sorted by the SORT_BY field. May be Ascending or Descending depending on requirements.
-
-=over 4
-
-=item DESCENDING
-
-Optional parameters. True for descending, False or absensent for ascending.
-
-=item SORT_BY
-
-A String of the field to sort by. Valid options at present are
-
-=over 6
-
-=item name
-
-The Section Name
-
-=item offset
-
-The Sections offset relative to the start of the file.
-
-=item size
-
-The Size of the section.
-
-=back
-
-=back
-
-=head1 Debugging
+=head1 DEBUGGING
This library uses L<Log::Log4perl>. To see more verbose processing notices, do this:
@@ -241,7 +305,7 @@ To suppress this, just do
I request however you B<don't> do that for modules intended to be consumed by others without good cause.
-=head1 Bugs
+=head1 BUGS
Please report any bugs or feature requests to C<bug-elf-extract-sections at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ELF-Extract-Sections>. I will be notified, and then you'll
@@ -250,7 +314,7 @@ automatically be notified of progress on your bug as I make changes.
-=head1 Support
+=head1 SUPPORT
You can find documentation for this module with the perldoc command.
@@ -279,8 +343,7 @@ L<http://search.cpan.org/dist/ELF-Extract-Sections/>
=back
-
-=head1 Acknowledgements
+=head1 ACKNOWLEDGEMENTS
=cut
211 lib/ELF/Extract/Sections/Section.pm
View
@@ -7,143 +7,98 @@ use warnings;
use MooseX::Declare;
class ELF::Extract::Sections::Section {
- use MooseX::Has::Sugar 0.0300;
- use MooseX::Types::Moose ( ':all', );
- use ELF::Extract::Sections::Meta::Types ( ':all', );
- use MooseX::Types::Path::Class ( 'File', );
-
- use overload '""' => \&to_string;
-
- has source => ( isa => File, ro, required, coerce, );
- has name => ( isa => Str, ro, required );
- has offset => ( isa => Int, ro, required );
- has size => ( isa => Int, ro, required );
-
- method to_string ( Any $other?, Bool $polarity? ) {
- return sprintf(
- qq{[ Section %s of size %s in %s @ %x to %x ]},
- $self->name, $self->size, $self->source, $self->offset, $self->offset + $self->size,
- );
- };
- method compare ( ELF::Extract::Sections::Section :$other! , FilterField :$field! ){
- if ( $field eq 'name' ) {
- return ( $self->name cmp $other->name );
- }
- if ( $field eq 'offset' ) {
- return ( $self->offset <=> $other->offset );
- }
- if ( $field eq 'size' ) {
- return ( $self->size <=> $other->size );
- }
- return undef;
- };
+=head1 DESCRIPTION
- method write_to( File :$file does coerce ){
- my $fh = $self->source->openr;
- seek( $fh, $self->offset, 0 );
- my $output = $file->openw;
- my $chunksize = 1024;
- my $bytes_left = $self->size;
- my $chunk = ( $bytes_left < $chunksize ) ? $bytes_left : $chunksize;
- while ( read( $fh, my $buffer, $chunk ) ) {
- print {$output} $buffer;
- $bytes_left -= $chunksize;
- $chunk = ( $bytes_left < $chunksize ) ? $bytes_left : $chunksize;
- }
- return 1;
- };
-
- method contents {
- my $fh = $self->source->openr;
- seek( $fh, $self->offset, 0 );
- my $b;
- read( $fh, $b, $self->size );
- return $b;
- };
-};
+Generally Intended for use by L<ELF::Extract::Sections> as a meta-structure for tracking data,
+but generated objects are returned to you for you to deal with
-1;
+=cut
-__END__
+=head1 SYNOPSIS
-=head1 Description
+ use ELF::Extract::Sections::Section;
-Generally Intended for use by L<ELF::Extract::Sections> as a meta-structure for tracking data,
-but generated objects are returned to you for you to deal with
+ my $s = ELF::Extract::Sections::Section->new(
+ source => '/foo/bar.pl',
+ name => '.comment',
+ offset => 45670,
+ size => 1244,
+ );
-=head1 Synopsis
+ # prints a human friendly description
+ print $s->to_string;
- use ELF::Extract::Sections::Section;
+ # does likewise.
+ print "$s";
- my $s = ELF::Extract::Sections::Section->new(
- source => '/foo/bar.pl',
- name => '.comment',
- offset => 45670,
- size => 1244,
- );
+ # Compare with another section ( preferably in the same file, meaningless otherwise )
+ if( $s->compare( $y , 'name' ) ){
- # prints a human friendly description
- print $s->to_string;
+ }
- # does likewise.
- print "$s";
+ # Unimplemented
+ $s->write_to ( file => '/tmp/out.txt' );
- # Compare with another section ( preferably in the same file, meaningless otherwise
- if( $s->compare( $y , 'name' ) ){
+ # Retuns the sections contents as a string
+ print $s->contents;
- }
+=cut
- # Unimplemented
- $s->write_to ( file => '/tmp/out.txt' );
+ use MooseX::Has::Sugar 0.0300;
+ use MooseX::Types::Moose ( ':all', );
+ use ELF::Extract::Sections::Meta::Types ( ':all', );
+ use MooseX::Types::Path::Class ( 'File', );
- # Retuns the sections contents as a string
- print $s->contents;
+ use overload '""' => \&to_string;
-=head1 Methods
+=head1 PUBLIC ATTRIBUTES
-=head2 -> new ( %PARAMS )
+=cut
-4 Parameters, all required.
+=head2 source
-=over 4
+C<Str>|C<Path::Class::File>: Either a String or a Path::Class instance pointing to the file in mention.
-=item source
+=cut
-C<Str>|C<Path::Class::File>: Either a String or a Path::Class instance pointing to the file in mention.
+ has source => ( isa => File, ro, required, coerce, );
-=item name
+=head2 name
C<Str>: The ELF Section Name
-=item size
+=cut
-C<Int>: The ELF Section Size
+ has name => ( isa => Str, ro, required );
-=item offset
+=head2 offset
C<Int>: Position in bytes relative to the start of the file.
-=back
+=cut
-Returns an C<ELF::Extract::Sections::Section> object.
+ has offset => ( isa => Int, ro, required );
+=head2 size
-=head2 -> source
+C<Int>: The ELF Section Size
-returns C<Path::Class::File>
+=cut
-=head2 -> name
+ has size => ( isa => Int, ro, required );
-returns C<Str>
+=head1 PUBLIC METHODS
-=head2 -> offset
+=cut
-returns C<Int>
+=head2 -> new ( %ATTRIBUTES )
-=head2 -> size
+4 Parameters, all required.
+
+Returns an C<ELF::Extract::Sections::Section> object.
-returns C<Int>
+=cut
=head2 -> to_string
@@ -151,7 +106,16 @@ returns C<Str> description of the object
[ Section {name} of size {size} in {file} @ {start} to {stop} ]
-=head2 -> compare ( %PARAMS )
+=cut
+
+ method to_string ( Any $other?, Bool $polarity? ) {
+ return sprintf(
+ qq{[ Section %s of size %s in %s @ %x to %x ]},
+ $self->name, $self->size, $self->source, $self->offset, $self->offset + $self->size,
+ );
+ };
+
+=head2 -> compare ( other => $other, field => $field )
2 Parameters, both required
@@ -169,7 +133,22 @@ C<Str['name','offset','size']>: Field to compare with.
returns C<Int> of comparison result, between -1 and 1
-=head2 -> write_to ( %PARAMS )
+=cut
+
+ method compare ( ELF::Extract::Sections::Section :$other! , FilterField :$field! ){
+ if ( $field eq 'name' ) {
+ return ( $self->name cmp $other->name );
+ }
+ if ( $field eq 'offset' ) {
+ return ( $self->offset <=> $other->offset );
+ }
+ if ( $field eq 'size' ) {
+ return ( $self->size <=> $other->size );
+ }
+ return undef;
+ };
+
+=head2 -> write_to ( file => $file )
B<UNIMPLEMENTED AS OF YET>
@@ -181,6 +160,40 @@ C<Str>|C<Path::Class::File>: File target to write section contents to.
=back
+=cut
+
+ method write_to( File :$file does coerce ){
+ my $fh = $self->source->openr;
+ seek( $fh, $self->offset, 0 );
+ my $output = $file->openw;
+ my $chunksize = 1024;
+ my $bytes_left = $self->size;
+ my $chunk = ( $bytes_left < $chunksize ) ? $bytes_left : $chunksize;
+ while ( read( $fh, my $buffer, $chunk ) ) {
+ print {$output} $buffer;
+ $bytes_left -= $chunksize;
+ $chunk = ( $bytes_left < $chunksize ) ? $bytes_left : $chunksize;
+ }
+ return 1;
+ };
+
=head2 -> contents
returns C<Str> of binary data read out of file.
+
+=cut
+
+ method contents {
+ my $fh = $self->source->openr;
+ seek( $fh, $self->offset, 0 );
+ my $b;
+ read( $fh, $b, $self->size );
+ return $b;
+ };
+};
+
+1;
+
+__END__
+
+
Please sign in to comment.
Something went wrong with that request. Please try again.