runfile 0.1.1.pre → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 140227a208cb696ecea61be2900adaa55a2e57c4
-  data.tar.gz: a8ebcc1b213d108fdb90661b586364860e6dbea3
+  metadata.gz: b145578577cc500e75a76396084f5c708f3ffc19
+  data.tar.gz: d3f5047c705832d2184c8975b0f55dfb7149354e
 SHA512:
-  metadata.gz: f8fc91d59ced071ec86d3bb156937b7f321872fc50f52a3269adfdc4d3227d4d086e05e187140bb397bab920fe326e6c69ce42a19f1dc7a88fed4ec58d4515e6
-  data.tar.gz: 1e42a00ceea31aa897dcc4905e137b2d9c24dcfcb015735c3000c43b5892835c4f1ec2d6204b676566d6cea7a292e8da2795f71cc2a93d80488f5d3a0c732b97
+  metadata.gz: 075be67037b4a3bb1680f0c90188332a4ca757f6f2672052496551a5bd8b8d763928e68d5ae304395e0f96306f3d7e058f21b6d3d310c706fd57811be589d674
+  data.tar.gz: 64f564a08e4e93deb4ba3ec4afcb371dc7788a68b7c1bf819efd37ff57f2bf4b526f138bac7aae0f89d76c208aabae1deffd841d6bbd45a58217eef52eed45b3

data/lib/runfile/action.rb

@@ -1,4 +1,9 @@
 module Runfile
+
+	# The Action class represents a single Runfile action.
+	# This object holds all the information needed to execute it and
+	# show its help text (excluding the options, as they are considered
+	# global throughout the application)
 	class Action
 		attr :usage, :help
 
@@ -8,6 +13,7 @@ module Runfile
 			@block = block
 		end
 
+		# Call the provided block
 		def execute(args)
 			@block.yield args
 		end

data/lib/runfile/docopt_maker.rb

@@ -3,6 +3,9 @@ require 'colsole'
 
 module Runfile
 	include Colsole
+
+	# The DocoptMaker class handles the dynamic generation of the docopt
+	# document.
 	class DocoptMaker
 		def initialize(version, summary, actions, options)
 			@version = version
@@ -11,6 +14,8 @@ module Runfile
 			@options = options
 		end
 
+		# Generate a document based on all the actions, help messages
+		# and options we have collected from the Runfile DSL.
 		def make
 			width, height = detect_terminal_size
 			doc = "Runfile #{@version}\n"

data/lib/runfile/dsl.rb

@@ -1,25 +1,41 @@
+# This file defines all the commands supported in a Runfile.
+# All commands are immediately handed over to the Runner instance
+# for handling.
+
 module Runfile
+
+	# Set the version of your Runfile program
 	def version(ver)
 		Runner.instance.version = ver
 	end
 
+	# Set the one line summary of your Runfile program
+	def summary(text)
+		Runner.instance.summary = text
+	end
+
+	# Set the usage pattern for the next action
 	def usage(text)
 		Runner.instance.last_usage = text
 	end
 
+	# Set the help message for the next action
 	def help(text)
 		Runner.instance.last_help = text
 	end
 
-	def action(name, &block) 
-		Runner.instance.add_action name, &block
+	# Add an option/flag to the next action (can be called multiple
+	# times)
+	def option(flag, text)
+		Runner.instance.add_option flag, text
 	end
 
-	def summary(text)
-		Runner.instance.summary = text
+	# Define the action
+	def action(name, &block) 
+		Runner.instance.add_action name, &block
 	end
 
-	def option(flag, text)
-		Runner.instance.add_option flag, text
+	def command(name)
+		Runner.instance.namespace = name
 	end
 end

data/lib/runfile/runner.rb

@@ -1,47 +1,64 @@
 require 'docopt'
 
 module Runfile
+
+	# The Runner class is the main workhorse behind Runfile.
+	# It handles all the Runfile DSL commands and executes the Runfile.
 	class Runner
-		attr_writer :last_usage, :last_help, :version, :summary
+		attr_accessor :last_usage, :last_help, :version, :summary, :namespace
 
 		@@instance = nil
 
+		# Initialize all variables to a sensible default.
 		def initialize
 			@last_usage = nil
 			@last_help = nil
+			@namespace = nil
 			@actions = {}
 			@options = {}
 			@version = "0.0.0"
 			@summary = false
 		end
 
+		# Return a singleton Runner instance.
 		def self.instance
 			@@instance = self.new if @@instance.nil?
 			@@instance
 		end
 
+		# Load and execute a Runfile call.
 		def execute(argv)
 			File.exist? 'Runfile' or abort "Runfile not found"
 			load 'Runfile'
 			@@instance.run *argv
 		end
 
+		# Add an action to the @actions array, and use the last known
+		# usage and help messages sent by the DSL.
 		def add_action(name, &block)
+			@last_usage = name if @last_usage.nil?
+			if @namespace 
+				name = "#{namespace}_#{name}".to_sym
+				@last_usage = "#{@namespace} #{@last_usage}"
+			end
 			@actions[name] = Action.new(block, @last_usage, @last_help)
 			@last_usage = nil
 			@last_help = nil
 		end
 
+		# Add an option flag and its help text.
 		def add_option(flag, text)
 			@options[flag] = text
 		end
 
+		# Run the command. This is a wrapper around docopt. It will 
+		# generate the docopt document on the fly, using all the 
+		# information collected so far.
 		def run(*argv)
-			action = argv[0]
-			action and action = action.to_sym
+			action = find_action argv
 			begin
 				args = Docopt::docopt(docopt, version: @version, argv:argv)
-			 	@actions.has_key? action or abort "Runfile error: Action :#{action} is not defined"
+				action or abort "Runfile error: Action not found"
 				@actions[action].execute args
 			rescue Docopt::Exit => e
 				puts e.message
@@ -50,9 +67,27 @@ module Runfile
 
 		private
 
+		# Dynamically generate the docopt document.
 		def docopt
 			maker = DocoptMaker.new(@version, @summary, @actions, @options)
 			maker.make
 		end
+
+		# Inspect the first two arguments in the argv and look for
+		# a matching action or command_action.
+		# We give priority to the second form (:make_jam) in order to
+		# also allow "overloading" of the command as an action 
+		# (e.g. also allow a global action called :make).
+		def find_action(argv)
+			if argv.size >= 2
+				action = "#{argv[0]}_#{argv[1]}".to_sym
+				return action if @actions.has_key? action
+			end
+			if argv.size >= 1
+				action = argv[0].to_sym
+				return action if @actions.has_key? action
+			end
+			return false
+		end
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: runfile
 version: !ruby/object:Gem::Version
-  version: 0.1.1.pre
+  version: 0.1.2
 platform: ruby
 authors:
 - Danny Ben Shitrit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-13 00:00:00.000000000 Z
+date: 2015-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colsole
@@ -51,7 +51,7 @@ files:
 - lib/runfile/docopt_maker.rb
 - lib/runfile/dsl.rb
 - lib/runfile/runner.rb
-homepage: http://sector-seven.net
+homepage: https://github.com/DannyBen/runfile
 licenses:
 - MIT
 metadata: {}
@@ -66,9 +66,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.4.6