Merge pull request #118 from townsen/document-property-filtering

Document Property filtering

_includes/navigation.html

@@ -27,6 +27,7 @@
   <li><a href="/documentation/advanced-features/console/">Console</a></li>
   <li><a href="/documentation/advanced-features/ptys/">PTYs</a></li>
   <li><a href="/documentation/advanced-features/host-and-role-filtering/">Host and Role Filtering</a></li>
+  <li><a href="/documentation/advanced-features/property-filtering/">Property Filtering</a></li>
   <li><a href="/documentation/advanced-features/host-filtering/">Host filtering</a></li>
   <li><a href="/documentation/advanced-features/role-filtering/">Role Filtering</a></li>
   <li><a href="/documentation/advanced-features/overriding-capistrano-tasks/">Overriding Capistrano Tasks</a></li>

documentation/advanced-features/property-filtering/index.markdown

@@ -0,0 +1,55 @@
+---
+title: Property Filtering
+layout: default
+---
+
+Options may be passed to the `roles()` method (and implicitly in methods like
+`release_roles()` and `primary()`) that affect the set of servers returned. These options
+take the form of a Hash passed as the last parameter.  Each of the key/value pairs in the
+hash are evaluated in the sequence they are declared and if all are true for a specific
+server then the server will be returned. The keys must always be symbols which have the
+following meaning:
+
+* `:filter`, or `:select`: The value must return true for the server to be included,
+* `:exclude`: The value must return false for the server to be included, and
+* Any other symbol is taken as a server property name whose value must equal the given value.
+
+In the first two cases the values themselves can be a lambda that will be evaluated with the
+current server. In the last case the value may be anything and is just tested for
+equality.
+
+Examples
+{% highlight ruby %}
+server 'example1.com', roles: %w{web}, active: true
+server 'example2.com', roles: %w{web}
+server 'example3.com', roles: %w{app web}, active: true
+server 'example4.com', roles: %w{app}, primary: true
+server 'example5.com', roles: %w{db}, no_release: true, active:true
+
+task :demo do
+  puts "All active release roles: 1,3"
+  release_roles(:all, filter: :active).each do |r|
+    puts "#{r.hostname}"
+  end
+  puts "All active roles: 1,3,5"
+  roles(:all, active: true).each do |r|
+    puts "#{r.hostname}"
+  end
+  puts "All web and db roles with selected names: 2,3"
+  roles(:web, :db, select: ->(s){ s.hostname =~ /[234]/}).each do |r|
+    puts "#{r.hostname}"
+  end
+  puts "All with no active property: 2,4"
+  roles(:all, active: nil).each do |r|
+    puts "#{r.hostname}"
+  end
+  puts "All except active: 2,4"
+  roles(:all, exclude: :active).each do |r|
+    puts "#{r.hostname}"
+  end
+  puts "All primary: 4"
+  roles(:all, select: :primary).each do |r|
+    puts "#{r.hostname}"
+  end
+end
+{% endhighlight %}