pygments.rb

Introduction

pygments.rb is a Ruby wrapper for Pygments syntax highlighter.

pygments.rb works by talking over a simple pipe to a long-lived Python child process. This library replaces github/albino, as well as an older version of pygments.rb that used an embedded Python interpreter.

Each Ruby process that runs has its own 'personal Python'; for example, 4 Unicorn workers will have one Python process each. If a Python process dies, a new one will be spawned on the next pygments.rb request.

System Requirements

Python >= 3.8
Ruby >= 2.6

Installation

Add this line to your application’s Gemfile:

gem 'pygments.rb'

And then execute:

$ bundle install

Or install pygments.rb gem yourself as:

$ gem install pygments.rb

Usage

Require pygments.rb module:

require 'pygments'

Highlight a file:

Pygments.highlight(File.read(__FILE__), lexer: 'ruby')

Optionally, pass encoding and other lexer/formatter options via an :options hash:

Pygments.highlight('code', options: {encoding: 'utf-8'})

pygments.rb uses HTML formatter by default. To use a different formatter, specify it via :formatter parameter:

Pygments.highlight('code', formatter: 'bbcode')
Pygments.highlight('code', formatter: 'terminal')

To generate CSS for HTML formatted code, use the Pygments.css method:

Pygments.css
Pygments.css('.highlight')

To use a specific pygments style, pass the :style option to the Pygments.css method:

Pygments.css(style: 'monokai')

Other Pygments high-level API methods are also available. These methods return arrays detailing all the available lexers, formatters, and styles:

Pygments.lexers
Pygments.formatters
Pygments.styles

To use a custom pygments installation, specify the path to Pygments.start:

Pygments.start("/path/to/pygments")

If you’d like logging, set the environmental variable MENTOS_LOG to a file path for your logfile.

You can apply a timeout to pygments.rb calls by specifying number of seconds in MENTOS_TIMEOUT environmental variable or by passing the :timeout argument (takes precedence over MENTOS_TIMEOUT):

Pygments.highlight('code', timeout: 4)

Benchmarks

$ ruby bench.rb 50
   Benchmarking....
   Size: 698 bytes
   Iterations: 50
                                                  user     system      total        real
   pygments popen                                0.010000   0.010000   0.020000 (  0.460370)
   pygments popen (process already started)      0.010000   0.000000   0.010000 (  0.272975)
   pygments popen (process already started 2)    0.000000   0.000000   0.000000 (  0.273589)

$ ruby bench.rb 10
   Benchmarking....
   Size: 15523 bytes
   Iterations: 10
                                                  user     system      total        real
   pygments popen                               0.000000   0.000000   0.000000 (  0.819419)
   pygments popen (process already started)     0.010000   0.000000   0.010000 (  0.676515)
   pygments popen (process already started 2)   0.000000   0.010000   0.010000 (  0.674189)

Development

After checking out the repo, run bundle install to install dependencies. Then, run bundle exec rake test to run the tests.

Copyright

For the full text of the license, see the LICENSE file.

slonopotamus / pygments.rb