Allow running local commands using on(:local)

This works as an alias for `run_locally`. The advantage of this
feature is that Capistrano can be easily configured to perform
actions on the local host or on a server, depending on user input,
without having to replace all `on` calls with `run_locally`.

For example (in Capistrano):

    if ENV['RUN_LOCALLY']
      server :local, :roles => [:app]
    else
      server "example.com", :roles => [:app]
    end

    on roles(:app) do
      execute :any_command
    end

Author: FooBarWidget

EXAMPLES.md

@@ -344,3 +344,10 @@ Replace `on` with `run_locally`
       end
     end
 
+You can achieve the same thing with `on(:local)`
+
+    on(:local) do
+      within '/tmp' do
+        execute :whoami
+      end
+    end

lib/sshkit/backends/local.rb

@@ -6,12 +6,12 @@ module Backend
     class Local < Printer
 
       def initialize(&block)
-        @host = Host.new(hostname: 'localhost') # just for logging
+        @host = Host.new(:local) # just for logging
         @block = block
       end
 
       def run
-        instance_exec(&@block)
+        instance_exec(@host, &@block)
       end
 
       def test(*args)

lib/sshkit/host.rb

@@ -1,4 +1,5 @@
 require 'ostruct'
+require 'etc'
 
 module SSHKit
 
@@ -22,7 +23,11 @@ def keys
 
     def initialize(host_string_or_options_hash)
 
-      unless host_string_or_options_hash.is_a?(Hash)
+      if host_string_or_options_hash == :local
+        @local = true
+        @hostname = "localhost"
+        @user = Etc.getpwuid.name
+      elsif !host_string_or_options_hash.is_a?(Hash)
         suitable_parsers = [
           SimpleHostParser,
           HostWithPortParser,
@@ -51,6 +56,10 @@ def initialize(host_string_or_options_hash)
       end
     end
 
+    def local?
+      @local
+    end
+
     def hash
       user.hash ^ hostname.hash ^ port.hash
     end

lib/sshkit/runners/abstract.rb

@@ -15,7 +15,11 @@ def initialize(hosts, options = nil, &block)
       private
 
       def backend(host, &block)
-        SSHKit.config.backend.new(host, &block)
+        if host.local?
+          SSHKit::Backend::Local.new(&block)
+        else
+          SSHKit.config.backend.new(host, &block)
+        end
       end
 
     end

test/unit/test_host.rb

@@ -1,4 +1,5 @@
 require 'helper'
+require 'etc'
 
 module SSHKit
 
@@ -41,6 +42,14 @@ def test_host_with_username_and_port
       assert_equal 'example.com', h.hostname
     end
 
+    def test_host_local
+      h = Host.new :local
+      assert       h.local?
+      assert_nil   h.port
+      assert_equal Etc.getpwuid.name, h.username
+      assert_equal 'localhost',       h.hostname
+    end
+
     def test_does_not_confuse_ipv6_hosts_with_port_specification
       h = Host.new '[1fff:0:a88:85a3::ac1f]:8001'
       assert_equal 8001,                    h.port