NAME
    Text::Outdent - Outdent chunks of text

SYNOPSIS
        my $foo = outdent($bar);

        my $baz = outdent_quote(q{
            this
                is
                a
            string
                that
                is
                indented
            with
                spaces
                or
                tab
        });

DESCRIPTION
    This module was created to make it easy to have large chunks of strings
    in the code. If you use a quote operator that spans over several lines
    or a "here-doc" and have an indention of the code you get leading
    whitespaces that you may or may not want. If you don't want them this
    module easily removes them.

    You can also use it for other texts that are indented.

EXPORTED FUNCTIONS
    No functions are exported by default. ":ALL" exports all.

    "outdent($str)"
        Removes the common leading whitespaces for each line. Currently
        lines with only whitespaces are ignored and left untouched; treated
        as blank lines if you like. No tab expansion is being performed; a
        tab is just a whitespace character.

        If the indention consists of both spaces and tabs then it's a good
        idea to expand the tabs first, see &expand_leading_tabs. If the mix
        of tabs and spaces is consistent, e.g. every line begins with
        "  \t ", then that is recognized as indention.

            # common leading whitespaces are removed.
            my $str = <<'_STR_';
                this
                    is
                    a
                string
                    that
                    is
                    indented
                with
                    spaces
                    or
                    tab
            _STR_

            print '* Indented: ', $str;
            print '* Outdented: ', outdent($str);

        outputs

            * Indented:
                this
                    is
                    a
                string
                    that
                    is
                    indented
                with
                    spaces
                    or
                    tab

            * Outdented:
            this
                is
                a
            string
                that
                is
                indented
            with
                spaces
                or
                tab

    "outdent_all($str)"
        Like &outdent except it doesn't treat "whitespace lines" as blank
        lines.

    "outdent_quote($str)"
        Like &outdent but with some twists to make it smooth to use a
        (possibly indented) quote operator spanning over several lines in
        your source. The arrows (that isn't part of the code) below point
        out the two issues this function takes care of.

            my $foo = q{       <--- newline and possible spaces
                foo
                    bar
                    baz
                zip
                    zap
            };                 <--- empty line with possible spaces

        First, all whitespaces uptil the first newline plus the newline
        itself are removed. This takes care of the first issue.

        Second, if the string ends with a newline followed by non-newline
        whitespaces the non-newline whitespaces are removed. This takes care
        of the second issue.

        These fixes serve to make the quote operator's semantics equivalent
        to a here-docs.

    "expand_leading_tabs($tabstop, $str)"
        Expands tabs that on a line only have whitespaces before them. Handy
        to have if you have a file with mixed tab/space indention.

AUTHOR
    Johan Lodin <lodin@cpan.org>

COPYRIGHT
    Copyright 2004-2005 Johan Lodin. All rights reserved.

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

SEE ALSO
