paru 0.2.4.2 → 0.2.4.3

data/lib/paru/filter/str.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,26 +17,37 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./inline"
+    module PandocFilter
+        require_relative "./inline"
 
-    # Str String
-    class Str < Inline
-      def initialize value
-        @string = value
-      end
+        # A Str node represents a string
+        class Str < Inline
 
-      def ast_contents
-        @string
-      end
+            # Create a new Str node based on the value
+            #
+            # @param value [String]
+            def initialize(value)
+                @string = value
+            end
 
-      def has_string?
-        true
-      end
+            # The AST contents
+            def ast_contents()
+                @string
+            end
 
-      def has_inline?
-        false
-      end
+            # Has the Str node a string value? Of course!
+            #
+            # @return [Boolean] true
+            def has_string?()
+                true
+            end
+
+            # Has the Str node inline contents? 
+            #
+            # @return [Boolean] false
+            def has_inline?()
+                false
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/strikeout.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,12 +17,12 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./inline"
+    module PandocFilter
+        require_relative "./inline"
 
-    # Strikeout [Inline]
-    class Strikeout < Inline
+        # A Strikeout inline node
+        class Strikeout < Inline
+        end
     end
-  end
 end
 

data/lib/paru/filter/strong.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,12 +17,12 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./inline"
+    module PandocFilter
+        require_relative "./inline"
 
-    # Strong [Inline]
-    class Strong < Inline
+        # A Strong inline node
+        class Strong < Inline
+        end
     end
-  end
 end
 

data/lib/paru/filter/subscript.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,12 +17,12 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./inline"
+    module PandocFilter
+        require_relative "./inline"
 
-    # Subscript [Inline]
-    class Subscript < Inline
+        # A Subscript inline node
+        class Subscript < Inline
+        end
     end
-  end
 end
 

data/lib/paru/filter/superscript.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,12 +17,12 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./inline"
+    module PandocFilter
+        require_relative "./inline"
 
-    # Superscript [Inline]
-    class Superscript < Inline
+        # A Superscript inline node
+        class Superscript < Inline
+        end
     end
-  end
 end
 

data/lib/paru/filter/table.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,37 +17,59 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
-    require_relative "./inline"
-    require_relative "./alignment"
+    module PandocFilter
+        require_relative "./block"
+        require_relative "./inline"
+    
+        # The allignment of a table column
+        ALIGNMENTS = ["AlignLeft", "AlignRight", "AlignCenter", "AlignDefault"]
 
-    ALIGNMENTS = ["AlignLeft", "AlignRight", "AlignCenter", "AlignDefault"]
+        # A Table node represents a table with an inline caption, column
+        # definition, widths, headers, and rows.
+        #
+        # @!attribute caption
+        #   @return [Inline]
+        #
+        # @!attribute alignment
+        #   @return [ALIGNMENTS]
+        #
+        # @!attribute column_widths
+        #   @return [Float]
+        #
+        # @!attribute headers
+        #   @return [TableRow]
+        #
+        # @!attribute rows
+        #   @return [Array<TableRow>]
+        class Table < Block
+            attr_accessor :caption, :alignment, :column_widths, :headers, :rows
 
-    # Table [Inline] [Alignment] [Double] [TableCell] [[TableCell]]
-    class Table < Block
-      attr_accessor :caption, :alignment, :column_widths, :headers, :rows
+            # Create a new Table based on the contents
+            #
+            # @param contents [Array]
+            def initialize(contents)
+                @caption = Inline.new contents[0]
+                @alignment = contents[1]
+                @column_widths = contents[2]
+                @headers = TableRow.new contents[3]
+                @rows = []
+                contents[4].each do |row_data|
+                    @rows.push TableRow.new row_data
+                end
+            end
 
-      def initialize contents
-        @caption = Inline.new contents[0]
-        @alignment = contents[1]
-        @column_widths = contents[2]
-        @headers = TableRow.new contents[3]
-        @rows = []
-        contents[4].each do |row_data|
-          @rows.push TableRow.new row_data
+            # The AST contents of this Table node
+            #
+            # @return [Array]
+            def ast_contents()
+                [
+                    @caption.ast_contents,
+                    @alignment,
+                    @column_widths,
+                    @headers.ast_contents,
+                    @rows.map {|row| row.ast_contents}
+                ]
+            end
         end
-      end
-
-      def ast_contents
-        [
-          @caption.ast_contents,
-          @alignment,
-          @column_widths,
-          @headers.ast_contents,
-          @rows.map {|row| row.ast_contents}
-        ]
-      end
     end
-  end
 end

data/lib/paru/filter/table_row.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,20 +17,27 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
+    module PandocFilter
+        require_relative "./block"
 
-    class TableRow < Block
-      def initialize row_data
-        super []
-        row_data.each do |cell|
-          @children.push Block.new cell
-        end
-      end
+        # A TableRow node represents a row in a table's head or body
+        class TableRow < Block
+            # Create a new TableRow based on the row_data
+            #
+            # @param row_data [Array]
+            def initialize(row_data)
+                super []
+                row_data.each do |cell|
+                    @children.push Block.new cell
+                end
+            end
 
-      def ast_contents
-        @children.map {|child| child.ast_contents}
-      end
+            # The AST contents of this TableRow
+            #
+            # @return [Array]
+            def ast_contents
+                @children.map {|child| child.ast_contents}
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/target.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,21 +17,35 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
+    module PandocFilter
+    
+        # A Target represents the target of a link or image
+        #
+        # @!attribute url
+        #   @return [String] the target
+        #
+        # @!attribute title
+        #   @return [String] the title of the target
+        class Target
+            attr_accessor :url, :title
 
-    class Target
-      attr_accessor :url, :title
-      def initialize contents
-        @url = contents[0]
-        @title = contents[1]
-      end
+            # Create a new Target based on the contents
+            #
+            # @param contents [Array]
+            def initialize(contents)
+                @url = contents[0]
+                @title = contents[1]
+            end
 
-      def to_ast
-        [
-          @url,
-          @title
-        ]
-      end
+            # Create an AST representation of this Target
+            #
+            # @return [Array]
+            def to_ast()
+                [
+                    @url,
+                    @title
+                ]
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/version.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,21 +17,30 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./node"
+    module PandocFilter
+        require_relative "./node"
 
-    class Version < Node
-      def initialize contents
-        @major, @minor, @revision = contents
-      end
+        # Version is a general Node containing the pandoc-api-version. It has
+        # the format major.minor.revision.sub
+        class Version < Node
 
-      def ast_type
-        "pandoc-api-version"
-      end        
+            # Create a Version node based on contents
+            #
+            # @param contents [Array<Integer>] a list with api, major, minor,
+            # revision number
+            def initialize(contents)
+                @api, @major, @minor, @revision = contents
+            end
 
-      def to_ast
-        [@major, @minor, @revision]
-      end
+            # The AST type is "pandoc-api-version"
+            def ast_type
+                "pandoc-api-version"
+            end        
+
+            # Create an AST representation of this Version
+            def to_ast()
+                [@api, @major, @minor, @revision]
+            end
+        end
     end
-  end
 end

data/lib/paru/pandoc.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -18,134 +18,188 @@
 #++
 module Paru
 
-  require "yaml"
-
-  # Pandoc is a wrapper around the pandoc system. See
-  # <http://pandoc.org/README.html> for details about pandoc.  This file is
-  # basically a straightforward translation from command line program to ruby
-  # class
-
-  class Pandoc
-
-    # Gather information about pandoc. It runs `pandoc --version` and extracts
-    # pandoc's version number and default data directory.
-    def self.info
-      output = ''
-      IO.popen('pandoc --version', 'r+') do |p|
-        p.close_write
-        output << p.read
-      end
-      version = output.match(/pandoc (\d+\.\d+.*)$/)[1]
-      data_dir = output.match(/Default user data directory: (.+)$/)[1]
-
-      {
-        :version => version,
-        :data_dir => data_dir
-      }
-    end
+    require "shellwords"
+    require "yaml"
 
-    def initialize &block 
-      @options = {}
-      configure(&block) if block_given?
-    end
+    # Pandoc is a wrapper around the pandoc document converter. See
+    # <http://pandoc.org/README.html> for details about pandoc.  This file is
+    # basically a straightforward translation from the pandoc command line
+    # program to a ruby class, giving a Rubyesque API to work with pandoc.
+    #
+    # @example Convert the markdown string 'hello *world*' to HTML
+    #     converter = Paru::Pandoc.new
+    #     converter.configure do
+    #         from "markdown"
+    #         to "html"
+    #     end
+    #     converter.convert 'hello *world*'
+    #
+    # @example Convert markdown to HTML, written in a more commonly used shorthand
+    #     Paru::Pandoc.new do
+    #         from markdown
+    #         to html
+    #     end << 'hello *world*'
+    #
+    #
+    class Pandoc
+
+        # Gather information about pandoc. It runs `pandoc --version` and extracts
+        # pandoc's version number and default data directory.
+        #
+        # @return [Hash] Return a Hash with the :verion and :data_dir of the
+        #   pandoc installation
+        def self.info()
+            output = ''
+            IO.popen('pandoc --version', 'r+') do |p|
+                p.close_write
+                output << p.read
+            end
+            version = output.match(/pandoc (\d+\.\d+.*)$/)[1]
+            data_dir = output.match(/Default user data directory: (.+)$/)[1]
+
+            {
+                :version => version,
+                :data_dir => data_dir
+            }
+        end
 
-    def configure &block
-      instance_eval(&block)
-      self
-    end
+        # Create a new Pandoc converter, optionally configured by block
+        #
+        # @param block [Proc] an optional configuration block. See #configure
+        #   for how to configure a Pandoc converter
+        def initialize(&block)
+            @options = {}
+            configure(&block) if block_given?
+        end
 
-    # Converts input string to output string using the pandoc invocation
-    # configures in this Pandoc instance.
-    def convert input
-      output = ""
-      IO.popen(to_command, "r+") do |p|
-        p << input
-        p.close_write
-        output << p.read
-      end
-      output
-    end
-    alias << convert
+        # Configure this Pandoc converter with block. In the block you can
+        # call all pandoc options as methods on this converter. In multi-word
+        # options the dash (-) is replaced by an underscore (_)
+        #
+        # Pandoc has a number of command line options. Most are simple options,
+        # like flags, that can be set only once. Other options can occur more than
+        # once, such as the css option: to add more than one css file to a
+        # generated standalone html file, use the css options once for each
+        # stylesheet to include. Other options do have the pattern key[:value],
+        # which can also occur multiple times, such as metadata. 
+        #
+        # All options are specified in a pandoc_options.yaml. If it is an option
+        # that can occur only once, the value of the option in that yaml file is
+        # its default value. If the option can occur multiple times, its value is
+        # an array with one value, the default value.
+        #
+        # @param block [Proc] the options to pandoc
+        # @return [Pandoc] this Pandoc converter
+        #
+        # @example Configure converting HTML to LaTeX with a LaTeX engine
+        #   converter.configure do
+        #       from 'html'
+        #       to 'latex'
+        #       latex_engine 'lualatex'
+        #   end
+        #
+        def configure(&block)
+            instance_eval(&block)
+            self
+        end
 
-    def to_command option_sep = " \\\n\t"
-      "pandoc\t#{to_option_string option_sep}"
-    end
+        # Converts input string to output string using the pandoc invocation
+        # configured in this Pandoc instance.
+        #
+        # @param input [String] the input string to convert
+        # @return [String] the converted output string
+        #
+        # The following two examples are the same:
+        #
+        # @example Using convert
+        #   output = converter.convert 'this is a *strong* word'
+        #
+        # @example Using <<
+        #   output = converter << 'this is a *strong* word'
+        def convert(input)
+            output = ''
+            IO.popen(to_command, 'r+') do |p|
+                p << input
+                p.close_write
+                output << p.read
+            end
+            output
+        end
+        alias << convert
+
+        # Create a string representation of this converter's pandoc command
+        # line invocation. This is useful for debugging purposes.
+        #
+        # @param option_sep [String] the string to separate options with
+        # @return [String] This converter's command line invocation string.
+        def to_command(option_sep = " \\\n\t")
+            "pandoc\t#{to_option_string option_sep}"
+        end
 
-    def to_option_string option_sep
-      options_arr = []
-      @options.each do |option, value|
-        option_string = "--#{option.to_s.gsub "_", "-"}"
-
-        case value
-        when TrueClass then
-          # Flags don"t have a value, only its name
-          # For example: --standalone
-          options_arr.push "#{option_string}"
-        when FalseClass then
-          # Skip this option; consider a flag with value false as unset
-        when Array then
-          # This option can occur multiple times: list each with its value.
-          # For example: --css=main.css --css=print.css
-          options_arr.push value.map {|val| "#{option_string}=#{val.to_s}"}.join(option_sep)
-        else
-          # All options that aren"t flags and can occur only once have the
-          # same pattern: --option=value
-          options_arr.push "#{option_string}=#{value.to_s}"
+        private
+        
+        def to_option_string(option_sep)
+            options_arr = []
+            @options.each do |option, value|
+                option_string = "--#{option.to_s.gsub '_', '-'}"
+
+                case value
+                when TrueClass then
+                    # Flags don't have a value, only its name
+                    # For example: --standalone
+                    options_arr.push "#{option_string}"
+                when FalseClass then
+                    # Skip this option; consider a flag with value false as unset
+                when Array then
+                    # This option can occur multiple times: list each with its value.
+                    # For example: --css=main.css --css=print.css
+                    options_arr.push value.map {|val| "#{option_string}=#{val.to_s.shellescape}"}.join(option_sep)
+                else
+                    # All options that aren't flags and can occur only once have the
+                    # same pattern: --option=value
+                    options_arr.push "#{option_string}=#{value.to_s.shellescape}"
+                end
+            end
+            options_arr.join(option_sep)
         end
-      end
-      options_arr.join(option_sep)
-    end
 
-    # Pandoc has a number of command line options. Most are simple options,
-    # like flags, that can be set only once. Other options can occur more than
-    # once, such as the css option: to add more than one css file to a
-    # generated standalone html file, use the css options once for each
-    # stylesheet to include. Other options do have the pattern key[:value],
-    # which can also occur multiple times, such as metadata. 
-    #
-    # All options are specified in a pandoc_options.yaml. If it is an option
-    # that can occur only once, the value of the option in that yaml file is
-    # its default value. If the option can occur multiple times, its value is
-    # an array with one value, the default value.
-    #
-    # For each of these options a method is defined as follows:
-    OPTIONS = YAML.load_file File.join(__dir__, "pandoc_options.yaml")
+        # For each pandoc command line option a method is defined as follows:
+        OPTIONS = YAML.load_file File.join(__dir__, 'pandoc_options.yaml')
 
-    OPTIONS.keys.each do |option|
-      if OPTIONS[option].is_a? Array then
+        OPTIONS.keys.each do |option|
+            if OPTIONS[option].is_a? Array then
 
-        # option can be set multiple times, for example adding multiple css
-        # files
+                # option can be set multiple times, for example adding multiple css
+                # files
 
-        default = OPTIONS[option][0]
+                default = OPTIONS[option][0]
 
-        define_method(option) do |value = default|
-          if @options[option].nil? then
-            @options[option] = []
-          end
+                define_method(option) do |value = default|
+                    if @options[option].nil? then
+                        @options[option] = []
+                    end
 
-          if value.is_a? Array then
-              @options[option] += value
-          else
-              @options[option].push value
-          end
+                    if value.is_a? Array then
+                        @options[option] += value
+                    else
+                        @options[option].push value
+                    end
 
-          self
-        end
+                    self
+                end
 
-      else
+            else
+                # option can be set only once, for example a flag or a template
 
-        # option can be set only once, for example a flag or a template
+                default = OPTIONS[option]
+                define_method(option) do |value = default|
+                    @options[option] = value
+                    self
+                end
 
-        default = OPTIONS[option]
-        define_method(option) do |value = default|
-        @options[option] = value
-        self
+            end
         end
 
-      end
     end
 
-  end
-
 end