Class: Paru::PandocFilter::Document

Inherits:
Node
  • Object
show all
Defined in:
lib/paru/filter/document.rb

Overview

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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(version = CURRENT_PANDOC_VERSION, meta = [], contents = []) ⇒ Document

Create a new Document node based on the pandoc type version, metadata, and the contents of the document

Parameters:

  • version (Integer = CURRENT_PANDOC_VERSION) (defaults to: CURRENT_PANDOC_VERSION) —

    the version of pandoc types

  • meta (Array = []) (defaults to: []) —

    metadata

  • contents (Array = []) (defaults to: []) —

    contents



114
115
116
117
118
 
# File 'lib/paru/filter/document.rb', line 114

def initialize(version = CURRENT_PANDOC_VERSION, meta = [], contents = [])
  @version = Version.new version
  @meta = Meta.new meta
  super(contents)
end

Instance Attribute Details

#meta ⇒ Meta

Returns the metadata of this document.

Returns:

  • (Meta) —

    the metadata of this document



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/paru/filter/document.rb', line 48

class Document < Node
  attr_accessor :meta

  # 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
  #
  # @raise [ParuFilterError] when parsing JSON AST from pandoc fails
  #   or the parsed results do not make sense.
  def self.from_JSON(json)
    begin
      doc = JSON.parse json
      version, metadata, contents = doc.values_at(VERSION, META, BLOCKS)
    rescue Exception => e
      raise FilterError, <<~WARNING
        Unable to read document.

        Most likely cause: Paru expects a pandoc installation that has been
        compiled with pandoc-types >= #{CURRENT_PANDOC_VERSION.join('.')}. You can
        check which pandoc-types have been compiled with your pandoc installation by
        running `pandoc -v`.#{' '}

        Original error message: #{e.message}
      WARNING
    end

    if ((version <=> CURRENT_PANDOC_VERSION) == -1) && metadata.key?('debug_')
      warn <<~WARNING
        pandoc-types API version used in document (version = #{version.join('.')}) is
        lower than the version of pandoc-types used by paru
        (#{CURRENT_PANDOC_VERSION.join('.')}. If you experience unexpected results,
        please try updating pandoc or downgrading paru.
      WARNING
    end

    PandocFilter::Document.new version, metadata, contents
  end

  # Create a new Document fragment from a list of Node elements
  #
  # @param node_list [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 = {}

    if node_list.nil? || node_list.any?(&: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

  # Create a new Document node based on the pandoc type version,
  # metadata, and the contents of the document
  #
  # @param version [Integer = CURRENT_PANDOC_VERSION] the version of pandoc types
  # @param meta [Array = []] metadata
  # @param contents [Array = []] contents
  def initialize(version = CURRENT_PANDOC_VERSION, meta = [], contents = [])
    @version = Version.new version
    @meta = Meta.new meta
    super(contents)
  end

  # Create an AST representation of this Document
  def to_ast
    {
      VERSION => @version.to_ast,
      META => @meta.to_ast,
      BLOCKS => ast_contents
    }
  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

Class Method Details

.fragment(node_list) ⇒ Document

Create a new Document fragment from a list of Node elements

Parameters:

  • node_list (Node[]) —

    a list of nodes to create a Document fragment from

Returns:

  • (Document) —

    the document containing nodes in node_list



93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/paru/filter/document.rb', line 93

def self.fragment(node_list)
  meta = {}

  if node_list.nil? || node_list.any?(&: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

.from_JSON(json) ⇒ Document

Create a new Document from a JSON representation of the AST

Parameters:

  • json (String) —

    a JSON string representation of the AST of a document

Returns:

  • (Document) —

    the newly created document

Raises:

  • (ParuFilterError) —

    when parsing JSON AST from pandoc fails or the parsed results do not make sense.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/paru/filter/document.rb', line 58

def self.from_JSON(json)
  begin
    doc = JSON.parse json
    version, metadata, contents = doc.values_at(VERSION, META, BLOCKS)
  rescue Exception => e
    raise FilterError, <<~WARNING
      Unable to read document.

      Most likely cause: Paru expects a pandoc installation that has been
      compiled with pandoc-types >= #{CURRENT_PANDOC_VERSION.join('.')}. You can
      check which pandoc-types have been compiled with your pandoc installation by
      running `pandoc -v`.#{' '}

      Original error message: #{e.message}
    WARNING
  end

  if ((version <=> CURRENT_PANDOC_VERSION) == -1) && metadata.key?('debug_')
    warn <<~WARNING
      pandoc-types API version used in document (version = #{version.join('.')}) is
      lower than the version of pandoc-types used by paru
      (#{CURRENT_PANDOC_VERSION.join('.')}. If you experience unexpected results,
      please try updating pandoc or downgrading paru.
    WARNING
  end

  PandocFilter::Document.new version, metadata, contents
end

Instance Method Details

#to_ast ⇒ Object

Create an AST representation of this Document



121
122
123
124
125
126
127
 
# File 'lib/paru/filter/document.rb', line 121

def to_ast
  {
    VERSION => @version.to_ast,
    META => @meta.to_ast,
    BLOCKS => ast_contents
  }
end

#to_JSON ⇒ Object

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.



132
133
134
 
# File 'lib/paru/filter/document.rb', line 132

def to_JSON
  to_ast.to_json
end