glyph 0.3.0 → 0.4.0

data/lib/glyph/macro_validators.rb

@@ -77,6 +77,18 @@ module Glyph
 				end
 			end
 
+			# Ensures that the macro receives the specified attribute
+			# @param [String, Symbol] name the name of the attribute
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
+			# @since 0.4.0
+			def required_attribute(name, options={:level=>:error})
+				validate("Macro '#{@name}' requires a '#{name}' attribute", options) do
+					!raw_attribute(name.to_sym).blank?
+				end
+			end
+
 			# Ensures that the macro receives no parameters.
 			# @param [Hash] options a hash containing validation options
 			# @option options :level the error level (:error, :warning)
@@ -133,8 +145,31 @@ module Glyph
 					macro_error "Mutual Inclusion in #{check_type}(#{arg}): '#{check_value}'", Glyph::MutualInclusionError 
 				end
 			end
-		end
 
-	end
+			# Ensure that the macros is within another
+			# @param [String, Symbol] arg the name of the container macro
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
+			# @since 0.4.0
+			def within(arg, options={:level => :error})
+				validate("Macro '#{@name}' must be within a '#{arg}' macro", options) do 
+					@node.find_parent {|n| Glyph.macro_eq? arg.to_sym, n[:name]}
+				end
+			end
+
+			# Ensure that the macros is _not_ within another
+			# @param [String, Symbol] arg the name of the container macro
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
+			# @since 0.4.0
+			def not_within(arg, options={:level => :error})
+				validate("Macro '#{@name}' must not be within a '#{arg}' macro", options) do 
+					!@node.find_parent {|n| Glyph.macro_eq? arg.to_sym, n[:name]}
+				end
+			end
 
+		end
+	end
 end

data/lib/glyph/reporter.rb

@@ -0,0 +1,182 @@
+module Glyph
+
+	# This class is used to display statistics collected by a Glyph::Analyzer. 
+	# @since 0.4.0
+	class Reporter
+
+		include Glyph::Utils
+
+		attr_accessor :detailed
+
+		# Initializes the reporter
+		# @param [Hash] stats the collected statistics
+		def initialize(stats)
+			@stats = stats
+			@detailed = true
+		end
+
+		# Displays the statistics
+		def display
+			[:files, :macros, :snippets, :bookmarks, :links, 
+				:macro, :snippet, :bookmark, :link].each do |s|
+				unless @stats[s].blank? then
+					send :"display_#{s}" 
+					puts
+				end
+			end
+		end
+
+		protected
+
+		def display_macros
+			s = @stats[:macros]
+			section :macros
+			total :macro_instances, s[:instances].length
+			total :macro_definitions, s[:definitions].length
+			total :macro_aliases, s[:aliases].length
+			total :used_macro_definitions, s[:used_definitions].length
+			if @detailed then
+				inline_list :macro_definitions, s[:definitions]
+				inline_list :used_macro_definitions, s[:used_definitions] 
+			end
+		end
+
+		def display_macro
+			s = @stats[:macro]
+			alias_for = s[:alias_for] ? " (alias for: #{s[:alias_for]})" : " "
+			section "Macro '#{s[:param]}'#{alias_for}"
+			total :instances, s[:instances].length
+			occurrences s[:files] if @detailed
+		end
+
+		def display_bookmarks
+			s = @stats[:bookmarks]
+			section :bookmarks
+			total :bookmarks, s[:codes].length
+			total :referenced_bookmarks, s[:referenced].length
+			total :unreferenced_bookmarks, s[:unreferenced].length
+			if @detailed then
+				inline_list :bookmarks, s[:codes]
+				occurrences s[:referenced], "Referenced Bookmarks:"
+				inline_list :unreferenced_bookmarks, s[:unreferenced]
+			end
+		end
+
+		def display_bookmark
+			s = @stats[:bookmark]
+			b_type = (s[:type] != :bookmark) ? " (#{s[:type]})" : " " 
+			section "Bookmark '#{s[:param]}'#{b_type}"
+			if s[:file] == s[:definition] then
+				info "Defined in: #{s[:file]}"
+			else
+				info "Defined in: #{s[:definition]} (pointing to: #{s[:file]})"
+			end
+			occurrences s[:references], "Referenced in:" if @detailed 
+		end
+
+		def display_snippets
+			s = @stats[:snippets]
+			section :snippets
+			total :snippets, s[:definitions].length
+			total :used_snippets, s[:used].length
+			total :unused_snippets, s[:unused].length
+			if @detailed then
+				inline_list :snippets, s[:definitions]
+				inline_list :used_snippets, s[:used]
+				inline_list :unused_snippets, s[:unused]
+			end
+		end
+
+		def display_snippet
+			s = @stats[:snippet]
+			section "Snippet '#{s[:param]}'"
+			info "Definition:"
+			puts "-------------------"
+			puts SNIPPETS[s[:param]]
+			puts "-------------------"
+			total :used_instances, s[:stats][:total]
+			occurrences s[:stats][:files], "Usage Details:" if @detailed
+		end
+
+		def display_links
+			s = @stats[:links]
+			section :links
+			total :internal_links, s[:internal].length
+			occurrences s[:internal], "Internal Links" if @detailed
+			total :external_links, s[:external].length
+			occurrences s[:external], "External Links" if @detailed
+		end
+
+		def display_link
+			s = @stats[:link]
+			section "Links matching /#{s[:param]}/"
+			total :links, s[:stats].length
+			occurrences s[:stats], "Link Targets:"
+			grouped_occurrences s[:stats], "Details:" if @detailed
+		end
+
+		def display_files
+			s = @stats[:files]
+			section :files 
+			total :files, s.values.inject{|sum, n| sum+n}
+			total "/text    --", s[:text]
+			total "/images  --", s[:images]
+			total "/styles  --", s[:styles]
+			total "/layouts --", s[:layouts]
+			total "/lib     --", s[:lib]
+		end
+
+
+		private
+
+		def total(objects, total)
+			label = objects.is_a?(Symbol) ? "Total #{objects.to_s.title_case}:" : objects
+			info "#{label} #{total}"
+		end
+
+		def section(name)
+			puts "===== #{(name.is_a? Symbol) ? name.to_s.title_case : name}"
+		end
+
+		def inline_list(name, arr)
+			return if arr.blank?
+			label = name.to_s.title_case
+			columns = 5
+			max = arr.map{|e| e.to_s.length}.max
+			if arr.length < columns+1 then
+				info "#{label}: #{arr.join(', ')}"
+			else
+				info "#{label}:"
+				count = 0
+				arr.each do |i|
+					print "     " if count%columns == 0 
+					print "#{i}#{' '*(max-i.to_s.length+1)}"
+					print "\n" if count%columns == 4
+					count +=1
+				end
+				puts
+			end
+		end
+
+		def occurrences(arr, label="Occurrences:")
+			return if arr.blank?
+			info label
+			arr.each do |f|
+				total = f[1].is_a?(Numeric) ? "(#{f[1]})" : ""
+				puts "   - #{f[0]} #{total}"
+			end
+		end
+
+		def grouped_occurrences(arr, label="Details:")
+			return if arr.blank?
+			info label
+			arr.each do |f|
+				puts "   - #{f[0]} (#{f[1][:total]})"
+				f[1][:files].each do |i|
+					puts "     - #{i[0]} (#{i[1]})"
+				end
+			end
+		end
+
+	end
+end

data/lib/glyph/syntax_node.rb

@@ -11,6 +11,18 @@ module Glyph
 			""
 		end
 
+		# @return [String] a textual representation of self
+		# @since 0.4.0
+		def inspect
+			string = ""
+			descend do |e, level|
+				# Remove document key to avoid endless resursion
+				hash = e.to_hash.reject{|k,v| k == :document}
+				string << "  "*level+"(#{e.class})"+hash.inspect+"\n"
+			end
+			string.chomp
+		end
+
 		# @return [String] the value of the :value key
 		# @since 0.3.0
 		def evaluate(context, options={})
@@ -49,7 +61,7 @@ module Glyph
 			e = self[:escape] ? "=" : ""
 			"#{self[:name]}["+e+attributes.join+parameters.join("|")+e+"]"
 		end
-
+		
 		# Expands the macro
 		# @return [String] the value of the macro
 		# @since 0.3.0
@@ -63,7 +75,16 @@ module Glyph
 			children.select{|n| n.is_a? ParameterNode }
 		end
 
-		# 
+		# @return [Array<Glyph::MacroNode>] an array of the child macro nodes
+		# @since 0.4.0
+		def child_macros
+			macros = []
+			parameters.each do |p|
+				macros += p.children.select{|n| n.is_a? MacroNode }
+			end
+			macros
+		end
+
 		# Returns the parameter syntax node at the specified index
 		# @param [Fixnum] n the index of the parameter 
 		# @return [Glyph::ParameterNode, nil] a parameter node
@@ -103,15 +124,21 @@ module Glyph
 		# @since 0.3.0 
 		def expand(context)
 			xml_element(context)	
-			self.merge!({
-				:source => context[:source], 
-				:document => context[:document], 
-				:info => context[:info],
-				:value => ""
-			})
+			self[:source] = context[:source]
+			self[:document] = context[:document] 
+			self[:info] = context[:info]
+			self[:value] = ""
 			Glyph::Macro.new(self).expand
 		end
 
+		# Returns where the macro was used (used in Glyph::Analyzer)
+		# @since 0.4.0
+		def source
+			s = self[:source][:file] rescue nil 
+			s ||= self[:source][:name] rescue nil
+			s
+		end
+
 		protected
 
 		def xml_element(context)
@@ -123,11 +150,11 @@ module Glyph
 			end
 			case
 				# Use XML syntax
-			when Glyph['language.set'] == 'xml' then
+			when Glyph['options.macro_set'] == 'xml' then
 				self[:element] = name
 				self[:name] = :"|xml|" 
 				# Fallback to XML syntax
-			when Glyph['language.options.xml_fallback'] then
+			when Glyph["options.xml_fallback"] then
 				unless known_macro then
 					self[:element] = name
 					self[:fallback] = true

data/lib/glyph/system_extensions.rb

@@ -1,49 +1,12 @@
-module Kernel
-
-	# Dumps and serialize an object to a YAML file
-	# @param [#to_s] file the file to write to
-	# @param [Object] obj the object to serialize
-	def yaml_dump(file, obj)
-		File.open(file.to_s, 'w+') {|f| f.write obj.to_yaml}
-	end
-
-	# Loads and deserialiaze the contents of a YAML file
-	# @param [#to_s] file the YAML file to load
-	# @return [Object] the contents of the YAML file, deserialized
-	def yaml_load(file)
-		YAML.load_file(file.to_s)
-	end
-
-	# Loads the contents of a file
-	# @param [#to_s] file the file to load
-	# @return [String] the contents of the file
-	def file_load(file)
-		result = ""
-		File.open(file.to_s, 'r') do |f|
-			while l = f.gets 
-				result << l
-			end
-		end
-		result
-	end
-
-	# Writes a string to a file
-	# @param [#to_s] file the file to write
-	# @param [String] contents the string to write
-	# @return [String] the string written to the file
-	def file_write(file, contents="")
-		File.open(file.to_s, 'w+') do |f|
-			f.print contents
-		end
-		contents
+class Symbol
+	def <=>(b)
+		self.to_s <=> b.to_s
 	end
+end
 
-	# An alias for FileUtils#cp
-	# @param [String] source the source file
-	# @param [String] dest the destination file or directory
-	# @param [Hash] options copy options
-	def file_copy(source, dest, options={})
-		FileUtils.cp source, dest, options
+class String
+	def title_case
+		self.snake_case.split('_').map{|s| s.capitalize}.join(' ')
 	end
-
 end
+

data/lib/glyph/utils.rb

@@ -0,0 +1,148 @@
+module Glyph
+	#@since 0.4.0
+	module Utils
+
+		# Prints a message
+		# @param [String] message the message to print
+		def msg(message)
+			puts message unless Glyph['system.quiet']
+		end
+
+		# Prints an informational message
+		# @param [String] message the message to print
+		def info(message)
+			puts "-- #{message}" unless Glyph['system.quiet']
+		end
+
+		# Prints a warning
+		# @param [String] message the message to print
+		def warning(message)
+			puts "-> warning: #{message}" unless Glyph['system.quiet']
+		end
+
+		# Prints an error
+		# @param [String] message the message to print
+		def error(message)
+			puts "=> error: #{message}" unless Glyph['system.quiet']
+		end
+
+		# Prints a message if running in debug mode
+		# @param [String] message the message to print
+		def debug(message)
+			puts message if Glyph.debug?
+		end
+
+		# Dumps and serialize an object to a YAML file
+		# @param [#to_s] file the file to write to
+		# @param [Object] obj the object to serialize
+		def yaml_dump(file, obj)
+			File.open(file.to_s, 'w+') {|f| f.write obj.to_yaml}
+		end
+
+		# Loads and deserialiaze the contents of a YAML file
+		# @param [#to_s] file the YAML file to load
+		# @return [Object] the contents of the YAML file, deserialized
+		def yaml_load(file)
+			YAML.load_file(file.to_s)
+		end
+
+		# Loads the contents of a file
+		# @param [#to_s] file the file to load
+		# @return [String] the contents of the file
+		def file_load(file)
+			result = ""
+			File.open(file.to_s, 'r') do |f|
+				while l = f.gets 
+					result << l
+				end
+			end
+			result
+		end
+
+		# Writes a string to a file
+		# @param [#to_s] file the file to write
+		# @param [String] contents the string to write
+		# @return [String] the string written to the file
+		def file_write(file, contents="")
+			File.open(file.to_s, 'w+') do |f|
+				f.print contents
+			end
+			contents
+		end
+
+		# An alias for FileUtils#cp
+		# @param [String] source the source file
+		# @param [String] dest the destination file or directory
+		# @param [Hash] options copy options
+		def file_copy(source, dest, options={})
+			FileUtils.cp source, dest, options
+		end
+
+		# Loads all child elements of the given directory, matching a given extension
+		# @param [Pathname] dir the directory containing the files
+		# @param [String] extension the file extension to check
+		# @yield [file, contents] the file (Pathname) and its contents
+		# @since 0.4.0
+		def load_files_from_dir(dir, extension, &block)
+			if dir.exist? then
+				dir.children.each do |c|
+					block.call(c, file_load(c)) unless c.directory? || c.extname != extension
+				end
+			end
+		end
+
+		# Iterates through the files in a source directory recursively
+		# @param [String] dir the directory to operate on (mirrored in the output directory)
+                # @yield [src, dest] the source file and the corresponding output file
+		# @since 0.4.0
+		def with_files_from(dir, &block)
+			output = (Glyph['document.output'] == 'pdf') ? 'html' : Glyph['document.output']
+			dir_path = Glyph::PROJECT/"output/#{output}/#{dir}"
+			dir_path.mkpath
+			(Glyph::PROJECT/dir).find do |i|
+				if i.file? then
+					dest = "#{Glyph::PROJECT/"output/#{output}/#{dir}"}/#{i.relative_path_from(Glyph::PROJECT/dir)}"
+					src = i.to_s
+					Pathname.new(dest).parent.mkpath
+					block.call src, dest
+				end
+			end
+		end
+
+		# Returns true if the macro name is used as an alias
+		# @param [String, Symbol] name the macro name to check
+		def macro_alias?(name)
+			ALIASES[:by_alias].include? name.to_sym
+		end
+
+		# Returns the name of the macro definition referenced by the supplied alias
+		# @param [String, Symbol] name the alias name to check
+		def macro_definition_for(name)
+			ALIASES[:by_alias][name.to_sym]
+		end
+
+		def macro_aliases_for(name)
+			ALIASES[:by_def][name.to_sym]
+		end
+
+		# Returns true if the macro names point to the same definition
+		# @param [String, Symbol] ident1 the first macro to compare
+		# @param [String, Symbol] ident2 the second macro to compare
+		def macro_eq?(ident1, ident2)
+			Glyph::MACROS[ident1.to_sym] == Glyph::MACROS[ident2.to_sym]
+		end
+
+		# Returns true if the PROJECT constant is set to a valid Glyph project directory
+		def project?
+			children = ["text", "snippets.yml", "config.yml", "document.glyph"].sort
+			actual_children = PROJECT.children.map{|c| c.basename.to_s}.sort 
+			(actual_children & children) == children
+		end
+
+		# Returns true if multiple output files are being generated
+		def multiple_output_files?
+			Glyph["output.#{Glyph['document.output']}.multifile"]
+		end
+
+	end
+end