1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
= {project-name}
Ted Nyman <ted@ted.io>; Aman Gupta <aman@tmm1.net>; Marat Radchenko <marat@slonopotamus.org>
:project-name: pygments.rb
:slug: pygments/{project-name}
:uri-project: https://github.com/{slug}
:uri-ci: {uri-project}/actions?query=branch%3Amaster
:uri-gem: https://rubygems.org/gems/{project-name}
:uri-pygments: https://pygments.org/
image:https://img.shields.io/gem/v/{project-name}.svg[Latest Release,link={uri-gem}]
image:{uri-project}/workflows/CI/badge.svg?branch=master[Build Status,link={uri-ci}]
== Introduction
{project-name} is a Ruby wrapper for {uri-pygments}[Pygments] syntax highlighter.
{project-name} works by talking over a simple pipe to a long-lived Python child process.
This library replaces https://github.com/github/albino[github/albino], as well as an older version of {project-name} 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.5
- Ruby >= 2.3
== Installation
Add this line to your application's Gemfile:
[source,ruby]
----
gem 'pygments.rb'
----
And then execute:
[source,shell script]
----
$ bundle install
----
Or install pygments.rb gem yourself as:
[source,shell script]
----
$ gem install pygments.rb
----
== Usage
Require pygments.rb module:
[source,ruby]
----
require 'pygments'
----
Highlight a file:
[source,ruby]
----
Pygments.highlight(File.read(__FILE__), lexer: 'ruby')
----
Optionally, pass encoding and other lexer/formatter options via an `:options` hash:
[source,ruby]
----
Pygments.highlight('code', options: {encoding: 'utf-8'})
----
pygments.rb uses HTML formatter by default.
To use a different formatter, specify it via `:formatter` parameter:
[source,ruby]
----
Pygments.highlight('code', formatter: 'bbcode')
Pygments.highlight('code', formatter: 'terminal')
----
To generate CSS for HTML formatted code, use the `Pygments.css` method:
[source,ruby]
----
Pygments.css
Pygments.css('.highlight')
----
To use a specific pygments style, pass the `:style` option to the `Pygments.css` method:
[source,ruby]
----
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:
[source,ruby]
----
Pygments.lexers
Pygments.formatters
Pygments.styles
----
To use a custom pygments installation, specify the path to
`Pygments.start`:
[source,ruby]
----
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`):
[source,ruby]
----
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
Copyright (C) Ted Nyman, Aman Gupta, Marat Radchenko, 2012-2021.
Free use of this software is granted under the terms of the MIT License.
For the full text of the license, see the link:LICENSE[] file.
|
