glyph 0.3.0 → 0.4.0

data/lib/glyph/commands/init.rb

@@ -0,0 +1,6 @@
+GLI.desc 'Create a new Glyph project'
+command :init do |c|
+	c.action do |global_options,options,args|
+		Glyph.run 'project:create', Dir.pwd
+	end
+end

data/lib/glyph/commands/outline.rb

@@ -0,0 +1,45 @@
+GLI.desc 'Display the document outline'
+command :outline do |c|
+	c.desc "Limit to level N"
+	c.flag :l, :level
+	c.desc "Show file names"
+	c.switch :f, :files
+	c.desc "Show titles"
+	c.switch :t, :titles
+	c.desc "Show IDs"
+	c.switch :i, :ids
+	c.action do |global_options, options, args|
+		levels = options[:l]
+		ids = options[:i]
+		files = options[:f]
+		titles = options[:t]
+		titles = true if !ids && !levels && !files || levels && !ids
+		Glyph['system.quiet'] = true
+		Glyph.run "generate:document"
+		Glyph['system.quiet'] = false
+		puts "====================================="
+		puts "#{Glyph['document.title']} - Outline"
+		puts "====================================="
+		Glyph.document.structure.descend do |n, level|
+			if n.is_a?(Glyph::MacroNode) then
+				case
+				when n[:name].in?(Glyph['system.structure.headers']) then
+					header = Glyph.document.header?(n[:header].code) rescue nil
+					next if !header || levels && header.level-1 > levels.to_i
+					last_level = header.level
+					h_id = ids ? "[##{header.code}]" : ""
+					h_title = titles ? "#{header.title} " : ""
+					text = ("  "*(header.level-1))+"- "+h_title+h_id
+					puts text unless text.blank?
+				when n[:name] == :include then
+					if files && n.find_parent{|p| p[:name] == :document && p.is_a?(Glyph::MacroNode)} then
+						# When using the book or article macros, includes appear twice: 
+						# * in the macro parameters
+						# * as children of the document macro
+						puts "=== #{n.param(0)}" 
+					end
+				end	
+			end
+		end
+	end
+end

data/lib/glyph/commands/stats.rb

@@ -0,0 +1,48 @@
+GLI.desc 'Display statistics'
+command :stats do |c|
+	c.desc "Display stats about macros"
+	c.switch [:m, :macros]
+	c.desc "Display stats about snippets"
+	c.switch [:s, :snippets]
+	c.desc "Display stats about bookmarks"
+	c.switch [:b, :bookmarks]
+	c.desc "Display stats about links"
+	c.switch [:l, :links]
+	c.desc "Display stats about project files"
+	c.switch [:f, :files]
+	c.desc "Display stats about a single macro"
+	c.flag :macro
+	c.desc "Display stats about a single bookmark"
+	c.flag :bookmark
+	c.desc "Display stats about links matching a regular expression"
+	c.flag :link
+	c.desc "Display stats about a single snippet"
+	c.flag :snippet
+	c.action do |global_options, options, args|
+		Glyph.info "Collecting stats..."
+		Glyph.run 'generate:document'
+		analyzer = Glyph::Analyzer.new
+		no_switches = true
+		[[:m, :macros], [:s, :snippets], [:b, :bookmarks], [:l, :links], [:f, :files]].each do |s|
+			if options[s[0]] then
+				analyzer.stats_for s[1]
+			 	no_switches = false
+			end	
+		end
+		no_flags = true
+		[:macro, :bookmark, :link, :snippet].each do |f|
+			if options[f] then
+				analyzer.stats_for f, options[f] 
+				no_flags = false
+			end
+		end
+		analyzer.stats_for :global if no_switches && no_flags 
+		puts "====================================="
+		puts "#{Glyph['document.title']} - Statistics"
+		puts "====================================="
+		puts
+		reporter = Glyph::Reporter.new(analyzer.stats)
+		reporter.detailed = false if no_switches && no_flags 
+		reporter.display
+	end
+end

data/lib/glyph/commands/todo.rb

@@ -0,0 +1,29 @@
+GLI.desc 'Display all project TODO items'
+command :todo do |c|
+	c.action do |global_options, options, args|
+		Glyph['system.quiet'] = true
+		Glyph.run "generate:document"
+		Glyph['system.quiet'] = false
+		unless Glyph.document.todos.blank?
+			puts "====================================="
+			puts "#{Glyph['document.title']} - TODOs"
+			puts "====================================="
+			# Group items
+			if Glyph.document.todos.respond_to? :group_by then
+				Glyph.document.todos.group_by{|e| e[:source]}.each_pair do |k, v|
+					puts
+					puts "=== #{k} "
+					v.each do |i|
+						puts " * #{i[:text]}"
+					end
+				end
+			else
+				Glyph.document.todos.each do |t|
+					Glyph.info t
+				end
+			end
+		else
+			Glyph.info "Nothing left to do."
+		end
+	end
+end

data/lib/glyph/config.rb

@@ -4,6 +4,8 @@ module Glyph
 	# and provides some useful methods to access keys and subkeys.
 	class Config
 
+		include Glyph::Utils
+
 		# Initializes the configuration with a hash of options:
 		# * :file (default: nil) - A YAML file to read data from
 		# * :data (default: {})- The initial contents

data/lib/glyph/document.rb

@@ -18,24 +18,28 @@ module Glyph
 			['\\|', '|']
 		]
 
-		attr_reader :bookmarks, :placeholders, :headers, :context, :errors, :todos
+		attr_reader :bookmarks, :placeholders, :headers, :styles, :context, :errors, :todos, :topics, :links, :toc
 
 		# 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
-		def initialize(tree, context)
+		def initialize(tree, context={})
 			@tree = tree
 			@context = context
-			@bookmarks = {}
+			@context[:source] ||= {:file => nil, :name => '--', :topic => nil}
 			@placeholders = {}
-			@headers = []
+			@bookmarks = {}
+			@headers = {}
+			@styles = []
 			@errors = []
 			@todos = []
+			@topics = []
+			@links = []
+			@toc = {}
 			@state = :new
 		end
 
-
 		# Returns a tree of Glyph::Node objects corresponding to the analyzed document
 		# @raise [RuntimeError] unless the document has been analized
 		def structure
@@ -43,13 +47,18 @@ module Glyph
 			@tree
 		end
 
-		# Copies bookmarks, headers, todos and placeholders from another Glyph::Document
+		# Copies bookmarks, headers, todos, styles and placeholders from another Glyph::Document
 		# @param [Glyph::Document] document a valid Glyph::Document
 		def inherit_from(document)
 			@bookmarks = document.bookmarks
 			@headers = document.headers
 			@todos = document.todos
+			@styles = document.styles
+			@topics = document.topics
 			@placeholders = document.placeholders
+			@toc = document.toc
+			@links = document.links
+			self
 		end
 
 		# Defines a placeholder block that will be evaluated after the whole document has been analyzed
@@ -63,34 +72,51 @@ module Glyph
 
 		# Returns a stored bookmark or nil
 		# @param [#to_sym] key the bookmark identifier
-		# @return [Hash, nil] the bookmark hash or nil if no bookmark is found
+		# @return [Glyph::Bookmark, nil] the bookmark or nil if no bookmark is found
 		def bookmark?(key)
 			@bookmarks[key.to_sym]
 		end
 
 		# Stores a new bookmark
-		# @param [Hash] hash the bookmark hash: {:id => "Bookmark ID", :title => "Bookmark Title"}
-		# @return [Hash] the stored bookmark (:id is converted to a symbol)
+		# @param [Hash] hash the bookmark hash: {:id => "BookmarkID", :title => "Bookmark Title", :file => "dir/preface.glyph"}
+		# @return [Glyph::Bookmark] the stored bookmark
+		# @raise [RuntimeError] if the bookmark is already defined.
 		def bookmark(hash)
-			ident = hash[:id].to_sym
-			hash[:id] = ident
-			@bookmarks[ident] = hash
-			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
 
 		# Stores a new header
-		# @param [Hash] hash the header hash: {:id => "Bookmark ID", :title => "Bookmark Title", :level => 3}
-		# @return [Hash] the stored header
+		# @param [Hash] hash the header hash: {:id => "Bookmark_ID", :title => "Bookmark Title", :level => 3}
+		# @return [Glyph::Header] the stored header
+		# @raise [RuntimeError] if the bookmark is already defined.
 		def header(hash)
-			@headers << hash
-			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] key the header identifier
-		# @return [Hash, nil] the header hash or nil if no header is found
+		# @param [String, Symbol] key the header identifier
+		# @return [Glyph::Header, nil] the header or nil if no header is found
 		def header?(key)
-			@headers.select{|h| h[:id] == key}[0] rescue nil
+			@headers[key.to_sym]
+		end
+
+		# @since 0.4.0
+		# Stores a stylesheet
+		# @param [String] file the stylesheet file
+		# @raises [RuntimeError] if the stylesheet is already specified for the document (unless the output has more than one file)
+		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
 
 		# Analyzes the document by evaluating its @tree
@@ -114,18 +140,23 @@ module Glyph
 			raise RuntimeError, "Document cannot be finalized due to previous errors" unless @context[:document].errors.blank?
 			# Substitute placeholders
 			ESCAPES.each{|e| @output.gsub! e[0], e[1]}
-			begin
-				@placeholders.each_pair do |key, value| 
-					begin
-						@output.gsub! key.to_s, value.call(self).to_s
-					rescue Glyph::MacroError => e
-						e.macro.macro_warning e.message, e
-					rescue Exception => e
-						puts e.class
-						Glyph.warning e.message
+			@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 if toc[:contents].to_s.match key_s 
+					if Glyph.multiple_output_files? then
+						@topics.each do |t|
+							ESCAPES.each{|e| t[:contents].gsub! e[0], e[1]}
+							t[:contents].gsub! key_s, value_s
+						end
 					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
-			rescue Exception => e
 			end
 			@state = :finalized
 		end

data/lib/glyph/interpreter.rb

@@ -11,7 +11,7 @@ module Glyph
 		# @param [Hash] context the context to pass along when expanding macros
 		def initialize(text, context={})
 			@context = context
-			@context[:source] ||= {:name => "--"}
+			@context[:source] ||= {:name => "--", :file => nil, :topic => nil}
 			@text = text
 			@parser = Glyph::Parser.new text, @context[:source][:name]
 		end
@@ -47,7 +47,7 @@ module Glyph
 			@document.inherit_from @context[:document] if @context[:document]
 			@tree
 		end
-	
+
 	end
 end
 

data/lib/glyph/macro.rb

@@ -8,8 +8,10 @@ module Glyph
 	class Macro
 
 		include Validators
+		include Helpers
+		include Utils
 
-		attr_reader :node, :source
+		attr_reader :node, :source_name, :source_file, :source_topic
 
 		# Creates a new macro instance from a Node
 		# @param [Node] node a node populated with macro data
@@ -17,14 +19,20 @@ module Glyph
 			@node = node
 			@name = @node[:name]
 			@updated_source = nil
-			@source = @node[:source][:name] rescue "--"
+			@source_name = @node[:source][:name] || nil rescue "--"
+			@source_topic = @node[:source][:topic] || nil rescue "--"
+			@source_file = @node[:source][:file] rescue nil
 		end
 
 		# Resets the name of the updated source (call before calling 
 		# Macro#interpret)
 		# @param [String] name the source name
-		def update_source(name)
-			@updated_source = {:node => @node, :name => name}
+		# @param [String] file the source file
+		# @param [String] topic the topic file
+		# @since 0.3.0
+		def update_source(name, file=nil, topic=nil)
+			file ||= @node[:source][:file] rescue nil
+			@updated_source = {:name => name, :file => file, :topic => topic}
 		end
 		
 		# Returns a Glyph code representation of the specified parameter
@@ -180,7 +188,7 @@ module Glyph
 			if e.is_a?(Glyph::MacroError) then
 				e.display 
 			else
-				message = "#{msg}\n    source: #{@source}\n    path: #{path}"
+				message = "#{msg}\n    source: #{@source_name}\n    path: #{path}"
 				if Glyph.debug? then
 					message << %{\n#{"-"*54}\n#{@node.to_s.gsub(/\t/, ' ')}\n#{"-"*54}} 
 					if e then
@@ -206,6 +214,7 @@ module Glyph
 				context[:document] = @node[:document]
 				interpreter = Glyph::Interpreter.new string, context
 				subtree = interpreter.parse
+				subtree[:source] = context[:source]
 				@node << subtree
 				result = interpreter.document.output
 			end

data/lib/glyph/macro_helpers.rb

@@ -0,0 +1,280 @@
+module Glyph
+	class Macro
+
+		# This module includes some output-agnostic methods used by the most common Glyph macros.
+		# @since 0.4.0
+		module Helpers
+
+			# Renders a link
+			# @param [String] target the target of the link
+			# @param[String] title the title of the link
+			# @yield [link_path, link_title] the block to call to render the link
+			# @yieldparam [String] link_path the path to the link target
+			# @yieldparam [String] link_title the title of the link
+			def link_element_for(target, title, &block)
+				if target.match /^#/ then
+					@node[:document].links << target 
+					anchor = target.gsub /^#/, ''
+					bmk = bookmark? anchor
+					if !bmk then
+						placeholder do |document|
+							bmk = document.bookmark?(anchor)
+							macro_error "Bookmark '#{anchor}' does not exist" unless bmk
+							bmk_title = title
+							bmk_title = bmk.title if bmk_title.blank?
+							block.call bmk.link(@source_file), bmk_title
+						end
+					else
+						bmk_title = title
+						bmk_title = bmk.title if bmk_title.blank?
+						block.call bmk.link(@source_file), bmk_title
+					end
+				else
+					if Glyph['options.url_validation'] && !@node[:document].links.include?(target) then
+						begin
+							url = URI.parse(target.gsub(/\\\./, ''))
+						rescue Exception => e
+							macro_warning "Invalid URL: #{url||target}", e
+						end
+						response = Net::HTTP.get_response(url)
+						debug "Checking link URL: #{url} (#{response.code})"
+						if response.code.to_i > 302 then
+							macro_warning "Linked URL '#{url}' returned status #{response.code} (#{response.message})"
+						end
+					end
+					@node[:document].links << target 
+					title ||= target
+					block.call target, title
+				end
+			end
+
+			# Renders a For More Information note
+			# @param [String] topic the topic of the note
+			# @param [String] href the reference to link to
+			# @yield [topic, link] the block used to render the FMI note
+			def fmi_element_for(topic, href, &block)
+				link = placeholder do |document| 
+					interpret "link[#{href}]"
+				end
+				block.call topic, link
+			end
+
+			# Renders a draft comment element
+			# @yield [value] the block used to render the comment
+			# @yieldparam [String] value the comment text
+			def draftcomment_element(&block)
+				if Glyph['document.draft'] then
+					block.call value
+				else
+					""
+				end
+			end
+
+			# Renders a todo element
+			# @yield [value] the block used to render the todo element 
+			# @yieldparam [String] value the todo text
+			def todo_element(&block)
+				todo = {:source => @source_name, :text => value}
+				@node[:document].todos << todo unless @node[:document].todos.include? todo
+				if Glyph['document.draft']  then
+					block.call value
+				else
+					""
+				end
+			end
+
+			# Renders an image element
+			# @param [String] image the image to render
+			# @param [String] alt the value of the image's ALT tag
+			# @yield [alt, dest_file] the block used to render the image
+			def image_element_for(image, alt, &block)
+				src_file = Glyph.lite? ? image : Glyph::PROJECT/"images/#{image}"
+				dest_file = Glyph.lite? ? image : "images/#{image}"
+				warning "Image '#{image}' not found" unless Pathname.new(src_file).exist? 
+				block.call alt, dest_file
+			end
+
+			# Renders a figure element
+			# @param [String] image the image to render
+			# @param [String] alt the value of the image's ALT tag
+			# @param [String] caption
+			# @yield alt, dest_file, caption] the block used to render the figure
+			def figure_element_for(image, alt, caption, &block)
+				src_file = Glyph.lite? ? image : Glyph::PROJECT/"images/#{image}"
+				dest_file = Glyph.lite? ? image : "images/#{image}"
+				warning "Figure '#{image}' not found" unless Pathname.new(src_file).exist? 
+				block.call alt, dest_file, caption
+			end
+
+			# Renders a title element
+			def title_element(&block)
+				unless Glyph["document.title"].blank? then
+					block.call
+				else
+					""
+				end
+			end
+
+			# Renders a subtitle element
+			def subtitle_element(&block)
+				unless Glyph["document.subtitle"].blank? then
+					block.call
+				else
+					""
+				end
+			end
+
+			# Renders an author element
+			def author_element(&block)
+				unless Glyph['document.author'].blank? then
+					block.call
+				else
+					""
+				end
+			end
+
+			# Renders a revision element
+			def revision_element(&block)
+				unless Glyph["document.revision"].blank? then
+					block.call
+				else
+					""
+				end
+			end
+
+			# Renders a Table of Contents
+			# @param [Integer] depth the maximum header level
+			# @param [String] title the title of the TOC
+			# @param [Hash] procs the Proc objects used to render the TOC
+			# @option procs [Proc] :link used to render TOC header links (parameters: Glyph::Header). 
+			# @option procs [Proc] :toc_list used to render the TOC list (parameters: a Proc used to traverse the document tree, the Glyph::Bookmark used for the TOC header, a Glyph::Document)
+			# @option procs [Proc] :toc_item used to render a TOC item (parameters: an Array of header classes, a String used for the header link)
+			# @option procs [Proc] :toc_sublist used to render a TOC sublist (parameters: a String containing the contents of the list)
+			def toc_element_for(depth, title, procs={})
+				return @node[:document].toc[:contents] if @node[:document].toc[:contents]
+				link_header = procs[:link]
+				toc = placeholder do |document|
+					descend_section = lambda do |n1, added_headers|
+						list = ""
+						added_headers ||= []
+						n1.descend do |n2, level|
+							if n2.is_a?(Glyph::MacroNode) && Glyph['system.structure.headers'].include?(n2[:name]) then
+								if Glyph.multiple_output_files? then
+									# Only consider topics/booklets when building TOC for web/web5
+									next if !n2.attribute(:src) && n2.child_macros.select{|child| child.attribute(:src)}.blank? 
+								end
+								next if n2.find_parent{|node| Glyph['system.structure.special'].include? node[:name] }
+								header_hash = n2[:header]
+								next if depth && header_hash && (header_hash.level-1 > depth.to_i) || header_hash && !header_hash.toc?
+								next if added_headers.include? header_hash
+								added_headers << header_hash
+								# Check if part of frontmatter, bodymatter or backmatter
+								container = n2.find_parent do |node| 
+									node.is_a?(Glyph::MacroNode) && 
+										node[:name].in?([:frontmatter, :bodymatter, :appendix, :backmatter])
+								end[:name] rescue nil
+								list << procs[:toc_item].call([container, n2[:name]], link_header.call(header_hash)) if header_hash
+								child_list = ""
+								n2.children.each do |c|
+									child_list << descend_section.call(c, added_headers)
+								end	
+								list << procs[:toc_sublist].call(child_list) unless child_list.blank?
+							end
+						end
+						list
+					end
+					title ||= "Table of Contents"
+					bmk = @node[:document].bookmark?(:toc) || bookmark(:id => :toc, :file => @source_file, :title => title)
+					procs[:toc_list].call descend_section, bmk, document
+				end
+				@node[:document].toc[:contents] = toc.to_s
+				toc
+			end
+
+			# Renders a section element
+			# @param [Hash] procs the Proc objects used to render the section
+			# @option procs [Proc] :title used to render the section header (parameters: the header level, the section ID, the section title)
+			# @option procs [Proc] :body used to render the section body (parameters: the section title, the section body)
+			def section_element_for(procs={})
+				h = ""
+				if attr(:title) then
+					level = 1
+					@node.ascend do |n| 
+						break if n.respond_to?(:attribute) && n.attribute(:class) && n.attribute(:class).children.join.strip == "topic"
+						if n.is_a?(Glyph::MacroNode) && Glyph["system.structure.headers"].include?(n[:name]) then
+							level+=1
+						end
+					end
+					ident = (attr(:id) || "h_#{@node[:document].headers.length+1}").to_sym
+					# The bookmark is added when the section is first processed; therefore it will exist already when a topic layout is processed
+					bmk = @node[:document].bookmark?(ident)
+					bmk ||=  header	:title => attr(:title), 
+													:level => level, 
+													:id => ident, 
+													:toc => !attr(:notoc),
+													:definition => @source_file,
+													:file => (attr(:src) || @source_file)
+					@node[:header] = bmk
+					h = procs[:title].call level, bmk, attr(:title)
+				end
+				if attr(:src) then 
+					# Create topic
+					if Glyph.multiple_output_files? 
+						topic_id = (attr(:id) || "t_#{@node[:document].topics.length}").to_sym
+						layout = attr(:layout) || Glyph["output.#{Glyph['document.output']}.layouts.topic"] || :topic
+						layout_name = "layout:#{layout}".to_sym
+						macro_error "Layout '#{layout}' not found" unless Glyph::MACROS[layout_name]
+						result = interpret %{#{layout_name}[
+											@title[#{attr(:title)}]
+											@id[#{topic_id}]
+											@contents[include[@topic[true]#{attr(:src)}]]
+									]}
+						bmk = @node[:document].bookmark? topic_id
+						if bmk then
+							# Fix file for topic bookmark
+							@node[:document].bookmark?(topic_id).file = attr(:src)
+						else
+							bookmark :title => attr(:title), :id => topic_id, :file => attr(:src), :definition => @source_file
+						end
+						topic_src = attr(:src)
+						topic_src += ".glyph" unless topic_src.match /\..+$/
+						@node[:document].topics << {:src => topic_src, :title => attr(:title), :id => topic_id, :contents => result}
+						# Process section contents
+						procs[:body].call h, value
+						# Return nothing
+						nil
+					else
+						v = raw_value
+						@node.children.delete_if{|c| !c.is_a?(Glyph::AttributeNode)}
+						body = interpret "include[#{attr(:src)}]#{v}"
+						procs[:body].call h, body
+					end
+				else
+					procs[:body].call h, value
+				end
+			end
+
+			# Renders a navigation element
+			# @param [String] topic_id the ID of the current topic
+			# @param [Hash] procs the Proc objects used to render the navigation element
+			#	@option procs [Proc] :previous the link to the previous topic
+			#	@option procs [Proc] :next the link to the next topic 
+			#	@option procs [Proc] :contents the link to the document contents 
+			def navigation_element_for(topic_id, procs={})
+				# Get the previous topic
+				previous_topic = @node[:document].topics.last
+				previous_link = procs[:previous].call previous_topic
+				# The next topic is not going to be available yet, use a placeholder
+				next_link = placeholder do |document|
+					current_topic = document.topics.select{|t| t[:id] == topic_id}[0] rescue nil
+					next_topic = document.topics[document.topics.index(current_topic)+1] rescue nil
+					procs[:next].call next_topic
+				end
+				contents_link = procs[:contents].call
+				procs[:navigation].call contents_link, previous_link, next_link
+			end
+
+
+		end
+	end
+end