utopia 1.9.11 → 2.0.0

data/lib/utopia/content/{transaction.rb → document.rb}

@@ -19,8 +19,8 @@
 # THE SOFTWARE.
 
 require_relative 'links'
-
 require_relative 'response'
+require_relative 'markup'
 
 module Utopia
 	class Content
@@ -35,26 +35,38 @@ module Utopia
 			attr :tag
 		end
 		
-		DEFERRED_TAG_NAME = "deferred".freeze
-		CONTENT_TAG_NAME = "content".freeze
-		
 		# A single request through content middleware. We use a struct to hide instance varibles since we instance_exec within this context.
-		class Transaction < Response
+		class Document < Response
+			def self.render(node, request, attributes)
+				self.new(request, attributes).render!(node, attributes)
+			end
+			
 			def initialize(request, attributes = {})
 				@request = request
 				
 				@attributes = attributes
 				
-				@begin_tags = []
+				@first = nil
+				@current = nil
 				@end_tags = []
 				
-				# TODO: Provide way to set encoding and content type.
-				#@encoding = Encoding::UTF_8
-				#self.content_type = "text/html; charset=#{@encoding.name}"
-				
 				super()
 			end
 			
+			def [] key
+				@attributes[key]
+			end
+			
+			def []= key, value
+				@attributes[key] = value
+			end
+			
+			def render!(node, attributes)
+				@body << render_node(node, attributes)
+				
+				return self
+			end
+			
 			# A helper method for accessing controller variables from view:
 			def controller
 				@controller ||= Utopia::Controller[request]
@@ -68,134 +80,137 @@ module Utopia
 				MarkupParser.parse(markup, self)
 			end
 
-			# The Rack::Request for this transaction.
+			# The Rack::Request for this document.
 			attr :request
 
-			# Per-transaction global attributes.
+			# Per-document global attributes.
 			attr :attributes
 
-			# Begin tags represents a list from outer to inner most tag.
-			# At any point in parsing markup, begin_tags is a list of the inner most tag,
-			# then the next outer tag, etc. This list is used for doing dependent lookups.
-			attr :begin_tags
+			# The current state, represents a list from outer to inner most tag by traversing {State#parent}.
+			# At any point in parsing markup, this is a list of the inner most tag,
+			# then the next outer tag, etc.
+			attr :current
+
+			# The first {State} generated by rendering this document. It contains useful information
+			# regarding the node and uri used to access the resource.
+			attr :first
 
 			# End tags represents a list of execution order. This is the order that end tags
 			# have appeared when evaluating nodes.
 			attr :end_tags
 
-			def tag(name, attributes = {}, &block)
+			def tag(name, attributes = {})
 				# If we provide a block which can give inner data, we are not self-closing.
 				tag = Tag.new(name, !block_given?, attributes)
 
-				node = tag_begin(tag)
-
-				yield node if block_given?
-
-				tag_end(tag)
+				if block_given?
+					node = tag_begin(tag)
+					yield node
+					tag_end(tag)
+				else
+					tag_complete(tag, node)
+				end
 			end
 
 			def tag_complete(tag, node = nil)
-				if tag.name == CONTENT_TAG_NAME
-					current.write(content)
-				else
-					node ||= lookup(tag)
+				node ||= lookup_tag(tag)
 
-					if node
-						tag_begin(tag, node)
-						tag_end(tag)
-					else
-						current.tag_complete(tag)
-					end
+				if node
+					tag_begin(tag, node)
+					tag_end(tag)
+				else
+					@current.tag_complete(tag)
 				end
 			end
 
 			def tag_begin(tag, node = nil)
-				node ||= lookup(tag)
+				node ||= lookup_tag(tag)
 
 				if node
-					state = State.new(tag, node)
-					self.begin_tags << state
+					@current = State.new(@current, tag, node)
 
-					if node.respond_to? :tag_begin
-						node.tag_begin(self, state)
-					end
+					node.tag_begin(self, state) if node.respond_to?(:tag_begin)
 
 					return node
 				end
 
-				current.tag_begin(tag)
+				# raise ArgumentError.new("tag_begin: #{tag} is tag.self_closed?") if tag.self_closed?
+
+				@current.tag_begin(tag)
 
 				return nil
 			end
 			
 			def write(string)
-				current.write(string)
+				@current.write(string)
 			end
 			
 			alias cdata write
 
 			def text(string)
-				current.text(string)
+				@current.text(string)
 			end
 
 			def tag_end(tag = nil)
-				# Get the current tag which we are completing/ending:
-				top = current
-				
-				if top.tags.empty?
-					if top.node.respond_to? :tag_end
-						top.node.tag_end(self, top)
+				# Determine if the current state contains tags that need to be completed, or if the state itself is finished.
+				if @current.empty?
+					if node = @current.node
+						node.tag_end(self, @current) if node.respond_to?(:tag_end)
 					end
 
-					self.end_tags << top
-					buffer = top.call(self)
+					@end_tags << @current
+					buffer = @current.call(self)
 
-					self.begin_tags.pop
-					self.end_tags.pop
+					@current = @current.parent
+					@end_tags.pop
 
-					if current
-						current.write(buffer)
-					end
+					@current.write(buffer) if @current
 
 					return buffer
 				else
-					current.tag_end(tag)
+					# raise ArgumentError.new("tag_begin: #{tag} is tag.self_closed?") if tag.self_closed?
+					@current.tag_end(tag)
 				end
 
 				return nil
 			end
-			
-			def render_node(node, attributes = {})
-				self.begin_tags << State.new(attributes, node)
 
+			def render_node(node, attributes = {})
+				@current = State.new(@current, nil, node, attributes)
+				
+				# We keep track of the first thing rendered by this document.
+				@first ||= @current
+				
+				# This returns the content of rendering the tag:
 				return tag_end
 			end
 
-			# Takes an instance of Tag
-			def lookup(tag)
-				result = tag
-				node = nil
-
-				self.begin_tags.reverse_each do |state|
-					result = state.lookup(result)
-					
-					node ||= state.node if state.node.respond_to? :lookup
-
-					return result if result.is_a?(Node)
-				end
-
-				self.end_tags.reverse_each do |state|
-					return state.node.lookup(result) if state.node.respond_to? :lookup
+			# Maps a tag to a node instance by asking the current node to lookup the tag name. This function is called for each tag and thus heavily affects performance.
+			# @return [Node] The node for the given tag.
+			def lookup_tag(tag)
+				# result = tag
+				# 
+				# # This loop works from inner to outer tags, and updates the tag we are currently searching for based on any overrides:
+				# @begin_tags.reverse_each do |state|
+				# 	result = state.lookup(result)
+				# 	
+				# 	return result if result.is_a?(Node)
+				# end
+				
+				# This loop looks up a tag by asking the most embedded node to look it up based on tag name. This almost always only evaluates the top state:
+				@end_tags.reverse_each do |state|
+					return state.node.lookup_tag(tag) if state.node.respond_to?(:lookup_tag)
 				end
-
+				
 				return nil
 			end
 			
-			# The current tag being processed/rendered. Prefer to access state directly.
-			def current
-				@begin_tags.last
+			# Lookup a node with the given path relative to the current node.
+			# @return [Node] The node if could be found.
+			def lookup_node(path)
+				@current.node.lookup_node(path)
 			end
-
+			
 			# The content of the node
 			def content
 				@end_tags.last.content
@@ -204,32 +219,30 @@ module Utopia
 			def parent
 				@end_tags[-2]
 			end
-
-			def first
-				@begin_tags.first
-			end
 		end
 		
-		# The state of a single tag being rendered within a Transaction instance.
-		class Transaction::State
-			def initialize(tag, node, attributes = tag.to_hash)
+		# The state of a single tag being rendered within a document instance.
+		class Document::State
+			def initialize(parent, tag, node, attributes = tag.to_hash)
+				@parent = parent
+				@tag = tag
 				@node = node
+				@attributes = attributes
 				
 				@buffer = Trenni::MarkupString.new.force_encoding(Encoding::UTF_8)
+				@content = nil
 				
-				@overrides = {}
+				@deferred = []
 				
 				@tags = []
-				@attributes = attributes
-				
-				@content = nil
-				@deferred = []
 			end
 
+			attr :parent
 			attr :attributes
-			attr :overrides
 			attr :content
 			attr :node
+			
+			# A list of all tags in order of rendering them, which have not been finished yet.
 			attr :tags
 
 			attr :deferred
@@ -244,28 +257,14 @@ module Utopia
 				@attributes[key]
 			end
 
-			def lookup(tag)
-				if override = @overrides[tag.name]
-					if override.respond_to? :call
-						return override.call(tag)
-					elsif String === override
-						return Tag.new(override, tag.attributes)
-					else
-						return override
-					end
-				else
-					return tag
-				end
-			end
-
-			def call(transaction)
+			def call(document)
 				@content = @buffer
 				@buffer = Trenni::MarkupString.new.force_encoding(Encoding::UTF_8)
 				
 				if node.respond_to? :call
-					node.call(transaction, self)
+					node.call(document, self)
 				else
-					transaction.parse_markup(@content)
+					document.parse_markup(@content)
 				end
 				
 				return @buffer
@@ -276,20 +275,27 @@ module Utopia
 			end
 
 			def text(string)
-				@buffer << Trenni::MarkupString(string)
+				Trenni::Markup.append(@buffer, string)
 			end
 
 			def tag_complete(tag)
 				tag.write(@buffer)
 			end
+			
+			# Whether this state has any nested tags.
+			def empty?
+				@tags.empty?
+			end
 
 			def tag_begin(tag)
+				# raise ArgumentError.new("tag_begin: #{tag} is tag.self_closed?") if tag.self_closed?
+				
 				@tags << tag
 				tag.write_opening_tag(@buffer)
 			end
 
 			def tag_end(tag)
-				raise UnbalancedTagError(tag) unless @tags.pop.name == tag.name
+				raise UnbalancedTagError.new(tag) unless @tags.pop.name == tag.name
 				tag.write_closing_tag(@buffer)
 			end
 		end

data/lib/utopia/content/link.rb

@@ -28,6 +28,7 @@ require_relative '../locale'
 
 module Utopia
 	class Content
+		# Represents a link to some content with associated metadata.
 		class Link
 			def initialize(kind, path, info = nil)
 				path = Path.create(path)
@@ -91,9 +92,13 @@ module Utopia
 			def to_anchor(**options)
 				Trenni::Builder.fragment(options[:builder]) do |builder|
 					if href?
-						relative_href(options[:base])
+						a_attributes = {
+							:class => options.fetch(:class, 'link'),
+							:href => relative_href(options[:base]),
+							:target => options.fetch(:target, @info[:target])
+						}
 						
-						builder.inline('a', class: options.fetch(:class, 'link'), href: relative_href(options[:base])) do
+						builder.inline('a', a_attributes) do
 							builder.text(options[:content] || title)
 						end
 					else

data/lib/utopia/content/links.rb

@@ -22,9 +22,10 @@ require_relative 'link'
 
 module Utopia
 	class Content
+		# The file extension for markup nodes on disk.
 		XNODE_EXTENSION = '.xnode'.freeze
 		
-		# Links are essentially a static list of information relating to the structure of the content. They are formed from the `links.yaml` file and the actual files on disk. 
+		# Represents a list of {Link} instances relating to the structure of the content. They are formed from the `links.yaml` file and the actual directory structure on disk.
 		class Links
 			def self.for(root, path, locale = nil)
 				links = self.new(root, path.dirname)

data/lib/utopia/content/markup.rb

@@ -21,11 +21,13 @@
 require 'trenni/parsers'
 require 'trenni/entities'
 require 'trenni/strings'
-
-require_relative 'tag'
+require 'trenni/tag'
 
 module Utopia
 	class Content
+		Tag = Trenni::Tag
+		
+		# A hash which forces all keys to be symbols and fails with KeyError when strings are used.
 		class SymbolicHash < Hash
 			def [] key
 				raise KeyError.new("attribute #{key} is a string, prefer a symbol") if key.is_a? String
@@ -49,7 +51,9 @@ module Utopia
 			end
 		end
 		
+		# Provides a high level interface for parsing markup.
 		class MarkupParser
+			# A tag generated by parsing markup.
 			class ParsedTag
 				def initialize(name, offset)
 					@offset = offset
@@ -64,6 +68,7 @@ module Utopia
 				end
 			end
 			
+			# The name of a closing tag fails to match up with the corresponding opening tag.
 			class UnbalancedTagError < StandardError
 				def initialize(buffer, opening_tag, closing_tag = nil)
 					@buffer = buffer

data/lib/utopia/{tags/deferred.rb → content/namespace.rb}

@@ -19,14 +19,33 @@
 # THE SOFTWARE.
 
 module Utopia
-	module Tags
-		class Deferred
-			def self.call(transaction, state)
-				id = state[:id].to_i
+	class Content
+		# A namespace which contains tags which can be rendered within a {Document}.
+		module Namespace
+			def self.extended(other)
+				other.class_exec do
+					@named = {}
+				end
+			end
+			
+			attr :named
+			
+			def freeze
+				return self if frozen?
 				
-				procedure = transaction.parent.deferred[id]
+				@named.freeze
+				@named.values.each(&:freeze)
 				
-				procedure.call(transaction, state)
+				super
+			end
+			
+			def tag(name, klass = nil, &block)
+				@named[name] = klass || block
+			end
+			
+			# @return [Node] The node which should be used to render the named tag.
+			def call(name, node)
+				@named[name]
 			end
 		end
 	end