paru 0.2.5b → 0.2.5c

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 87a2a350eeeb33246aa3d841ca14062935c29806
-  data.tar.gz: 92e889e2dd7b06f6966327406cb8fed6d3b2f3dc
+  metadata.gz: e39519f32865af110131f673e16b6e4a99f567d0
+  data.tar.gz: bfc70e18a105a8488cc4ba06b2f3cc393e7bb9b6
 SHA512:
-  metadata.gz: 616a84c6f967318840a95e4c4f993a63e48cc461e95bab75981dc92b35a8b32db473a1878dc46371893a2b875eddbc964d2974a616ebc0f37c1f5c8b092f5015
-  data.tar.gz: 4ce02c9ad9a3983c2751bda198efcbdab1701ad9e5a5f181d03e5cf440ebc7a98f2390723c635fffb327b65e44a7856c4564e8e67e8ed26c60d2273760178c8d
+  metadata.gz: d1169e0f995d1722251fcfbb0107c386aaf6d5f0df98ead73fac6adf64276bf7715e1f4003c512186cd41d228a38f007fa26cc18cb62c033f3c69e863a570268
+  data.tar.gz: 12f8bbb1532f99347ac624b56215b2932bf56db09ac2d4a8f3583601fe5aadbc2df071ba4b183b07d1165c3e29f3e111743c677854cc967677341e62c24bcb44

data/lib/paru/filter.rb

@@ -198,11 +198,23 @@ module Paru
     #
     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. ".
+        # Create a new Filter instance. For convenience, {run} creates a new
+        # {Filter} and runs it immediately. Use this constructor if you want
+        # to run a filter on different input and output streams that STDIN and
+        # STDOUT respectively.
+        #
+        # @param input [IO = $stdin] the input stream to read, defaults to
+        #   STDIN
+        # @param output [IO = $stdout] the output stream to write, defaults to 
+        #   STDOUT
+        def initialize(input = $stdin, output = $stdout)
+            @input = input
+            @output = output
+        end
+
+        # Run the filter specified by block. This is a convenience method that
+        # creates a new {Filter} using input stream STDIN and output stream
+        # STDOUT and immediately runs {filter} with the block supplied. 
         #
         # @param block [Proc] the filter specification
         #
@@ -213,23 +225,39 @@ module Paru
         #       end
         #   end
         def self.run(&block)
-            Filter.new().filter(&block)
+            Filter.new($stdin, $stdout).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
+            PandocFilter::Document.from_JSON @input.read
         end
 
-        # Create a filter using +block+.
+        # Create a filter using +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
         #
-        # @param block [Proc] a block specifying selectors and actions
         # @return [JSON] a JSON string with the filtered pandoc AST
+        #
+        # @example Add 'Figure' to each image's caption
+        #   input = IOString.new(File.read("my_report.md")
+        #   output = IOString.new
+        #
+        #   Paru::Filter.new(input, output).filter do
+        #       with "Image" do |image|
+        #           image.inner_markdown = "Figure. #{image.inner_markdown}"
+        #       end
+        #   end
+        #
+        #   # do something with output.string
         def filter(&block)
             @selectors = Hash.new
             @filtered_nodes = []
@@ -240,10 +268,9 @@ module Paru
                 instance_eval(&block)
             end
 
-            puts @doc.to_JSON
+            @output.write @doc.to_JSON
         end
 
-
         # +current_node+ points to the node that is *now* being processed while
         # running this filter.
         #

data/lib/paru/filter/meta_map.rb

@@ -42,7 +42,7 @@ module Paru
             end
 
             # Get the value belonging to key. Prefer to use the {has?}, {get},
-            # and {delete} methods to manipulate metadata.
+            # {replace} and {delete} methods to manipulate metadata.
             #
             # @param key [String] the key
             #
@@ -56,9 +56,7 @@ module Paru
             # to set the metadata.
             #
             # @param key [String] the key to set
-            # @param value
-            #   [MetaBlocks|MetaBool|MetaInline|MetaList|MetaMap|MetaString|MetaValue]
-            #   the value to set
+            # @param value [MetaBlocks|MetaBool|MetaInlines|MetaList|MetaMap|MetaString|MetaValue] the value to set
             def []=(key, value)
                 @children[key] = value
             end
@@ -73,6 +71,7 @@ module Paru
             # Mixin the YAML code into this metadata object
             #
             # @param yaml_string [YAML] A string with YAML data
+            # @return [MetaMap] this MetaMap object
             #
             # @example Set some properties in the metadata
             #   #!/usr/bin/env ruby
@@ -82,7 +81,7 @@ module Paru
             #   Paru::Filter.run do
             #     metadata.yaml <<~YAML
             #       ---
-            #       date: Date.today.to_s
+            #       date: #{Date.today.to_s}
             #       title: This **is** the title
             #       pandoc_options:
             #         from: markdown
@@ -99,6 +98,7 @@ module Paru
                 meta_from_yaml(yaml_string).each do |key, value|
                     self[key] = value
                 end
+                self
             end
 
             # Replace the property in this MetaMap matching the selector with
@@ -108,8 +108,7 @@ module Paru
             # @param selector [String] a dot-separated sequence of property
             # names denoting a sequence of descendants.
             #
-            # @param value
-            # [MetaBlocks|MetaBool|MetaInline|MetaList|MetaMap|MetaString|MetaValue|String]
+            # @param value [MetaBlocks|MetaBool|MetaInlines|MetaList|MetaMap|MetaString|MetaValue|String]
             #   if value is a String, it is treated as a yaml string
             def replace(selector, value)
                 parent = select(selector, true)
@@ -124,7 +123,7 @@ module Paru
             # @param selector [String] a dot-separated sequence of property
             #   names denoting a sequence of descendants.
             #
-            # @return [MetaBlocks|MetaBool|MetaInline|MetaList|MetaMap|MetaString|MetaValue] the value matching the selected property, nil if it cannot be found
+            # @return [MetaBlocks|MetaBool|MetaInlines|MetaList|MetaMap|MetaString|MetaValue] the value matching the selected property, nil if it cannot be found
             def get(selector)
                 select(selector)
             end 
@@ -145,14 +144,13 @@ module Paru
             # @param selector [String] a dot-separated sequence of property
             #   names denoting a sequence of descendants
             #
-            # @return [MetaBlocks|MetaBool|MetaInline|MetaList|MetaMap|MetaString|MetaValue] the value of the deleted property, nil if it cannot be found
+            # @return [MetaBlocks|MetaBool|MetaInlines|MetaList|MetaMap|MetaString|MetaValue] the value of the deleted property, nil if it cannot be found
             #
             def delete(selector)
                 parent = select(selector, true)
                 parent.children.delete(last_key(selector))
             end
 
-
             # The AST contents
             def ast_contents()
                 ast = Hash.new
@@ -173,7 +171,7 @@ module Paru
             # @param get_parent [Boolean = false] Get the parent MetaMap
             #   of the selected property instead of its value
             # 
-            # @return [MetaBlocks|MetaBool|MetaInline|MetaList|MetaMap|MetaString|MetaValue] the value of the deleted property, nil if it cannot be found
+            # @return [MetaBlocks|MetaBool|MetaInlines|MetaList|MetaMap|MetaString|MetaValue] the value of the deleted property, nil if it cannot be found
             def select(selector, get_parent = false)
                 keys = selector.split(".")
                 level = self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paru
 version: !ruby/object:Gem::Version
-  version: 0.2.5b
+  version: 0.2.5c
 platform: ruby
 authors:
 - Huub de Beer