pandoc-ruby 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bb86a51dc3901cc03725daebcaa9afe2c4d2d4b2
-  data.tar.gz: 0c53e1b182af84515130b764a06d68041dae22ab
+  metadata.gz: 606934acc12140a2ce1f99e2f9c4e0cadfc24977
+  data.tar.gz: 6ae5fa55a9d05bb7f9f915d45a388f06869395fe
 SHA512:
-  metadata.gz: d607cd66c09554e971bd9757e2b155125867117d5ce4a6dcac8f08e8245f9261a40b1b6843cc52dae87afe26da885f04f7f338b19891a2b637cb529ce4781ff8
-  data.tar.gz: eaa4f5abf913287d78d70f054e64e0bde58d7c3675151ac058850bfa87ee9e77c5857cf649aace0fac640c3f001ad37d0ffa5b000199617592d0788a1adbc434
+  metadata.gz: 367018a0d5f56c3edac2a521ade4c695b6afc14f1755dc11605f30856a71b1ed7160da1aead1a4aa0e9919175a6e40e920bb0908bfb90539e98c3a397744e062
+  data.tar.gz: 9ebe803a32985af625b33165cf5db03d9daca6763bda2a80dda948e41fcd58bfdb46eac2181a8a0da2ba21a711ad3747cafce25d2cf80ac9fe76fad2c2d52b4e

data/Gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
 # Add dependencies required to use your gem here.
 # Example:
 #   gem "activesupport", ">= 2.3.5"
@@ -6,9 +6,8 @@ source "http://rubygems.org"
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development, :test do
-  gem "mocha",      "~> 1.1.0"
-  gem "rake"
-  gem "rdoc",       "~> 4.2.0"
-  gem "shoulda",    "~> 3.5.0"
-  gem "test-unit",  "~> 3.0.9"
+  gem 'minitest', '~>5.8.3'
+  gem 'mocha', '~>1.1.0'
+  gem 'rake'
+  gem 'rdoc'
 end

data/Gemfile.lock

@@ -1,39 +1,21 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (4.2.0)
-      i18n (~> 0.7)
-      json (~> 1.7, >= 1.7.7)
-      minitest (~> 5.1)
-      thread_safe (~> 0.3, >= 0.3.4)
-      tzinfo (~> 1.1)
-    i18n (0.7.0)
-    json (1.8.2)
     metaclass (0.0.4)
-    minitest (5.5.1)
+    minitest (5.8.3)
     mocha (1.1.0)
       metaclass (~> 0.0.1)
-    power_assert (0.2.2)
     rake (10.4.2)
     rdoc (4.2.0)
-    shoulda (3.5.0)
-      shoulda-context (~> 1.0, >= 1.0.1)
-      shoulda-matchers (>= 1.4.1, < 3.0)
-    shoulda-context (1.2.1)
-    shoulda-matchers (2.8.0)
-      activesupport (>= 3.0.0)
-    test-unit (3.0.9)
-      power_assert
-    thread_safe (0.3.4)
-    tzinfo (1.2.2)
-      thread_safe (~> 0.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  minitest (~> 5.8.3)
   mocha (~> 1.1.0)
   rake
-  rdoc (~> 4.2.0)
-  shoulda (~> 3.5.0)
-  test-unit (~> 3.0.9)
+  rdoc
+
+BUNDLED WITH
+   1.10.6

data/README.md

@@ -0,0 +1,131 @@
+# PandocRuby
+
+PandocRuby is a wrapper for [Pandoc](http://johnmacfarlane.net/pandoc/), a
+Haskell library with command line tools for converting one markup format to
+another.
+
+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.
+
+*This documentation is for version 2 and higher. For version 1 documentation
+[see here](https://github.com/alphabetum/pandoc-ruby/blob/v1.0.0/README.markdown).*
+
+## Installation
+
+First, make sure to
+[install Pandoc](http://johnmacfarlane.net/pandoc/installing.html).
+
+Next, add PandocRuby to your Gemfile
+
+```ruby
+gem 'pandoc-ruby'
+```
+
+or install PandocRuby from [RubyGems](http://rubygems.org/gems/pandoc-ruby).
+
+```bash
+gem install pandoc-ruby
+```
+
+## Usage
+
+```ruby
+require 'pandoc-ruby'
+@converter = PandocRuby.new('# Markdown Title', :from => :markdown, :to => :rst)
+puts @converter.convert
+```
+
+This takes the Markdown formatted file and converts it to reStructuredText.
+
+You can also use the `#convert` class method:
+
+```ruby
+puts PandocRuby.convert('# Markdown Title', :from => :markdown, :to => :html)
+```
+
+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.
+
+```ruby
+PandocRuby.convert('# Markdown Title', :s, {:f => :markdown, :to => :rst}, 'no-wrap', :table_of_contents)
+```
+
+is equivalent to
+
+```bash
+echo "# Markdown Title" | pandoc -s -f markdown --to=rst --no-wrap --table-of-contents
+```
+
+Also provided are `#to_[writer]` instance methods for each of the writers,
+and these can also accept options:
+
+```ruby
+PandocRuby.new("# Some title").to_html(:no_wrap)
+# => "<div id=\"some-title\"><h1>Some title</h1></div>"
+# or
+PandocRuby.new("# Some title").to_rst
+# => "Some title\n=========="
+```
+
+Similarly, there are class methods for each of the readers, so readers
+and writers can be specified like this:
+
+```ruby
+PandocRuby.html("<h1>hello</h1>").to_latex
+# => "\\section{hello}"
+```
+
+PandocRuby assumes the `pandoc` executable is via your environment's `$PATH`
+variable.  If you'd like to set an explicit path to the `pandoc` executable,
+you can do so with  `PandocRuby.pandoc_path = '/path/to/pandoc'`
+
+Pandoc can also be set to take an array of file paths as the first argument.
+
+```ruby
+# One file path as a single-element array.
+PandocRuby.html(['/path/to/file1.html']).to_markdown
+# Multiple file paths as an array.
+PandocRuby.html(['/path/to/file1.html', '/path/to/file2.html']).to_markdown
+```
+
+Available format readers and writers are available in the `PandocRuby::READERS`
+and `PandocRuby::WRITERS` constants.
+
+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)).
+
+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.
+
+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).
+
+## Additional Notes
+
+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.
+
+```ruby
+PandocRuby.new("# Some title", :standalone).to_rtf
+```
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+  bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.

data/Rakefile

@@ -6,7 +6,7 @@ begin
   Bundler.setup(:default, :development)
 rescue Bundler::BundlerError => e
   $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
+  $stderr.puts 'Run `bundle install` to install missing gems'
   exit e.status_code
 end
 require 'rake'
@@ -22,7 +22,7 @@ task :default => :test
 
 require 'rdoc/task'
 Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  version = File.exist?('VERSION') ? File.read('VERSION') : ''
 
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "pandoc-ruby #{version}"

data/lib/pandoc-ruby.rb

@@ -1,18 +1,10 @@
 require 'open3'
 require 'tempfile'
+require 'timeout'
 
 class PandocRuby
 
-  @@bin_path = nil
-  @@allow_file_paths = false
-
-  # The executable options. The `pandoc` executable is used by default.
-  EXECUTABLES = %W[
-    pandoc
-    markdown2pdf
-    html2markdown
-    hsmarkdown
-  ]
+  @@pandoc_path = 'pandoc'
 
   # The available readers and their corresponding names. The keys are used to
   # generate methods and specify options to Pandoc.
@@ -23,8 +15,8 @@ class PandocRuby
     'rst'      => 'reStructuredText',
     'textile'  => 'textile',
     'html'     => 'HTML',
-    'latex'    => 'LaTeX',
-  }
+    'latex'    => 'LaTeX'
+  }.freeze
 
   # The available string writers and their corresponding names. The keys are
   # used to generate methods and specify options to Pandoc.
@@ -51,7 +43,7 @@ class PandocRuby
     'rtf'           => 'rich text format',
     'org'           => 'emacs org mode',
     'asciidoc'      => 'asciidoc'
-  }
+  }.freeze
 
   # The available binary writers and their corresponding names. The keys are
   # used to generate methods and specify options to Pandoc.
@@ -60,22 +52,15 @@ class PandocRuby
     'docx'  => 'Word docx',
     'epub'  => 'EPUB V2',
     'epub3' => 'EPUB V3'
-  }
+  }.freeze
 
   # All of the available Writers.
   WRITERS = STRING_WRITERS.merge(BINARY_WRITERS)
 
-  # If the pandoc executables are not in the PATH, bin_path can be set to
-  # the directory they are contained in.
-  def self.bin_path=(path)
-    @@bin_path = path
-  end
-
-  # Pandoc can also be used with a file path as the first argument. For
-  # security reasons, this is disabled by default, but it can be enabled by
-  # setting this to `true`.
-  def self.allow_file_paths=(value)
-    @@allow_file_paths = value
+  # To use run the pandoc command with a custom executable path, the path
+  # to the pandoc executable can be set here.
+  def self.pandoc_path=(path)
+    @@pandoc_path = path
   end
 
   # A shortcut method that creates a new PandocRuby object and immediately
@@ -87,31 +72,40 @@ class PandocRuby
   end
 
   attr_accessor :options
-  def options; @options || [] end
+  def options
+    @options || []
+  end
 
   attr_accessor :option_string
-  def option_string; @option_string || '' end
+  def option_string
+    @option_string || ''
+  end
 
   attr_accessor :binary_output
-  def binary_output; @binary_output || false end
+  def binary_output
+    @binary_output || false
+  end
 
   attr_accessor :writer
-  def writer; @writer || 'html' end
+  def writer
+    @writer || 'html'
+  end
 
-  # Create a new PandocRuby converter object. The first argument should be
-  # the string that will be converted or, if `.allow_file_paths` has been set
-  # to `true`, this can also be a path to a file. The executable name can
-  # be used as the second argument, but will default to `pandoc` if the second
-  # argument is omitted or anything other than an executable name. Any other
-  # arguments will be converted to pandoc options.
+  # Create a new PandocRuby converter object. The first argument contains the
+  # input either as string or as an array of filenames.
+  #
+  # Any other arguments will be converted to pandoc options.
+  #
+  # Usage:
+  #   new("# A String", :option1 => :value, :option2)
+  #   new(["/path/to/file.md"], :option1 => :value, :option2)
+  #   new(["/to/file1.html", "/to/file2.html"], :option1 => :value)
   def initialize(*args)
-    target = args.shift
-    @target = if @@allow_file_paths && File.exists?(target)
-      File.read(target)
-    else
-      target rescue target
+    if args[0].is_a?(String)
+      @input_string = args.shift
+    elsif args[0].is_a?(Array)
+      @input_files = args.shift.join(' ')
     end
-    @executable = args.shift if EXECUTABLES.include?(args[0])
     self.options = args
   end
 
@@ -135,7 +129,7 @@ class PandocRuby
       convert_string
     end
   end
-  alias_method :to_s, :convert
+  alias to_s convert
 
   # Generate class methods for each of the readers in PandocRuby::READERS.
   # When one of these methods is called, it simply calls the initializer
@@ -144,11 +138,11 @@ class PandocRuby
   # Example:
   #
   #   PandocRuby.markdown("# text")
-  #   # => #<PandocRuby:0x007 @target="# text", @options=[{:from=>"markdown"}]
+  #   # => #<PandocRuby:0x007 @input_string="# text", @options=[{:from=>"markdown"}]
   class << self
     READERS.each_key do |r|
       define_method(r) do |*args|
-        args += [{:from => r}]
+        args += [{ :from => r }]
         new(*args)
       end
     end
@@ -165,107 +159,114 @@ class PandocRuby
   #   # => "<h1 id=\"text\">text</h1>\n"
   WRITERS.each_key do |w|
     define_method(:"to_#{w}") do |*args|
-      args += [{:to => w.to_sym}]
+      args += [{ :to => w.to_sym }]
       convert(*args)
     end
   end
 
-private
-
-  # Sets the executable, which by default is `pandoc`. The `@executable`
-  # variable can be set in the initializer, so testing for its presence first.
-  # Finally, checking to see if the bin_path was set and, if so, using that.
-  def executable
-    @executable ||= 'pandoc'
-    @@bin_path ? File.join(@@bin_path, @executable) : @executable
-  end
+  private
 
-  # Executes the pandoc command for binary writers. A temp file is created
-  # and written to, then read back into the program as a string, then the
-  # temp file is closed and unlinked.
-  def convert_binary
-    tmp_file = Tempfile.new('pandoc-conversion')
-    begin
-      self.options += [{:output => tmp_file.path}]
-      self.option_string =  "#{self.option_string} --output #{tmp_file.path}"
-      execute(command_with_options)
-      return IO.binread(tmp_file)
-    ensure
-      tmp_file.close
-      tmp_file.unlink
+    # Execute the pandoc command for binary writers. A temp file is created
+    # and written to, then read back into the program as a string, then the
+    # temp file is closed and unlinked.
+    def convert_binary
+      tmp_file = Tempfile.new('pandoc-conversion')
+      begin
+        self.options += [{ :output => tmp_file.path }]
+        self.option_string = "#{self.option_string} --output #{tmp_file.path}"
+        execute("#{@@pandoc_path}#{self.option_string}")
+        return IO.binread(tmp_file)
+      ensure
+        tmp_file.close
+        tmp_file.unlink
+      end
     end
-  end
 
-  # Executes the pandoc command for btring writers.
-  def convert_string
-    execute(command_with_options)
-  end
+    # Execute the pandoc command for string writers.
+    def convert_string
+      if ! @input_files.nil?
+        execute("#{@@pandoc_path} #{@input_files}#{self.option_string}")
+      else
+        execute("#{@@pandoc_path}#{self.option_string}")
+      end
+    end
 
-  # Combines the executable string with the option string.
-  def command_with_options
-    executable + self.option_string
-  end
+    # Run the command and returns the output.
+    def execute(command)
+      output = error = exit_status = nil
+      @timeout ||= 31_557_600 # A year should be enough?
+      Open3.popen3(command) do |stdin, stdout, stderr, wait_thr|
+        begin
+          Timeout.timeout(@timeout) do
+            unless @input_string.nil?
+              stdin.puts @input_string
+              stdin.close
+            end
+            output = stdout.read
+            error = stderr.read
+            exit_status = wait_thr.value
+          end
+        rescue Timeout::Error => ex
+          Process.kill 9, wait_thr.pid
+          maybe_ex = "\n#{ex}" if ex
+          error = "Pandoc timed out after #{@timeout} seconds.#{maybe_ex}"
+        end
+      end
 
-  # Runs the command and returns the output.
-  def execute(command)
-    output = error = exit_status = nil
-    Open3::popen3(command) do |stdin, stdout, stderr, wait_thr|
-      stdin.puts @target
-      stdin.close
-      output = stdout.read
-      error = stderr.read
-      exit_status = wait_thr.value
+      raise error unless exit_status && exit_status.success?
+      output
     end
-    raise error unless exit_status.success?
-    output
-  end
 
-  # Builds the option string to be passed to pandoc by iterating over the
-  # opts passed in. Recursively calls itself in order to handle hash options.
-  def prepare_options(opts = [])
-    opts.inject('') do |string, (option, value)|
-      string += case
-                when value
-                  create_option(option, value)
-                when option.respond_to?(:each_pair)
-                  prepare_options(option)
-                else
-                  create_option(option)
-                end
+    # Builds the option string to be passed to pandoc by iterating over the
+    # opts passed in. Recursively calls itself in order to handle hash options.
+    def prepare_options(opts = [])
+      opts.inject('') do |string, (option, value)|
+        string += case
+                  when value
+                    create_option(option, value)
+                  when option.respond_to?(:each_pair)
+                    prepare_options(option)
+                  else
+                    create_option(option)
+                  end
+      end
     end
-  end
 
-  # Takes a flag and optional argument, uses it to set any relevant options
-  # used by the library, and returns string with the option formatted as a
-  # command line options. If the option has an argument, it is also included.
-  def create_option(flag, argument = nil)
-    return if !flag
-    flag = flag.to_s
-    set_pandoc_ruby_options(flag, argument)
-    if !!argument
-      "#{format_flag(flag)} #{argument}"
-    else
-      format_flag(flag)
+    # Takes a flag and optional argument, uses it to set any relevant options
+    # used by the library, and returns string with the option formatted as a
+    # command line options. If the option has an argument, it is also included.
+    def create_option(flag, argument = nil)
+      return '' unless flag
+      flag = flag.to_s
+      set_pandoc_ruby_options(flag, argument)
+      return '' if flag == 'timeout' # pandoc doesn't accept timeouts yet
+      if !argument.nil?
+        "#{format_flag(flag)} #{argument}"
+      else
+        format_flag(flag)
+      end
     end
-  end
 
-  # Formats an option flag in order to be used with the pandoc command line
-  # tool.
-  def format_flag(flag)
-    if flag.length == 1
-      " -#{flag}"
-    else
-      " --#{flag.to_s.gsub(/_/, '-')}"
+    # Formats an option flag in order to be used with the pandoc command line
+    # tool.
+    def format_flag(flag)
+      if flag.length == 1
+        " -#{flag}"
+      else
+        " --#{flag.to_s.tr('_', '-')}"
+      end
     end
-  end
 
-  # Takes an option and optional argument and uses them to set any flags
-  # used by PandocRuby.
-  def set_pandoc_ruby_options(flag, argument = nil)
-    if flag == 't' || flag == 'to'
-      self.writer = argument.to_s
-      self.binary_output = true if BINARY_WRITERS.keys.include?(self.writer)
+    # Takes an option and optional argument and uses them to set any flags
+    # used by PandocRuby.
+    def set_pandoc_ruby_options(flag, argument = nil)
+      case flag
+      when 't', 'to'
+        self.writer = argument.to_s
+        self.binary_output = true if BINARY_WRITERS.keys.include?(self.writer)
+      when 'timeout'
+        @timeout = argument
+      end
     end
-  end
 
 end