NAME

Syntax::Highlight::WithEmacs - syntax-highlight source code using Emacs

VERSION

version 0.1

SYNOPSIS

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');

DESCRIPTION

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.

EXTENDED SETUP INSTRUCTIONS

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:

(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.

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))

METHODS

new

create new highlighter object. the following options are available:

mode

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.

emacs_args

an array reference of additional parameters to pass to the emacs(client) command. Defaults to the empty array. Possible uses might be ['-q'] or

[-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

emacs_cmd

command to start emacs. Defaults to emacs

client_cmd

command to start the emacs client. Defaults to emacsclient

term_spec

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

htmlize_generate_hyperlinks

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.

use_client

whether to use the emacs client. Defaults to true

server_name

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.

start_server

whether to start the emacs server on object creation time. Defaults to true

kill_server

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

ansi_opts

a hashref of additional options for the ansifier. see the ansify_string method.

htmlize_file

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:

$file: input file to run htmlize on
$out: output file to save html in. Can be omitted, in which case the output file will be the input file with .html appended

this method does not return anything. You can process the generated HTML file with any tool you like.

htmlize_string

run htmlize on the given string. The following parameters are expected:

$string: a string with code to highlight.
$mode: 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.

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.

ansify_string

run htmlize on the given string, like htmlize_string, but return the result as a string formatted with ANSI escape codes.

$string

a string with code to highlight.

$mode

extension of the temporary file created. (see htmlize_string)

%opts

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:

italic_as

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!

css

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

color_depth

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.

color_format

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.

COLOR_FORMAT ENCODER

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" }
}

$is_background: true if this is background colour
$index: the colour index in 8, 16 or 256 colour palette (see color_depth)
$r, $g, $b: 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

marked_string

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.

$string: a string with code to highlight.
$mode: extension of the temporary file created. (see htmlize_string)

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!

start_server

manually start the emacs server

kill_server

manually send the kill command to the emacs server.

AUTHOR

Ailin Nemui <ailin at devio dot us>

COPYRIGHT AND LICENSE

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)