Syntax::Highlight::WithEmacs - syntax-highlight source code using Emacs
version 0.1
my $hl = Syntax::Highlight::WithEmacs->new(); my $html = $hl->htmlize_string(q{my $x = 42;}, 'pl'); my $hl = Syntax::Highlight::WithEmacs->new( mode => 'css', use_client => 0, emacs_cmd => 'emacs24', ); my ($pre_node, $css) = $hl->htmlize_string(q{my $x = 42;}, 'pl'); print $hl->ansify_string(q{my $x = 42;}, 'pl');
This module uses the Emacs script htmlize.el to provide syntax highlighting the same way as your local Emacs does.
Care has been taken so that it works on the server, especially it has been tested to work as part of a Movable Type CodeBeautifier plug-in (but see MT::Plugin::BeautifierWithEmacs).
Note that you do need a working copy of Emacs including a working set-up of htmlize. This module has been tested to work on GNU FSF Emacs 23 and 24.
htmlize for Emacs can be found on http://fly.srk.fer.hr/~hniksic/emacs/htmlize.el.cgi. You need this Emacs script, otherwise this module won't work.
You can download it to any place you like, for example ~/.emacs.d/elisp and insert this code in your emacs start-up file:
~/.emacs.d/elisp
(add-to-list 'load-path "~/.emacs.d/elisp")
Check its operation from within Emacs using M-x htmlize-buffer.
To highlight Perl code, the cperl mode by JROCKWAY is highly recommended (but you probably already know this if you are using Emacs). Please download it from https://github.com/jrockway/cperl-mode/tree/mx-declare, the mx-declare tree has support for the MooseX::Declare syntaxes like class, method and so on.
class
method
To turn the old perl-mode into cperl-mode (default on XEmacs), you can use this elisp in your start-up file:
(mapc (lambda (pair) (if (eq (cdr pair) 'perl-mode) (setcdr pair 'cperl-mode))) (append auto-mode-alist interpreter-mode-alist))
Other important modes for Emacs:
yaml-mode
(autoload 'yaml-mode "yaml-mode" "Simple mode to edit YAML." t) (add-to-list 'auto-mode-alist '("\\.yml$" . yaml-mode)) (add-to-list 'auto-mode-alist '("\\.yaml$" . yaml-mode))
js2-mode
(autoload 'js2-mode "js2-mode" "Major mode for editing JavaScript code." t) (add-to-list 'auto-mode-alist '("\\.js$" . js2-mode))
csharp-mode
(autoload 'csharp-mode "csharp-mode" "Major mode for editing C# code." t) (setq auto-mode-alist (append '(("\\.cs$" . csharp-mode)) auto-mode-alist))
nxml-mode as default (on GNU FSF Emacs 23):
(mapc (lambda (pair) (if (eq (cdr pair) 'xml-mode) (setcdr pair 'nxml-mode))) (append auto-mode-alist interpreter-mode-alist))
create new highlighter object. the following options are available:
designates the htmlize-output-type. Defaults to font. Valid choices usually include css and inline-css. See C-h v htmlize-output-type inside Emacs.
an array reference of additional parameters to pass to the emacs(client) command. Defaults to the empty array. Possible uses might be ['-q'] or
['-q']
[-eval => qq((add-to-list 'load-path "$ENV{HOME}/.emacs.d/elisp"))]
to customise the load path, or
[-eval => q((custom-set-variables '(frame-background-mode 'dark)))]
(or 'light) to set the colour scheme
'light
command to start emacs. Defaults to emacs
emacs
command to start the emacs client. Defaults to emacsclient
emacsclient
setting for the TERM environment variable when running emacs. Defaults to xterm-256color. Different values result in different set-ups for the face properties, so the colours you get back from htmlize will be different (use an eight colour set) if you use a value such as xterm
xterm-256color
xterm
whether htmlize should add hyperlinks. as the default implementation of htmlize-create-auto-links frequently generates incorrect links for me, this is disabled by default.
htmlize-create-auto-links
whether to use the emacs client. Defaults to true
the name of the emacs server to which the client will connect. Defaults to "EmacsHtmlize(pid)_(counter)". You might want to set this to the empty string to make it connect to your default server. See also kill_server below.
whether to start the emacs server on object creation time. Defaults to true
whether to kill the emacs server during object destroy. Defaults to true. You should definitely disable this if you have it connect to your default server
a hashref of additional options for the ansifier. see the ansify_string method.
ansify_string
run htmlize on a given filename. The major-mode emacs uses to highlight it will be chosen by your own emacs configuration file, which is usually by the file extension.
The following parameters are expected:
input file to run htmlize on
output file to save html in. Can be omitted, in which case the output file will be the input file with .html appended
.html
this method does not return anything. You can process the generated HTML file with any tool you like.
run htmlize on the given string. The following parameters are expected:
a string with code to highlight.
extension of the temporary file created. As most emacs configurations choose major mode by extension, this will directly influence the file mode used for highlighting.
Note: the file name passed to htmlize matches ^EmacsHtmlize.*\.$mode$. You can use this to configure mode rules based on filename in your .gnu-emacs file.
^EmacsHtmlize.*\.$mode$
This method returns the highlighted code as a XML::LibXML::Node and the accompanying stylesheet as a CSS::Tiny object. In scalar context, only the HTML node is returned.
run htmlize on the given string, like htmlize_string, but return the result as a string formatted with ANSI escape codes.
htmlize_string
extension of the temporary file created. (see htmlize_string)
additional key => value pairs to configure the ansifier. the defaults can be overwritten by setting a hashref in the ansi_opts property of the object. the following keys are possible:
key => value
ansi_opts
attribute to use as italic, which can be given as a raw number to the ANSI CSI m command or as string which is an alias as specified by the Term::ANSIColor module. popular choices include bold, underline, reverse and italic. Defaults to reverse. Note that italic was only added in Perl 5.18, so stick with
italic_as => 3
for backwards compatibility!
an alternate CSS stylesheet to use for formatting, this can be a CSS::Tiny compatible hashref, CSS::Tiny compatible object or a string to be fed to CSS::Tiny. defaults empty
overwrite the colour depth that is used to render the ANSI escape sequences. Defaults to 2**24. sensible other values would be 8, 16, or 256.
this sets the output format for colour escape sequences, which is not quite standardised. the only current possible string value and also the default is 'aix', which is xterm-compatible. however, if you specify a coderef you can provide compatible output format for, say, fbterm.
fbterm
you can give a coderef to the color_format option of the ANSI encoder to render colours to custom control codes. it takes the following format:
color_format => sub { my ($is_background, $index_or_r, $g, $b) = @_; my $color; if (defined $g) { $color = munge_rgb($index_or_r, $g, $b); } elsif (defined $index_or_r) { $color = munge_index($index_r); } else { $color = "default" } if ($is_background) { "control code to set background to $color" } elsif (defined $is_background) { "control code to set foreground to $color" } else { "control code to reset all colours" } }
true if this is background colour
the colour index in 8, 16 or 256 colour palette (see color_depth)
the colour values of the r-g-b channels as integer in the range of 0..255
and returns the control codes for the requested colour spec
run htmlize on the given string, like htmlize_string, but return an arrayref of arrayrefs with class => string pairs similar to Text::VimColor's marked method.
marked
Example:
$hl->marked_string(q{my $x = 42;}, 'pl'); # ==> result is like follows [ [ 'keyword', 'my' ], [ '', ' ' ], [ 'variable-name', '$x' ], [ '', ' = 42;' ] ];
note, it is not compatible to Text::VimColor!
manually start the emacs server
manually send the kill command to the emacs server.
Text::EmacsColor
This module wants to do the same but it does not work properly when not using emacsclient, and it fails to include the colour definitions because Emacs does not load those in batch mode.
Other Syntax::Highlight::* modules on CPAN.
Text::VimColor which does the same using VIM.
Ailin Nemui <ailin at devio dot us>
This software is copyright (c) 2013 by Ailin Nemui.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Syntax::Highlight::WithEmacs, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Syntax::Highlight::WithEmacs
CPAN shell
perl -MCPAN -e shell install Syntax::Highlight::WithEmacs
For more information on module installation, please visit the detailed CPAN module installation guide.