Previous Page
Next Page

4.11. Heredoc Terminators

Make every heredoc terminator a single uppercase identifier with a standard prefix.

You can use just about anything you like as a heredoc terminator. For example:

    print <<'end list';          # Prints 3 lines then [DONE]
    get name
    set size
    put next
    end list

    print "[DONE]\n";

or:

    print <<'';                  # Prints 4 lines (up to the empty line) then [DONE]
    get name
    set size
    put next
    end list

    print "[DONE]\n";

or even:

    print <<'print "[DONE]\n";'; # Prints 5 lines but no [DONE]!
    get name
    set size
    put next
    end list

    print "[DONE]\n";

Please don't. Heredocs are tough enough to understand as it is. Using bizarre terminators only makes them more difficult. It's a far better practice to stick with terminators that are capitalized (so they stand out better in mixed-case code) and free of whitespace (so only a single visual token has to be recognized).

For example, compared to the previous examples, it's much easier to tell what the contents of the following heredoc are:


    print <<'END_LIST';
    get name
    set size
    put next
    END_LIST

But even with a single identifier as terminator, both the contents and the termination marker of a heredoc still have to be left-justified. So it can still be difficult to detect the end of a heredoc. By naming every heredoc marker with a standard, easily recognized prefix, you can make them much easier to pick out.

'END_...' is the recommended choice for this prefix. That is, instead of:

    Readonly my $USAGE => <<"USAGE";
    Usage: $0 <file> [-full] [-o] [-beans]
    Options:
        -full  : produce a full dump
        -o     : dump in octal
        -beans : source is Java
    USAGE

delimit your heredocs like so:


    Readonly my $USAGE => <<"END_USAGE";
    Usage: $0 <file> [-full] [-o] [-beans]
    Options:
        -full  : produce a full dump
        -o     : dump in octal
        -beans : source is Java
    END_USAGE

It helps to think of the << heredoc introducer as being pronounced "Everything up to...", so that the previous code reads as: the read-only $USAGE variable is initialized with everything up to END_USAGE.

    Previous Page
    Next Page