paru 0.2.4.2 → 0.2.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ca9b8f9a5dfb9ed996c9ebd36fa23691aa1e448f
-  data.tar.gz: 0bf2eafd97f4531197070770e63669915594c2ac
+  metadata.gz: c1b0bdd09190def2f416be363cec8c5dc2e51106
+  data.tar.gz: fb2184d30afb43207c81ce1a681b39a58dea2343
 SHA512:
-  metadata.gz: 137ac8ad91c1ed028fac5cda72d748ce237061e9a8e8a8e1f5387ab07a4b57fdaa96ef3a5624aae1185859788b477a656a536106363fd966f211f16c1289446c
-  data.tar.gz: 7c9ef903d1c6f55c5872c42b6bd70c94de2098b691a869141027ccb9f8db3b7901bc85aba40c9ad0f09cc1facdd5944586538a6107e3f453cff695a8ee6b7d34
+  metadata.gz: 006cfa8e6e18ad4ee4596c27e23bac083a8afa820e0e31744632417f1e2d9beae70047623b8db4a01b64ad28823e746cc4c8b9fbd10ad6c9326dd9b731c15224
+  data.tar.gz: ee5d944ce20ba48171b51f6700587c7cb264f0c7a8ea807fcc51002e642980a6823b30dbb5c652fa9051cbfb74fa1d68fabcbd51d0811147d62c1cf9558753c0

data/lib/paru.rb

@@ -1,19 +1,5 @@
-# = This is the API documentation for paru generated by RDoc.
-# 
-# Paru is a simple Ruby wrapper around {pandoc}[http://www.pandoc.org], the
-# great multi-format document converter. Paru supports automating pandoc by
-# writing Ruby programs and using pandoc in your Ruby programs. Paru also
-# supports writing pandoc filters in Ruby. In {paru's user
-# manual}[https://heerdebeer.org/Software/markdown/paru/] the use of paru is
-# explained in detail, from explaining how to install and use paru, creating
-# and using filters, to putting it all together in a real-world use case like
-# generating that manual page.
-#
-# This document, however, describes paru's API.
-#
-# == Licence
-#
-# 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
 #
@@ -29,7 +15,9 @@
 #
 # You should have received a copy of the GNU General Public License along with
 # Paru.  If not, see <http://www.gnu.org/licenses/>.
-
-require "paru/pandoc"
-require "paru/error"
-require "paru/filter"
+#++
+module Paru
+    require "paru/pandoc"
+    require "paru/error"
+    require "paru/filter"
+end

data/lib/paru/error.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
 #
@@ -19,9 +19,7 @@
 
 module Paru
 
-  # An error class to use as a basis for paru specific errors. It has not yet
-  # been used in that capacity much, however.
-  
-  class Error < RuntimeError
-  end
+    # An error class to use as a basis for paru specific errors.
+    class Error < RuntimeError
+    end
 end

data/lib/paru/filter.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
 #
@@ -16,117 +16,151 @@
 # You should have received a copy of the GNU General Public License
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
-
 module Paru
 
-  require_relative "./selector"
-  require_relative "filter/document"
-
-  # Paru filter is a wrapper around pandoc's JSON api, which is based on
-  # {pandoc-types}[https://hackage.haskell.org/package/pandoc-types-1.17.0.4/docs/Text-Pandoc-Definition.html].
-  # Pandoc treats block elements and inline elements differently. 
-  #
-  # Pandoc's block elements are:
-
-  PANDOC_BLOCK = [
-    "Plain",
-    "Para",
-    "LineBlock",
-    "CodeBlock",
-    "RawBlock",
-    "BlockQuote",
-    "OrderedList",
-    "BulletList",
-    "DefinitionList",
-    "Header",
-    "HorizontalRule",
-    "Table",
-    "Div",
-    "Null"
-  ]
-
-  # Pandoc's inline elements are
-
-  PANDOC_INLINE = [
-    "Str",
-    "Emph",
-    "Strong",
-    "Strikeout",
-    "Superscript",
-    "Subscript",
-    "SmallCaps",
-    "Quoted",
-    "Cite",
-    "Space",
-    "SoftBreak",
-    "LineBreak",
-    "Math",
-    "RawInline",
-    "Link",
-    "Image",
-    "Note",
-    "Span"
-  ]
-
-  # All of pandoc's type together:
-
-  PANDOC_TYPES = PANDOC_BLOCK + PANDOC_INLINE
-
-
-  # Filter is used to write your own pandoc filter in Ruby. A Filter is
-  # almost always created and immediately executed via the +run+ method as
-
-  class Filter
-
-    def self.run &block
-      Filter.new().filter(&block)
-    end
-
-
-    # Create a new Document node from JSON formatted pandoc document structure
-    # on STDIN
-
-    def document
-      PandocFilter::Document.from_JSON $stdin.read
-    end
-
-    # Create a filter using +block+.
-
-    def filter &block
-      @selectors = Hash.new
-      @filtered_nodes = []
-      @doc = document
-
-      @doc.each_depth_first do |node|
-        @filtered_nodes.push node
-        instance_eval(&block)
-      end
-
-      puts @doc.to_JSON
-    end
-
-
-    # +current_node+ points to the node that is *now* being processed while
-    # running this filter.
-
-    def current_node
-      @filtered_nodes.last
-    end
+    require_relative "./selector"
+    require_relative "filter/document"
+
+    # Paru filter is a wrapper around pandoc's JSON api, which is based on
+    # {pandoc-types}[https://hackage.haskell.org/package/pandoc-types-1.17.0.4/docs/Text-Pandoc-Definition.html].
+    # Pandoc treats block elements and inline elements differently. 
+    #
+    # Pandoc's block elements are:
+    PANDOC_BLOCK = [
+        "Plain",
+        "Para",
+        "LineBlock",
+        "CodeBlock",
+        "RawBlock",
+        "BlockQuote",
+        "OrderedList",
+        "BulletList",
+        "DefinitionList",
+        "Header",
+        "HorizontalRule",
+        "Table",
+        "Div",
+        "Null"
+    ]
+
+    # Pandoc's inline elements are
+    PANDOC_INLINE = [
+        "Str",
+        "Emph",
+        "Strong",
+        "Strikeout",
+        "Superscript",
+        "Subscript",
+        "SmallCaps",
+        "Quoted",
+        "Cite",
+        "Space",
+        "SoftBreak",
+        "LineBreak",
+        "Math",
+        "RawInline",
+        "Link",
+        "Image",
+        "Note",
+        "Span"
+    ]
+
+    # All of pandoc's type together:
+    PANDOC_TYPES = PANDOC_BLOCK + PANDOC_INLINE
+
+
+    # Filter is used to write your own pandoc filter in Ruby. A Filter is
+    # almost always created and immediately executed via the +run+ method as
+    # shown in the following examples:
+    #
+    # @example Identity filter
+    #     Paru::Filter.run do
+    #         # nothing
+    #     end
+    #
+    # @example Remove horizontal lines
+    #     Paru::Filter.run do
+    #       with "HorizontalRule" do |rule|
+    #           if rule.has_parent? then
+    #               rule.parent.delete rule
+    #           else
+    #               rule.outer_markdown = ""
+    #           end
+    #       end
+    #     end
+    class Filter
+
+        # Run the filter specified by block. In the block you specify
+        # selectors and actions to be performed on selected nodes. In the
+        # example below, the selector is "Image", which selects all image
+        # nodes. The action is to prepend the contents of the image's caption
+        # by the string "Figure. ".
+        #
+        # @param block [Proc] the filter specification
+        #
+        # @example Add 'Figure' to each image's caption
+        #   Paru::Filter.run do
+        #       with "Image" do |image|
+        #           image.inner_markdown = "Figure. #{image.inner_markdown}"
+        #       end
+        #   end
+        def self.run(&block)
+            Filter.new().filter(&block)
+        end
+
+
+        # The Document node from JSON formatted pandoc document structure
+        # on STDIN that is being filtered
+        #
+        # @return [Document] create a new Document node from a pandoc AST from
+        #   JSON from STDIN
+        def document()
+            PandocFilter::Document.from_JSON $stdin.read
+        end
+
+        # Create a filter using +block+.
+        #
+        # @param block [Proc] a block specifying selectors and actions
+        # @return [JSON] a JSON string with the filtered pandoc AST
+        def filter(&block)
+            @selectors = Hash.new
+            @filtered_nodes = []
+            @doc = document
+
+            @doc.each_depth_first do |node|
+                @filtered_nodes.push node
+                instance_eval(&block)
+            end
+
+            puts @doc.to_JSON
+        end
+
+
+        # +current_node+ points to the node that is *now* being processed while
+        # running this filter.
+        #
+        # @return [Node] the node that is currently being processed
+        def current_node()
+            @filtered_nodes.last
+        end
+
+        # Specify what nodes to filter with a +selector+. If the +current_node+
+        # matches that selector, it is passed to the block to this +with+ method.
+        #
+        # @param selector [String] a selector string 
+        # @yield [Node] the current node if it matches the selector
+        def with(selector)
+            @selectors[selector] = Selector.new selector unless @selectors.has_key? selector
+            yield current_node if @selectors[selector].matches? current_node, @filtered_nodes
+        end
+
+        # While running a filter you can access the document's metadata through
+        # the +metadata+ method.
+        #
+        # @return [Meta] the filtered document's metadata
+        def metadata()
+            @doc.meta
+        end
 
-    # Specify what nodes to filter with a +selector+. If the +current_node+
-    # matches that selector, it is passed to the block to this +with+ method.
-
-    def with selector
-      @selectors[selector] = Selector.new selector unless @selectors.has_key? selector
-      yield current_node if @selectors[selector].matches? current_node, @filtered_nodes
     end
-
-    # While running a filter you can access the document's metadata through
-    # the +metadata+ method.
-
-    def metadata
-      @doc.meta
-    end
-
-  end
 end

data/lib/paru/filter/ast_manipulation.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,46 +17,82 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 module Paru
-  module PandocFilter
-    module ASTManipulation
-
-      def insert index, child
-        @children.insert index, child
-      end
-
-      def delete child
-        @children.delete child
-      end
-
-      def remove_at index
-        @children.delete_at index
-      end 
-
-      def append child
-        @children.push child
-      end
-      alias << append
-
-      def prepend child
-        insert 0, child
-      end
-
-      def replace old_child, new_child
-        old_child_index = @children.find_index old_child
-        if old_child_index then
-          replace_at old_child_index, new_child
-        end
-      end
+    module PandocFilter
+
+        # ASTManipulation is a mixin for Node with some standard tree
+        # manipulation methods such as inserting or removing nodes, replacing
+        # nodes, and so on.
+        module ASTManipulation
+
+            # Insert child node among this node's children at position index.
+            #
+            # @param index [Integer] the position to insert the child
+            # @param child [Node] the child to insert
+            def insert(index, child)
+                @children.insert index, child
+            end
+
+            # Delete child from this node's children.
+            #
+            # @param child [Node] the child node to delete.
+            def delete(child)
+                @children.delete child
+            end
+
+            # Remove the child at position index from this node's children
+            #
+            # @param index [Integer] the position of the child to remove
+            def remove_at(index)
+                @children.delete_at index
+            end 
 
-      def replace_at index, new_child
-        @children[index] = new_child
-      end
+            # Append a child to the list with this node's children.
+            #
+            # @param child [Node] the child to append.
+            def append(child)
+                @children.push child
+            end
+            alias << append
 
-      def each_depth_first &block
-        yield self
-        each {|child| child.each_depth_first(&block)} if has_children?
-      end
+            # Prepend a child to the list with this node's children.
+            #
+            # @param child [Node] the child to prepend.
+            def prepend(child)
+                insert 0, child
+            end
 
+            # Replace a child from this node's children with a new child.
+            #
+            # @param old_child [Node] the child to replace
+            # @param new_child [Node] the replacement child
+            def replace(old_child, new_child)
+                old_child_index = @children.find_index old_child
+                if old_child_index then
+                    replace_at old_child_index, new_child
+                end
+            end
+
+            # Replace the child at position index from this node's children
+            # with a new child.
+            #
+            # @param index [Integer] the position of the child to replace
+            # @param new_child [Node] the replacement child
+            def replace_at(index, new_child)
+                @children[index] = new_child
+            end
+
+            # Walk the node tree starting at this node, depth first, and apply
+            # block to each node in the tree
+            #
+            # @param block [Proc] the block to apply to each node in this node
+            #   tree
+            #
+            # @yield node
+            def each_depth_first(&block)
+                yield self
+                each {|child| child.each_depth_first(&block)} if has_children?
+            end
+
+        end
     end
-  end
 end