glyph 0.4.2 → 0.5.0

data/lib/glyph/interpreter.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Glyph
 	
 	# A Glyph::Interpreter object perform the following actions:

data/lib/glyph/macro.rb

@@ -8,14 +8,14 @@ module Glyph
 	class Macro
 
 		include Validators
-		include Helpers
 		include Utils
 
-		attr_reader :node, :source_name, :source_file, :source_topic
+		attr_reader :node, :source_name, :source_file, :source_topic, :name
 
 		# Creates a new macro instance from a Node
 		# @param [Node] node a node populated with macro data
 		def initialize(node)
+			@data = {}
 			@node = node
 			@name = @node[:name]
 			@updated_source = nil
@@ -34,7 +34,7 @@ module Glyph
 			file ||= @node[:source][:file] rescue nil
 			@updated_source = {:name => name, :file => file, :topic => topic}
 		end
-		
+
 		# Returns a Glyph code representation of the specified parameter
 		# @param [Fixnum] n the index of the parameter
 		# @return [String, nil] the string representation of the parameter
@@ -109,8 +109,8 @@ module Glyph
 			@parameters = []
 			@node.parameters.each do |value|
 				@parameters << value.evaluate(@node, :params => true)
-				@parameters.last.strip! if options[:strip]
-				@parameters.last = nil if @parameters.last.blank? && options[:null_if_blank]
+				@parameters[@parameters.length-1].strip! if options[:strip]
+				@parameters[@parameters.length-1] = nil if @parameters.last.blank? && options[:null_if_blank]
 			end
 			@parameters
 		end
@@ -163,7 +163,7 @@ module Glyph
 			end
 			macros.reverse.compact.join('/')
 		end
-		
+
 		# Returns a todo message to include in the document in case of errors.
 		# @param [String] message the message to include in the document
 		# @return [String] the resulting todo message
@@ -209,23 +209,10 @@ module Glyph
 		# @param [String] string the string to interpret
 		# @return [String] the interpreted output
 		def interpret(string)
-			if @node[:escape] then
-				result = string 
-			else
-				context = {}
-				context[:source] = @updated_source || @node[:source]
-				context[:embedded] = true
-				context[:document] = @node[:document]
-				interpreter = Glyph::Interpreter.new string, context
-				subtree = interpreter.parse
-				subtree[:source] = context[:source]
-				@node << subtree
-				result = interpreter.document.output
-			end
-			result
+			@node[:escape] ? string : inject(string).document.output
 		end
 
-		# @see Glyph::Document#placeholder
+    # @see Glyph::Document#placeholder
 		def placeholder(&block)
 			@node[:document].placeholder &block
 		end			
@@ -250,14 +237,99 @@ module Glyph
 			@node[:document].header hash
 		end
 
+		# @see Glyph::Document#snippet
+		def snippet(key, value)
+			@node[:document].snippet key, value
+		end
+
+		# @see Glyph::Document#snippet?
+		def snippet?(ident)
+			@node[:document].snippet? ident
+		end
+
+		# @since 0.5.0
+		# Renders a macro representation
+		# @param [Symbol, String] rep the representation to render
+		# @param [Hash] data the data to pass to the representation
+		def render(rep=nil, data=nil)
+			rep ||= @name
+			data ||= @data
+			block = Glyph::REPS[rep.to_sym]
+			macro_error "No macro representation for '#{rep}'", e unless block
+			instance_exec(data, &block).to_s
+		end
+
+		# Stores a block of code to be "dispatched" via macro composition
+		# @since 0.5.0
+		# @example
+		#   # Macro definition (Ruby)
+		#   macro :greet do
+		#			dispatch do |node|
+		#				"#{node[:name]}, #{node.param 0}!"
+		#			end
+		#   end
+		#		
+		#		# macro usage (Glyph)
+		#		greet/Hello[World] --[Outputs: Hello, World!]
+		#		greet/GoodBye[John] --[Outputs: Goodbye, John!]
+		def dispatch(&block)
+			@node[:dispatch] = block
+			value
+		end
+
+		# Performs parameter/attribute substitution and interprets text
+		# @since 0.5.0
+		# @param [String] text the text to interpret
+		# @return [String] the interpreted output
+		def apply(text)
+			body = text.dup
+			# Parameters
+			body.gsub!(/\{\{(\d+)\}\}/) do
+				raw_param($1.to_i).to_s.strip
+			end
+			# Attributes
+			body.gsub!(/\{\{([^\[\]\|\\\s]+)\}\}/) do
+				raw_attr($1.to_sym).to_s.strip
+			end
+			interpret body
+		end
+
+		# Parses text and injects the syntax tree into the current node
+		# @since 0.5.0
+		# @param [String] text the text to parse
+		# @return [Glyph::Interpreter] the interpreter instance used to parse text
+		def inject(text)
+			context = create_context
+			interpreter = Glyph::Interpreter.new text, context
+			subtree = interpreter.parse
+			subtree[:source] = context[:source]
+			@node << subtree
+			interpreter
+		end
+
+		# Parses text
+		# @since 0.5.0
+		# @param [String] text the text to parse
+		# @return [Glyph::Node] the syntax tree generated by parsing
+		def parse(text)
+			Glyph::Interpreter.new(text, create_context).parse
+		end
+
 		# Executes a macro definition in the context of self
 		def expand
 			block = Glyph::MACROS[@name]
-			macro_error "Undefined macro '#@name'}" unless block
-			res = instance_exec(@node, &block).to_s
-			res.gsub!(/\\?([\[\]\|])/){"\\#$1"} 
-			res
+			macro_error "Undefined macro '#@name'" unless block
+			instance_exec(@node, &block).to_s.gsub(/\\?([\[\]\|])/){"\\#$1"}
 		end
 
+		private
+
+		def create_context
+			context = {}
+			context[:source] = @updated_source || @node[:source]
+			context[:embedded] = true
+			context[:document] = @node[:document]
+			context
+		end
 	end
 end

data/lib/glyph/macro_validators.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Glyph
 	class Macro
 
@@ -20,12 +22,13 @@ module Glyph
 				result
 			end
 
-			# Ensures that the macro element attributes is a valid XML element name.
+			# Ensures that the provided name is a valid XML element name.
+			# @param [String, Symbol] name the element name to validate
 			# @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<>]|_)[^<>"']*/) }
+			def valid_xml_element(name, options={:level => :error})
+				validate("Invalid XML element '#{name}'", options) { name.to_s.match(/^([^[:punct:]0-9<>]|_)[^<>"']*/) }
 			end
 
 			# Ensures that a macro attribute name is a valid XML attribute name.
@@ -118,7 +121,7 @@ module Glyph
 				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
+			# Ensures 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
@@ -146,7 +149,7 @@ module Glyph
 				end
 			end
 
-			# Ensure that the macros is within another
+			# Ensures 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)
@@ -158,7 +161,7 @@ module Glyph
 				end
 			end
 
-			# Ensure that the macros is _not_ within another
+			# Ensures 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)

data/lib/glyph/node.rb

@@ -1,3 +1,6 @@
+# encoding: utf-8
+
+# Core Hash class.
 class Hash
 
 	# Converts self to a Node
@@ -85,7 +88,6 @@ class Node < Hash
 
 	# Iterates through children recursively (including self)
 	# @param [Node, nil] element the node to process
-	# @yieldparam [Integer] level the initial tree depth
 	# @yieldparam [Node] element the current node
 	# @yieldparam [Integer] level the current tree depth
 	def descend(element=nil, level=0, &block)

data/lib/glyph/parser.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+
 require 'strscan'
 
 module Glyph
@@ -13,6 +14,7 @@ module Glyph
 		# @param [String] source_name the name of the source file (stored in the root node) 
 		# @since 0.3.0
 		def initialize(text, source_name="--")
+			@ruby19 = RUBY_VERSION >= '1.9' ? true : false
 			@source_name = source_name || "--"
 			@input = StringScanner.new text
 			@output = create_node DocumentNode, :name => @source_name.to_sym
@@ -29,8 +31,8 @@ module Glyph
 				@output << result
 				count +=1
 			end
-			if @input.pos < @input.string.length then
-				current_char = @input.string[@input.pos].chr
+			if @input.pos < @input.string.bytesize then
+				current_char = @input.string[@input.pos].chr rescue nil
 				illegal_delimiter = current_char.match(/\]|\[/) rescue nil
 				error "Macro delimiter '#{current_char}' not escaped" if illegal_delimiter
 			end
@@ -58,18 +60,15 @@ module Glyph
 				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)
+				error "#{name}[=...=] - A macro cannot start with a digit or contain '@'" if (name.match(/^[0-1]/) || name.match(/@/)) && !name.match(/^@:?$/)
+				node = macro_node_for name, true
+				leaf = node
+				node.descend { |n, level| leaf = n }
+				while contents = parse_escaped_contents(leaf) do
+					leaf << contents unless contents.is_a?(AttributeNode)
 				end
 				@input.scan(/\=\]/) or error "Escaping macro '#{name}' not closed"		
-				organize_children_for node
+				organize_children_for leaf
 				node
 			else
 				nil
@@ -77,9 +76,9 @@ module Glyph
 		end
 
 		def escaping_attribute(current)
-			if @input.scan(/@[^\[\]\|\\\s]+\[\=/) then
+			if @input.scan(/@[^:\[\]\|\\\s]+\[\=/) then
 				error "Attributes cannot be nested" if @current_attribute
-				name = @input.matched[1..@input.matched.length-3]
+				name = @input.matched[1..@input.matched.bytesize-3]
 				node = create_node(AttributeNode, {
 					:escape => true, 
 					:name => name.to_sym
@@ -99,18 +98,15 @@ module Glyph
 			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)
+				error "#{name}[...] - A macro cannot start with a digit or contain '@'" if (name.match(/^[0-1]/) || name.match(/@/)) && !name.match(/^@:?$/)
+				node = macro_node_for name 
+				leaf = node
+				node.descend { |n, level| leaf = n }
+				while contents = parse_contents(leaf) do
+					leaf << contents unless contents.is_a?(AttributeNode)
 				end
 				@input.scan(/\]/) or error "Macro '#{name}' not closed"		
-				organize_children_for node
+				organize_children_for leaf
 				node
 			else
 				nil
@@ -118,9 +114,9 @@ module Glyph
 		end
 
 		def attribute(current)
-			if @input.scan(/@[^\[\]\|\\\s]+\[/) then
+			if @input.scan(/@[^:\[\]\|\\\s]+\[/) then
 				error "Attributes cannot be nested" if current.is_a?(AttributeNode)
-				name = @input.matched[1..@input.matched.length-2]
+				name = @input.matched[1..@input.matched.bytesize-2]
 				node = create_node(AttributeNode, {
 					:escape => false, 
 					:name => name.to_sym
@@ -139,12 +135,12 @@ module Glyph
 		def text(current)
 			start_p = @input.pos
 			res = @input.scan_until /(\\.)|(\A(\]|\|)|[^\\](\]|\|)|[^\[\]\|\\\s]+\[|\Z)/
-				offset = @input.matched.match(/^[^\\](\]|\|)$/) ? 1 : @input.matched.length
+			offset = @input.matched.match(/^[^\\](\]|\|)$/) ? 1 : @input.matched.bytesize
 			@input.pos = @input.pos - offset rescue @input.pos
 			return nil if @input.pos == start_p
-			match = @input.string[start_p..@input.pos-1]
+			match = extract_string(start_p..@input.pos-1)
 			illegal_macro_delimiter? start_p, match
-			if match.length > 0 then
+			if match.bytesize > 0 then
 				create_node TextNode, :value => match
 			else
 				nil
@@ -160,16 +156,16 @@ module Glyph
 				when @input.matched.match(/^[^\\]\|$/) then
 					offset = 1
 				else
-					offset = @input.matched.length
+					offset = @input.matched.bytesize
 				end
 			@input.pos = @input.pos - offset rescue @input.pos
 			return nil if @input.pos == start_p
-			match = @input.string[start_p..@input.pos-1]
+			match = extract_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
+				if match.bytesize > 0 then
 					create_node TextNode, :value => match, :escaped => true
 				else
 					nil
@@ -197,6 +193,45 @@ module Glyph
 
 		private
 
+		def macro_node_for(ident, escape=false)
+			macro_names = ident.split(/\//).select{|e| !e.blank?}
+			nest_node = lambda do |parent, count|
+				node = create_node(MacroNode, {
+					:escape => false, 
+					:name => macro_names[count].to_sym
+				})
+				parent ? (parent&0) << node : parent = node
+				if macro_names[count+1] then
+					node << create_node(ParameterNode, :name => :"0") 
+					nest_node.call(node, count+1)
+				else
+					node[:parameters] = []
+					node[:attributes] = []
+					node[:escape] = escape
+				end
+				node
+			end
+			nest_node.call(nil, 0)
+		end
+		
+		# Thanks Thomas Leitner
+		# http://redmine.ruby-lang.org/issues/show/2645
+		def extract_string(range)
+			result = nil
+			if @ruby19 then 
+				begin
+					enc = @input.string.encoding
+					@input.string.force_encoding('ASCII-8BIT')
+					result = @input.string[range].force_encoding(enc)
+				ensure
+					@input.string.force_encoding(enc)
+				end
+			else
+				result = @input.string[range]
+			end
+			result
+		end
+
 		def aggregate_parameters_for(node)
 			indices = []
 			count = 0
@@ -216,7 +251,7 @@ module Glyph
 				total_parameters = 0
 				save_parameter = lambda do |max_index|
 					parameter = create_node ParameterNode, :name => "#{total_parameters}".to_sym
-						total_parameters +=1
+					total_parameters +=1
 					current_index.upto(max_index) do |index|
 						parameter << (node & index)
 					end

data/lib/glyph/reporter.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Glyph
 
 	# This class is used to display statistics collected by a Glyph::Analyzer. 
@@ -92,7 +94,7 @@ module Glyph
 			section "Snippet '#{s[:param]}'"
 			info "Definition:"
 			puts "-------------------"
-			puts SNIPPETS[s[:param]]
+			puts @stats[:snippets][:values][s[:param]]
 			puts "-------------------"
 			total :used_instances, s[:stats][:total]
 			occurrences s[:stats][:files], "Usage Details:" if @detailed

data/lib/glyph/syntax_node.rb

@@ -1,3 +1,5 @@
+# encoding: utf-8
+
 module Glyph
 
 	# A subclass of Glyph::SyntaxNode is instantiated by Glyph::Parser whenever a known
@@ -59,7 +61,13 @@ module Glyph
 		# @since 0.3.0
 		def to_s
 			e = self[:escape] ? "=" : ""
-			"#{self[:name]}["+e+attributes.join+parameters.join("|")+e+"]"
+			"#{self[:name]}["+e+contents+e+"]"
+		end
+
+    # @return [String] a textual representation of the macro parameters.
+    # @since 0.3.0
+		def contents
+			attributes.join+parameters.join("|")
 		end
 		
 		# Expands the macro
@@ -123,11 +131,18 @@ module Glyph
 		# @return [String] the value of the macro
 		# @since 0.3.0 
 		def expand(context)
-			xml_element(context)	
 			self[:source] = context[:source]
 			self[:document] = context[:document] 
 			self[:info] = context[:info]
 			self[:value] = ""
+			dispatched = parent_macro.dispatch(self) if parent_macro
+			return dispatched if dispatched
+			if Glyph['options.macro_set'] == "xml" || Glyph::MACROS[self[:name]].blank? && Glyph['options.xml_fallback'] then
+				m = Glyph::MacroNode.new
+				m[:name] = :xml
+				Glyph::Macro.new(m).expand
+				return m[:dispatch].call self
+			end
 			Glyph::Macro.new(self).expand
 		end
 
@@ -139,33 +154,13 @@ module Glyph
 			s
 		end
 
-		protected
-
-		def xml_element(context)
-			known_macro = Glyph::MACROS.include? self[:name]
-			name = self[:name].to_s
-			if !known_macro && name.match(/^=(.+)/) then
-				# Force tag name override if macro starts with a '='
-				name.gsub! /^=(.+)/, '\1' 
-			end
-			case
-				# Use XML syntax
-			when Glyph['options.macro_set'] == 'xml' then
-				self[:element] = name
-				self[:name] = :"|xml|" 
-				# Fallback to XML syntax
-			when Glyph["options.xml_fallback"] then
-				unless known_macro then
-					self[:element] = name
-					self[:fallback] = true
-					self[:name] = :"|xml|" 
-				end
-			else
-				# Unknown macro
-				raise RuntimeError, "Undefined macro '#{name}'\n -> source: #{context[:source][:name]}" unless known_macro
-			end
+		# @since 0.5.0
+		# Calls the ruby block stored in the :dispatch key, if present,
+		# in the context of node
+		def dispatch(node)
+			return self[:dispatch].call node if self[:dispatch]
+			false
 		end
-
 	end
 
 	# A piece of text in Glyph Abstract Syntax Tree