pandoc-ruby 1.0.0 → 2.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile +5 -6
- data/Gemfile.lock +6 -24
- data/README.md +131 -0
- data/Rakefile +2 -2
- data/lib/pandoc-ruby.rb +129 -128
- data/pandoc-ruby.gemspec +27 -30
- data/test/benchmark.rb +10 -8
- data/test/files/test.md +2 -1
- data/test/helper.rb +3 -6
- data/test/test_conversions.rb +21 -58
- data/test/test_pandoc_ruby.rb +205 -0
- metadata +12 -31
- data/README.markdown +0 -95
- data/test/test_pandoc-ruby.rb +0 -199
data/README.markdown
DELETED
@@ -1,95 +0,0 @@
|
|
1
|
-
# PandocRuby
|
2
|
-
|
3
|
-
Wrapper for [Pandoc](http://johnmacfarlane.net/pandoc/), a Haskell library with command line tools for converting one markup format to another.
|
4
|
-
|
5
|
-
Pandoc can convert documents in markdown, reStructuredText, textile, HTML, DocBook, LaTeX, or MediaWiki markup to a variety of formats, including markdown, reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNU Texinfo, MediaWiki markup, groff man pages, HTML slide shows, EPUB, and Microsoft Word docx.
|
6
|
-
|
7
|
-
## Installation
|
8
|
-
|
9
|
-
First, make sure to [install Pandoc](http://johnmacfarlane.net/pandoc/installing.html).
|
10
|
-
|
11
|
-
Next, install PandocRuby from [RubyGems](http://rubygems.org/gems/pandoc-ruby).
|
12
|
-
|
13
|
-
gem install pandoc-ruby
|
14
|
-
|
15
|
-
## Usage
|
16
|
-
|
17
|
-
require 'pandoc-ruby'
|
18
|
-
@converter = PandocRuby.new('# Markdown Title', :from => :markdown, :to => :rst)
|
19
|
-
puts @converter.convert
|
20
|
-
|
21
|
-
This takes the Markdown formatted file and converts it to reStructuredText.
|
22
|
-
|
23
|
-
You can also use the `#convert` class method:
|
24
|
-
|
25
|
-
puts PandocRuby.convert('# Markdown Title', :from => :markdown, :to => :html)
|
26
|
-
|
27
|
-
When no options are passed, pandoc's default behavior converts markdown to html. To specify options, simply pass options as a hash to the initializer. Pandoc's wrapper executables can also be used by passing the executable name as the second argument. For example,
|
28
|
-
|
29
|
-
PandocRuby.new('<p>Some <em>HTML</em></p>', 'html2markdown')
|
30
|
-
|
31
|
-
will use Pandoc's `html2markdown` wrapper.
|
32
|
-
|
33
|
-
Other arguments are simply converted into command line options, accepting symbols or strings for options without arguments and hashes of strings or symbols for options with arguments.
|
34
|
-
|
35
|
-
PandocRuby.convert('# Markdown Title', :s, {:f => :markdown, :to => :rst}, 'no-wrap', :table_of_contents)
|
36
|
-
|
37
|
-
is equivalent to
|
38
|
-
|
39
|
-
echo "# Markdown Title" | pandoc -s -f markdown --to=rst --no-wrap --table-of-contents
|
40
|
-
|
41
|
-
Also provided are `#to_[writer]` instance methods for each of the writers, and these can also accept options:
|
42
|
-
|
43
|
-
PandocRuby.new("# Some title").to_html(:no_wrap)
|
44
|
-
=> "<div id=\"some-title\"><h1>Some title</h1></div>"
|
45
|
-
# or
|
46
|
-
PandocRuby.new("# Some title").to_rst
|
47
|
-
=> "Some title\n=========="
|
48
|
-
|
49
|
-
Similarly, there are class methods for each of the readers, so readers and writers can be specified like this:
|
50
|
-
|
51
|
-
PandocRuby.html("<h1>hello</h1>").to_latex
|
52
|
-
=> "\\section{hello}"
|
53
|
-
|
54
|
-
PandocRuby assumes the pandoc executables are in the path. If not, set their location
|
55
|
-
with `PandocRuby.bin_path = '/path/to/bin'`
|
56
|
-
|
57
|
-
Pandoc can also be set to take a file path as the first argument. For security reasons, this is disabled by default, but it can be enabled and used as follows
|
58
|
-
|
59
|
-
PandocRuby.allow_file_paths = true
|
60
|
-
PandocRuby.html('/some/file.html').to_markdown
|
61
|
-
|
62
|
-
Available format readers and writers are available in the `PandocRuby::READERS` and `PandocRuby::WRITERS` constants.
|
63
|
-
|
64
|
-
For more information on Pandoc, see the [Pandoc documentation](http://johnmacfarlane.net/pandoc/) or run `man pandoc` ([also available here](http://johnmacfarlane.net/pandoc/pandoc.1.html)).
|
65
|
-
|
66
|
-
If you'd prefer a pure-Ruby extended markdown interpreter that can output a few different formats, take a look at [Maruku](http://maruku.rubyforge.org/). If you want to use the full reStructuredText syntax from within Ruby, check out [RbST](https://github.com/alphabetum/rbst), a docutils wrapper.
|
67
|
-
|
68
|
-
This gem was inspired by [Albino](http://github.com/github/albino). For a slightly different approach to using Pandoc with Ruby, see [Pandoku](http://github.com/dahlia/pandoku).
|
69
|
-
|
70
|
-
## Pandoc Tip
|
71
|
-
|
72
|
-
If you are trying to generate a standalone file with full file headers rather than just a marked up fragment, remember to pass the `:standalone` option so the correct header and footer are added.
|
73
|
-
|
74
|
-
PandocRuby.new("# Some title", :standalone).to_rtf
|
75
|
-
|
76
|
-
## Caveats
|
77
|
-
|
78
|
-
* Ruby 1.9.3 or higher is required.
|
79
|
-
* This has only been tested on \*nix systems.
|
80
|
-
* PDF conversion may require additional dependencies and has not been tested.
|
81
|
-
|
82
|
-
## Note on Patches/Pull Requests
|
83
|
-
|
84
|
-
* Fork the project.
|
85
|
-
* Make your feature addition or bug fix.
|
86
|
-
* Add tests for it. This is important so I don't break it in a
|
87
|
-
future version unintentionally.
|
88
|
-
* Commit, do not mess with rakefile, version, or history.
|
89
|
-
(if you want to have your own version, that is fine but
|
90
|
-
bump version in a commit by itself I can ignore when I pull)
|
91
|
-
* Send me a pull request. Bonus points for topic branches.
|
92
|
-
|
93
|
-
## Copyright
|
94
|
-
|
95
|
-
Copyright (c) 2009-∞ William Melody · => [@alphabetum](http://twitter.com/alphabetum)
|
data/test/test_pandoc-ruby.rb
DELETED
@@ -1,199 +0,0 @@
|
|
1
|
-
require 'helper'
|
2
|
-
|
3
|
-
class TestPandocRuby < Test::Unit::TestCase
|
4
|
-
|
5
|
-
def setup
|
6
|
-
@file = File.join(File.dirname(__FILE__), 'files', 'test.md')
|
7
|
-
@converter = PandocRuby.new(@file, :t => :rst)
|
8
|
-
end
|
9
|
-
|
10
|
-
def teardown
|
11
|
-
PandocRuby.bin_path = nil
|
12
|
-
PandocRuby.allow_file_paths = false
|
13
|
-
end
|
14
|
-
|
15
|
-
should "call bare pandoc when passed no options" do
|
16
|
-
converter = PandocRuby.new(@file)
|
17
|
-
converter.expects(:execute).with('pandoc').returns(true)
|
18
|
-
assert converter.convert
|
19
|
-
end
|
20
|
-
|
21
|
-
should "convert with altered bin_path" do
|
22
|
-
path = %x[which pandoc].strip
|
23
|
-
PandocRuby.bin_path = path
|
24
|
-
converter = PandocRuby.new(@file)
|
25
|
-
converter.expects(:execute).with("#{path}/pandoc").returns(true)
|
26
|
-
assert converter.convert
|
27
|
-
end
|
28
|
-
|
29
|
-
should "treat file paths as strings by default" do
|
30
|
-
assert_equal "<p>#{@file}</p>\n", PandocRuby.new(@file).to_html
|
31
|
-
end
|
32
|
-
|
33
|
-
should "treat file paths as file paths when enabled" do
|
34
|
-
PandocRuby.allow_file_paths = true
|
35
|
-
assert PandocRuby.new(@file).to_html.match(%r{This is a Title})
|
36
|
-
end
|
37
|
-
|
38
|
-
should "accept short options" do
|
39
|
-
@converter.expects(:execute).with('pandoc -t rst').returns(true)
|
40
|
-
assert @converter.convert
|
41
|
-
end
|
42
|
-
|
43
|
-
should "accept long options" do
|
44
|
-
converter = PandocRuby.new(@file, :to => :rst)
|
45
|
-
converter.expects(:execute).with('pandoc --to rst').returns(true)
|
46
|
-
assert converter.convert
|
47
|
-
end
|
48
|
-
|
49
|
-
should "accept a variety of options in initializer" do
|
50
|
-
converter = PandocRuby.new(@file, :s, {
|
51
|
-
:f => :markdown, :to => :rst
|
52
|
-
}, 'no-wrap')
|
53
|
-
converter \
|
54
|
-
.expects(:execute) \
|
55
|
-
.with('pandoc -s -f markdown --to rst --no-wrap') \
|
56
|
-
.returns(true)
|
57
|
-
assert converter.convert
|
58
|
-
end
|
59
|
-
|
60
|
-
should "accept a variety of options in convert" do
|
61
|
-
converter = PandocRuby.new(@file)
|
62
|
-
converter \
|
63
|
-
.expects(:execute) \
|
64
|
-
.with('pandoc -s -f markdown --to rst --no-wrap') \
|
65
|
-
.returns(true)
|
66
|
-
assert converter.convert(:s, {:f => :markdown, :to => :rst}, 'no-wrap')
|
67
|
-
end
|
68
|
-
|
69
|
-
should "convert underscore symbol ares to hyphenated long options" do
|
70
|
-
converter = PandocRuby.new(@file, {
|
71
|
-
:email_obfuscation => :javascript
|
72
|
-
}, :table_of_contents)
|
73
|
-
converter \
|
74
|
-
.expects(:execute) \
|
75
|
-
.with('pandoc --email-obfuscation javascript --table-of-contents') \
|
76
|
-
.returns(true)
|
77
|
-
assert converter.convert
|
78
|
-
end
|
79
|
-
|
80
|
-
should "accept optional executable" do
|
81
|
-
converter = PandocRuby.new(@file, 'html2markdown')
|
82
|
-
converter.expects(:execute).with('html2markdown').returns(true)
|
83
|
-
assert converter.convert
|
84
|
-
end
|
85
|
-
|
86
|
-
should "use non-executable second arg as option" do
|
87
|
-
converter = PandocRuby.new(@file, 'toc')
|
88
|
-
converter.expects(:execute).with('pandoc --toc').returns(true)
|
89
|
-
assert converter.convert
|
90
|
-
end
|
91
|
-
|
92
|
-
should "raise RuntimeError from pandoc executable error" do
|
93
|
-
assert_raise RuntimeError do
|
94
|
-
PandocRuby.new("# hello", "badopt").to_html5
|
95
|
-
end
|
96
|
-
end
|
97
|
-
|
98
|
-
PandocRuby::READERS.each_key do |r|
|
99
|
-
should "convert from #{r} with PandocRuby.#{r}" do
|
100
|
-
converter = PandocRuby.send(r, @file)
|
101
|
-
converter.expects(:execute).with("pandoc --from #{r}").returns(true)
|
102
|
-
assert converter.convert
|
103
|
-
end
|
104
|
-
end
|
105
|
-
|
106
|
-
PandocRuby::STRING_WRITERS.each_key do |w|
|
107
|
-
should "convert to #{w} with to_#{w}" do
|
108
|
-
converter = PandocRuby.new(@file)
|
109
|
-
converter \
|
110
|
-
.expects(:execute) \
|
111
|
-
.with("pandoc --no-wrap --to #{w}") \
|
112
|
-
.returns(true)
|
113
|
-
assert converter.send("to_#{w}", :no_wrap)
|
114
|
-
end
|
115
|
-
end
|
116
|
-
|
117
|
-
PandocRuby::BINARY_WRITERS.each_key do |w|
|
118
|
-
should "convert to #{w} with to_#{w}" do
|
119
|
-
converter = PandocRuby.new(@file)
|
120
|
-
converter \
|
121
|
-
.expects(:execute) \
|
122
|
-
.with(regexp_matches(/^pandoc --no-wrap --to #{w} --output /)) \
|
123
|
-
.returns(true)
|
124
|
-
assert converter.send("to_#{w}", :no_wrap)
|
125
|
-
end
|
126
|
-
end
|
127
|
-
|
128
|
-
should "work with strings" do
|
129
|
-
converter = PandocRuby.new('## this is a title')
|
130
|
-
assert_match %r(h2), converter.convert
|
131
|
-
end
|
132
|
-
|
133
|
-
should "alias to_s" do
|
134
|
-
assert_equal @converter.convert, @converter.to_s
|
135
|
-
end
|
136
|
-
|
137
|
-
should "have convert class method" do
|
138
|
-
assert_equal @converter.convert, PandocRuby.convert(@file, :t => :rst)
|
139
|
-
end
|
140
|
-
|
141
|
-
should "run more than 400 times without error" do
|
142
|
-
begin
|
143
|
-
400.times do
|
144
|
-
PandocRuby.convert(@file)
|
145
|
-
end
|
146
|
-
assert true
|
147
|
-
rescue Errno::EMFILE, Errno::EAGAIN => e
|
148
|
-
flunk e
|
149
|
-
end
|
150
|
-
end
|
151
|
-
|
152
|
-
should "have reader and writer constants" do
|
153
|
-
assert_equal PandocRuby::READERS, {
|
154
|
-
"html" => "HTML",
|
155
|
-
"latex" => "LaTeX",
|
156
|
-
"textile" => "textile",
|
157
|
-
"native" => "pandoc native",
|
158
|
-
"markdown" => "markdown",
|
159
|
-
"json" => "pandoc JSON",
|
160
|
-
"rst" => "reStructuredText"
|
161
|
-
}
|
162
|
-
|
163
|
-
assert_equal PandocRuby::STRING_WRITERS, {
|
164
|
-
"mediawiki" => "MediaWiki markup",
|
165
|
-
"html" => "HTML",
|
166
|
-
"plain" => "plain",
|
167
|
-
"latex" => "LaTeX",
|
168
|
-
"s5" => "S5 HTML slideshow",
|
169
|
-
"textile" => "textile",
|
170
|
-
"texinfo" => "GNU Texinfo",
|
171
|
-
"docbook" => "DocBook XML",
|
172
|
-
"html5" => "HTML5",
|
173
|
-
"native" => "pandoc native",
|
174
|
-
"org" => "emacs org mode",
|
175
|
-
"rtf" => "rich text format",
|
176
|
-
"markdown" => "markdown",
|
177
|
-
"man" => "groff man",
|
178
|
-
"dzslides" => "Dzslides HTML slideshow",
|
179
|
-
"beamer" => "Beamer PDF slideshow",
|
180
|
-
"json" => "pandoc JSON",
|
181
|
-
"opendocument" => "OpenDocument XML",
|
182
|
-
"slidy" => "Slidy HTML slideshow",
|
183
|
-
"rst" => "reStructuredText",
|
184
|
-
"context" => "ConTeXt",
|
185
|
-
"asciidoc" => "asciidoc"
|
186
|
-
}
|
187
|
-
|
188
|
-
assert_equal PandocRuby::BINARY_WRITERS, {
|
189
|
-
"odt" => "OpenDocument",
|
190
|
-
"docx" => "Word docx",
|
191
|
-
"epub" => "EPUB V2",
|
192
|
-
"epub3" => "EPUB V3"
|
193
|
-
}
|
194
|
-
|
195
|
-
assert_equal PandocRuby::WRITERS, (
|
196
|
-
PandocRuby::STRING_WRITERS.merge(PandocRuby::BINARY_WRITERS)
|
197
|
-
)
|
198
|
-
end
|
199
|
-
end
|