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



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

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



46
47
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
136
137
138
 
# File 'lib/paru/filter/document.rb', line 46

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.new <<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 -1 == (version <=> CURRENT_PANDOC_VERSION)
            if metadata.has_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
        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 = Hash.new

        if node_list.nil? or 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

    # 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



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

def self.fragment(node_list)
    meta = Hash.new

    if node_list.nil? or 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

.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.



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
 
# File 'lib/paru/filter/document.rb', line 57

def self.from_JSON(json)
    begin
        doc = JSON.parse json
        version, metadata, contents = doc.values_at(VERSION, META, BLOCKS)
    rescue Exception => e
        raise FilterError.new <<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 -1 == (version <=> CURRENT_PANDOC_VERSION)
        if metadata.has_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
    end

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

Instance Method Details

#to_ast ⇒ Object

Create an AST representation of this Document



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

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.



134
135
136
 
# File 'lib/paru/filter/document.rb', line 134

def to_JSON
    to_ast.to_json
end