paru 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c83324117fee453bf3031bd1f6f6d9b66add4888
-  data.tar.gz: 331a7af6160201098413f75d356e8a8d0cb263f1
+  metadata.gz: 1f9744e21c17335e591270f4332e03a7fcbd7230
+  data.tar.gz: 250f63c5dd1858e568b57613824c27676d0b4220
 SHA512:
-  metadata.gz: 366cd44bfd6ed8a1fd80394dd1aab28c7bbcb1f366e15afc0f7812054a1cf894facda59d2659db80395d7078386a6af42a7970727b5e2c7dcb437b3f83249e60
-  data.tar.gz: 5c9fb0387b5f5dca3457a8ccec3e91a0fb9c2543b27dab3ec84567bac373ba9fbbddeff8eedbf653b58eb3490e5760cd86004e54509e7742c1c221e75dd6afe5
+  metadata.gz: 73498311b6eef5f2edea155981816aa529f84b8adb1097d4625f73e2afc0dd1d2808acd5bc14e9a010903a1304c297136ee51d2959634344f38ef1a3ed61960f
+  data.tar.gz: 012ba505e5af505770b98647e8e2585a3a36330f7f48aa3072d03debdbfee7c8d1712869cdd5465048ef38554298d67e0ea366399cf470cffcd7638b5a497faa

data/bin/do-pandoc.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+require "yaml"
+require 'optparse'
+require "paru/pandoc"
+require_relative "./pandoc2yaml.rb"
+
+include Pandoc2Yaml
+
+parser = OptionParser.new do |opts|
+  opts.banner = "do-pandoc.rb runs pandoc on an input file using the pandoc configuration specified in that input file."
+  opts.banner << "\n\nUsage: do-pandoc.rb some-pandoc-markdownfile.md"
+  opts.separator ""
+  opts.separator "Common options"
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on("-v", "--version", "Show version") do 
+    puts "do-pandoc.rb is part of paru version 0.2.2"
+    exit
+  end
+end
+
+parser.parse! ARGV
+
+input_document = ARGV.pop
+
+if ARGV.size != 0 then
+  warn "Expecting exactly one argument: the pandoc file to convert"
+  puts ""
+  puts parser
+  exit
+end
+
+document = File.expand_path input_document
+if not File.exist? document
+  warn "Cannot find file: #{input_document}"
+  exit
+end
+
+if !File.readable? document
+  warn "Cannot read file: #{input_document}"
+  exit
+end
+metadata = YAML.load Pandoc2Yaml.extract_metadata(document)
+
+if metadata.has_key? "pandoc" then
+  begin
+    pandoc = Paru::Pandoc.new
+    to_stdout = true
+    metadata["pandoc"].each do |option, value|
+      pandoc.send option, value
+      to_stdout = false if option == "output"
+    end
+    output = pandoc << File.read(document)
+    puts output if to_stdout
+  rescue Exception => e
+    warn "Something went wrong while using pandoc:\n\n#{e.message}"
+  end
+else
+    warn "Unsure what to do: no pandoc options in #{input}"
+end

data/bin/pandoc2yaml.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+##
+# pandoc2yaml.rb extracts the metadata from a pandoc markdown file and prints
+# that metadata out again as a pandoc markdown file with nothing in it but that
+# metadata
+#
+# Usage:
+#
+#  pandoc2yaml.rb input_file
+#
+##
+module Pandoc2Yaml
+  require "json"
+  require "paru/pandoc"
+
+  # Paru converters:
+  # Note. When converting metadata back to the pandoc markdown format, you have
+  # to use the option "standalone", otherwise the metadata is skipped
+  PANDOC_2_JSON = Paru::Pandoc.new {from "markdown"; to "json"}
+  JSON_2_PANDOC = Paru::Pandoc.new {from "json"; to "markdown"; standalone}
+
+  # When converting a pandoc document to JSON, or vice versa, the JSON object
+  # has the following three properties:
+  VERSION = "pandoc-api-version"
+  META = "meta"
+  BLOCKS = "blocks"
+
+  def extract_metadata input_document
+    json = JSON.parse(PANDOC_2_JSON << File.read(input_document))
+    yaml = ""
+
+    version, metadata = json.values_at(VERSION, META)
+
+    if not metadata.empty? then
+      metadata_document = {
+        VERSION => version, 
+        META => metadata, 
+        BLOCKS => []
+      }
+
+      yaml = JSON_2_PANDOC << JSON.generate(metadata_document)
+    end
+
+    yaml
+  end
+end
+
+if __FILE__ == $0
+  include Pandoc2Yaml
+  require 'optparse'
+
+  parser = OptionParser.new do |opts|
+    opts.banner = "pandoc2yaml.rb mines a pandoc markdown file for its YAML metadata"
+    opts.banner << "\n\nUsage: pandoc2yaml.rb some-pandoc-markdownfile.md"
+    opts.separator ""
+    opts.separator "Common options"
+
+    opts.on_tail("-h", "--help", "Show this message") do
+      puts opts
+      exit
+    end
+
+    opts.on("-v", "--version", "Show version") do 
+      puts "pandoc2yaml.rb is part of paru version 0.2.2"
+      exit
+    end
+  end
+
+  parser.parse! ARGV
+
+  input_document = ARGV.pop
+
+  if ARGV.size != 0 then
+    warn "Expecting exactly one argument: the pandoc file to strip for metadata"
+    puts ""
+    puts parser
+    exit
+  end
+
+  document = File.expand_path input_document
+  if not File.exist? document
+    warn "Cannot find file: #{input_document}"
+    exit
+  end
+
+  if !File.readable? document
+    warn "Cannot read file: #{input_document}"
+    exit
+  end
+
+  output_metadata = Pandoc2Yaml.extract_metadata document
+  
+  puts output_metadata
+end

data/lib/paru.rb

@@ -1,18 +1,34 @@
+# = 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>
 #
 # This file is part of Paru
 #
-# Paru is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
+# Paru is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
 #
-# Paru is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# Paru is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
 #
-# You should have received a copy of the GNU General Public License
-# along with Paru.  If not, see <http://www.gnu.org/licenses/>.
+# 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/filter"

data/lib/paru/error.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,7 +15,13 @@
 #
 # 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
+
+  # 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
 end

data/lib/paru/filter.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,11 +15,19 @@
 #
 # 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",
@@ -35,6 +44,9 @@ module Paru
     "Div",
     "Null"
   ]
+
+  # Pandoc's inline elements are
+
   PANDOC_INLINE = [
     "Str",
     "Emph",
@@ -55,18 +67,31 @@ module Paru
     "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 = []
@@ -80,15 +105,25 @@ module Paru
       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
 
+    # 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

data/lib/paru/filter/alignment.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,6 +15,7 @@
 #
 # 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
   module PandocFilter
 

data/lib/paru/filter/ast_manipulation.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,6 +15,7 @@
 #
 # 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
   module PandocFilter
     module ASTManipulation

data/lib/paru/filter/attr.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,6 +15,7 @@
 #
 # 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
   module PandocFilter
     class Attr

data/lib/paru/filter/block.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,6 +15,7 @@
 #
 # 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
   module PandocFilter
     require_relative "./node"

data/lib/paru/filter/block_quote.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,11 +15,12 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
-# BlockQuote [Block]
+#++
 module Paru
   module PandocFilter
     require_relative "./block"
 
+    # BlockQuote [Block]
     class BlockQuote < Block
       def has_block?
         true

data/lib/paru/filter/bullet_list.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,11 +15,12 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
-# BulletList [[Block]]
+#++
 module Paru
   module PandocFilter
     require_relative "./list"
 
+    # BulletList [[Block]]
     class BulletList < List
     end
   end

data/lib/paru/filter/citation.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,6 +15,7 @@
 #
 # 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
   module PandocFilter
     require_relative "./inline"

data/lib/paru/filter/cite.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015, 2016 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
@@ -14,11 +15,12 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
-# Cite [Citation] [Inline]
+#++
 module Paru
   module PandocFilter
     require_relative "./inline"
 
+    # Cite [Citation] [Inline]
     class Cite < Inline
       attr_accessor :citations