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
Public Class Methods
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
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
@return [Boolean] Returns true if the document is analyzed, false otherwise
# File lib/glyph/document.rb, line 201 def analyzed? @state == :analyzed end
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
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
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
@return [Boolean] Returns true if the document is analyzed, false otherwise
# File lib/glyph/document.rb, line 206 def finalized? @state == :finalized end
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
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
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
@return [Boolean] Returns true if the document is new, false otherwise
# File lib/glyph/document.rb, line 196 def new? @state == :new end
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
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
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
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
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
@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