mothership 0.0.1

data/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c)2012, Alex Suraci
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+
+    * Neither the name of Alex Suraci nor the names of other
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,24 @@
+require "rubygems"
+require "bundler"
+
+if Gem::Version.new(Bundler::VERSION) > Gem::Version.new("1.0.12")
+  require "bundler/gem_tasks"
+end
+
+task :default => "spec"
+
+desc "Run specs"
+task "spec" => ["bundler:install", "test:spec"]
+
+namespace "bundler" do
+  desc "Install gems"
+  task "install" do
+    sh("bundle install")
+  end
+end
+
+namespace "test" do
+  task "spec" do |t|
+    sh("cd spec && bundle exec rake spec")
+  end
+end

data/lib/mothership/base.rb

@@ -0,0 +1,62 @@
+require "mothership/command"
+require "mothership/inputs"
+
+class Mothership
+  # all commands
+  @@commands = {}
+
+  # parsed global input set
+  @@inputs = nil
+
+  # Initialize with the command being executed.
+  def initialize(command = nil)
+    @command = command
+  end
+
+  class << self
+    # start defining a new command with the given description
+    def desc(description)
+      @command = Command.new(self, description)
+    end
+
+    # define an input for the current command or the global command
+    def input(name, options = {}, &default)
+      raise "no current command" unless @command
+
+      @command.add_input(name, options, &default)
+    end
+
+    # register a command
+    def method_added(name)
+      return unless @command
+
+      @command.name = name
+      @@commands[name] = @command
+
+      @command = nil
+    end
+
+    def alias_command(orig, new)
+      @@commands[new] = @@commands[orig]
+    end
+  end
+
+  def execute(cmd, argv)
+    cmd.invoke(Parser.new(cmd).inputs(argv))
+  rescue Mothership::Error => e
+    puts e
+    puts ""
+    Mothership::Help.command_usage(cmd)
+
+    @@exit_status = 1
+  end
+
+  # invoke a command with the given inputs
+  def invoke(name, inputs = {})
+    if cmd = @@commands[name]
+      cmd.invoke(inputs)
+    else
+      unknown_command(name)
+    end
+  end
+end

data/lib/mothership/callbacks.rb

@@ -0,0 +1,75 @@
+class Mothership
+  # temporary filters via #with_filters
+  #
+  # command => { tag => [callbacks] }
+  @@filters = Hash.new { |h, k| h[k] = Hash.new { |h, k| h[k] = [] } }
+
+  class << self
+    # register a callback that's evaluated before a command is run
+    def before(name, &callback)
+      @@commands[name].before << [callback, self]
+    end
+
+    # register a callback that's evaluated after a command is run
+    def after(name, &callback)
+      @@commands[name].after << [callback, self]
+    end
+
+    # register a callback that's evaluated around a command, controlling its
+    # evaluation (i.e. inputs)
+    def around(name, &callback)
+      @@commands[name].around << [callback, self]
+    end
+
+    # register a callback that's evaluated when a command uses the given
+    # filter
+    def filter(name, tag, &callback)
+      @@commands[name].filters[tag] << [callback, self]
+    end
+
+    # change an argument's status, i.e. optional, splat, or required
+    def change_argument(name, arg, to)
+      @@commands[name].arguments.each do |a|
+        if a[:name] == arg
+          a[:type] = to
+        end
+      end
+    end
+  end
+
+  # filter a value through any plugins
+  def filter(tag, val)
+    if @@filters.key?(@command.name) &&
+         @@filters[@command.name].key?(tag)
+      @@filters[@command.name][tag].each do |f, ctx|
+        val = ctx.instance_exec(val, &f)
+      end
+    end
+
+    @command.filters[tag].each do |f, c|
+      val = c.new.instance_exec(val, &f)
+    end
+
+    val
+  end
+
+  # temporary dynamically-scoped filters
+  def with_filters(filters)
+    filters.each do |cmd, callbacks|
+      callbacks.each do |tag, callback|
+        @@filters[cmd][tag] << [callback, self]
+      end
+    end
+
+    yield
+  ensure
+    filters.each do |cmd, callbacks|
+      callbacks.each do |tag, callback|
+        @@filters[cmd][tag].pop
+        @@filters[cmd].delete(tag) if @@filters[cmd][tag].empty?
+      end
+
+      @@filters.delete(cmd) if @@filters[cmd].empty?
+    end
+  end
+end

data/lib/mothership/command.rb

@@ -0,0 +1,120 @@
+require "mothership/inputs"
+
+class Mothership
+  class Command
+    attr_accessor :name, :description
+
+    attr_reader :inputs, :arguments, :flags
+
+    attr_reader :before, :after, :around, :filters
+
+    def initialize(context, description = nil)
+      @context = context
+      @description = description
+      @aliases = []
+
+      # inputs accepted by command
+      @inputs = {}
+
+      # inputs that act as arguments
+      @arguments = []
+
+      # flag -> input (e.g. --name -> :name)
+      @flags = {}
+
+      # various callbacks
+      @before = []
+      @after = []
+      @around = []
+      @filters = Hash.new { |h, k| h[k] = [] }
+    end
+
+    def inspect
+      "\#<Command '#{@name}'>"
+    end
+
+    def usage
+      str = @name.to_s.gsub("_", "-")
+
+      @arguments.each do |a|
+        name = a[:name].to_s.upcase
+
+        case a[:type]
+        when :splat
+          str << " #{name}..."
+        when :optional
+          str << " [#{name}]"
+        else
+          str << " #{name}"
+        end
+      end
+
+      str
+    end
+
+    def invoke(inputs)
+      @before.each { |f, c| c.new.instance_exec(&f) }
+
+      name = @name
+      ctx = @context.new(self)
+      input = Inputs.new(self, ctx, inputs)
+
+      action = proc do |*given_inputs|
+        ctx.send(name, given_inputs.first || input)
+      end
+
+      cmd = self
+      @around.each do |a, c|
+        before = action
+
+        sub = c.new(cmd)
+        action = proc do |*given_inputs|
+          sub.instance_exec(before, given_inputs.first || input, &a)
+        end
+      end
+
+      res = ctx.instance_exec(input, &action)
+
+      @after.each { |f, c| c.new.instance_exec(&f) }
+
+      res
+    end
+
+    def add_input(name, options = {}, &default)
+      options[:default] = default if default
+      options[:description] = options.delete(:desc) if options.key?(:desc)
+
+      @flags["--#{name.to_s.gsub("_", "-")}"] = name
+
+      if options[:singular]
+        @flags["--#{options[:singular]}"] = name
+      end
+
+      if aliases = options[:aliases] || options[:alias]
+        Array(aliases).each do |a|
+          @flags[a] = name
+        end
+      end
+
+      # :argument => true means accept as single argument
+      # :argument => :foo is shorthand for :argument => {:type => :foo}
+      if opts = options[:argument]
+        type =
+          case opts
+          when true
+            :normal
+          when Symbol
+            opts
+          when Hash
+            opts[:type]
+          end
+
+        options[:argument] = type
+
+        @arguments << { :name => name, :type => type }
+      end
+
+      @inputs[name] = options
+    end
+  end
+end

data/lib/mothership/errors.rb

@@ -0,0 +1,37 @@
+class Mothership
+  class Error < RuntimeError
+  end
+
+  class MissingArgument < Error
+    def initialize(cmd, arg)
+      @command = cmd
+      @argument = arg
+    end
+
+    def to_s
+      "#{@command}: missing input '#{@argument}'"
+    end
+  end
+
+  class ExtraArguments < Error
+    def initialize(cmd)
+      @command = cmd
+    end
+
+    def to_s
+      "#{@command}: too many arguments"
+    end
+  end
+
+  class TypeMismatch < Error
+    def initialize(cmd, input, type)
+      @command = cmd
+      @input = input
+      @type = type
+    end
+
+    def to_s
+      "#{@command}: expected #{@type} value for #{@input}"
+    end
+  end
+end

data/lib/mothership/help.rb

@@ -0,0 +1,237 @@
+require "mothership/base"
+
+module Mothership::Help
+  @@groups = []
+  @@tree = {}
+
+  class << self
+    def has_groups?
+      !@@groups.empty?
+    end
+
+    def print_help_groups(global = nil, all = false)
+      @@groups.each do |commands|
+        print_help_group(commands, all)
+      end
+
+      command_options(global)
+    end
+
+    def print_help_group(group, all = false, indent = 0)
+      return if nothing_printable?(group, all)
+
+      members = group[:members]
+
+      unless all
+        members = members.reject do |_, opts|
+          opts[:hidden]
+        end
+      end
+
+      commands = members.collect(&:first)
+
+      i = "  " * indent
+
+      print i
+      puts group[:description]
+
+      width = 0
+      commands.each do |cmd|
+        len = cmd.usage.size
+        if len > width
+          width = len
+        end
+      end
+
+      commands.each do |cmd|
+        puts "#{i}  #{cmd.usage.ljust(width)}\t#{cmd.description}"
+      end
+
+      puts "" unless commands.empty?
+
+      group[:children].each do |group|
+        print_help_group(group, all, indent + 1)
+      end
+    end
+
+    # define help groups
+    def groups(*tree)
+      tree.each do |*args|
+        add_group(@@groups, @@tree, *args.first)
+      end
+    end
+
+    def add_to_group(command, names, options)
+      where = @@tree
+      top = true
+      names.each do |n|
+        where = where[:children] unless top
+        break unless where
+
+        where = where[n]
+        break unless where
+
+        top = false
+      end
+
+      unless where
+        raise "unknown help group: #{names.join("/")}"
+      end
+
+      where[:members] << [command, options]
+    end
+
+    def basic_help(commands, global)
+      puts "Commands:"
+
+      width = 0
+      commands.each do |_, c|
+        len = c.usage.size
+        width = len if len > width
+      end
+
+      commands.each do |_, c|
+        puts "  #{c.usage.ljust(width)}\t#{c.description}"
+      end
+
+      unless global.flags.empty?
+        puts ""
+        command_options(global)
+      end
+    end
+
+    def command_help(cmd)
+      puts cmd.description
+      puts ""
+      command_usage(cmd)
+    end
+
+    def command_usage(cmd)
+      puts "Usage: #{cmd.usage}"
+
+      unless cmd.flags.empty?
+        puts ""
+        command_options(cmd)
+      end
+    end
+
+    def command_options(cmd)
+      puts "Options:"
+
+      rev_flags = Hash.new { |h, k| h[k] = [] }
+
+      cmd.flags.each do |f, n|
+        rev_flags[n] << f
+      end
+
+      usages = []
+
+      max_bool = 0
+      rev_flags.collect do |name, fs|
+        info = cmd.inputs[name]
+
+        usage =
+          case info[:type]
+          when :boolean
+            fs.sort.join(", ")
+          else
+            fs.sort.collect { |f| "#{f} #{name.to_s.upcase}" }.join(", ")
+          end
+
+        say_no =
+          if info[:type] == :boolean
+            max_bool = usage.size if usage.size > max_bool
+            "--no-#{name.to_s.gsub("_", "-")}"
+          end
+
+        usages << [usage, info[:description], say_no]
+      end
+
+      max_width = 0
+      usages.collect! do |usage, desc, bool_no|
+        if bool_no
+          usage = usage.ljust(max_bool) + "   #{bool_no}"
+        end
+
+        max_width = usage.size if usage.size > max_width
+
+        [usage, desc]
+      end
+
+      usages.sort! { |a, b| a.first <=> b.first }
+
+      usages.each do |u, d|
+        if d
+          puts "  #{u.ljust(max_width)}    #{d}"
+        else
+          puts "  #{u}"
+        end
+      end
+    end
+
+    private
+
+    def nothing_printable?(group, all = false)
+      group[:members].reject { |_, opts| !all && opts[:hidden] }.empty? &&
+        group[:children].all? { |g| nothing_printable?(g) }
+    end
+
+    def add_group(groups, tree, name, desc, *subs)
+      members = []
+
+      meta = { :members => members, :children => [] }
+      groups << meta
+
+      tree[name] = { :members => members, :children => {} }
+
+      meta[:description] = desc
+
+      subs.each do |*args|
+        add_group(meta[:children], tree[name][:children], *args.first)
+      end
+    end
+  end
+end
+
+class Mothership
+  class << self
+    # add command to help group
+    def group(*names)
+      options =
+        if names.last.is_a? Hash
+          names.pop
+        else
+          {}
+        end
+
+      Mothership::Help.add_to_group(@command, names, options)
+    end
+  end
+
+  def default_action
+    invoke :help
+  end
+
+  def unknown_command(name)
+    puts "Unknown command '#{name}'. See 'help' for available commands."
+    exit_status 1
+  end
+
+  desc "Help!"
+  input :command, :argument => :optional
+  input :all, :type => :boolean
+  def help(input)
+    if name = input[:command]
+      Mothership::Help.command_help(@@commands[name.gsub("-", "_").to_sym])
+    elsif Help.has_groups?
+      unless input[:all]
+        puts "Showing basic command set. Pass --all to list all commands."
+        puts ""
+      end
+
+      Mothership::Help.print_help_groups(@@global, input[:all])
+    else
+      Mothership::Help.basic_help(@@commands, @@global)
+    end
+  end
+end

data/lib/mothership/inputs.rb

@@ -0,0 +1,58 @@
+class Mothership
+  class Inputs
+    attr_reader :inputs
+
+    def initialize(command, context, inputs = {})
+      @command = command
+      @context = context
+      @inputs = inputs
+      @cache = {}
+    end
+
+    def given?(name)
+      @inputs.key?(name)
+    end
+
+    def given(name)
+      @inputs[name]
+    end
+
+    def merge(inputs)
+      self.class.new(@command, @context, @inputs.merge(inputs))
+    end
+
+    def [](name, *args)
+      return @inputs[name] if @inputs.key?(name) && @inputs[name] != []
+      return @cache[name] if @cache.key? name
+
+      meta = @command.inputs[name]
+
+      return unless meta
+
+      val =
+        if meta[:default].respond_to? :to_proc
+          @context.instance_exec(*args, &meta[:default])
+        elsif meta[:default]
+          meta[:default]
+        elsif meta[:type] == :boolean
+          false
+        elsif meta[:argument] == :splat
+          if meta[:singular] && single = @inputs[meta[:singular]]
+            [single]
+          else
+            []
+          end
+        end
+
+      unless meta[:forget]
+        @cache[name] = val
+      end
+
+      val
+    end
+
+    def forget(name)
+      @cache.delete(name)
+    end
+  end
+end