utopia 2.18.0 → 2.18.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8851f81c898bf14616952ae21c9c5379bff340c112e84c422f652ceeff26a2f
-  data.tar.gz: e1abf3e367e371b83edfb2089371367952d6f4d23ffae441074abe3dd3daff66
+  metadata.gz: 2e27bab1354cbb8b2d4ab415c3c2570db443ece1628692bbd17ef1f6e7bd2329
+  data.tar.gz: 155b3b5ff07f33d836297db25be41d534c84e50ed9133b4d2ab69eec6730aeb8
 SHA512:
-  metadata.gz: e191685798e34a85a19c06828987938efc4876b50691add9dd923ab6b53d38c6a5e578cc3b94fa5fc3129dba368106dcf621f02d1a6cf0e8243238d79fac83e9
-  data.tar.gz: fc79ea764f46e0352ed1fa000a049d32c7c2c3ea8511ef12fd2e5270d4465873fac12468bb93fe576eeea496297dd23826bff342216493b98b54b2b36f7e0dc5
+  metadata.gz: d73b02adae74b577cff9e5a9b47f2d226f5bf97b9e246baeb325c21728d83e3c46069c20b6b6e38309900951c74d72985800864e7c682e39b27681fc3bc58cf2
+  data.tar.gz: 8038fbd4bd0334ec21391e86e2c0e55cb3a0caeef59b7700f310c5772fdc50c71997e8fa4ab258a34ca1d36fe5f17f7c3363dc6645dcd1d25eed06e42795b2db

data/lib/utopia/controller/actions.md

@@ -0,0 +1,76 @@
+# Utopia::Controller::Actions
+
+Actions let you match path patterns in your controller and execute code. In your `controller.rb` simply add:
+
+```ruby
+prepend Actions
+```
+
+If you are adding multiple things, like rewriting, they should come earlier in the chain, e.g:
+
+```ruby
+prepend Rewrite, Actions
+```
+
+A simple CRUD controller might look like:
+
+```ruby
+prepend Actions
+
+on 'index' do
+	@users = User.all
+end
+
+on 'new' do |request|
+	@user = User.new
+	
+	if request.post?
+		@user.update_attributes(request.params['user'])
+		
+		redirect! "index"
+	end
+end
+
+on 'edit' do |request|
+	@user = User.find(request.params['id'])
+	
+	if request.post?
+		@user.update_attributes(request.params['user'])
+		
+		redirect! "index"
+	end
+end
+
+on 'delete' do |request|
+	User.find(request.params['id']).destroy
+	
+	redirect! "index"
+end
+```
+	
+## Path Matching
+
+Path matching works from right to left, and `'**'` is a greedy operator. Controllers are invoked with a path relative to the controller's `URI_PATH`, so all lookups are relative to the controller.
+
+<dl>
+	<dt><code class="language-ruby">"*"</code></dt>
+	<dd>Match a single path element</dd>
+	<dt><code class="language-ruby">"**"</code></dt>
+	<dd>Match all remaining path elements</dd>
+	<dt><code class="language-ruby">String</code></dt>
+	<dd>Match a named path component, e.g. <code class="language-ruby">"edit"</code>.</dd>
+	<dt><code class="language-ruby">Symbol</code></dt>
+	<dd>Equivalent to <code class="language-ruby">["**", symbol.to_s]</code>, e.g. <code class="language-ruby">:logout</code>.</dd>
+</dl>
+
+## Otherwise Matching
+
+If no action was matched, it is sometimes useful to perform some specific behaviour. You can specify this by using the otherwise handler:
+
+```ruby
+otherwise do |request, path|
+	fail! :teapot
+end
+```
+
+If you are doing this to perform some kind of rewriting, it may be preferable to use the [Rewrite](../rewrite/) controller layer.

data/lib/utopia/controller/rewrite.md

@@ -0,0 +1,69 @@
+# Utopia::Controller::Rewrite
+
+This module can match and rewrite requests before they processed. This allows you to handle URLs like `/post/15/view` or `/blog/123-pictures-of-my-cat` easily. The basic rewrite operation is to extract some part of the path and optionally executes a block. That means that the path is modified before being passed on to the next layer in the controller, and controller instance variables may be set.
+
+## Regular Expressions
+
+In your `controller.rb`:
+
+```ruby
+prepend Rewrite, Actions
+
+rewrite.extract_prefix permalink: /(?<id>\d+)-(?<title>.*)/ do |request, path, match|
+	# The rewrite matched, but there was no valid post, so we fail:
+	fail! unless @post = Post.find(@permalink[:id])
+	
+	# If the path matched, but there was no suffix, we make it default to the post action:
+	if match.post_match.empty?
+		match.post_match.components << "post"
+	end
+end
+
+on 'post' do
+	# You can do further processing here.
+	fail! unless @post.published?
+	
+	@comments = @post.comments.first(5)
+end
+
+on 'edit' do
+	# You can do further processing here.
+	fail! unless @current_user&.editor?
+end
+```
+
+In your `post.xnode`, as an example:
+
+```trenni
+<content:page>
+	<content:heading>Post #{attributes[:permalink][:id]} about #{attributes[:permalink][:title]}</content:heading>
+	
+	<p>#{attributes[:post].content}</p>
+</content:page>
+```
+
+Keep in mind, that URLs like `/123-pictures-of-my-cat/edit` will work as expected, and hit the `edit` action of the controller.
+
+## Restful Resources
+
+Similar to the above, if we were solely interested in IDs, we could do the following:
+
+```ruby
+prepend Rewrite, Actions
+
+rewrite.extract_prefix post_id: Integer do |request, path, match|
+	# The rewrite matched, but there was no valid post, so we fail:
+	fail! unless @post = Post.find(@post_id)
+	
+	# If the path matched, but there was no suffix, we make it default to the post action:
+	if match.post_match.empty?
+		match.post_match.components << "post"
+	end
+end
+```
+
+This will only match complete integers. Assuming this code is in `/blog/controller.rb`, it would match something like `/blog/123/view` and assign <code class="language-ruby">Integer("123")</code> to <code class="language-ruby">@post_id</code>.
+
+### Matching.. other things
+
+It's possible to match using <code class="language-ruby">Integer</code>, <code class="language-ruby">Float</code>, <code class="language-ruby">String</code>, and you can provide your own class which will be instantiated. If it doesn't match, raise an exception and the rewrite rule will fail.

data/lib/utopia/path.rb

@@ -178,8 +178,14 @@ module Utopia
 			@components
 		end
 		
+		# @parameter other [Array(String)] The path components to append.
 		def join(other)
-			self.class.new(@components + other).simplify
+			# Check whether other is an absolute path:
+			if other.first == ''
+				self.class.new(other)
+			else
+				self.class.new(@components + other).simplify
+			end
 		end
 		
 		def expand(root)

data/lib/utopia/version.rb

@@ -21,5 +21,5 @@
 # THE SOFTWARE.
 
 module Utopia
-	VERSION = "2.18.0"
+	VERSION = "2.18.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: utopia
 version: !ruby/object:Gem::Version
-  version: 2.18.0
+  version: 2.18.1
 platform: ruby
 authors:
 - Samuel Williams
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-06-17 00:00:00.000000000 Z
+date: 2020-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -248,20 +248,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.6'
-- !ruby/object:Gem::Dependency
-  name: utopia-project
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description:
 email:
 executables:
@@ -291,9 +277,11 @@ files:
 - lib/utopia/content/tags.rb
 - lib/utopia/content_length.rb
 - lib/utopia/controller.rb
+- lib/utopia/controller/actions.md
 - lib/utopia/controller/actions.rb
 - lib/utopia/controller/base.rb
 - lib/utopia/controller/respond.rb
+- lib/utopia/controller/rewrite.md
 - lib/utopia/controller/rewrite.rb
 - lib/utopia/controller/variables.rb
 - lib/utopia/exceptions.rb