Permalink
Browse files

docs restructured a bit

  • Loading branch information...
1 parent b3d34ae commit a645d081f10b7d80bfd282039e6c1af404dfba75 @kentfredric kentfredric committed Aug 21, 2009
Showing with 294 additions and 218 deletions.
  1. +182 −119 lib/ELF/Extract/Sections.pm
  2. +112 −99 lib/ELF/Extract/Sections/Section.pm
View
@@ -8,45 +8,151 @@ 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', );
use ELF::Extract::Sections::Meta::Types ( ':all', );
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;
$m = -1 if ($descending);
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
Oops, something went wrong.

0 comments on commit a645d08

Please sign in to comment.