David Farrell > PPI-Prettify-0.06 > PPI::Prettify

Download:
PPI-Prettify-0.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Source  

NAME ^

PPI::Prettify - A Perl HTML pretty printer to use with Google prettify CSS skins, no JavaScript required!

VERSION ^

version 0.06

SYNOPSIS ^

    use PPI::Prettify 'prettify';

    my $codeSample = q! # get todays date in Perl
                        use Time::Piece;
                        print Time::Piece->new;
                      !;

    my $html = prettify({ code => $codeSample });

    # every Perl token wrapped in a span e.g. for "use PPI::Prettify;":
        <span class="kwd">use</span>
        <span class="pln"> </span>
        <span class="atn">PPI::Prettify</span>
        <span class="pln">;</span>

    my $htmlDebug = prettify({ code => $codeSample, debug => 1 });
    # with PPI::Token class, e.g. for "use PPI::Prettify;":
        <span class="kwd" title="PPI::Token::Function">use</span>
        <span class="pln" title="PPI::Token::Whitespace"> </span>
        <span class="atn" title="PPI::Token::Word">PPI::Prettify</span>
        <span class="pln" title="PPI::Token::Structure">;</span>

DESCRIPTION ^

This module takes a string Perl code sample and returns the tokens of the code surrounded with <span> tags. The class attributes are the same used by the prettify.js. Using PPI::Prettify you can generate the prettified code for use in webpages without using JavaScript but you can use all the CSS skins developed for prettify.js. Also, because this module uses PPI::Document to tokenize the code, it's more accurate than prettify.js.

PPI::Prettify exports prettify() and the $MARKUP_RULES hashref which is used to match PPI::Token classes to the class attribute given to that token's <span> tag. You can modify $MARKUP_RULES to tweak the mapping if you require it.

I wrote an article with more detail about the module for: PerlTricks.com.

MOTIVATION ^

I wanted to generate marked-up Perl code without using JavaScript for PerlTricks.com. I was dissatisfied with prettify.js as it doesn't always tokenize Perl correctly and won't run if the user has disabled JavaScript. I considered PPI::HTML but it embeds the CSS in the generated code, and I wanted to use the same markup class attributes as prettify.js so I could reuse the existing CSS developed for it.

BUGS AND LIMITATIONS ^

SUBROUTINES/METHODS ^

prettify

Takes a hashref consisting of $code and an optional debug flag. Every Perl code token is given a <span> tag that corresponds to the tags used by Google's prettify.js library. If debug => 1, then every token's span tag will be given a title attribute with the value of the originating PPI::Token class. This can help if you want to override the mappings in $MARKUP_RULES. See "SYNOPSIS" for examples.

getExampleHTML

Returns an HTML document as a string with built-in CSS to demo the syntax highlighting capabilites of PPI::Prettify. At the command line:

    $ perl -MPPI::Prettify -e 'print PPI::Prettify::getExampleHTML()' > example.html

INTERNAL FUNCTIONS ^

_decorate

Iterates through the tokens of a PPI::Document, marking up each token with a <span> tag.

_to_html

Marks up a token with a span tag with the appropriate class attribute and the PPI::Token class.

_determine_token

Determines the PPI::Token type.

THANKS ^

Thanks to Adam Kennedy for developing PPI::Document, without which this module would not be possible.

SEE ALSO ^

PPI::HTML is another prettifier for Perl code samples that allows the embedding of CSS directly into the HTML generation.

AUTHOR ^

David Farrell <sillymoos@cpan.org> PerlTricks.com

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2014 by David Farrell.

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

syntax highlighting: