paru 0.2.4.2 → 0.2.4.3

data/lib/paru/filter/image.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,17 +17,19 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
+    module PandocFilter
 
-    require_relative "./link"
+        require_relative "./link"
 
-    # Image Attr [Inline] Target
-    class Image < Link
-      # Although Image is defined to be inline, probably because in HTML it
-      # can be an inline element, often it acts like a block element.
-      def can_act_as_both_block_and_inline?
-        true
-      end
+        # An Image has an attribute object, a caption, and a target
+        class Image < Link
+
+            # Although Image is defined to be inline, probably because in HTML it
+            # can be an inline element, often it acts like a block element.
+            # @return [Boolean] true 
+            def can_act_as_both_block_and_inline?
+                true
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/inline.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
 #
@@ -20,18 +20,29 @@ module Paru
     module PandocFilter
         require_relative "./node"
 
+        # An Inline node
+        # @see http://hackage.haskell.org/package/pandoc-types-1.17.0.4/docs/Text-Pandoc-Definition.html#t:Inline
         class Inline < Node
-           def initialize contents
-              super contents, true
-           end 
 
-           def is_inline?
-               true
-           end
+            # Create a new Inline node with contents
+            # @param contents [Array] the contents of this inline node
+            def initialize(contents)
+                super contents, true
+            end 
 
-           def has_inline?
-               true
-           end
+            # Is this Inline node inline? Of course!
+            #
+            # @return [Boolean] true
+            def is_inline?()
+                true
+            end
+
+            # Has this Inline node inline contents? Of course!
+            #
+            # @return [Boolean] true
+            def has_inline?()
+                true
+            end
         end
     end
 end

data/lib/paru/filter/line_block.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,11 +17,11 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #--
 module Paru
-  module PandocFilter
-    require_relative "./list.rb"
+    module PandocFilter
+        require_relative "./list.rb"
 
-    # LineBlock [[Inline]]
-    class LineBlock < List
+        # A LineBlock is a List of Lists of Inline nodes
+        class LineBlock < List
+        end
     end
-  end
 end

data/lib/paru/filter/line_break.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,11 +17,11 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./empty_inline"
+    module PandocFilter
+        require_relative "./empty_inline"
 
-    # LineBreak
-    class LineBreak < EmptyInline
+        # A LineBreak is an empty inline element
+        class LineBreak < EmptyInline
+        end
     end
-  end
 end

data/lib/paru/filter/link.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,30 +17,42 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
+    module PandocFilter
 
-    require_relative "./inline"
-    require_relative "./attr"
-    require_relative "./target"
+        require_relative "./inline"
+        require_relative "./attr"
+        require_relative "./target"
 
-    # Link Attr [Inline] Target
-    class Link < Inline
-      attr_accessor :attr, :target
+        # A Link node has an attribute object, an Inline description and a
+        # target
+        #
+        # @!attribute attr
+        #   @return [Attr]
+        #
+        # @!attribute targer
+        #   @return [Target]
+        class Link < Inline
+            attr_accessor :attr, :target
 
-      def initialize contents
-        @attr = Attr.new contents[0]
-        super contents[1]
-        @target = Target.new contents[2]
-      end
+            # Create a new Link node with contents
+            #
+            # @param contents [Array] an array with attributes, description,
+            #   and target information
+            def initialize(contents)
+                @attr = Attr.new contents[0]
+                super contents[1]
+                @target = Target.new contents[2]
+            end
 
-      def ast_contents
-        [
-          @attr.to_ast,
-          super,
-          @target.to_ast
-        ]
-      end
+            # Create an AST representation of this Link node
+            def ast_contents
+                [
+                    @attr.to_ast,
+                    super,
+                    @target.to_ast
+                ]
+            end
 
+        end
     end
-  end
 end

data/lib/paru/filter/list.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,24 +17,33 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
+    module PandocFilter
+        require_relative "./block"
 
-    class List < Block
-      def initialize contents
-        super []
-        contents.each do |item|
-          @children.push Block.new item
-        end
-      end
+        # A List node is a base node for various List node types
+        class List < Block
+
+            # Create a new List node based on contents
+            #
+            # @param contents [Array] the contents of the list
+            def initialize contents
+                super []
+                contents.each do |item|
+                    @children.push Block.new item
+                end
+            end
 
-      def ast_contents
-        @children.map {|child| child.ast_contents}
-      end
+            # Create an AST representation of this List node
+            def ast_contents
+                @children.map {|child| child.ast_contents}
+            end
 
-      def has_block?
-        true
-      end
+            # Has this List node block contents?
+            #
+            # @return [Boolean] true
+            def has_block?
+                true
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/list_attributes.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,39 +17,60 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    class ListAttributes
+    module PandocFilter
+        # ListAttributes represent the attributes of a list.
+        #
+        # @see http://hackage.haskell.org/package/pandoc-types-1.17.0.4/docs/Text-Pandoc-Definition.html#t:ListAttributes
+        #
+        # @!attribute start
+        #   @return [Integer]
+        #
+        # @!attribute number_style
+        #   @return [STYLES]
+        #
+        # @!attribute number_delim
+        #   @return [DELIMS]
+        class ListAttributes
+            
+            # The various styles of list numbers
+            STYLES = [
+                "DefaultStyle", 
+                "Example", 
+                "Decimal", 
+                "LowerRoman", 
+                "UpperRoman", 
+                "LowerAlpha", 
+                "UpperAlpha"
+            ]
 
-      STYLES = [
-        "DefaultStyle", 
-        "Example", 
-        "Decimal", 
-        "LowerRoman", 
-        "UpperRoman", 
-        "LowerAlpha", 
-        "UpperAlpha"
-      ]
-      DELIMS = [
-        "DefaultDelim", 
-        "Period", 
-        "OneParen", 
-        "TwoParens"
-      ]
+            # The various delimeters of list numbers
+            DELIMS = [
+                "DefaultDelim", 
+                "Period", 
+                "OneParen", 
+                "TwoParens"
+            ]
 
-      attr_accessor :start, :number_style, :number_delim
-      def initialize attributes
-        @start = attributes[0]
-        @number_style = attributes[1]
-        @number_delim = attributes[2]
-      end
+            attr_accessor :start, :number_style, :number_delim
 
-      def to_ast
-        [
-          @start,
-          @number_style,
-          @number_delim
-        ]
-      end
+            # Create a new ListAttribute object with attributes
+            #
+            # @param attributes [Array] an array with start, number style, and
+            #   number delimeter
+            def initialize(attributes)
+                @start = attributes[0]
+                @number_style = attributes[1]
+                @number_delim = attributes[2]
+            end
+
+            # Create an AST representation of this ListAttributes object
+            def to_ast()
+                [
+                    @start,
+                    @number_style,
+                    @number_delim
+                ]
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/markdown.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,74 +17,117 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    module Markdown
+    module PandocFilter
+        # A mixin to add inner_markdown and outer_markdown properties to Nodes
+        module Markdown
+            require_relative "../pandoc"
+            require_relative "./document"
 
-      require_relative "../pandoc"
-      require_relative "./document"
+            # A Paru::Pandoc converter from JSON to markdown
+            AST2MARKDOWN = Paru::Pandoc.new do
+                from "json"
+                to "markdown"
+            end
 
-      AST2MARKDOWN = Paru::Pandoc.new do
-        from "json"
-        to "markdown"
-      end
+            # A Paru::Pandoc converter from markdown to JSON
+            MARKDOWN2JSON = Paru::Pandoc.new do
+                from "markdown"
+                to "json"
+            end
 
-      MARKDOWN2JSON = Paru::Pandoc.new do
-        from "markdown"
-        to "json"
-      end
+            # Get the markdown representation of this Node, including the Node
+            # itself.
+            #
+            # @return [String] the outer markdown representation of this Node
+            def outer_markdown()
+                temp_doc = PandocFilter::Document.fragment [self]
+                AST2MARKDOWN << temp_doc.to_JSON
+            end
 
-      def outer_markdown 
-        temp_doc = PandocFilter::Document.fragment [self]
-        AST2MARKDOWN << temp_doc.to_JSON
-      end
+            # Set the markdown representation of this Node: replace this Node
+            # by the Node represented by the markdown string
+            #
+            # @param markdown [String] the markdown string to replace this
+            #   Node
+            #
+            # @example Replacing all horizontal lines by a Plain node saying "hi"
+            #   Paru::Filter.run do
+            #       with "HorizontalLine" do |line|
+            #           line.outer_markdown = "hi"
+            #       end
+            #   end
+            #       
+            def outer_markdown=(markdown)
+                json = MARKDOWN2JSON << markdown
+                temp_doc = PandocFilter::Document.from_JSON json
 
-      def outer_markdown= markdown
-        json = MARKDOWN2JSON << markdown
-        temp_doc = PandocFilter::Document.from_JSON json
+                if not has_parent? or is_root?
+                    @children = temp_doc.children
+                else
+                    # replace current node by new nodes
+                    # There is a difference between inline and block nodes
+                    current_index = parent.find_index self
+                    index = current_index
+                    temp_doc.each do |child|
+                        index += 1
+                        parent.insert index, child
+                    end
+                    # Remove the original node
+                    parent.remove_at current_index
+                end
 
-        if not has_parent? or is_root?
-          @children = temp_doc.children
-        else
-          # replace current node by new nodes
-          # There is a difference between inline and block nodes
-          current_index = parent.find_index self
-          index = current_index
-          temp_doc.each do |child|
-            index += 1
-            parent.insert index, child
-          end
-          # Remove the original node
-          parent.remove_at current_index
-        end
-
-      end
+            end
 
-      def inner_markdown
-        temp_doc = PandocFilter::Document.fragment @children
-        AST2MARKDOWN << temp_doc.to_JSON
-      end
+            # Get the markdown representation of this Node's children
+            #
+            # @return [String] the inner markdown representation of this Node
+            #
+            # @example Replace all occurrences of "hello" by "world" in all paragraphs
+            #   Paru::Filter.run do
+            #       with "Para" do |p|
+            #           p.inner_markdown = p.inner_markdown.gsub "hello", "world"
+            #       end
+            #   end         
+            #
+            def inner_markdown()
+                temp_doc = PandocFilter::Document.fragment @children
+                AST2MARKDOWN << temp_doc.to_JSON
+            end
 
-      def inner_markdown= markdown
-        if has_string?
-          @string = markdown
-        else
-          if markdown.empty?
-            @children = []
-          else 
-            json = MARKDOWN2JSON << markdown
-            temp_doc = PandocFilter::Document.from_JSON json
-            temp_doc.children.each {|c| c.parent = @parent}
+            # Replace this Node's children with the Nodes represented by the
+            # markdown string
+            #
+            # @param markdown [String] the markdown string to replace this
+            #   Node's children
+            #
+            # @example Replace all occurrences of "hello" by "world" in all paragraphs
+            #   Paru::Filter.run do
+            #       with "Para" do |p|
+            #           p.inner_markdown = p.inner_markdown.gsub "hello", "world"
+            #       end
+            #   end         
+            #
+            def inner_markdown=(markdown)
+                if has_string?
+                    @string = markdown
+                else
+                    if markdown.empty?
+                        @children = []
+                    else 
+                        json = MARKDOWN2JSON << markdown
+                        temp_doc = PandocFilter::Document.from_JSON json
+                        temp_doc.children.each {|c| c.parent = @parent}
 
-            if has_inline?
-              @children = temp_doc.children[0].children
-            elsif has_block?
-              @children = temp_doc.children
-            else
-              # Unknown; what to do here?
+                        if has_inline?
+                            @children = temp_doc.children[0].children
+                        elsif has_block?
+                            @children = temp_doc.children
+                        else
+                            # Unknown; what to do here?
+                        end
+                    end
+                end
             end
-          end
         end
-      end
     end
-  end
 end