pandoc-ruby 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ad0727403c2a9e84af99ce2e676e1975fa044456
-  data.tar.gz: 3a8b9eea46119c7da84b8053119a346e4c45714c
+  metadata.gz: 17b3f81bb4b27fe9caf0f61c14043084c0f02776
+  data.tar.gz: aa1251098ed96b13d1690f17055f230aa50bbc29
 SHA512:
-  metadata.gz: 285b9a4c740eb15bb97986973d8e6dd96789764d448775ee905c2ef322eb5d1d4750d1f1977272150ce5f8072c0ce1d3ff61ea419622784904a14b02ff07566d
-  data.tar.gz: ae7fdb8048811b0924aa012dc16d1646e1ede48f4086afabe4cc529b723cef273c6decdbcef8ff3ce1c52e02796c5915060946cd1138d6df1042414e9f73a48e
+  metadata.gz: 9dbf61c66d2e5e4f2bf6c7f16d587b36f99d90fea3c7a3d4d5ea84aac57b2b54da11066edd88f159a71f28c00d3827fa8a6a3e21105ac876c0688bb1ada53bae
+  data.tar.gz: 7dc6c106893b19897971b80a217d3ca4fe8f897ef5e627d4ee52d65b1e7cc07c332c60c83dabc4ab5fb4fe8bed2a4142a3445fb25cb2f222e9ed2199820204b7

data/README.markdown

@@ -67,7 +67,7 @@ If you'd prefer a pure-Ruby extended markdown interpreter that can output a few
 
 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).
 
-## Pandoc Hint
+## Pandoc Tip
 
 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.
 

data/lib/pandoc-ruby.rb

@@ -2,9 +2,11 @@ require 'open3'
 require 'tempfile'
 
 class PandocRuby
+
   @@bin_path = nil
   @@allow_file_paths = false
   
+  # The executable options. The `pandoc` executable is used by default.
   EXECUTABLES = %W[
     pandoc
     markdown2pdf
@@ -12,6 +14,8 @@ class PandocRuby
     hsmarkdown
   ]
   
+  # The available readers and their corresponding names. The keys are used to
+  # generate methods and specify options to Pandoc.
   READERS = {
     'native'   => 'pandoc native',
     'json'     => 'pandoc JSON',
@@ -22,7 +26,9 @@ class PandocRuby
     'latex'    => 'LaTeX',
   }
 
-  WRITERS = {
+  # The available string writers and their corresponding names. The keys are
+  # used to generate methods and specify options to Pandoc.
+  STRING_WRITERS = {
     'native'        => 'pandoc native',
     'json'          => 'pandoc JSON',
     'html'          => 'HTML',
@@ -47,25 +53,57 @@ class PandocRuby
     'asciidoc'      => 'asciidoc'
   }
 
+  # The available binary writers and their corresponding names. The keys are
+  # used to generate methods and specify options to Pandoc.
   BINARY_WRITERS = {
     'odt'   => 'OpenDocument',
     'docx'  => 'Word docx',
     'epub'  => 'EPUB V2',
     'epub3' => 'EPUB V3'
   }
+
+  # 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
   end
-  
+
+  # A shortcut method that creates a new PandocRuby object and immediately
+  # calls `#convert`. Options passed to this method are passed directly to
+  # `#new` and treated the same as if they were passed directly to the
+  # initializer.
   def self.convert(*args)
     new(*args).convert
   end
 
+  attr_accessor :options
+  def options; @options || [] end
+  
+  attr_accessor :option_string
+  def options_string; @option_string || '' end
+
+  attr_accessor :binary_output
+  def binary_output; @binary_output || false end
+  
+  attr_accessor :writer
+  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.
   def initialize(*args)
     target = args.shift
     @target = if @@allow_file_paths && File.exists?(target)
@@ -73,31 +111,40 @@ class PandocRuby
     else
       target rescue target
     end
-    @executable = EXECUTABLES.include?(args[0]) ? args.shift : 'pandoc'
-    @options = args
-  end
-
-  def convert_binary(executable, *args)
-    tmp_file = Tempfile.new('pandoc-conversion')
-    begin
-      args += [{:output => tmp_file.path}]
-      execute executable + convert_options(args)
-      return IO.binread(tmp_file)
-    ensure
-      tmp_file.unlink
-    end
+    @executable = args.shift if EXECUTABLES.include?(args[0])
+    self.options = args
   end
 
+  # Run the conversion. The convert method can take any number of arguments,
+  # which will be converted to pandoc options. If options were already
+  # specified in an initializer or reader method, they will be combined with
+  # any that are passed to this method.
+  #
+  # Returns a string with the converted content.
+  #
+  # Example:
+  #
+  #   PandocRuby.new("# text").convert
+  #   # => "<h1 id=\"text\">text</h1>\n"
   def convert(*args)
-    executable = @@bin_path ? File.join(@@bin_path, @executable) : @executable
-    if will_output_binary?(args)
-      convert_binary(executable, *args)
+    self.options += args if args
+    self.option_string = prepare_options(self.options)
+    if self.binary_output
+      convert_binary
     else
-      execute executable + convert_options(args)
+      convert_string
     end
   end
   alias_method :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
+  # with the `from` option set to the reader key, and returns the object.
+  #
+  # Example:
+  # 
+  #   PandocRuby.markdown("# text")
+  #   # => #<PandocRuby:0x007 @target="# text", @options=[{:from=>"markdown"}]
   class << self
     READERS.each_key do |r|
       define_method(r) do |*args|
@@ -107,7 +154,15 @@ class PandocRuby
     end
   end
   
-  WRITERS.merge(BINARY_WRITERS).each_key do |w|
+  # Generate instance methods for each of the writers in PandocRuby::WRITERS.
+  # When one of these methods is called, it simply calls the `#convert` method
+  # with the `to` option set to the writer key, thereby returning the
+  # converted string.
+  #
+  # Example:
+  #   PandocRuby.new("# text").to_html
+  #   # => "<h1 id=\"text\">text</h1>\n"
+  WRITERS.each_key do |w|
     define_method(:"to_#{w}") do |*args|
       args += [{:to => w.to_sym}]
       convert(*args)
@@ -116,6 +171,41 @@ class PandocRuby
   
 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
+
+  # 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
+    begin
+      tmp_file = Tempfile.new('pandoc-conversion')
+      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
+    end
+  end
+
+  # Executes the pandoc command for btring writers.
+  def convert_string
+    execute(command_with_options)
+  end
+
+  # Combines the executable string with the option string.
+  def command_with_options
+    executable + self.option_string
+  end
+
+  # Runs the command and returns the output.
   def execute(command)
     output = ''
     Open3::popen3(command) do |stdin, stdout, stderr| 
@@ -126,34 +216,52 @@ private
     output
   end
 
-  def convert_options(opts = [])
-    (@options + opts).flatten.inject('') do |string, opt|
-      string + if opt.respond_to?(:each_pair)
-        convert_opts_with_args(opt)
-      else
-        opt.to_s.length == 1 ? " -#{opt}" : " --#{opt.to_s.gsub(/_/, '-')}"
-      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 != nil
+                  create_option(option, value)
+                when option.respond_to?(:each_pair)
+                  prepare_options(option)
+                else
+                  create_option(option)
+                end
     end
   end
-  
-  def convert_opts_with_args(opt)
-    opt.inject('') do |string, (flag, val)|
-      flag = flag.to_s.gsub(/_/, '-')
-      string + (flag.length == 1 ? " -#{flag} #{val}" : " --#{flag}=#{val}")
+
+  # 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
+    set_pandoc_ruby_options(flag, argument)
+    if !!argument
+      "#{option_flag(flag)} #{argument}"
+    else
+      option_flag(flag)
     end
   end
 
-  def will_output_binary?(opts = [])
-    (@options+opts).flatten.each do |opt|
-      if opt.respond_to?(:each_pair)
-        opt.each_pair do |opt_key, opt_value|
-          if opt_key == :to && BINARY_WRITERS.keys.include?(opt_value.to_s)
-            return true
-          end 
-        end
-      end
+  # Formats an option flag in order to be used with the pandoc command line
+  # tool.
+  def option_flag(flag)
+    if flag.length == 1
+      " -#{flag}"
+    else
+      " --#{flag.to_s.gsub(/_/, '-')}"
+    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)
+    case flag.to_sym
+    when :t, :to
+      self.writer = argument.to_s
+      self.binary_output = true if BINARY_WRITERS.keys.include?(self.writer)
     end
-    false
   end
 
 end

data/pandoc-ruby.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "pandoc-ruby"
-  s.version = "0.7.1"
+  s.version = "0.7.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["William Melody"]
-  s.date = "2013-05-19"
+  s.date = "2013-06-21"
   s.description = "Ruby wrapper for Pandoc"
   s.email = "hi@williammelody.com"
   s.extra_rdoc_files = [

data/test/test_pandoc-ruby.rb

@@ -43,7 +43,7 @@ class TestPandocRuby < Test::Unit::TestCase
   
   should "accept long options" do
     converter = PandocRuby.new(@file, :to => :rst)
-    converter.expects(:execute).with('pandoc --to=rst').returns(true)
+    converter.expects(:execute).with('pandoc --to rst').returns(true)
     assert converter.convert
   end
   
@@ -53,7 +53,7 @@ class TestPandocRuby < Test::Unit::TestCase
     }, 'no-wrap')
     converter \
       .expects(:execute) \
-      .with('pandoc -s -f markdown --to=rst --no-wrap') \
+      .with('pandoc -s -f markdown --to rst --no-wrap') \
       .returns(true)
     assert converter.convert
   end
@@ -62,7 +62,7 @@ class TestPandocRuby < Test::Unit::TestCase
     converter = PandocRuby.new(@file)
     converter \
       .expects(:execute) \
-      .with('pandoc -s -f markdown --to=rst --no-wrap') \
+      .with('pandoc -s -f markdown --to rst --no-wrap') \
       .returns(true)
     assert converter.convert(:s, {:f => :markdown, :to => :rst}, 'no-wrap')
   end
@@ -73,7 +73,7 @@ class TestPandocRuby < Test::Unit::TestCase
     }, :table_of_contents)
     converter \
       .expects(:execute) \
-      .with('pandoc --email-obfuscation=javascript --table-of-contents') \
+      .with('pandoc --email-obfuscation javascript --table-of-contents') \
       .returns(true)
     assert converter.convert
   end
@@ -93,17 +93,17 @@ class TestPandocRuby < Test::Unit::TestCase
   PandocRuby::READERS.each_key do |r|
     should "convert from #{r} with PandocRuby.#{r}" do
       converter = PandocRuby.send(r, @file)
-      converter.expects(:execute).with("pandoc --from=#{r}").returns(true)
+      converter.expects(:execute).with("pandoc --from #{r}").returns(true)
       assert converter.convert
     end
   end
   
-  PandocRuby::WRITERS.each_key do |w|
+  PandocRuby::STRING_WRITERS.each_key do |w|
     should "convert to #{w} with to_#{w}" do
       converter = PandocRuby.new(@file)
       converter \
         .expects(:execute) \
-        .with("pandoc --no-wrap --to=#{w}") \
+        .with("pandoc --no-wrap --to #{w}") \
         .returns(true)
       assert converter.send("to_#{w}", :no_wrap)
     end
@@ -114,7 +114,7 @@ class TestPandocRuby < Test::Unit::TestCase
       converter = PandocRuby.new(@file)
       converter \
         .expects(:execute) \
-        .with(regexp_matches(/^pandoc --no-wrap --to=#{w} --output=/)) \
+        .with(regexp_matches(/^pandoc --no-wrap --to #{w} --output /)) \
         .returns(true)
       assert converter.send("to_#{w}", :no_wrap)
     end
@@ -155,7 +155,7 @@ class TestPandocRuby < Test::Unit::TestCase
       "rst"       =>  "reStructuredText"
     }
     
-    assert_equal PandocRuby::WRITERS, {
+    assert_equal PandocRuby::STRING_WRITERS, {
       "mediawiki"     =>  "MediaWiki markup",
       "html"          =>  "HTML",
       "plain"         =>  "plain",
@@ -187,5 +187,8 @@ class TestPandocRuby < Test::Unit::TestCase
       "epub3" => "EPUB V3"
     }
 
+    assert_equal PandocRuby::WRITERS, (
+      PandocRuby::STRING_WRITERS.merge(PandocRuby::BINARY_WRITERS)
+    )
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pandoc-ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.2
 platform: ruby
 authors:
 - William Melody
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-19 00:00:00.000000000 Z
+date: 2013-06-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mocha