utopia 2.2.0 → 2.3.0

data/documentation/Guardfile

@@ -6,16 +6,4 @@ group :development do
 		watch(%r{^config|lib|pages/.*})
 		notification :off
 	end
-	
-	# # Open the documentation website when the command is run, once puma has started:
-	# require 'launchy'
-	# $first_time = true
-	# 
-	# url_path = 'run/url.txt'
-	# watch(url_path) do
-	# 	if $first_time
-	# 		$first_time = false
-	# 		Launchy.open(File.read(url_path))
-	# 	end
-	# end
 end

data/documentation/Rakefile

@@ -1,4 +1,7 @@
 
+require 'pathname'
+SITE_ROOT = Pathname.new(__dir__).realpath
+
 # Load all rake tasks:
 import(*Dir.glob('tasks/*.rake'))
 

data/documentation/pages/_page.xnode

@@ -9,6 +9,8 @@
 			<title>Utopia</title>
 		<?r end ?>
 		
+		<meta charset="UTF-8" />
+		
 		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous" />
 		
 		<link rel="icon" type="image/png" href="/_static/icon.png" />

data/documentation/pages/wiki/content.md

@@ -9,6 +9,7 @@ Reading these pages in order will give you an overview of the design of Utopia,
 - [Development Environment Setup](development-environment-setup/)
 - [Server Setup](server-setup/)
 - [Your First Page](your-first-page/)
+  - [What is `.xnode`?](faq/what-is-xnode/)
 - [Installing JavaScript Libraries](bower-integration/)
 - [Website Tests](testing/)
 - [Updating Your Site](updating-utopia/)

data/documentation/pages/wiki/faq/what-is-xnode/content.md

@@ -0,0 +1,37 @@
+# What Is `.xnode`?
+
+Xnodes are the files on disk which are used as part of Utopia's content/view layer. Xnode templates are designed to maximise the ratio of content to markup. They improve separation of concerns and semantic organisation because repeated markup can be reused easily.
+
+Here is a example of a blog post:
+
+```xml
+<content:entry title="My day as a fish">
+	<p>It was not very exciting</p>
+</content:entry>
+```
+
+The `Utopia::Content` middleware is built on top of the [Trenni](https://github.com/ioquatix/trenni) template language which uses two-phase evaluation.
+
+## Phase 1: Evaluation
+
+Trenni processes the view content by evaluation `#{expressions}` and `<?r statements ?>`. This generates an output buffer. The output buffer should contain valid markup (i.e. balanced tags, no invalid characters).
+
+## Phase 2: Markup
+
+Once the template is evaluated to text, it is parsed again into an event stream which is used to generate the final output. The event stream contains things like "open tag", "attribute", "close tag", and so on, and these are fed into the `Utopia::Content` middleware which generates the actual content. Tags without namespaces are output verbatim, while tags with namespaces invoke the tag lookup machinery. This uses the tag name to invoke further behaviour, e.g. inserting more content. Here is a simple example of a basic page:
+
+```xml
+<content:page>
+	<content:heading>Welcome to my page</content:heading>
+
+	<p>This page is so awesome</p>
+</content:page>
+```
+
+In order to render this, you will need two additional files, `_page.xnode` and `_heading.xnode`. As a short example, `_heading.xnode` might look like this:
+
+```xml
+<h1><utopia:content/></h1>
+```
+
+When the parser encounters `<content:heading>...` in the main page, it would evaluate the above template. `<utopia:content/>` is a special tag that evaluates to the content that the parent tag provided, so in this case: `"Welcome to my page"`.  Thus, the final output is `<h1>Welcome to my page</h1>`.

data/documentation/pages/wiki/links.yaml

@@ -1,2 +1,4 @@
 index:
-  title: "Wiki"
+  title: Wiki
+faq:
+  title: FAQ

data/documentation/pages/wiki/server-setup/content.md

@@ -26,7 +26,7 @@ $ git push --set-upstream production master
 Utopia will load `config/environment.yaml` and update `ENV` before executing any code. You can set default environment values using the `utopia` command:
 
 ```bash
-$ sudo -u http utopia server environment RACK_ENV=production DATABASE_ENV=production_cluster_primary
+$ sudo -u http utopia environment RACK_ENV=production DATABASE_ENV=production_cluster_primary
 ENV["RACK_ENV"] will default to "production" unless otherwise specified.
 ENV["DATABASE_ENV"] will default to "production_cluster_primary" unless otherwise specified.
 ```

data/documentation/pages/wiki/show.xnode

@@ -5,6 +5,8 @@
 	
 	<footer>
 		Last Modified: #{File.mtime(self[:page_file]) rescue "N/A"} &mdash;
+		<?r if RACK_ENV != :static ?>
 		<a href="edit">Edit Page</a>
+		<?r end ?>
 	</footer>
 </content:page>

data/documentation/pages/wiki/your-first-page/content.md

@@ -9,7 +9,7 @@ $ utopia site create
 $ rake server
 ```
 
-You will now have a basic template site running on <a href="http://localhost:9292">http://localhost:9292</a>.
+You will now have a basic template site running on `http://localhost:9292`.
 
 ## Welcome Page
 

data/lib/utopia/command.rb

@@ -22,6 +22,7 @@ require_relative 'version'
 
 require_relative 'command/site'
 require_relative 'command/server'
+require_relative 'command/environment'
 
 module Utopia
 	module Command
@@ -41,7 +42,8 @@ module Utopia
 			
 			nested '<command>',
 				'site' => Site,
-				'server' => Server
+				'server' => Server,
+				'environment' => Environment
 			
 			# The root directory for the site.
 			def root
@@ -54,9 +56,7 @@ module Utopia
 				elsif @options[:help] or @command.nil?
 					print_usage(program_name)
 				else
-					track_time do
-						@command.invoke(self)
-					end
+					@command.invoke(self)
 				end
 			end
 		end

data/lib/utopia/command/environment.rb

@@ -0,0 +1,73 @@
+# Copyright, 2016, by Samuel G. D. Williams. <http://www.codeotaku.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'securerandom'
+require 'yaml/store'
+
+module Utopia
+	module Command
+		# Set environment variables within the server deployment.
+		class Environment < Samovar::Command
+			self.description = "Update environment variables in config/environment.yaml"
+			
+			options do
+				option '-e/--environment-name <name>', "The environment file to modify.", default: 'environment'
+			end
+			
+			many :variables, "A list of environment KEY=VALUE pairs to set."
+			
+			# Setup `config/environment.yaml` according to specified options.
+			def update_environment(root, name = @options[:environment_name])
+				environment_path = File.join(root, "config", "#{name}.yaml")
+				FileUtils.mkpath File.dirname(environment_path)
+				
+				store = YAML::Store.new(environment_path)
+				
+				store.transaction do
+					yield store
+				end
+			end
+			
+			def invoke(parent)
+				destination_root = parent.root
+				
+				update_environment(destination_root) do |store|
+					variables.each do |variable|
+						key, value = variable.split('=', 2)
+						
+						if value
+							puts "ENV[#{key.inspect}] will default to #{value.inspect} unless otherwise specified."
+							store[key] = value
+						else
+							puts "ENV[#{key.inspect}] will be unset unless otherwise specified."
+							store.delete(key)
+						end
+					end
+					
+					store.roots.each do |key|
+						value = store[key]
+						
+						puts "#{Rainbow(key).blue}: #{Rainbow(value.inspect).green}"
+					end
+				end
+			end
+		end
+	end
+end

data/lib/utopia/command/server.rb

@@ -18,7 +18,11 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require_relative 'setup'
+require_relative 'site'
+
+require 'fileutils'
+
+require 'samovar'
 
 module Utopia
 	module Command
@@ -46,6 +50,11 @@ module Utopia
 			class Update < Samovar::Command
 				self.description = "Update the git hooks in an existing server repository."
 				
+				def template_root
+					# The root directory of the template server deployment:
+					File.join(SETUP_ROOT, 'server')
+				end
+				
 				def invoke(parent)
 					destination_root = parent.root
 					
@@ -64,49 +73,27 @@ module Utopia
 						# chmod g+s `find . -type d`                # New files get group id of directory
 					end
 					
-					Setup::Server.update_default_environment(destination_root)
+					# Set some useful defaults for the environment.
+					environment = Environment[]
+					environment.update_environment(destination_root) do |store|
+						store['RACK_ENV'] ||= 'production'
+						store['DATABASE_ENV'] ||= 'production'
+						store['UTOPIA_SESSION_SECRET'] ||= SecureRandom.hex(40)
+					end
 					
 					# Copy git hooks:
-					system("cp", "-r", File.join(Setup::Server::ROOT, 'git', 'hooks'), File.join(destination_root, '.git')) or fail "could not copy git hooks"
+					system("cp", "-r", File.join(template_root, 'git', 'hooks'), File.join(destination_root, '.git')) or fail "could not copy git hooks"
 					# finally set everything in the .git directory to be group writable
 					# This failed for me and I had to do sudo chown http:http .git -R first.
 					system("chmod", "-Rf", "g+w", File.join(destination_root, '.git')) or fail "could not update permissions of .git directory"
 				end
 			end
 			
-			# Set environment variables within the server deployment.
-			class Environment < Samovar::Command
-				self.description = "Update environment variables in config/environment.yaml"
-				
-				many :variables, "A list of environment KEY=VALUE pairs to set."
-				
-				def invoke(parent)
-					return if variables.empty?
-					
-					destination_root = parent.root
-					
-					Setup::Server.environment(destination_root) do |store|
-						variables.each do |variable|
-							key, value = variable.split('=', 2)
-							
-							if value
-								puts "ENV[#{key.inspect}] will default to #{value.inspect} unless otherwise specified."
-								store[key] = value
-							else
-								puts "ENV[#{key.inspect}] will be unset unless otherwise specified."
-								store.delete(key)
-							end
-						end
-					end
-				end
-			end
-			
 			self.description = "Manage server deployments."
 			
 			nested '<command>',
 				'create' => Create,
-				'update' => Update,
-				'environment' => Environment
+				'update' => Update
 			
 			def invoke(parent)
 				@command.invoke(parent)

data/lib/utopia/command/site.rb

@@ -18,29 +18,46 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
-require_relative 'setup'
+require 'fileutils'
+require 'find'
+
+require 'samovar'
 
 module Utopia
 	module Command
+		# This path must point to utopia/setup in the gem source.
+		SETUP_ROOT = File.expand_path("../../../setup", __dir__)
+		
 		# Local site setup commands.
 		class Site < Samovar::Command
+			# Configuration files which should be installed/updated:
+			CONFIGURATION_FILES = ['.bowerrc', '.gitignore', 'config.ru', 'config/environment.rb', 'Gemfile', 'Guardfile', 'Rakefile', 'tasks/bower.rake', 'tasks/deploy.rake', 'tasks/development.rake', 'tasks/environment.rake', 'tasks/log.rake']
+			
+			# Directories that should exist:
+			DIRECTORIES = ["config", "lib", "pages", "public", "tasks"]
+			
+			# Directories that should be removed during upgrade process:
+			OLD_PATHS = ["access_log", "cache", "tmp", 'tasks/test.rake', 'tasks/utopia.rake']
+			
+			# The root directory of the template site:
+			ROOT = File.join(SETUP_ROOT, 'site')
+			
 			# Create a local site.
 			class Create < Samovar::Command
 				self.description = "Create a new local Utopia website using the default template."
-				# self.example = "utopia --in www.example.com site create"
 				
 				def invoke(parent)
 					destination_root = parent.root
 					
 					$stderr.puts "Setting up initial site in #{destination_root} for Utopia v#{Utopia::VERSION}..."
 					
-					Setup::Site::DIRECTORIES.each do |directory|
+					DIRECTORIES.each do |directory|
 						FileUtils.mkdir_p(File.join(destination_root, directory))
 					end
 					
-					Find.find(Setup::Site::ROOT) do |source_path|
+					Find.find(ROOT) do |source_path|
 						# What is this doing?
-						destination_path = File.join(destination_root, source_path[Setup::Site::ROOT.size..-1])
+						destination_path = File.join(destination_root, source_path[ROOT.size..-1])
 						
 						if File.directory?(source_path)
 							FileUtils.mkdir_p(destination_path)
@@ -51,7 +68,7 @@ module Utopia
 						end
 					end
 					
-					Setup::Site::CONFIGURATION_FILES.each do |configuration_file|
+					CONFIGURATION_FILES.each do |configuration_file|
 						destination_path = File.join(destination_root, configuration_file)
 						
 						buffer = File.read(destination_path).gsub('$UTOPIA_VERSION', Utopia::VERSION)
@@ -128,17 +145,17 @@ module Utopia
 						system('git', 'checkout', '-b', branch_name) or fail "could not change branch"
 					end
 					
-					Setup::Site::DIRECTORIES.each do |directory|
+					DIRECTORIES.each do |directory|
 						FileUtils.mkdir_p(File.join(destination_root, directory))
 					end
 					
-					Setup::Site::OLD_PATHS.each do |path|
+					OLD_PATHS.each do |path|
 						path = File.join(destination_root, path)
 						$stderr.puts "\tRemoving #{path}..."
 						FileUtils.rm_rf(path)
 					end
 					
-					Setup::Site::CONFIGURATION_FILES.each do |configuration_file|
+					CONFIGURATION_FILES.each do |configuration_file|
 						source_path = File.join(Setup::Site::ROOT, configuration_file)
 						destination_path = File.join(destination_root, configuration_file)
 						

data/lib/utopia/content/markup.rb

@@ -103,7 +103,7 @@ module Utopia
 				# This is for compatibility with the existing API which passes in a string:
 				buffer = Trenni::Buffer(buffer)
 				
-				self.new(buffer, delegate).parse!
+				self.new(buffer, delegate, entities).parse!
 			end
 			
 			def initialize(buffer, delegate, entities = Trenni::Entities::HTML5)

data/lib/utopia/setup.rb

@@ -18,55 +18,84 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 # THE SOFTWARE.
 
+require 'yaml'
+
 module Utopia
 	# Used for setting up a Utopia web application, typically via `config/environment.rb`
-	class Bootstrap
+	class Setup
 		def initialize(config_root, external_encoding: Encoding::UTF_8)
 			@config_root = config_root
 			
 			@external_encoding = external_encoding
+			
+			@environment = nil
 		end
 		
-		def setup
-			setup_encoding
+		attr :config_root
+		attr :external_encoding
+		attr :environment
+		
+		ENVIRONMENT_KEY = 'UTOPIA_ENV'.freeze
+		DEFAULT_ENVIRONMENT = 'environment'.freeze
+		
+		def explicit_environment_name
+			ENV[ENVIRONMENT_KEY]
+		end
+		
+		def site_root
+			File.dirname(@config_root)
+		end
+		
+		def apply
+			set_external_encoding
 			
-			setup_environment
+			apply_environment
 			
-			setup_load_path
+			add_load_path('lib')
 			
 			require_relative '../utopia'
 		end
 		
-		def environment_path
-			File.expand_path('environment.yaml', @config_root)
+		def apply_environment
+			if name = explicit_environment_name
+				load_environment(name)
+			else
+				load_environment(DEFAULT_ENVIRONMENT)
+			end
+		end
+		
+		def environment_path(name, root = @config_root)
+			File.expand_path("#{name}.yaml", root)
 		end
 		
 		# If you don't specify these, it's possible to have issues when encodings mismatch on the server.
-		def setup_encoding
+		def set_external_encoding(encoding = Encoding::UTF_8)
 			# TODO: Deprecate and remove this setup - it should be the responsibility of the server to set this correctly.
-			if @external_encoding and Encoding.default_external != @external_encoding
-				warn "Updating Encoding.default_external from #{Encoding.default_external} to #{@external_encoding}" if $VERBOSE
-				Encoding.default_external = @external_encoding
+			if Encoding.default_external != encoding
+				warn "Updating Encoding.default_external from #{Encoding.default_external} to #{encoding}" if $VERBOSE
+				Encoding.default_external = encoding
 			end
 		end
 		
-		def setup_environment
-			if File.exist? environment_path
-				require 'yaml'
-				
+		# Load the named configuration file from the `config_root` directory.
+		def load_environment(*args)
+			path = environment_path(*args)
+			
+			if File.exist?(path)
 				# Load the YAML environment file:
-				environment = YAML.load_file(environment_path)
+				@environment = YAML.load_file(path)
 				
 				# We update ENV but only when it's not already set to something:
-				ENV.update(environment) do |name, old_value, new_value|
+				ENV.update(@environment) do |name, old_value, new_value|
 					old_value || new_value
 				end
 			end
 		end
 		
-		def setup_load_path
+		# Add the given path to $LOAD_PATH. If it's relative, make it absolute relative to `site_path`.
+		def add_load_path(path)
 			# Allow loading library code from lib directory:
-			$LOAD_PATH << File.expand_path('../lib', @config_root)
+			$LOAD_PATH << File.expand_path(path, site_root)
 		end
 	end
 	
@@ -77,6 +106,6 @@ module Utopia
 			config_root = File.dirname(caller[0])
 		end
 		
-		Bootstrap.new(config_root, **options).tap(&:setup)
+		Setup.new(config_root, **options).tap(&:apply)
 	end
 end