/ 
SyntaxHighlight-Any-0.07
River stage one • 2 direct dependents • 2 total dependents
/ SyntaxHighlight::Any

NAME

SyntaxHighlight::Any - Common interface for syntax highlighting and detecting language in code

VERSION

This document describes version 0.07 of SyntaxHighlight::Any (from Perl distribution SyntaxHighlight-Any), released on 2017-07-10.

SYNOPSIS

use SyntaxHighlight::Any qw(highlight_string detect_language);

my $str = <<'EOT';
while (<>) {
    $lines++;
    $nonblanks++ if  /\S/;
    $blanks++ unless /\S/;
}
EOT
say highlight_string($str, {lang=>"perl"});
my @lang = detect_language($str); # => ("perl")

DESCRIPTION

CAVEAT: EARLY DEVELOPMENT MODULE. SOME FUNCTIONS NOT YET IMPLEMENTED. HELP ON ADDING BACKENDS APPRECIATED.

This module provides a common interface for syntax highlighting and detecting programming language in code.

BACKENDS

Currently, the distribution does not pull the backends as dependencies. Please make sure you install desired backends.

FUNCTIONS

detect_language($code, \%opts) => LIST

CURRENTLY NOT YET IMPLEMENTED.

Attempt to detect programming language of $code and return zero or more possible candidates. Return empty list if cannot detect. Die on error (e.g. no backends available or unexpected output from backend).

%opts is optional. Known options:

highlight_string($code, \%opts) => STR

Syntax-highlight $code and return the highlighted string. Will choose an appropriate and available backend which is capable of formatting code in the specified/detected language and to the specified output. Die on error (e.g. unexpected output from backend).

Will return $code as-is if no backends are available (a warning is produced via Log::Any though).

By default try to detect whether to output HTML code or ANSI codes (see output option). By default try to detect language of $code.

Backends: currently in general tries GNU Source-highlight (via Syntax::SourceHighlight, or binary if module not available), then Pygments (binary). Patches for detecting/using other backends are welcome.

%opts is optional. Known options:

  • lang => STR

    Tell the function what programming language $code should be regarded as. The list of known languages can be retrieved using list_languages().

    If unspecified, the function will perform the following. For backends which can detect the language, this function will just give $code to the backend for it to figure out the language. For backends which cannot detect the language, this function will first call detect_language().

    NOTE: SINCE detect_language() is not implemented yet, please specify this.>

  • output => STR

    Either ansi, in which syntax-highlighting is done with ANSI escape color codes, or html. If not specified, will try to detect whether program is running under terminal (in which case ansi is chosen) or web environment e.g. under CGI/FastCGI, mod_perl, or Plack (in which case html is chosen). If detection fails, ansi is chosen.

list_languages() => LIST

List known languages.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/SyntaxHighlight-Any.

SOURCE

Source repository is at https://github.com/perlancar/perl-SyntaxHighlight-Any.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=SyntaxHighlight-Any

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

For syntax-highlighting (as well as encoding/formatting) to JSON, there's JSON::Color or Syntax::Highlight::JSON (despite the module name, the latter is an encoder, not strictly a string syntax highlighter). For YAML there's YAML::Tiny::Color.

An article in late 2012 describing the various CPAN modules for syntax highlighting http://blogs.perl.org/users/steven_haryanto/2012/11/the-sad-state-of-syntax-highlighting-libraries-on-cpan.html (with the actual reviews posted to http://cpanratings.perl.org). Modules mentioned including: Syntax::SourceHighlight (reviews), Syntax::Highlight::Engine::Kate (reviews), Syntax::Highlight::JSON (reviews), Syntax::Highlight::Engine::Simple (reviews), Syntax::Highlight::Universal (reviews), and Text::Highlight (reviews). Some non-Perl solutions are also mentioned.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017, 2015, 2014, 2013 by perlancar@cpan.org.

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