class Glyph::Document

The Glyph::Document class stores information about a document or a chunk of text currently being interpreted.

It is responsible of analyzing (evaluating) the syntax tree and return the corresponding output as well as replacing placeholders.

Constants

ESCAPES

A Regexp containing the characters to escape

Attributes

bookmarks[R]
context[R]
errors[R]
fragments[R]
headers[R]
placeholders[R]
snippets[R]
styles[R]
toc[R]
todos[R]
topics[R]

Public Class Methods

new(tree, context={}) click to toggle source

Creates a new document @param [GlyphSyntaxNode] tree the syntax tree to be evaluate @param [Glyph::Node] context the context associated with the tree @raise [RuntimeError] unless tree responds to :evaluate

# File lib/glyph/document.rb, line 22
def initialize(tree, context={})
        @tree = tree
        @context = context
        @context[:source] ||= {:file => nil, :name => '--', :topic => nil}
        @placeholders = {}
        @bookmarks = {}
        @headers = {}
        @snippets = {}
        @fragments = {}
        @styles = []
        @errors = []
        @todos = []
        @topics = []
        @links = []
        @toc = {}
        @state = :new
end

Public Instance Methods

analyze() click to toggle source

Analyzes the document by evaluating its @tree @return [:analyzed] @raise [RuntimeError] if the document is already analyzed or finalized

# File lib/glyph/document.rb, line 147
def analyze
        raise RuntimeError, "Document is #{@state}" if analyzed? || finalized?
        @context[:document] = self
        @output = @tree.evaluate @context
        @state = :analyzed
end
analyzed?() click to toggle source

@return [Boolean] Returns true if the document is analyzed, false otherwise

# File lib/glyph/document.rb, line 201
def analyzed?
        @state == :analyzed
end
bookmark(hash) click to toggle source

Stores a new bookmark @param [Hash] hash the bookmark hash @example {:id => “BookmarkID”, :title => “Bookmark Title”, :file => “dir/preface.glyph”} @return [Glyph::Bookmark] the stored bookmark @raise [RuntimeError] if the bookmark is already defined.

# File lib/glyph/document.rb, line 88
def bookmark(hash)
        b = Glyph::Bookmark.new(hash)
        raise RuntimeError, "Bookmark '#{b.code}' already exists" if @bookmarks.has_key? b.code
        @bookmarks[b.code] = b
        b
end
bookmark?(key) click to toggle source

Returns a stored bookmark or nil @param [#to_sym] key the bookmark identifier @return [Glyph::Bookmark, nil] the bookmark or nil if no bookmark is found

# File lib/glyph/document.rb, line 79
def bookmark?(key)
        @bookmarks[key.to_sym]
end
finalize() click to toggle source

Finalizes the document by evaluating its @placeholders @return [:finalized] @raise [RuntimeError] if the document the document has not been analyzed,

if it is already finalized or if errors occurred during analysis
# File lib/glyph/document.rb, line 158
def finalize
        raise RuntimeError, "Document has not been analyzed" unless analyzed?
        raise RuntimeError, "Document has already been finalized" if finalized?
        return (@state = :finalized) if @context[:embedded]
        raise RuntimeError, "Document cannot be finalized due to previous errors" unless @context[:document].errors.blank?
        # Substitute placeholders
        @placeholders.each_pair do |key, value| 
                begin
                        key_s = key.to_s
                        value_s = value.call(self).to_s
                        toc[:contents].gsub! key_s, value_s rescue nil
                        @topics.each do |t|
                                t[:contents].gsub! key_s, value_s
                        end
                        @output.gsub! key_s, value_s
                rescue Glyph::MacroError => e
                        e.macro.macro_warning e.message, e
                rescue Exception => e
                        Glyph.warning e.message
                end
        end
        # Substitute escape sequences
        @output.gsub!(ESCAPES) { |match| ($1 == '/') ? '' : $1 }
        toc[:contents].gsub!(ESCAPES) { |match| ($1 == '/') ? '' : $1 } rescue nil
        @topics.each do |t|
                t[:contents].gsub!(ESCAPES) { |match| ($1 == '/') ? '' : $1 }
        end
        @state = :finalized
end
finalized?() click to toggle source

@return [Boolean] Returns true if the document is analyzed, false otherwise

# File lib/glyph/document.rb, line 206
def finalized?
        @state == :finalized
end
header(hash) click to toggle source

Stores a new header @param [Hash] hash the header hash @example {:id => “Bookmark_ID”, :title => “Bookmark Title”, :level => 3} @return [Glyph::Header] the stored header @raise [RuntimeError] if the bookmark is already defined.

# File lib/glyph/document.rb, line 100
def header(hash)
        b = Glyph::Header.new(hash)
        raise RuntimeError, "Bookmark '#{b.code}' already exists" if @bookmarks.has_key? b.code
        @bookmarks[b.code] = b
        @headers[b.code] = b
        b
end
header?(key) click to toggle source

Returns a stored header or nil @param [String, Symbol] key the header identifier @return [Glyph::Header, nil] the header or nil if no header is found

# File lib/glyph/document.rb, line 111
def header?(key)
        @headers[key.to_sym]
end
inherit_from(document, data={}) click to toggle source

Copies bookmarks, headers, todos, styles and placeholders from another Glyph::Document @param [Glyph::Document] document a valid Glyph::Document @param [Hash] data specifies which data will be inherited (e.g. bookmarks, headers, …).

By default, all data is inherited.

@example Inheriting everything except topics

doc1.inherit_from doc2, :topics => false
# File lib/glyph/document.rb, line 53
def inherit_from(document, data={})
        @bookmarks = document.bookmarks unless data[:bookmarks] == false
        @headers = document.headers unless data[:headers] == false
        @snippets = document.snippets unless data[:snippets] == false
        @todos = document.todos unless data[:todos] == false
        @styles = document.styles unless data[:styles] == false
        @topics = document.topics unless data[:topics] == false
        @placeholders = document.placeholders unless data[:placeholders] == false
        @toc = document.toc unless data[:toc] == false
        @links = document.links unless data[:links] == false
        @fragments = document.fragments unless data[:fragments] == false
        self
end
new?() click to toggle source

@return [Boolean] Returns true if the document is new, false otherwise

# File lib/glyph/document.rb, line 196
def new?
        @state == :new
end
output() click to toggle source

Returns the document output @raise [RuntimeError] unless the document is finalized.

# File lib/glyph/document.rb, line 190
def output
        raise RuntimeError, "Document is not finalized" unless finalized?
        @output
end
placeholder(&block) click to toggle source

Defines a placeholder block that will be evaluated after the whole document has been analyzed @param [Proc] &block a block taking the document itself as parameter @return [String] the placeholder key string

# File lib/glyph/document.rb, line 70
def placeholder(&block)
        key = "‡‡‡‡‡PLACEHOLDER¤#{@placeholders.length+1}‡‡‡‡‡".to_sym
        @placeholders[key] = block
        key
end
snippet(key, value) click to toggle source

Stores a new snippet @param [Symbol, String] key the snippet identifier @param [string] value the snippet contents @return [String] the stored snippet @since 0.5.0

# File lib/glyph/document.rb, line 120
def snippet(key, value)
        @snippets[key.to_sym] = value
end
snippet?(key) click to toggle source

Returns a stored snippet or nil @param [String, Symbol] key the snippet identifier @return [String, nil] the snippet contents or nil if no snippet is found @since 0.5.0

# File lib/glyph/document.rb, line 128
def snippet?(key)
        @snippets[key.to_sym]
end
structure() click to toggle source

Returns a tree of Glyph::Node objects corresponding to the analyzed document @raise [RuntimeError] unless the document has been analized

# File lib/glyph/document.rb, line 42
def structure
        raise RuntimeError, "Document has not been analyzed" unless analyzed? || finalized?
        @tree
end
style(file) click to toggle source

@since 0.4.0 Stores a stylesheet @param [String] file the stylesheet file @raise [RuntimeError] if the stylesheet is already specified for the document (unless the output has more than one file)

# File lib/glyph/document.rb, line 136
def style(file)
        f = Pathname.new file
        if @styles.include?(f) && !Glyph.multiple_output_files? then
                raise RuntimeError, "Stylesheet '#{f}' already specified for the current document" 
        end
        @styles << f
end