NAME

Whitespace - Cleanup various types of bogus whitespace in source files.

SYNOPSIS

use Whitespace;

# Instantiate a whitespace object with
# both input and output files specified
$ws = new Whitespace($infile, $outfile);

# Instantiate a whitespace object with
# only the input files specified (in-place cleanup)
$ws2 = new Whitespace($infile);

# Detect the whitespaces
$ret = $ws->detect();

detect returns undef if it is unable to operate on the given file.

The error that caused the undef can be retrieved using error

print $ws->error() . "\n" unless defined $ret;

detect returns the types of whitespaces detected as a hash which can be retrieved using the method status. The populated hash might look like this, if the file only had leading, trailing and end-of-line spaces (say on 3 lines).

%stat = %{$env->status()};
print map "$_ => $stat{$_}\n", sort keys %stat;

eol => 3
indent => 0
leading => 1
spacetab => 0
trailing => 1

Cleanup can be achieved for all the whitespaces or for just a given type of whitespace, using the following methods.

If a outfile is given, the cleaned contents are written to this file. If not, the contents are replaced in-place. undef is returned if there was an error writing the file.

# To cleanup the all the whitespaces
$ret = $env->cleanup();

# To cleanup leading whitespaces only
$leadstat = $env->leadclean();

# To cleanup trailing whitespaces only
$trailstat = $env->trailclean();

# To cleanup indentation whitespaces only
$indentstat = $env->indentclean();

# To cleanup space-followed-by-tabs only
$sftstat = $env->spacetabclean();

# To cleanup end-of-line whitespaces only
$eolstat = $env->eolclean();

DESCRIPTION

Leading space

Empty lines at the top of a file.

Trailing space

Empty lines at the end of a file.

Indentation space

8 or more spaces at the beginning of a line, that should be replaced with TABS.

Since this is the most controversial one, here is the rationale:
Most terminal drivers and printer drivers have TAB configured or
even hardcoded to be 8 spaces. (Some of them allow configuration,
but almost always they default to 8.)

Changing tab-width to other than 8 and editing will cause your
code to look different from within emacs, and say, if you cat it
or more it, or even print it.

Almost all the popular programming modes let you define an offset
(like c-basic-offset or perl-indent-level) to configure the
offset, so you should never have to set your tab-width to be other
than 8 in all these modes. In fact, with an indent level of say,
4, 2 TABS will cause emacs to replace your 8 spaces with one \t
(try it). If vi users in your office complain, tell them to use
vim, which distinguishes between tabstop and shiftwidth (vi
equivalent of our offsets), and also ask them to set smarttab.

Spaces followed by a TAB.

Almost always, we never want that.

EOL Whitespace

Spaces or TABS at the end of a line.

ACKNOWLEDGMENTS

This module is based on the original whitespace program written by Bradley W. White, distributed under the same license as the module itself.

AUTHORS

Rajesh Vaidheeswarran <rv@gnu.org>

Bradley W. White

LICENSE

Copyright (C) 2000-2001 Rajesh Vaidheeswarran

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.