glyph 0.2.0 → 0.3.0

data/lib/glyph/macro_validators.rb

@@ -1,48 +1,140 @@
 module Glyph
 	class Macro
 
+		# @since 0.2.0
 		module Validators
 
 			# Validates the macro according to the specified block
 			# @param [String] message the message to display if the validation fails.
-			# @param [Hash] options a hash containing validation options (for now the only option is :level)
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
 			# @example
-			#     validate("Invalid macro value", :level => :error) {@value == 'valid'} # Raises an error in case of failure
-			#     validate("Invalid macro value", :level => :warning) {@value == 'valid'} # Displays a warning in case of failure
+			#     validate("Invalid macro value", :level => :error) {value == 'valid'} # Raises an error in case of failure
+			#     validate("Invalid macro value", :level => :warning) {value == 'valid'} # Displays a warning in case of failure
 			def validate(message, options={:level => :error}, &block)
-				unless instance_eval(&block) then
+				result = instance_eval(&block)
+				unless result then
 					send("macro_#{options[:level]}".to_sym, message)
 				end
+				result
+			end
+
+			# Ensures that the macro element attributes is a valid XML element name.
+			# @param [Hash] options a hash containing validation options (for now the only option is :level)
+			# @return [Boolean] whether the validation passed or not
+			# @since 0.3.0
+			def valid_xml_element(options={:level => :error})
+				validate("Invalid XML element '#{@node[:element]}'", options) { @node[:element].to_s.match(/^([^[:punct:]0-9<>]|_)[^<>"']*/) }
+			end
+
+			# Ensures that a macro attribute name is a valid XML attribute name.
+			# @param [String, Symbol] name the attribute name to validate
+			# @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.3.0
+			def valid_xml_attribute(name, options={:level => :warning})
+				validate("Invalid XML attribute '#{name}'", options) { name.to_s.match(/^([^[:punct:]0-9<>]|_)[^<>"']*/) }
 			end
 
 			# Ensures that the macro receives up to _n_ parameters.
 			# @param [Integer] n the maximum number of parameters allowed for the macro.
-			# @param [Hash] options a hash containing validation options (for now the only option is :level)
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
 			def max_parameters(n, options={:level=>:error})
-				validate("Macro '#{@name}' takes up to #{n} parameter(s) (#{params.length} given)", options) { params.length <= n }
+				validate("Macro '#{@name}' takes up to #{n} parameter(s) (#{@node.params.length} given)", options) do
+					if n == 0 then
+						no_parameters options
+					else
+						@node.params.length <= n 
+					end
+				end
 			end
 
 			# Ensures that the macro receives at least _n_ parameters.
 			# @param [Integer] n the minimum number of parameters allowed for the macro.
-			# @param [Hash] options a hash containing validation options (for now the only option is :level)
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
 			def min_parameters(n, options={:level=>:error})
-				validate("Macro '#{@name}' takes at least #{n} parameter(s) (#{params.length} given)", options) { params.length >= n }
+				validate("Macro '#{@name}' takes at least #{n} parameter(s) (#{@node.params.length} given)", options) { @node.params.length >= n }
 			end
 
 			# Ensures that the macro receives exactly _n_ parameters.
 			# @param [Integer] n the number of parameters allowed for the macro.
-			# @param [Hash] options a hash containing validation options (for now the only option is :level)
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
 			def exact_parameters(n, options={:level=>:error})
-				validate("Macro '#{@name}' takes exactly #{n} parameter(s) (#{params.length} given)", options) { params.length == n }
+				validate("Macro '#{@name}' takes exactly #{n} parameter(s) (#{@node.params.length} given)", options) do
+					if n == 0 then
+						no_parameters options
+					else
+						@node.params.length == n 
+					end
+				end
 			end
 
 			# Ensures that the macro receives no parameters.
-			# @param [Hash] options a hash containing validation options (for now the only option is :level)
+			# @param [Hash] options a hash containing validation options
+			# @option options :level the error level (:error, :warning)
+			# @return [Boolean] whether the validation passed or not
 			def no_parameters(options={:level=>:error})
-				validate("Macro '#{@name}' takes no parameters (#{params.length} given)", options) { params.length == 0 }
+				validate("Macro '#{@name}' takes no parameters (#{@node.params.length} given)", options) do 
+					case @node.params.length
+					when 0 then
+						true
+					when 1 then
+						result = true
+						@node.param(0).children.each do |p|
+							result = p.is_a?(Glyph::TextNode) && p[:value].blank?
+							break unless result
+						end
+						result
+					else
+						false
+					end
+				end
+			end
+
+			# Raises a macro error if Glyph is running in safe mode.
+			# @raise [Glyph::MacroError] the macro cannot be used allowed in safe mode
+			# @since 0.3.0
+			def safety_check
+				macro_error "Macro '#@name' cannot be used in safe mode" if Glyph.safe?
 			end
 
+			# Ensure that no mutual inclusion occurs within the specified parameter or attribute
+			# @param [Fixnum, Symbol] the parameter index or attribute name to check
+			# @raise [Glyph::MacroError] mutual inclusion was detected
+			# @since 0.3.0
+			def no_mutual_inclusion_in(arg)
+				check_type = arg.is_a?(Symbol) ? :attribute : :parameter
+				check_value = nil
+				found = @node.find_parent do |n|
+					if n.is_a?(Glyph::MacroNode) && Glyph::MACROS[n[:name]] == Glyph::MACROS[@name] then
+						case check_type
+						when :attribute then
+							check_value = n.children.select do |node| 
+								node.is_a?(Glyph::AttributeNode) && node[:name] == arg
+							end[0][:value] rescue nil
+							check_value == attr(arg) 
+						when :parameter then
+							check_value = n.children.select do |node| 
+								node.is_a?(Glyph::ParameterNode) && node[:name] == :"#{arg}"
+							end[0][:value] rescue nil
+							check_value == param(arg) 
+						end
+					end
+				end
+				if found then
+					macro_error "Mutual Inclusion in #{check_type}(#{arg}): '#{check_value}'", Glyph::MutualInclusionError 
+				end
+			end
 		end
 
 	end
+
 end

data/lib/glyph/node.rb

@@ -135,4 +135,28 @@ class Node < Hash
 		ascend(parent) {|e| return e unless e.parent }
 	end
 
+	# Converts self to a hash
+	# @return [Hash] the converted hash
+	# @since 0.3.0
+	def to_hash
+		{}.merge(self)
+	end
+
+	# @return [String] a textual representation of self
+	# @since 0.3.0
+	def inspect
+		string = ""
+		descend do |e, level|
+			string << "  "*level+e.to_hash.inspect+"\n"
+		end
+		string.chomp
+	end
+	
+	# @return (Boolean) true if the nodes are equal
+	# @since 0.3.0
+	def ==(node)
+		return false unless node.is_a? Node
+	 	self.to_hash == node.to_hash && self.children == node.children
+	end
+
 end

data/lib/glyph/parser.rb

@@ -0,0 +1,278 @@
+# encoding: utf-8
+require 'strscan'
+
+module Glyph
+
+	# The Glyph::Parser class can parse a string of text containing Glyph macros and produce the
+	# corresponding syntax tree.
+	# @since 0.3.0
+	class Parser
+
+		# Initializes the parser.
+		# @param [String] text the text to parse
+		# @param [String] source_name the name of the source file (stored in the root node) 
+		# @since 0.3.0
+		def initialize(text, source_name="--")
+			@source_name = source_name || "--"
+			@input = StringScanner.new text
+			@output = create_node DocumentNode, :name => @source_name.to_sym
+			@current_macro = nil
+			@current_attribute = nil
+		end
+
+		# Parses the string of text provided during initialization
+		# @return [Glyph::SyntaxNode] the Abstract Syntax Tree corresponding to the string
+		# @since 0.3.0
+		def parse
+			count = 0
+			while result = parse_contents(@output) do
+				@output << result
+				count +=1
+			end
+			if @input.pos < @input.string.length then
+				current_char = @input.string[@input.pos].chr
+				illegal_delimiter = current_char.match(/\]|\[/) rescue nil
+				error "Macro delimiter '#{current_char}' not escaped" if illegal_delimiter
+			end
+			@output
+		end
+
+		protected
+
+		def parse_contents(current)
+			escape_sequence(current) || 
+				parameter_delimiter(current) || 
+				escaping_attribute(current) || 
+				escaping_macro(current) || 
+				attribute(current) || 
+				macro(current) || 
+				text(current)
+		end
+
+		def parse_escaped_contents(current)
+			escape_sequence(current) || parameter_delimiter(current) || escaped_text(current)
+		end
+
+		def escaping_macro(current)
+			if @input.scan(/[^\[\]\|\\\s]+\[\=/) then
+				name = @input.matched
+				name.chop!
+				name.chop!
+				error "#{name}[...] - A macro cannot start with '@' or a digit." if name.match(/^[0-1@]/)
+				node = create_node(MacroNode, {
+					:name => name.to_sym, 
+					:escape => true, 
+					:attributes => [], 
+					:parameters => []
+				})
+				while contents = parse_escaped_contents(node) do
+					node << contents unless contents.is_a?(AttributeNode)
+				end
+				@input.scan(/\=\]/) or error "Escaping macro '#{name}' not closed"		
+				organize_children_for node
+				node
+			else
+				nil
+			end
+		end
+
+		def escaping_attribute(current)
+			if @input.scan(/@[^\[\]\|\\\s]+\[\=/) then
+				error "Attributes cannot be nested" if @current_attribute
+				name = @input.matched[1..@input.matched.length-3]
+				node = create_node(AttributeNode, {
+					:escape => true, 
+					:name => name.to_sym
+				})
+				while contents = parse_escaped_contents(node) do
+					node << contents
+				end
+				current[:attributes] << node
+				@input.scan(/\=\]/) or error "Attribute @#{name} not closed"		
+				node
+			else
+				nil
+			end
+		end
+
+		def macro(current)
+			if @input.scan(/[^\[\]\|\\\s]+\[/) then
+				name = @input.matched
+				name.chop!
+				error "#{name}[...] - A macro cannot start with '@' or a digit." if name.match(/^[0-1@]/)
+				node = create_node(MacroNode, {
+					:escape => false, 
+					:name => name.to_sym, 
+					:attributes => [], 
+					:parameters => []
+				})
+				while contents = parse_contents(node) do
+					node << contents unless contents.is_a?(AttributeNode)
+				end
+				@input.scan(/\]/) or error "Macro '#{name}' not closed"		
+				organize_children_for node
+				node
+			else
+				nil
+			end
+		end
+
+		def attribute(current)
+			if @input.scan(/@[^\[\]\|\\\s]+\[/) then
+				error "Attributes cannot be nested" if current.is_a?(AttributeNode)
+				name = @input.matched[1..@input.matched.length-2]
+				node = create_node(AttributeNode, {
+					:escape => false, 
+					:name => name.to_sym
+				})
+				while contents = parse_contents(node) do
+					node << contents
+				end
+				current[:attributes] << node
+				@input.scan(/\]/) or error "Attribute @#{name} not closed"		
+				node
+			else
+				nil
+			end
+		end
+
+		def text(current)
+			start_p = @input.pos
+			res = @input.scan_until /(\\.)|(\A(\]|\|)|[^\\](\]|\|)|[^\[\]\|\\\s]+\[|\Z)/
+				offset = @input.matched.match(/^[^\\](\]|\|)$/) ? 1 : @input.matched.length
+			@input.pos = @input.pos - offset rescue @input.pos
+			return nil if @input.pos == start_p
+			match = @input.string[start_p..@input.pos-1]
+			illegal_macro_delimiter? start_p, match
+			if match.length > 0 then
+				create_node TextNode, :value => match
+			else
+				nil
+			end
+		end
+
+		def escaped_text(current)
+			start_p = @input.pos
+			res = @input.scan_until /(\\.)|(\A(\=\]|\|)|[^\\](\=\]|\|)|\Z)/
+				case 
+				when @input.matched.match(/^[^\\]\=\]$/) then
+					offset = 2
+				when @input.matched.match(/^[^\\]\|$/) then
+					offset = 1
+				else
+					offset = @input.matched.length
+				end
+			@input.pos = @input.pos - offset rescue @input.pos
+			return nil if @input.pos == start_p
+			match = @input.string[start_p..@input.pos-1]
+			illegal_nesting = match.match(/([^\[\]\|\\\s]+)\[\=/)[1] rescue nil
+				if illegal_nesting then
+					error "Cannot nest escaping macro '#{illegal_nesting}' within escaping macro '#{current[:name]}'"
+				end
+				if match.length > 0 then
+					create_node TextNode, :value => match, :escaped => true
+				else
+					nil
+				end
+		end
+
+		def parameter_delimiter(current)
+			if @input.scan(/\|/) then
+				# Parameters are not allowed outside macros or inside attributes
+				if current.is_a?(DocumentNode) || current.is_a?(AttributeNode) then
+					@input.pos = @input.pos-1
+					error "Parameter delimiter '|' not allowed here"  
+				end
+				create_node SyntaxNode, :parameter => true
+			else
+				nil
+			end
+		end
+
+		def escape_sequence(current)
+			if @input.scan(/\\./) then
+				create_node EscapeNode, :value => @input.matched, :escaped => true
+			end
+		end
+
+		private
+
+		def aggregate_parameters_for(node)
+			indices = []
+			count = 0
+			node.children.each do |n|
+				indices << count if n[:parameter]
+				count += 1
+			end
+			# No parameter found
+			if indices == [] then
+				node[:parameters][0] = create_node ParameterNode, :name => :"0"
+				node.children.each do |c|
+					node[:parameters][0] << c
+				end
+			else
+				# Parameters found
+				current_index = 0
+				total_parameters = 0
+				save_parameter = lambda do |max_index|
+					parameter = create_node ParameterNode, :name => "#{total_parameters}".to_sym
+						total_parameters +=1
+					current_index.upto(max_index) do |index|
+						parameter << (node & index)
+					end
+					node[:parameters] << parameter
+				end
+				indices.each do |i|
+					save_parameter.call(i-1)
+					current_index = i+1
+				end
+				save_parameter.call(node.children.length-1)
+			end
+			node[:parameters]
+		end
+
+		def organize_children_for(node)
+			aggregate_parameters_for node
+			node.children.clear
+			node[:parameters].each do |p|
+				node << p
+			end
+			empty_parameter = 
+				node.children.length == 1 && 
+				((node&0).children.length == 0 || 
+				 (node&0).children.length == 0 &&
+				 (node&0&0).is_a?(TextNode) && 
+				 (node&0&0)[:value].blank?)
+			node.children.clear if empty_parameter
+			node.delete(:parameters)
+			node[:attributes].each do |a|
+				node << a
+			end
+			node.delete(:attributes)
+		end
+
+		def illegal_macro_delimiter?(start_p, string)
+			string.match(/\A(\[|\])|[^\\](\[|\])/)
+			illegal_delimiter = $1 || $2
+			if illegal_delimiter then
+				@input.pos = start_p + string.index(illegal_delimiter)
+				error "Macro delimiter '#{illegal_delimiter}' not escaped" 
+			end
+		end
+
+		def error(msg)
+			lines = @input.string[0..@input.pos].split(/\n/)
+			line = lines.length
+			column = lines.last.length
+			raise Glyph::SyntaxError.new("#{@source_name} [#{line}, #{column}] "+msg)
+		end
+
+		def create_node(klass, hash={})
+			klass.new.from hash
+		end
+
+	end
+
+end
+
+