utopia 2.32.0 → 3.0.0

data/lib/utopia/content/document.rb

@@ -7,11 +7,14 @@ require_relative "links"
 require_relative "response"
 require_relative "markup"
 require_relative "builder"
+require_relative "../request"
 
 module Utopia
 	module Content
 		# This error is raised if a tag doesn't match up when parsing.
 		class UnbalancedTagError < StandardError
+			# Initialize an error for a mismatched rendering tag.
+			# @parameter tag [Object] The tag.
 			def initialize(tag)
 				@tag = tag
 				
@@ -23,12 +26,23 @@ module Utopia
 		
 		# A single request through content middleware. We use a struct to hide instance varibles since we instance_exec within this context.
 		class Document < Response
-			def self.render(node, request, attributes)
-				self.new(request, attributes).render!(node, attributes)
+			# Render a content node into a new document.
+			# @parameter node [Utopia::Content::Node] The content node.
+			# @parameter request [Utopia::Request] The application request.
+			# @parameter attributes [Hash] The attributes.
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
+			# @returns [Document] The rendered document.
+			def self.render(node, request, attributes, localization: request&.localization)
+				self.new(request, attributes, localization: localization).render!(node, attributes)
 			end
 			
-			def initialize(request, attributes = {})
+			# Initialize a document for a protocol request.
+			# @parameter request [Utopia::Request] The application request.
+			# @parameter attributes [Hash] The attributes.
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
+			def initialize(request, attributes = {}, localization: request&.localization)
 				@request = request
+				@localization = localization
 				
 				@attributes = attributes
 				
@@ -41,7 +55,7 @@ module Utopia
 			
 			# @returns [Path] The original request path, if known.
 			def request_path
-				Path[request.env["REQUEST_PATH"]]
+				request.request_path
 			end
 			
 			protected def current_base_uri_path
@@ -60,14 +74,25 @@ module Utopia
 				Path[relative_to].dirname.shortest_path(request_path)
 			end
 			
+			# Fetch a document-global attribute.
+			# @parameter key [String | Symbol] The lookup key.
+			# @returns [Object | Nil] The document attribute.
 			def [] key
 				@attributes[key]
 			end
 			
+			# Assign a document-global attribute.
+			# @parameter key [String | Symbol] The lookup key.
+			# @parameter value [Object] The value to assign.
+			# @returns [Object] The assigned value.
 			def []= key, value
 				@attributes[key] = value
 			end
 			
+			# Render.
+			# @parameter node [Utopia::Content::Node] The content node.
+			# @parameter attributes [Hash] The attributes.
+			# @returns [self] This object.
 			def render!(node, attributes)
 				@body << render_node(node, attributes)
 				
@@ -79,15 +104,20 @@ module Utopia
 				@controller ||= Utopia::Controller[request]
 			end
 			
+			# Return the selected localization preferences for this document.
+			# @returns [Localization::Preferences | Nil] The localization preferences.
 			def localization
-				@localization ||= Utopia::Localization[request]
+				@localization
 			end
 			
+			# Parse markup into this document.
+			# @parameter markup [String] The markup.
+			# @returns [Nil] Parsing completes through document callbacks.
 			def parse_markup(markup)
 				MarkupParser.parse(markup, self)
 			end
 			
-			# The Rack::Request for this document.
+			# The request for this document.
 			attr :request
 			
 			# Per-document global attributes.
@@ -106,6 +136,11 @@ module Utopia
 			# have appeared when evaluating nodes.
 			attr :end_tags
 			
+			# Render a complete or block-delimited tag.
+			# @parameter name [String] The name.
+			# @parameter attributes [Hash] The attributes.
+			# @yields {|node| ...} The node selected to render a block-delimited tag.
+			# @returns [Object | Nil] The completed tag result.
 			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)
@@ -119,6 +154,10 @@ module Utopia
 				end
 			end
 			
+			# Render a complete tag through a matching content node or the current builder.
+			# @parameter tag [XRB::Tag] The tag.
+			# @parameter node [Utopia::Content::Node] The content node.
+			# @returns [Object] The builder's completion result.
 			def tag_complete(tag, node = nil)
 				node ||= lookup_tag(tag)
 				
@@ -130,6 +169,10 @@ module Utopia
 				end
 			end
 			
+			# Begin a tag through a matching content node or the current builder.
+			# @parameter tag [XRB::Tag] The tag.
+			# @parameter node [Utopia::Content::Node] The content node.
+			# @returns [Node | Nil] The content node selected for the tag.
 			def tag_begin(tag, node = nil)
 				node ||= lookup_tag(tag)
 				
@@ -148,16 +191,25 @@ module Utopia
 				return nil
 			end
 			
+			# Append raw content to the current builder.
+			# @parameter string [String] The string.
+			# @returns [String] The current output buffer.
 			def write(string)
 				@current.write(string)
 			end
 			
 			alias cdata write
 			
+			# Process text content.
+			# @parameter string [String] The string.
+			# @returns [Object | Nil] The builder's text result.
 			def text(string)
 				@current.text(string)
 			end
 			
+			# Complete the current content node or close a nested markup tag.
+			# @parameter tag [XRB::Tag | Nil] The nested tag to close.
+			# @returns [String | Nil] The completed node output, or `nil` after closing a nested tag.
 			def tag_end(tag = nil)
 				# Determine if the current state contains tags that need to be completed, or if the state itself is finished.
 				if @current.empty?
@@ -182,6 +234,10 @@ module Utopia
 				return nil
 			end
 			
+			# Render a content node within the current builder state.
+			# @parameter node [Utopia::Content::Node] The content node.
+			# @parameter attributes [Hash] The attributes.
+			# @returns [String] The rendered node output.
 			def render_node(node, attributes = {})
 				@current = Builder.new(@current, nil, node, attributes, indent: false)
 				
@@ -225,6 +281,8 @@ module Utopia
 				@end_tags.last.content
 			end
 			
+			# Return the enclosing rendering state.
+			# @returns [Builder | Nil] The parent rendering state.
 			def parent
 				@end_tags[-2]
 			end

data/lib/utopia/content/link.rb

@@ -6,6 +6,7 @@
 # Copyright, 2020, by Michael Adams.
 
 require "yaml"
+require "protocol/url"
 require "xrb/builder"
 
 require "xrb/strings"
@@ -26,6 +27,8 @@ module Utopia
 				@title = XRB::Strings.to_title(title || name)
 			end
 			
+			# Build the filesystem key, including the locale suffix when present.
+			# @returns [String | Nil] The link key.
 			def key
 				if @path
 					if locale
@@ -36,16 +39,23 @@ module Utopia
 				end
 			end
 			
+			# Resolve the backing content file beneath a root directory.
+			# @parameter root [String] The root directory.
+			# @parameter extension [String] The file extension.
+			# @returns [String | Nil] The backing file path, or `nil` for links without file paths.
 			def full_path(root, extension = XNODE_EXTENSION)
 				if @path&.file?
 					File.join(root, @path.dirname, self.key + XNODE_EXTENSION)
 				end
 			end
 			
+			# Resolve this link's target URI.
+			# @returns [String | Nil] The explicit target URI or one derived from the content path.
 			def href
 				@href ||= @info.fetch(:uri) do
 					@info.fetch(:href) do
-						(@path.dirname + @path.basename).to_s if @path
+						# Omit the variant suffix from inferred content links:
+						(@path.dirname + @path.basename).to_url_path.encoded if @path
 					end
 				end
 			end
@@ -61,30 +71,55 @@ module Utopia
 			attr :info
 			attr :locale
 			
+			# Check whether this link has a target URI.
+			# @returns [Boolean] Whether this link has a target URI.
 			def href?
 				!!href
 			end
 			
+			# Check whether this link refers to an index document.
+			# @returns [Boolean] Whether this link represents an index document.
 			def index?
 				@kind == :index
 			end
 			
+			# Check whether this link is virtual.
+			# @returns [Boolean] Whether this link exists only in metadata.
 			def virtual?
 				@kind == :virtual
 			end
 			
+			# Resolve this link's target relative to a base path.
+			# @parameter base [Path | String | Nil] The source path.
+			# @returns [String | Nil] The relative or unchanged target.
 			def relative_href(base = nil)
-				if base and href.start_with? "/"
-					Path.shortest_path(href, base)
-				else
-					href
+				target = href
+				return unless target
+				return target unless base
+				
+				url = Protocol::URL[target]
+				relative_url = url.relative_to(Path[base].to_url_path)
+				
+				# Preserve unchanged targets exactly and avoid allocating a serialized replacement:
+				if relative_url.equal?(url)
+					return target
 				end
+				
+				return relative_url.to_s
 			end
 			
+			# Return the display title from metadata or the inferred title.
+			# @returns [String] The display title.
 			def title
 				@info.fetch(:title, @title)
 			end
 			
+			# Render this link as an anchor element.
+			# @parameter base [Path | String | Nil] The source path for relative links.
+			# @parameter content [String] The content.
+			# @parameter builder [XRB::Builder] The markup builder.
+			# @parameter attributes [Hash] The attributes.
+			# @returns [XRB::Builder::Fragment] The rendered anchor or span fragment.
 			def to_anchor(base: nil, content: self.title, builder: nil, **attributes)
 				attributes[:class] ||= "link"
 				
@@ -106,18 +141,28 @@ module Utopia
 			
 			alias to_href to_anchor
 			
+			# Convert this object to a string.
+			# @returns [String] The resulting string.
 			def to_s
 				"\#<#{self.class}(#{self.kind}) title=#{title.inspect} href=#{href.inspect}>"
 			end
 			
+			# Check whether this object is equivalent to another object.
+			# @parameter other [Object] The object to compare.
+			# @returns [Boolean] Whether both links have equivalent metadata.
 			def eql? other
 				self.class.eql?(other.class) and kind.eql?(other.kind) and name.eql?(other.name) and path.eql?(other.path) and info.eql?(other.info)
 			end
 			
+			# Compare this object with another object.
+			# @parameter other [Object] The object to compare.
+			# @returns [Boolean | Nil] Whether both links have the same kind, name, and path.
 			def == other
 				other and kind == other.kind and name == other.name and path == other.path
 			end
 			
+			# Check whether this link uses the default locale.
+			# @returns [Boolean] Whether this link has no locale override.
 			def default_locale?
 				@locale == nil
 			end

data/lib/utopia/content/links.rb

@@ -13,17 +13,32 @@ module Utopia
 		XNODE_EXTENSION = ".xnode"
 		INDEX = "index"
 		
+		# A collection of links resolved from the filesystem content hierarchy.
 		class Links
-			def self.for(root, path, locale = nil)
+			# Build links for the given root and path.
+			# @parameter root [String] The root directory.
+			# @parameter path [Utopia::Path | String] The path.
+			# @parameter locale [String] The locale.
+			# @parameter fallback [Boolean] Whether to return an unlocalized link as a fallback.
+			# @returns [Link | Nil] The resolved link.
+			def self.for(root, path, locale = nil, fallback: true)
 				warn "Using uncached links metadata!"
-				self.new(root).for(path, locale)
+				self.new(root).for(path, locale, fallback: fallback)
 			end
 			
+			# Build an index of links for the given path.
+			# @parameter root [String] The root directory.
+			# @parameter path [Utopia::Path | String] The path.
+			# @parameter options [Hash] The options.
+			# @returns [Array(Link)] The indexed links.
 			def self.index(root, path, **options)
 				warn "Using uncached links metadata!"
 				self.new(root).index(path, **options)
 			end
 			
+			# Initialize cached link resolution beneath a content root.
+			# @parameter root [String] The root directory.
+			# @parameter extension [String] The file extension.
 			def initialize(root, extension: XNODE_EXTENSION)
 				@root = root
 				
@@ -40,9 +55,12 @@ module Utopia
 			attr :index_filter
 			
 			# Resolve a link for the specified path, which must be a path to a specific link.
-			# 	for(Path["/index"])
-			def for(path, locale = nil)
-				links(path.dirname).lookup(path.last, locale)
+			# @parameter path [Utopia::Path | String] The path.
+			# @parameter locale [String | Nil] The locale.
+			# @parameter fallback [Boolean] Whether to return an unlocalized link as a fallback.
+			# @returns [Link | Nil] The resolved link.
+			def for(path, locale = nil, fallback: true)
+				links(path.dirname).lookup(path.last, locale, fallback: fallback)
 			end
 			
 			# Give an index of all links that can be reached from the given path.
@@ -97,12 +115,18 @@ module Utopia
 			
 			attr :root
 			
+			# Load and cache metadata for a content directory.
+			# @parameter path [Utopia::Path | String] The path.
+			# @returns [Hash] The content metadata.
 			def metadata(path)
 				@metadata_cache.fetch_or_store(path.to_s) do
 					load_metadata(path)
 				end
 			end
 			
+			# Load and cache the link resolver for a content directory.
+			# @parameter path [Utopia::Path | String] The path.
+			# @returns [Resolver] The link resolver.
 			def links(path)
 				@links_cache.fetch_or_store(path.to_s) do
 					load_links(path)
@@ -136,6 +160,9 @@ module Utopia
 			
 			# 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 Resolver
+				# Resolve and order links from a content directory and its metadata.
+				# @parameter links [Object] The links.
+				# @parameter top [Object] The top.
 				def initialize(links, top = Path.root)
 					raise ArgumentError.new("top path must be absolute") unless top.absolute?
 					
@@ -165,10 +192,15 @@ module Utopia
 				attr :ordered
 				attr :named
 				
+				# Select index-document links.
+				# @returns [Array(Link)] The index-document links.
 				def indices
 					return @ordered.select{|link| link.index?}
 				end
 				
+				# Enumerate the contained values.
+				# @parameter locale [String] The locale.
+				# @returns [Enumerator] An enumerator over the resulting values.
 				def each(locale)
 					return to_enum(:each, locale) unless block_given?
 					
@@ -177,7 +209,12 @@ module Utopia
 					end
 				end
 				
-				def lookup(name, locale = nil)
+				# Lookup.
+				# @parameter name [String] The name.
+				# @parameter locale [String] The locale.
+				# @parameter fallback [Boolean] Whether to return an unlocalized link as a fallback.
+				# @returns [Link | Nil] The exact locale match, or the unlocalized link when fallback is enabled.
+				def lookup(name, locale = nil, fallback: true)
 					# This allows generic links to serve any locale requested.
 					if links = @named[name]
 						generic_link = nil
@@ -185,7 +222,7 @@ module Utopia
 						links.each do |link|
 							if link.locale == locale
 								return link
-							elsif link.locale.nil?
+							elsif fallback && link.locale.nil?
 								generic_link = link
 							end
 						end

data/lib/utopia/content/markup.rb

@@ -14,21 +14,37 @@ module Utopia
 		
 		# A hash which forces all keys to be symbols and fails with KeyError when strings are used.
 		class SymbolicHash < Hash
+			# Fetch a value using a symbolic key.
+			# @parameter key [String | Symbol] The lookup key.
+			# @returns [Object | Nil] The associated value.
+			# @raises [KeyError] If `key` is a string.
 			def [] key
 				raise KeyError.new("attribute #{key} is a string, prefer a symbol") if key.is_a? String
 				super key.to_sym
 			end
 			
+			# Assign a value after coercing its key to a symbol.
+			# @parameter key [String | Symbol] The lookup key.
+			# @parameter value [Object] The value to assign.
+			# @returns [Object] The assigned value.
 			def []= key, value
 				super key.to_sym, value
 			end
 			
+			# Fetch a value after coercing the key to a symbol.
+			# @parameter key [String | Symbol] The lookup key.
+			# @parameter arguments [Array] The arguments.
+			# @yields {|key| ...} The missing symbolic key when no default argument is given.
+			# @returns [Object] The associated, default, or block-provided value.
 			def fetch(key, *arguments, &block)
 				key = key.to_sym
 				
 				super
 			end
 			
+			# Check whether this collection includes the given value.
+			# @parameter key [String | Symbol] The lookup key.
+			# @returns [Boolean] Whether the symbolic key exists.
 			def include? key
 				key = key.to_sym
 				
@@ -40,6 +56,9 @@ module Utopia
 		class MarkupParser
 			# A tag generated by parsing markup.
 			class ParsedTag
+				# Initialize a parsed opening tag at a source offset.
+				# @parameter name [String] The name.
+				# @parameter offset [Integer] The source offset.
 				def initialize(name, offset)
 					@offset = offset
 					@tag = Tag.new(name, false, SymbolicHash.new)
@@ -48,6 +67,8 @@ module Utopia
 				attr :tag
 				attr :offset
 				
+				# Convert this object to a string.
+				# @returns [String] The resulting string.
 				def to_s
 					"<#{@tag.name}#{@tag.attributes.empty? ? '' : ' ...'}>"
 				end
@@ -55,6 +76,10 @@ module Utopia
 			
 			# The name of a closing tag fails to match up with the corresponding opening tag.
 			class UnbalancedTagError < StandardError
+				# Initialize an error for mismatched source tags.
+				# @parameter buffer [String] The markup source buffer.
+				# @parameter opening_tag [Object] The opening tag token.
+				# @parameter closing_tag [Object] The closing tag token.
 				def initialize(buffer, opening_tag, closing_tag = nil)
 					@buffer = buffer
 					@opening_tag = opening_tag
@@ -65,16 +90,22 @@ module Utopia
 				attr :opening_tag
 				attr :closing_tag
 				
+				# Locate the opening tag in the source buffer.
+				# @returns [XRB::Location] The opening tag location.
 				def start_location
 					XRB::Location.new(@buffer.read, opening_tag.offset)
 				end
 				
+				# Locate the closing tag in the source buffer.
+				# @returns [XRB::Location | Nil] The closing tag location.
 				def end_location
 					if closing_tag and closing_tag.respond_to? :offset
 						XRB::Location.new(@buffer.read, closing_tag.offset)
 					end
 				end
 				
+				# Convert this object to a string.
+				# @returns [String] The resulting string.
 				def to_s
 					if @closing_tag
 						"#{start_location}: #{@opening_tag} was not closed!"
@@ -84,6 +115,12 @@ module Utopia
 				end
 			end
 			
+			# Parse markup events into a delegate.
+			# @parameter buffer [String | XRB::Buffer] The markup source buffer.
+			# @parameter delegate [Object] The delegate.
+			# @parameter entities [Hash] The named entity mappings.
+			# @returns [Nil] Parsing completes through delegate callbacks.
+			# @raises [UnbalancedTagError] If the markup contains mismatched tags.
 			def self.parse(buffer, delegate, entities = XRB::Entities::HTML5)
 				# This is for compatibility with the existing API which passes in a string:
 				buffer = XRB::Buffer(buffer)
@@ -91,6 +128,10 @@ module Utopia
 				self.new(buffer, delegate, entities).parse!
 			end
 			
+			# Initialize a streaming markup parser and its delegate.
+			# @parameter buffer [String] The markup source buffer.
+			# @parameter delegate [Object] The delegate.
+			# @parameter entities [Hash] The named entity mappings.
 			def initialize(buffer, delegate, entities = XRB::Entities::HTML5)
 				@buffer = buffer
 				
@@ -101,6 +142,8 @@ module Utopia
 				@stack = []
 			end
 			
+			# Parse the markup buffer into delegate callbacks and validate balanced tags.
+			# @returns [Nil] Parsing completes through delegate callbacks.
 			def parse!
 				XRB::Parsers.parse_markup(@buffer, self, @entities)
 				
@@ -109,14 +152,25 @@ module Utopia
 				end
 			end
 			
+			# Begin collecting an opening tag.
+			# @parameter name [String] The name.
+			# @parameter offset [Integer] The source offset.
+			# @returns [ParsedTag] The tag being collected.
 			def open_tag_begin(name, offset)
 				@current = ParsedTag.new(name, offset)
 			end
 			
+			# Process a markup attribute.
+			# @parameter key [String | Symbol] The lookup key.
+			# @parameter value [Object] The value to assign.
+			# @returns [Object] The assigned attribute value.
 			def attribute(key, value)
 				@current.tag.attributes[key] = value
 			end
 			
+			# Complete an opening tag and dispatch it to the delegate.
+			# @parameter self_closing [Boolean] Whether the tag is self-closing.
+			# @returns [Nil] The current tag is cleared.
 			def open_tag_end(self_closing)
 				if self_closing
 					@current.tag.closed = true
@@ -129,6 +183,11 @@ module Utopia
 				@current = nil
 			end
 			
+			# Process a closing markup tag.
+			# @parameter name [String] The name.
+			# @parameter offset [Integer] The source offset.
+			# @returns [Object] The delegate's tag-end result.
+			# @raises [UnbalancedTagError] If the closing tag does not match its opening tag.
 			def close_tag(name, offset)
 				@current = @stack.pop
 				tag = @current.tag
@@ -140,22 +199,37 @@ module Utopia
 				@delegate.tag_end(tag)
 			end
 			
+			# Process a document type declaration.
+			# @parameter string [String] The string.
+			# @returns [Object] The delegate's write result.
 			def doctype(string)
 				@delegate.write(string)
 			end
 			
+			# Process a markup comment.
+			# @parameter string [String] The string.
+			# @returns [Object] The delegate's write result.
 			def comment(string)
 				@delegate.write(string)
 			end
 			
+			# Process a markup instruction.
+			# @parameter string [String] The string.
+			# @returns [Object] The delegate's write result.
 			def instruction(string)
 				@delegate.write(string)
 			end
 			
+			# Process a CDATA section.
+			# @parameter string [String] The string.
+			# @returns [Object] The delegate's write result.
 			def cdata(string)
 				@delegate.write(string[9..-4])
 			end
 			
+			# Process text content.
+			# @parameter string [String] The string.
+			# @returns [Object] The delegate's text result.
 			def text(string)
 				@delegate.text(string)
 			end