=head1 NAME PPI::Prettify - A Perl HTML pretty printer to use with Google prettify CSS skins, no JavaScript required! =head1 VERSION version 0.07 =head1 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;": use PPI::Prettify ; my $htmlDebug = prettify({ code => $codeSample, debug => 1 }); # with PPI::Token class, e.g. for "use PPI::Prettify;": use PPI::Prettify ; =head1 DESCRIPTION This module takes a string Perl code sample and returns the tokens of the code surrounded with tags. The class attributes are the same used by the L. Using L you can generate the prettified code for use in webpages without using JavaScript but you can use all L developed for prettify.js. Also, because this module uses L to tokenize the code, it's more accurate than prettify.js. L exports prettify() and the $MARKUP_RULES hashref which is used to match PPI::Token classes to the class attribute given to that token's 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: L. =head1 MOTIVATION I wanted to generate marked-up Perl code without using JavaScript for L. 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 L 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. =head1 BUGS AND LIMITATIONS =over 4 =item * What constitutes a function and a keyword is somewhat arbitrary in Perl. L mostly uses L to help distinguish functions and keywords. However, some words such as "if", "my" and "BEGIN" are given a special class of "PPI::Token::KeywordFunction" which can be overridden in $MARKUP_RULES, should you wish to display these as keywords instead of functions. =item * This module does not yet process Perl code samples with heredocs correctly. =item * Line numbering needs to be added. =back =head1 SUBROUTINES/METHODS =head2 prettify Takes a hashref consisting of $code and an optional debug flag. Every Perl code token is given a 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 L for examples. =head2 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 =head1 INTERNAL FUNCTIONS =head2 _decorate Iterates through the tokens of a L, marking up each token with a tag. =head2 _to_html Marks up a token with a span tag with the appropriate class attribute and the PPI::Token class. =head2 _determine_token Determines the PPI::Token type. =head1 REPOSITORY L =head1 SEE ALSO L is another prettifier for Perl code samples that allows the embedding of CSS directly into the HTML generation. =head1 THANKS Thanks to Adam Kennedy for developing L, without which this module would not be possible. =head1 AUTHOR David Farrell L =head1 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.