utopia 1.9.11 → 2.0.0

data/lib/utopia/exceptions.rb

@@ -22,6 +22,7 @@ require_relative 'exceptions/handler'
 require_relative 'exceptions/mailer'
 
 module Utopia
+	# Middleware for handling exceptional situations.
 	module Exceptions
 	end
 end

data/lib/utopia/exceptions/handler.rb

@@ -20,8 +20,9 @@
 
 module Utopia
 	module Exceptions
-		# Catches exceptions and performs an internal redirect.
+		# A middleware which catches exceptions and performs an internal redirect.
 		class Handler
+			# @param location [String] Peform an internal redirect to this location when an exception is raised.
 			def initialize(app, location = '/errors/exception')
 				@app = app
 				
@@ -29,6 +30,8 @@ module Utopia
 			end
 			
 			def freeze
+				return self if frozen?
+				
 				@location.freeze
 				
 				super
@@ -74,7 +77,9 @@ module Utopia
 				end
 			end
 			
-			private def write_exception_to_stream(stream, env, exception, include_backtrace = false)
+			private
+			
+			def write_exception_to_stream(stream, env, exception, include_backtrace = false)
 				buffer = []
 				
 				buffer << "While requesting resource #{env[Rack::PATH_INFO].inspect}, a fatal error occurred:"

data/lib/utopia/exceptions/mailer.rb

@@ -23,7 +23,7 @@ require 'mail'
 
 module Utopia
 	module Exceptions
-		# Catches all exceptions raised from the app it wraps and sends a useful email with the exception, stacktrace, and contents of the environment.
+		# A middleware which catches all exceptions raised from the app it wraps and sends a useful email with the exception, stacktrace, and contents of the environment.
 		class Mailer
 			# A basic local non-authenticated SMTP server.
 			LOCAL_SMTP = [:smtp, {
@@ -32,17 +32,36 @@ module Utopia
 				:enable_starttls_auto => false
 			}]
 			
-			def initialize(app, config = {})
+			DEFAULT_FROM = (ENV['USER'] || 'rack') + "@localhost"
+			DEFAULT_SUBJECT = '%{exception} [PID %{pid} : %{cwd}]'
+			
+			# @param to [String] The address to email error reports to.
+			# @param from [String] The from address for error reports.
+			# @param subject [String] The subject template which can access attributes defined by `#attributes_for`.
+			# @param delivery_method [Object] The delivery method as required by the mail gem.
+			# @param dump_environment [Boolean] Attach `env` as `environment.yaml` to the error report.
+			def initialize(app, to: "postmaster", from: DEFAULT_FROM, subject: DEFAULT_SUBJECT, delivery_method: LOCAL_SMTP, dump_environment: false)
 				@app = app
 				
-				@to = config[:to] || "postmaster"
-				@from = config.fetch(:from) {(ENV['USER'] || 'rack') + "@localhost"}
-				@subject = config[:subject] || '%{exception} [PID %{pid} : %{cwd}]'
-				@delivery_method = config.fetch(:delivery_method, LOCAL_SMTP)
+				@to = to
+				@from = from
+				@subject = subject
+				@delivery_method = delivery_method
+				@dump_environment = dump_environment
+			end
+			
+			def freeze
+				return self if frozen?
+				
+				@to.freeze
+				@from.freeze
+				@subject.freeze
+				@delivery_method.freeze
+				@dump_environment.freeze
 				
-				@dump_environment = config.fetch(:dump_environment, false)
+				super
 			end
-
+			
 			def call(env)
 				begin
 					return @app.call(env)
@@ -100,17 +119,19 @@ module Utopia
 				return io.string
 			end
 			
-			def generate_mail(exception, env)
-				attributes = {
+			def attributes_for(exception, env)
+				{
 					exception: exception.class.name,
 					pid: $$,
 					cwd: Dir.getwd,
 				}
-				
+			end
+			
+			def generate_mail(exception, env)
 				mail = Mail.new(
 					:from => @from,
 					:to => @to,
-					:subject => @subject % attributes
+					:subject => @subject % attributes_for(exception, env)
 				)
 				
 				mail.text_part = Mail::Part.new

data/lib/utopia/{tags/node.rb → extensions/array_split.rb}

@@ -19,15 +19,17 @@
 # THE SOFTWARE.
 
 module Utopia
-	module Tags
-		class Node
-			def self.call(transaction, state)
-				path = Path[state[:path]]
-				
-				node = transaction.lookup_node(path)
-				
-				transaction.render_node(node)
+	module Extensions
+		module ArraySplit
+			def split_at(*args, &block)
+				if middle = index(*args, &block)
+					[self[0...middle], self[middle], self[middle+1..-1]]
+				else
+					[[], nil, []]
+				end
 			end
 		end
+
+		::Array.prepend(ArraySplit)
 	end
-end
+end

data/lib/utopia/{tags/environment.rb → extensions/date_comparisons.rb}

@@ -18,24 +18,34 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require 'date'
+
 module Utopia
-	module Tags
-		class Environment
-			def self.for(environment)
-				self.new(environment)
-			end
-			
-			def initialize(environment)
-				@environment = environment
+	module Extensions
+		# Provides comparison operator extensions.
+		module TimeDateComparison
+			def <=>(other)
+				if Date === other or DateTime === other
+					self.to_datetime <=> other
+				else
+					super
+				end
 			end
-			
-			def call(transaction, state)
-				only = state[:only].split(",").collect(&:to_sym) rescue []
+		end
+
+		::Time.prepend(TimeDateComparison)
 
-				if defined?(@environment) and only.include?(@environment)
-					transaction.parse_markup(state.content)
+		# Provides comparison operator extensions.
+		module DateTimeComparison
+			def <=>(other)
+				if Time === other
+					self.to_datetime <=> other.to_datetime
+				else
+					super
 				end
 			end
 		end
+
+		::Date.prepend(DateTimeComparison)
 	end
-end
+end

data/lib/utopia/http.rb

@@ -23,7 +23,9 @@ require 'rack'
 require 'http/accept'
 
 module Utopia
+	# HTTP protocol implementation.
 	module HTTP
+		# Pull in {::HTTP::Accept} for parsing.
 		Accept = ::HTTP::Accept
 		
 		# A list of commonly used HTTP status codes.

data/lib/utopia/locale.rb

@@ -19,6 +19,7 @@
 # THE SOFTWARE.
 
 module Utopia
+	# A structured representation of locale based on RFC3066.
 	Locale = Struct.new(:language, :country, :variant) do
 		def to_s
 			to_a.compact.join('-')

data/lib/utopia/localization.rb

@@ -21,7 +21,7 @@
 require_relative 'middleware'
 
 module Utopia
-	# If you request a URL which has localized content, a localized redirect would be returned based on the content requested.
+	# A middleware which attempts to find localized content.
 	class Localization
 		# A wrapper to provide easy access to locale related data in the request.
 		class Wrapper
@@ -59,38 +59,42 @@ module Utopia
 		LOCALIZATION_KEY = 'utopia.localization'.freeze
 		CURRENT_LOCALE_KEY = 'utopia.localization.current_locale'.freeze
 		
-		DEFAULT_LOCALE = 'en'
-		
-		def initialize(app, **options)
+		# @param locales [Array<String>] An array of all supported locales.
+		# @param default_locale [String] The default locale if none is provided.
+		# @param default_locales [String] The locales to try in order if none is provided.
+		# @param hosts [Hash<Pattern, String>] Specify a mapping of the HTTP_HOST header to a given locale.
+		# @param ignore [Array<Pattern>] A list of patterns matched against PATH_INFO which will not be localized.
+		def initialize(app, locales:, default_locale: nil, default_locales: nil, hosts: {}, ignore: [], **options)
 			@app = app
 			
-			@all_locales = HTTP::Accept::Languages::Locales.new(options[:locales])
+			@all_locales = HTTP::Accept::Languages::Locales.new(locales)
 			
-			# Locales here are represented as an array of strings, e.g. ['en', 'ja', 'cn', 'de'].
-			unless @default_locales = options[:default_locales] 
+			# Locales here are represented as an array of strings, e.g. ['en', 'ja', 'cn', 'de'] and are used in order if no locale is specified by the user.
+			unless @default_locales = default_locales
 				# We append nil, i.e. no localization.
 				@default_locales = @all_locales.names + [nil]
 			end
 			
-			if @default_locale = options[:default_locale]
-				@default_locales.unshift(default_locale)
-			else
-				@default_locale = @default_locales.first
-			end
+			@default_locale = default_locale || @default_locales.first
 			
-			@hosts = options[:hosts] || {}
+			unless @default_locales.include? @default_locale
+				@default_locales.unshift(@default_locale)
+			end
 			
-			@nonlocalized = options.fetch(:nonlocalized, [])
+			# Select a localization based on a request host name:
+			@hosts = hosts
 			
-			self.freeze
+			@ignore = ignore || options[:nonlocalized]
 		end
 		
 		def freeze
+			return self if frozen?
+			
 			@all_locales.freeze
 			@default_locales.freeze
 			@default_locale.freeze
 			@hosts.freeze
-			@nonlocalized.freeze
+			@ignore.freeze
 			
 			super
 		end
@@ -104,7 +108,7 @@ module Utopia
 			# Keep track of what locales have been tried:
 			locales = Set.new
 			
-			host_preferred_locales(env).each do |locale|
+			host_preferred_locales(env) do |locale|
 				yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
 			end
 			
@@ -124,16 +128,13 @@ module Utopia
 			end
 		end
 		
-		HTTP_HOST = 'HTTP_HOST'.freeze
-		
 		def host_preferred_locales(env)
 			http_host = env[Rack::HTTP_HOST]
 			
-			# Get a list of all hosts which match the incoming htt_host:
-			matching_hosts = @hosts.select{|host_pattern, locale| http_host =~ host_pattern}
-			
-			# Extract all the valid locales:
-			matching_hosts.flat_map{|host_pattern, locale| locale}
+			# Yield all hosts which match the incoming http_host:
+			@hosts.each do |pattern, locale|
+				yield locale if http_host[pattern]
+			end
 		end
 		
 		def request_preferred_locale(env)
@@ -163,10 +164,18 @@ module Utopia
 			return []
 		end
 		
-		def nonlocalized?(env)
+		SAFE_METHODS = ['GET', 'HEAD']
+		
+		def localized?(env)
+			# Only SAFE_METHODS can be localized:
+			request_method = env[Rack::REQUEST_METHOD]
+			return false unless SAFE_METHODS.include?(request_method)
+			
+			# Ignore requests which match the ignored paths:
 			path_info = env[Rack::PATH_INFO]
+			return false if @ignore.any? { |pattern| path_info[pattern] != nil }
 			
-			@nonlocalized.any? { |pattern| path_info[pattern] != nil }
+			return true
 		end
 		
 		# Set the Vary: header on the response to indicate that this response should include the header in the cache key.
@@ -190,8 +199,8 @@ module Utopia
 		end
 		
 		def call(env)
-			# Pass the request through with no localization if it is a nonlocalized path:
-			return @app.call(env) if nonlocalized?(env)
+			# Pass the request through if it shouldn't be localized:
+			return @app.call(env) unless localized?(env)
 			
 			env[LOCALIZATION_KEY] = self
 			

data/lib/utopia/logger.rb

@@ -21,6 +21,7 @@
 require_relative 'logger/compact_formatter'
 
 module Utopia
+	# Manages an instance of Logger with useful defaults. Used in rake `tasks/log.rake`.
 	module Logger
 		def self.new(output: STDERR, level: ::Logger::WARN)
 			log = ::Logger.new(output)

data/lib/utopia/logger/compact_formatter.rb

@@ -23,6 +23,7 @@ require 'rainbow'
 
 module Utopia
 	module Logger
+		# Provides a concise log output format.
 		class CompactFormatter
 			def initialize
 				@start = Time.now

data/lib/utopia/middleware.rb

@@ -24,12 +24,22 @@ require_relative 'http'
 require_relative 'path'
 
 module Utopia
+	# The default pages path for {Utopia::Content} middleware.
 	PAGES_PATH = 'pages'.freeze
 	
-	# This is used for shared controller variables which get consumed by the content middleware:
+	# This is used for shared controller variables which get consumed by the content middleware.
 	VARIABLES_KEY = 'utopia.variables'.freeze
 	
+	# The default root directory for middleware to operate within, e.g. the web-site directory. Convention over configuration.
+	# @param subdirectory [String] Appended to the default root to make a more specific path.
+	# @param pwd [String] The working directory for the current site.
 	def self.default_root(subdirectory = PAGES_PATH, pwd = Dir.pwd)
 		File.expand_path(subdirectory, pwd)
 	end
+	
+	# The same as {default_root} but returns an instance of {Path}.
+	# @return [Path] The path as requested.
+	def self.default_path(*args)
+		Path[default_root(*args)]
+	end
 end

data/lib/utopia/path.rb

@@ -65,6 +65,7 @@ module Utopia
 		end
 	end
 	
+	# Represents a path as an array of path components. Useful for efficient URL manipulation.
 	class Path
 		include Comparable
 		

data/lib/utopia/path/matcher.rb

@@ -22,14 +22,23 @@ require_relative '../path'
 
 module Utopia
 	class Path
+		# Performs structured, efficient, matches against {Path} instances. Supports regular expressions, type-casts and constants.
+		# @example
+		# 	path = Utopia::Path['users/20/edit']
+		# 	matcher = Utopia::Path::Matcher[users: /users/, id: Integer, action: String]
+		# 	match_data = matcher.match(path)
 		class Matcher
+			# The result of matching against a {Path}.
 			class MatchData
 				def initialize(named_parts, post_match)
 					@named_parts = named_parts
 					@post_match = Path[post_match]
 				end
 				
+				# Matched components by name.
 				attr :named_parts
+				
+				# Any remaining part past the end of the explicitly matched components.
 				attr :post_match
 				
 				def [] key
@@ -41,7 +50,7 @@ module Utopia
 				end
 			end
 			
-			# patterns = {key: /\d+/, 'foo', }
+			# @param patterns [Hash<Symbol,Pattern>] An ordered list of things to match.
 			def initialize(patterns = [])
 				@patterns = patterns
 			end
@@ -64,14 +73,16 @@ module Utopia
 				return nil
 			end
 			
-			# This is a path prefix matching algorithm. The pattern is an array of String, Symbol, Regexp, or nil. The components is an array of String.
+			# This is a path prefix matching algorithm. The pattern is an array of String, Symbol, Regexp, or nil. The path is an array of String.
 			def match(path)
 				components = path.to_a
 				
+				# Can't possibly match if not enough components:
 				return nil if components.size < @patterns.size
 				
 				named_parts = {}
 				
+				# Try to match each component against the pattern:
 				@patterns.each_with_index do |(key, pattern), index|
 					component = components[index]
 					
@@ -83,6 +94,7 @@ module Utopia
 						if result = pattern.match(component)
 							named_parts[key] = result
 						else
+							# Couldn't match:
 							return nil
 						end
 					else