strelka 0.11.0 → 0.12.0

data/lib/strelka/command/discover.rb

@@ -0,0 +1,29 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'strelka/cli' unless defined?( Strelka::CLI )
+
+
+# Command to show discovered Strelka apps
+module Strelka::CLI::Discover
+	extend Strelka::CLI::Subcommand
+
+	desc 'Show installed Strelka apps'
+	command :discover do |cmd|
+
+		cmd.action do |globals, options, args|
+			prompt.say( headline_string "Searching for Strelka applications..." )
+
+			apps = Strelka::Discovery.discovered_apps
+
+			if apps.empty?
+				prompt.say "None found."
+			else
+				rows = apps.sort_by {|name, path| name }
+				display_table( rows )
+			end
+		end
+	end
+
+end # module Strelka::CLI::Discover
+

data/lib/strelka/command/start.rb

@@ -0,0 +1,40 @@
+# -*- ruby -*-
+#encoding: utf-8
+
+require 'strelka/cli' unless defined?( Strelka::CLI )
+
+
+# Command to start a Strelka application
+module Strelka::CLI::Start
+	extend Strelka::CLI::Subcommand
+
+	desc 'Start a Strelka app'
+	arg :GEMNAME, :optional
+	arg :APPNAME
+	command :start do |cmd|
+
+		cmd.action do |globals, options, args|
+			appname = args.pop
+			gemname = args.pop
+			path    = nil
+
+			gem( gemname ) if gemname
+
+			app = if File.exist?( appname )
+					Strelka::Discovery.load_file( appname ) or
+						exit_now!( "Didn't find an app while loading %p!" % [appname] )
+				else
+					Strelka::Discovery.load( appname ) or
+						exit_now!( "Couldn't find the %p app!" % [appname] )
+				end
+
+			Strelka::CLI.prompt.say "Starting %s (%p)." % [ appname, app ]
+			Strelka.load_config( options[:c] ) if options[:c]
+			unless_dryrun( "starting the app" ) do
+				app.run
+			end
+		end
+	end
+
+end # module Strelka::CLI::Start
+

data/lib/strelka/discovery.rb

@@ -7,6 +7,83 @@ require 'strelka' unless defined?( Strelka )
 
 
 # The Strelka application-discovery system.
+#
+# This module provides a mechanism for registering Strelka apps and their
+# resources for discovery by the strelka CLI and other systems.
+#
+# It's responsible for three kinds of discovery:
+#
+# - Discovery of Strelka app files via Rubygems discovery
+# - Discovery and loading of Strelka app classes by name
+# - Discovery of data directories for strelka apps
+#
+# As such it can be used in several different ways.
+#
+# == \App File \Discovery
+#
+# If you have an app that you wish to be discoverable, create a
+# <tt>lib/strelka/apps.rb</tt> file. This file will be added to those returned
+# by the ::app_discovery_files call, which is the list loaded by
+# ::discovered_apps.
+#
+# == \App \Discovery Registration
+#
+# To add a name and file path to Strelka::Discovery.discovered_apps, you can
+# call ::register_app. This will check to make sure no other apps are registered
+# with the same name. To register several at the same time, call
+# ::register_apps with a Hash of <tt>name => path</tt> pairs.
+#
+# == Loading Discovered Apps
+#
+# To load a discovered app, call ::load with its registered name.
+#
+# This will load the associated file and returns the first Ruby class to inherit
+# from a discoverable app class like Strelka::App or Strelka::WebSocketServer.
+#
+# === Putting it all together
+#
+# Say, for example, you were putting together an <tt>acme-apps</tt> gem for the
+# Acme company that contained Strelka apps for a web store and a CMS. You could
+# add a <tt>lib/strelka/apps.rb</tt> file to the <tt>acme-apps</tt> gem that
+# contained the following:
+#
+#     # -*- ruby -*-
+#     require 'strelka/discovery'
+#
+#     Strelka::Discovery.register_apps(
+#         'acme-store' => 'lib/acme/store.rb',
+#         'acme-cms' => 'lib/acme/cms.rb'
+#     )
+#
+# This would let you do:
+#
+#     $ gem install acme-apps
+#     $ strelka start acme-store
+#
+#
+# == Data Directory \Discovery
+#
+# If your app requires some filesystem resources, a good way to distribute these
+# is in your gem's "data directory". This is a directory in your gem called
+# <tt>data/«your gem name»</tt>, and can be found via:
+#
+#    Gem.datadir( your_gem_name )
+#
+# Strelka::Discoverable builds on top of this, and can return a Hash of glob
+# patterns that will match the data directories of all gems that depend on
+# Strelka, keyed by gem name. You can use this to populate search paths for
+# templates, static assets, etc.
+#
+#    template_paths = Strelka::Discovery.discover_data_dirs.
+#        flat_map {|_, pattern| Dir.glob(pattern + '/templates') }
+#
+# == Making a class Discoverable
+#
+# If you write your own app base class (e.g., Strelka::App,
+# Strelka::WebSocketServer), you can make it discoverable by extending it with
+# this module. You typically won't have to do this unless you're working on
+# Strelka itself.
+#
 module Strelka::Discovery
 	extend Loggability,
 	       Configurability,
@@ -22,7 +99,7 @@ module Strelka::Discovery
 
 	# Default config
 	CONFIG_DEFAULTS = {
-		app_glob_pattern: '{apps,handlers}/**/*',
+		app_discovery_file: 'strelka/apps.rb',
 		local_data_dirs:  'data/*',
 	}.freeze
 
@@ -30,11 +107,11 @@ module Strelka::Discovery
 	##
 	# The Hash of Strelka::App subclasses, keyed by the Pathname of the file they were
 	# loaded from, or +nil+ if they weren't loaded via ::load.
-	singleton_attr_reader :subclasses
+	singleton_attr_reader :discovered_classes
 
 	##
-	# The glob(3) pattern for matching Apps during discovery
-	singleton_attr_accessor :app_glob_pattern
+	# The glob(3) pattern for matching the discovery hook file.
+	singleton_attr_accessor :app_discovery_file
 
 	##
 	# The glob(3) pattern for matching local data directories during discovery. Local
@@ -46,11 +123,55 @@ module Strelka::Discovery
 	singleton_attr_reader :loading_file
 
 
-	# Module instance variables
-	@subclasses       = Hash.new {|h,k| h[k] = [] }
-	@loading_file     = nil
-	@app_glob_pattern = CONFIG_DEFAULTS[:app_glob_pattern]
+	# Class instance variables
+	@discovered_classes = Hash.new {|h,k| h[k] = [] }
+	@app_discovery_file = CONFIG_DEFAULTS[:app_discovery_file]
 	@local_data_dirs  = CONFIG_DEFAULTS[:local_data_dirs]
+	@discovered_apps    = nil
+
+
+	### Register an app with the specified +name+ that can be loaded from the given
+	### +path+.
+	def self::register_app( name, path )
+		@discovered_apps ||= {}
+
+		if @discovered_apps.key?( name )
+			raise "Can't register a second '%s' app at %s; already have one at %s" %
+				[ name, path, @discovered_apps[name] ]
+		end
+
+		self.log.debug "Registered app at %s as %p" % [ path, name ]
+		@discovered_apps[ name ] = path
+	end
+
+
+	### Register multiple apps by passing +a_hash+ of names and paths.
+	def self::register_apps( a_hash )
+		a_hash.each do |name, path|
+			self.register_app( name, path )
+		end
+	end
+
+
+	### Return a Hash of apps discovered by loading #app_discovery_files.
+	def self::discovered_apps
+		unless @discovered_apps
+			@discovered_apps ||= {}
+			self.app_discovery_files.each do |path|
+				self.log.debug "Loading discovery file %p" % [ path ]
+				Kernel.load( path )
+			end
+		end
+
+		return @discovered_apps
+	end
+
+
+	### Return an Array of app discovery hook files found in the latest installed gems and
+	### the current $LOAD_PATH.
+	def self::app_discovery_files
+		return Gem.find_latest_files( self.app_discovery_file )
+	end
 
 
 	### Configure the App. Override this if you wish to add additional configuration
@@ -59,7 +180,7 @@ module Strelka::Discovery
 	def self::configure( config=nil )
 		config = self.defaults.merge( config || {} )
 
-		self.app_glob_pattern = config[:app_glob_pattern]
+		self.app_discovery_file = config[:app_discovery_file]
 		self.local_data_dirs  = config[:local_data_dirs]
 	end
 
@@ -92,103 +213,36 @@ module Strelka::Discovery
 	end
 
 
-	### Return a Hash of Strelka app files as Pathname objects from installed gems,
-	### keyed by gemspec name .
-	def self::discover_paths
-		appfiles = {}
+	### Attempt to load the file associated with the specified +app_name+ and return
+	### the first Strelka::App class declared in the process.
+	def self::load( app_name )
+		apps = self.discovered_apps or return nil
+		file = apps[ app_name ] or return nil
 
-		self.discover_data_dirs.each do |gemname, dir|
-			pattern = File.join( dir, self.app_glob_pattern )
-			appfiles[ gemname ] = Pathname.glob( pattern )
-		end
-
-		return appfiles
+		return self.load_file( file )
 	end
 
 
-	### Return an Array of Strelka::App classes loaded from the installed Strelka gems.
-	def self::discover
-		discovered_apps = []
-		app_paths = self.discover_paths
-
-		self.log.debug "Loading apps from %d discovered paths" % [ app_paths.length ]
-		app_paths.each do |gemname, paths|
-			self.log.debug "  loading gem %s" % [ gemname ]
-			gem( gemname ) unless gemname == ''
-
-			self.log.debug "  loading apps from %s: %d handlers" % [ gemname, paths.length ]
-			paths.each do |path|
-				classes = begin
-					self.load( path )
-				rescue StandardError, ScriptError => err
-					self.log.error "%p while loading Strelka apps from %s: %s" %
-						[ err.class, path, err.message ]
-					self.log.debug "Backtrace: %s" % [ err.backtrace.join("\n\t") ]
-					[]
-				end
-				self.log.debug "  loaded app classes: %p" % [ classes ]
-
-				discovered_apps += classes
-			end
-		end
-
-		return discovered_apps
-	end
-
+	### Load the specified +file+ and return the first class that extends Strelka::Discovery.
+	def self::load_file( file )
+		self.log.debug "Loading application/s from %p" % [ file ]
+		Thread.current[ :__loading_file ] = loading_file = file
+		self.discovered_classes.delete( loading_file )
 
-	### Find the first app with the given +appname+ and return the path to its file and the name of
-	### the gem it's from. If the optional +gemname+ is given, only consider apps from that gem.
-	### Raises a RuntimeError if no app with the given +appname+ was found.
-	def self::find( appname, gemname=nil )
-		discovered_apps = self.discover_paths
-
-		path = nil
-		if gemname
-			discovered_apps[ gemname ].each do |apppath|
-				self.log.debug "    %s (%s)" % [ apppath, apppath.basename('.rb') ]
-				if apppath.basename('.rb').to_s == appname
-					path = apppath
-					break
-				end
-			end
-		else
-			self.log.debug "No gem name; searching them all:"
-			discovered_apps.each do |disc_gemname, paths|
-				self.log.debug "  %s: %d paths" % [ disc_gemname, paths.length ]
-				path = paths.find do |apppath|
-					self.log.debug "    %s (%s)" % [ apppath, apppath.basename('.rb') ]
-					self.log.debug "    %p vs. %p" % [ apppath.basename('.rb').to_s, appname ]
-					apppath.basename('.rb').to_s == appname
-				end or next
-				gemname = disc_gemname
-				break
-			end
-		end
+		Kernel.load( loading_file.to_s )
 
-		unless path
-			msg = "Couldn't find an app named '#{appname}'"
-			msg << " in the #{gemname} gem" if gemname
-			raise( msg )
-		end
-		self.log.debug "  found: %s" % [ path ]
+		new_subclasses = self.discovered_classes[ loading_file ]
+		self.log.debug "  loaded %d new app class/es" % [ new_subclasses.size ]
 
-		return path, gemname
+		return new_subclasses.first
+	ensure
+		Thread.current[ :__loading_file ] = nil
 	end
 
 
-	### Load the specified +file+, and return any Strelka::App subclasses that are loaded
-	### as a result.
-	def self::load( file )
-		self.log.debug "Loading application/s from %p" % [ file ]
-		@loading_file = Pathname( file ).expand_path
-		self.subclasses.delete( @loading_file )
-		Kernel.load( @loading_file.to_s )
-		new_subclasses = self.subclasses[ @loading_file ]
-		self.log.debug "  loaded %d new app class/es" % [ new_subclasses.size ]
-
-		return new_subclasses
-	ensure
-		@loading_file = nil
+	### Return the Pathname of the file being loaded by the current thread (if there is one)
+	def self::loading_file
+		return Thread.current[ :__loading_file ]
 	end
 
 
@@ -196,7 +250,7 @@ module Strelka::Discovery
 	### with Discovery.
 	def self::add_inherited_class( subclass )
 		self.log.debug "Registering discovered subclass %p" % [ subclass ]
-		self.subclasses[ self.loading_file ] << subclass
+		self.discovered_classes[ self.loading_file ] << subclass
 	end
 
 

data/spec/strelka/cli_spec.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/env rspec -cfd
+#encoding: utf-8
+
+require_relative '../helpers'
+
+require 'tempfile'
+require 'rspec'
+
+require 'strelka/cli'
+
+describe Strelka::CLI do
+
+	before( :all ) do
+		testcommands = Module.new
+		testcommands.extend( Strelka::CLI::Subcommand )
+		testcommands.module_eval do
+			command :test_output do |cmd|
+				cmd.action do
+					prompt.say "Test command!"
+				end
+			end
+
+			command :test_dryrun do |cmd|
+				cmd.action do
+					unless_dryrun( "Running the test." ) do
+						$stdout.puts "Ran it!"
+					end
+				end
+			end
+		end
+	end
+
+	after( :each ) do
+		described_class.reset_prompt
+	end
+
+	describe "output redirection" do
+
+		it "uses STDERR for user interaction" do
+			expect {
+				described_class.run([ 'test_output' ])
+			}.to output( /Test command!\n/ ).to_stderr
+		end
+
+
+		it "redirects its output to STDOUT when run with `-o -`" do
+			expect {
+				described_class.run([ '-o', '-', 'test_output' ])
+			}.to output( /Test command!\n/ ).to_stdout
+		end
+
+
+		it "redirects its output to the named file when run with `-o filename`" do
+			tmpfile = Dir::Tmpname.create( 'strelka-command-fileout' ) { }
+
+			begin
+				described_class.run([ '-o', tmpfile, 'test_output' ])
+				expect( IO.read(tmpfile) ).to match( /Test command!\n/ )
+			ensure
+				File.unlink( tmpfile ) if tmpfile && File.exist?( tmpfile )
+			end
+		end
+
+	end
+
+
+	describe "dry-run mode" do
+
+		it "executes the protected block if dry-run mode isn't enabled" do
+			expect {
+				described_class.run([ 'test_dryrun' ])
+			}.to output( /Ran it!/ ).to_stdout
+		end
+
+
+		it "doesn't execute the block if dry-run mode *is* enabled" do
+			expect {
+				described_class.run([ '-n', 'test_dryrun' ])
+			}.to_not output( /Ran it!/ ).to_stdout
+		end
+
+	end
+
+end
+