https://github.com/dnmfarrell/ppi-prettify
A Perl HTML pretty printer to use with Google prettify CSS skins, no JavaScript required!
https://github.com/dnmfarrell/ppi-prettify
Last synced: 13 days ago
JSON representation
A Perl HTML pretty printer to use with Google prettify CSS skins, no JavaScript required!
- Host: GitHub
- URL: https://github.com/dnmfarrell/ppi-prettify
- Owner: dnmfarrell
- License: other
- Created: 2014-08-16T14:38:24.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2017-06-21T16:39:22.000Z (almost 9 years ago)
- Last Synced: 2025-03-06T05:43:40.847Z (over 1 year ago)
- Language: Perl
- Size: 117 KB
- Stars: 0
- Watchers: 3
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.pod
- Changelog: Changes
- License: LICENSE
Awesome Lists containing this project
README
=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.