paru 0.2.4.2 → 0.2.4.3

data/lib/paru/filter/definition_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,22 +17,26 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
+    module PandocFilter
+        require_relative "./block"
 
-    # DefinitionList [([Inline], [[Block]])]
-    class DefinitionList < Block
-      def initialize contents
-        super []
-        contents.each do |item|
-          @children.push DefinitionListItem.new item
-        end
-      end
+        # A DefinitionList is a list of term-definition pairs, respecitively an Inline list and a Block list.
+        class DefinitionList < Block
+            # Create a new DefinitionList node
+            #
+            # @param contents [Array] the contents of this definition list.
+            def initialize(contents)
+                super []
+                contents.each do |item|
+                    @children.push DefinitionListItem.new item
+                end
+            end
 
-      def ast_contents
-        @children.map {|child| child.to_ast}
-      end
+            # Create an AST representation of this DefinitionList node
+            def ast_contents
+                @children.map {|child| child.to_ast}
+            end
 
+        end
     end
-  end
 end

data/lib/paru/filter/definition_list_item.rb

@@ -17,24 +17,37 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
-    require_relative "./list"
-    require_relative "./inline"
+    module PandocFilter
+        require_relative "./block"
+        require_relative "./list"
+        require_relative "./inline"
 
-    class DefinitionListItem < Block
-      attr_accessor :term, :definition
-      def initialize item
-        @term = Block.new item[0]
-        @definition = List.new item[1]
-      end
+        # A DefinitionListItem is a helper node to represent the pair of a term
+        # and its definition in a DefinitionList
+        #
+        # @!attribute term
+        #   @return [Block]
+        #
+        # @!attribute definition
+        #   @return [List]
+        class DefinitionListItem < Block
+            attr_accessor :term, :definition
 
-      def to_ast
-        [
-          @term.ast_contents,
-          @definition.ast_contents
-        ]
-      end
+            # Create a new DefinitionListItem 
+            #
+            # @param item [Array] the [term, definition]
+            def initialize(item)
+                @term = Block.new item[0]
+                @definition = List.new item[1]
+            end
+
+            # Create an AST representation of this DefinitionListItem
+            def to_ast
+                [
+                    @term.ast_contents,
+                    @definition.ast_contents
+                ]
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/div.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,28 +17,36 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
-    require_relative "./attr"
+    module PandocFilter
+        require_relative "./block"
+        require_relative "./attr"
 
-    # Div Attr [Block]
-    class Div < Block
-      def initialize contents
-        @attr = Attr.new contents[0]
-        super contents[1]
-      end
+        # A Div node consisting of an attribute object and a list of Block nodes.
+        class Div < Block
 
-      def ast_contents
-        [
-          @attr.to_ast,
-          super
-        ]
-      end
+            # Create a new Div node based on the contents
+            #
+            # @param contents [Array] an array containing the attribute object
+            #   and the contents of this div.
+            def initialize(contents)
+                @attr = Attr.new contents[0]
+                super contents[1]
+            end
 
-      def has_block?
-        true
-      end
+            # Create an AST representation of this Div node.
+            def ast_contents()
+                [
+                    @attr.to_ast,
+                    super
+                ]
+            end
+
+            # Has this Div node Blocks as children?
+            #
+            # @return [Boolean] true
+            def has_block?
+                true
+            end
+        end
     end
-  end
 end
-

data/lib/paru/filter/document.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,63 +17,90 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
+    module PandocFilter
 
-    require "json"
-    require_relative "./node"
-    require_relative "./plain"
-    require_relative "./meta"
-    require_relative "./version"
+        require "json"
+        require_relative "./node"
+        require_relative "./plain"
+        require_relative "./meta"
+        require_relative "./version"
 
-    VERSION = "pandoc-api-version"
-    META = "meta"
-    BLOCKS = "blocks"
+        VERSION = "pandoc-api-version"
+        META = "meta"
+        BLOCKS = "blocks"
 
-    CURRENT_PANDOC_VERSION = [1, 17, 4]
+        # The current pandoc type version
+        # @see https://hackage.haskell.org/package/pandoc-types
+        CURRENT_PANDOC_VERSION = [1, 17, 0, 5]
 
-    class Document < Node
+        # Each file that is being filtered by pandoc is represented by a root
+        # Document. It is the root node of the AST of the document in the file.
+        #
+        # @!attribute meta
+        #   @return [Meta] the metadata of this document
+        class Document < Node
 
-      attr_reader :meta
+            attr_reader :meta
 
-      def self.from_JSON json
-        doc = JSON.parse json
-        version, metadata, contents = doc.values_at(VERSION, META, BLOCKS)
-        PandocFilter::Document.new version, metadata, contents
-      end
+            # Create a new Document from a JSON representation of the AST
+            #
+            # @param json [String] a JSON string representation of the AST of a document
+            # @return [Document] the newly created document
+            def self.from_JSON(json)
+                doc = JSON.parse json
+                version, metadata, contents = doc.values_at(VERSION, META, BLOCKS)
+                PandocFilter::Document.new version, metadata, contents
+            end
 
-      def self.fragment node_list
-        meta = Hash.new
+            # Create a new Document fragment from a list of Node elements
+            #
+            # @param node_list [Array<Node>] a list of nodes to create a Document
+            #   fragment from
+            #
+            # @return [Document] the document containing nodes in node_list
+            def self.fragment(node_list)
+                meta = Hash.new
 
-        if node_list.any? {|n| n.is_block?}
-          new_doc = Document.new CURRENT_PANDOC_VERSION, meta, []
-          new_doc.children = node_list
-        else
-          node = PandocFilter::Plain.new [] 
-          node.children = node_list
-          new_doc = Document.new CURRENT_PANDOC_VERSION, meta, [node.to_ast]
-        end
+                if node_list.any? {|n| n.is_block?}
+                    new_doc = Document.new CURRENT_PANDOC_VERSION, meta, []
+                    new_doc.children = node_list
+                else
+                    node = PandocFilter::Plain.new [] 
+                    node.children = node_list
+                    new_doc = Document.new CURRENT_PANDOC_VERSION, meta, [node.to_ast]
+                end
 
-        new_doc
-      end
+                new_doc
+            end
 
-      def initialize(version, meta, contents)
-        @version = Version.new version
-        @meta = Meta.new meta
-        super contents
-      end
+            # Create a new Document node based on the pandoc type version,
+            # metadata, and the contents of the document
+            #
+            # @param version [Array<Integer>] the version of pandoc types
+            # @param meta [Array] metadata
+            # @param contents [Array] contents
+            def initialize(version, meta, contents)
+                @version = Version.new version
+                @meta = Meta.new meta
+                super contents
+            end
 
-      def to_ast
-        {
-          VERSION => @version.to_ast,
-          META => @meta.to_ast,
-          BLOCKS => ast_contents
-        }
-      end
+            # Create an AST representation of this Document
+            def to_ast()
+                {
+                    VERSION => @version.to_ast,
+                    META => @meta.to_ast,
+                    BLOCKS => ast_contents
+                }
+            end
 
-      def to_JSON
-        to_ast.to_json
-      end
+            # Create a JSON string representation of the AST of this Document.
+            # Use this to write back the manipulated AST in a format that
+            # pandoc understands.
+            def to_JSON
+                to_ast.to_json
+            end
 
+        end
     end
-  end
 end

data/lib/paru/filter/emph.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 "./inline"
+    module PandocFilter
+        require_relative "./inline"
 
-    # Emph [Inline]
-    class Emph < Inline
+        # An Emph, emphasized Inline
+        class Emph < Inline
+        end
     end
-  end
 end

data/lib/paru/filter/empty_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,19 +17,23 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
+    module PandocFilter
+        require_relative "./block"
 
-    class EmptyBlock < Block
-      def initialize _
-        super []
-      end
+        # An EmptyBlock, has not contents
+        class EmptyBlock < Block
 
-      def to_ast
-        {
-          "t" => ast_type
-        }
-      end
+            # Create an empty block
+            def initialize _
+                super []
+            end
+
+            # Create an AST representation of this EmptyBlock
+            def to_ast
+                {
+                    "t" => ast_type
+                }
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/empty_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
 #
@@ -17,23 +17,30 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./inline"
+    module PandocFilter
+        require_relative "./inline"
 
-    class EmptyInline < Inline
-      def initialize _
-        super []
-      end
-      
-      def has_inline?
-        false
-      end
+        # An EmptyInline node, has no content
+        class EmptyInline < Inline
 
-      def to_ast
-        {
-          "t" => ast_type
-        }
-      end
+            # Create an EmptyInline node
+            def initialize _
+                super []
+            end
+
+            # Has this empty inline contents?
+            #
+            # @return [Boolean] false
+            def has_inline?
+                false
+            end
+
+            # Create an AST representation of this EmptyInline
+            def to_ast
+                {
+                    "t" => ast_type
+                }
+            end
+        end
     end
-  end
 end

data/lib/paru/filter/header.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,31 +17,46 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    require_relative "./block"
-    require_relative "./attr"
+    module PandocFilter
+        require_relative "./block"
+        require_relative "./attr"
 
-    # Header Int Attr [Inline]
-    class Header < Block
-      attr_accessor :level, :attr
+        # A Header node has a level, an attribute object and the contents of
+        # the header as a list on Inline nodes.
+        #
+        # @!attribute level
+        #   @return [Integer]
+        #
+        # @!attribute attr
+        #   @return [Attr]
+        class Header < Block
+            attr_accessor :level, :attr
 
-      def initialize contents
-        @level = contents[0]
-        @attr = Attr.new contents[1]
-        super contents[2], true
-      end
+            # Create a new Header node
+            #
+            # @param contents [Array] an array with the level, attribute, and
+            #   the header contents
+            def initialize(contents)
+                @level = contents[0]
+                @attr = Attr.new contents[1]
+                super contents[2], true
+            end
 
-      def ast_contents
-        [
-          @level,
-          @attr.to_ast,
-          super
-        ]
-      end
+            # Create an AST representation of this Header node
+            def ast_contents()
+                [
+                    @level,
+                    @attr.to_ast,
+                    super
+                ]
+            end
 
-      def has_inline?
-        true
-      end
+            # Has this Header node inline contents?
+            #
+            # @return [Boolean] true
+            def has_inline?
+                true
+            end
+        end
     end
-  end
 end