NAME

Pod::Tidy - reformat Pod documents without effecting other text or code

SYNOPSIS

    use Pod::Tidy qw( tidy_files tidy_filehandle );

    my $processed = Pod::Tidy::tidy_files(
        files       => \@list,
        recursive   => $recursive,
        verbose     => $verbose,
        inplace     => $inplace,
        nobackup    => $nobackup,
    );

    Pod::Tidy::tidy_filehandle($input);

DESCRIPTION

This module provides the heavy lifting need by the podtidy utility although the API should be general enough that it can be used directly.

USAGE

Import Parameters

This module accepts no arguments to it's import method and exports no symbols.

Exportable Subroutines

• tidy_files( ... )

  Accepts a mandatory hash.

      my $processed = Pod::Tidy::tidy_files(
          files       => \@list,
          recursive   => $recursive,
          verbose     => $verbose,
          inplace     => $inplace,
          nobackup    => $nobackup,
      );

  • files

    An array ref to a list of files and/or directories.

  • recursive

    Accepts undef, 0, or 1. If set to 1 any directories provided to the files key will be recursively expanded. Defaults to undef

    This key is optional.

  • verbose

    Accepts undef, 0, or 1. 1 enables verbose warnings. Defaults to undef.

    This key is optional.

  • inplace

    Accepts undef, 0, or 1. 1 enables in place reformatting of files. Updated files will be backed up unless the nobackup key is set. The mtime of the file is guarenteed not to be changed unless formating changes did occur. Defaults to undef.

    This key is optional.

  • nobackup

    Accepts undef, 0, or 1. If set to 1 files being reformatted in place will not be backed up. Defaults to undef.

    This key is optional.

  Before processing a file it is checked for:

  • correct access permissions

  • containing Pod

  • legal Pod syntax

  Any file failing to meet those criteria will not be processed.

  Returns a count of processed files or undef if no files could be processed.

• tidy_filehandle($input)

  Accepts an open filehandle. Data from the filehandle is processed as it is read so this subroutine can be used to filter large amounts of data. Because of this behavior the input can not be checked in advance to verify a) That it's actually Pod and b) that the Pod document uses only valid Pod syntax. Output is set to STDOUT. Returns nothing.

Internal Subroutines

These subroutines are not exportable.

• backup_file

• build_pod_queue

• process_pod_queue

• valid_pod_syntax

DEVELOPER NOTES

The tidy_files() subroutine does a number of highly inefficient things. Each file is opened and closed at least 3 different times as it is passed through a number of different modules to see if it meets the processing criteria. This shouldn't be a major performance issue with an modern OS's VM subsystem but it still leaves much to be desired. When doing inplace file reformatting a complete copy of the original file and the updated file and held in memory for comparison. Thus you are limited to reformatting Pod documents < ( available_system_memory / 2 ).

BUGS

Due to a bug in the version of Pod::Find::contains_pod bundled with Pod::Parser 1.33, Pod containing files will not be detetect if the only =[foo]N directive is on the first line of the file. For example:

    =head1 foo
    
    foobarbaz

    =cut

Would not be detected unless there was a newline before =head1 foo. See CPAN bug #14871 for a patch to correct Pod::Find.

CREDITS

Just me, myself, and I.

SUPPORT

Please contact the author directly via e-mail.

AUTHOR

Joshua Hoblitt jhoblitt@cpan.org

COPYRIGHT

Copyright (c) 2005 Joshua Hoblitt. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the licenses can be found in the LICENSE file included with this module, or in perlartistic and perlgpl Pods as supplied with Perl 5.8.1 and later.

SEE ALSO

Pod::Wrap::Pretty, Pod::Wrap, Perl::Tidy

cpanm Pod::Tidy

perl -MCPAN -e shell
install Pod::Tidy