boson 0.4.0 → 1.0.0

data/.gemspec

@@ -9,17 +9,16 @@ Gem::Specification.new do |s|
   s.email       = "gabriel.horner@gmail.com"
   s.homepage    = "http://tagaholic.me/boson/"
   s.summary = "A command/task framework similar to rake and thor that opens your ruby universe to the commandline and irb."
-  s.description =  "Boson is a command/task framework with the power to turn any ruby method into a full-fledged executable with options.  Some unique features that differentiate it from rake and thor include being usable from irb and the commandline, optional automated views generated by hirb and allowing libraries to be written as plain ruby. For my libraries that use this, see irbfiles.  Works with all major ruby versions."
+  s.description =  "Boson is a modular command/task framework. Thanks to its rich set of plugins, it differentiates itself from rake and thor by being usable from irb and the commandline, having optional automated views generated by hirb and allowing libraries to be written as plain ruby. Works with ruby >= 1.9.2"
   s.required_rubygems_version = ">= 1.3.6"
   s.executables = ['boson']
-  s.add_dependency 'hirb', '>= 0.5.0'
-  s.add_dependency 'alias', '>= 0.2.2'
-  s.add_development_dependency 'mocha', '= 0.9.8'
+  s.add_development_dependency 'mocha', '~> 0.10.4'
   s.add_development_dependency 'bacon', '>= 1.1.0'
   s.add_development_dependency 'mocha-on-bacon'
   s.add_development_dependency 'bacon-bits'
-  s.add_development_dependency 'rake'
-  s.files = Dir.glob(%w[{lib,test}/**/*.rb bin/* [A-Z]*.{txt,rdoc} ext/**/*.{rb,c} **/deps.rip]) + %w{Rakefile .gemspec .travis.yml}
-  s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
+  s.add_development_dependency 'bahia', '>= 0.4.0'
+  s.files = Dir.glob(%w[{lib,test}/**/*.rb bin/* [A-Z]*.{txt,rdoc,md} ext/**/*.{rb,c} **/deps.rip]) + %w{Rakefile .gemspec .travis.yml}
+  s.files += ['.rspec']
+  s.extra_rdoc_files = ["README.md", "LICENSE.txt"]
   s.license = 'MIT'
 end

data/.rspec

@@ -0,0 +1,2 @@
+--default_path test
+--pattern test/**_test.rb

data/.travis.yml

@@ -1,4 +1,11 @@
 before_install: bundle init --gemspec=.gemspec
+script: bacon -q -Ilib -I. test/*_test.rb
 rvm:
 - 1.9.2
 - 1.9.3
+- rbx-19mode
+- jruby-19mode
+matrix:
+  # until jruby + bacon issue fixed
+  allow_failures:
+  - rvm: jruby-19mode

data/CHANGELOG.rdoc

@@ -1,4 +1,4 @@
-= 0.4.0
+== 0.4.0
 * Add file lock for concurrent processes
 
 == 0.3.4

data/README.md

@@ -0,0 +1,144 @@
+## Description
+
+Boson is a modular command/task framework. Thanks to its rich set of plugins,
+it differentiates itself from rake and thor by being usable from irb and the
+commandline, having automated views generated by hirb and allowing libraries to
+be written as plain ruby. Works with on all major rubies for ruby >= 1.9.2
+
+## New Boson
+
+Starting with 1.0, boson has changed significantly. Please read [the upgrading
+doc](http://rdoc.info/gems/boson/file/Upgrading.md) if you have an older version
+or if your [reading about boson](http://tagaholic.me/blog.html#gem:name=boson)
+predates 2012.
+
+Boson has been rewritten to have a smaller core (no dependencies) with optional
+plugins to hook into its various features. The major focus of 1.0 has been to
+provide an easy way for third-party gems to create their executable and define
+subcommands with options.
+
+## Docs
+
+Nicely formatted docs are available
+[here](http://rdoc.info/gems/boson/file/README.md).
+
+## Example Executable
+
+For a gem with an executable, bin/cow:
+
+```ruby
+#!/usr/bin/env ruby
+require 'boson/runner'
+
+class CowRunner < Boson::Runner
+  option :urgent, type: :boolean
+  def say(text, options={})
+    text.capitalize! if options[:urgent]
+    puts text
+  end
+
+  def moo
+    puts "MOOOO"
+  end
+end
+
+CowRunner.start
+```
+
+You can now execute cow with say and moo subcommands:
+
+    $ cow say hungry
+    hungry
+    $ cow moo
+    MOOOO
+    # use say's urgent option
+    $ cow say hungry -urgent
+    HUNGRY
+
+You'll notice that this syntax is powerful and concise and is very similar to
+thor's API. Subcommands map to ruby methods and the class represents the executable.
+
+## Comparison to Thor
+
+Since boson and it's rewrite are both heavily inspired by [thor](http://github.com/wycats/thor), it
+makes sense to compare them.
+
+First, what I consider pros boson has over thor. Boson
+
+* is designed to handle plugins. This means it core parts are extendable by
+  modules and core components like commands can have arbitrary metadata
+  associated with them.
+* has a rich set of plugins. See [boson-more](http://github.com/cldwalker/boson-more).
+* has commands that are easily testable. Whereas thor has options that automagically
+  appear in command methods, boson explicitly passes options to its command
+  method as a hash i.e. `MyRunner.new.subcommand(arg, verbose: true)`. This
+  also allows commands to just be called as ruby, with no magic to consider.
+* supports custom-user option types i.e. creating a Date option type. See
+  Boson::Options.
+* supports custom method decorators i.e. methods like desc that add functionality
+  to a command. While boson supports option, options, desc and config out of the box,
+  users can create their own.
+* automatically creates usage for your subcommand. With thor you need to
+  manually define your usage with desc: `desc "SOME USAGE", "SOME DESCRIPTION"`
+* is lenient about descriptions. Describe commands at your leisure. With thor
+  you must define a desc.
+* has a smaller blacklist for command names i.e. just Kernel + Object method
+  names. Thor has a bigger
+  [blacklist](https://github.com/wycats/thor/blob/a24b6697a37d9bc0c0ea94ef9bf2cdbb33b8abb9/lib/thor/base.rb#L18-19) due to its design.
+
+Now for pros thor has over boson. Thor
+
+* is widely used and thus has been community QAed thoroughly.
+* supports generators as a major feature.
+* is more stable as its feature set is mostly frozen.
+* is used by rails and thus is guaranteed support for some time.
+* supports ruby 1.8.7.
+* TODO: I'm sure there's more
+
+## Writing Plugins
+
+The most common way to write a plugin is to extend one of the many method hooks
+available. Any methods that are defined in an API or APIClassMethods module
+are extendable. For example, if you want to extend what any boson-based
+executable does first, extend BareRunner.start:
+
+```ruby
+module CustomStartUp
+  def start(*)
+    super
+    # additional startup
+  end
+end
+
+BareRunner.extend CustomStartUp
+```
+
+Notice that `extend` was used to extend a class method. To extend an instance
+method you would use `include`. Also notice that you use `super` in an
+overridden method to call original functionality. If you don't, you're
+possibly overridden existing functionality, which is fine as long as you know
+what you are overriding.
+
+For many plugin examples, see
+[boson-more](http://github.com/cldwalker/boson-more).
+
+## Bugs/Issues
+
+Please report them [on github](http://github.com/cldwalker/boson/issues).
+If the issue is about upgrading from old boson, please file it in
+[boson-more](http://github.com/cldwalker/boson-more/issues).
+
+## Contributing
+[See here](http://tagaholic.me/contributing.html)
+
+## Motiviation
+
+Motivation for the new boson is all the damn executables I'm making.
+
+## Credits
+Boson stands on the shoulders of these people and their ideas:
+
+* Contributors: @mirell, @martinos
+* Yehuda Katz for Thor and its awesome option parser (Boson::OptionParser).
+* Daniel Berger for his original work on thor's option parser.
+* Chris Wanstrath for inspiring Boson's libraries with Rip's packages.

data/README.rdoc

@@ -9,9 +9,9 @@ libraries to be written as plain ruby. For my libraries that use this, see
 
 == UPDATE
 Boson 0.4.x will be the last 1.8 compatible version.
-Boson 0.5 will be a rewrite compatible with only 1.9. Work is going on in {boson2
+Boson 1.0 will be a rewrite compatible with only 1.9. Work is going on in {boson2
 branch}[https://github.com/cldwalker/boson/tree/boson2]. The goal of boson2 is to have a slimmer
-core, move everything else {to plugins}[https://github.com/cldwalker/boson-all]
+core, move everything else {to plugins}[https://github.com/cldwalker/boson-more]
 and to allow gems to use boson to make executables like thor.
 
 == Features

data/Upgrading.md

@@ -0,0 +1,23 @@
+## Using Old Boson
+
+Any version before 1.0 is considered the old boson. Although I will accept bug
+fixes for it (branched from
+[old_boson](http://github.com/cldwalker/boson/tree/old_boson)), I will *not*
+accept any new features. Since the new boson supports almost all of [boson's
+origin functionality](http://tagaholic.me/blog.html#gem:name=boson) via plugins,
+there is little reason to hang onto this version.
+
+## Using New Boson
+
+To enjoy the same experience you've had with the old boson, you'll need to
+also install boson-more and create a ~/.bosonrc:
+
+    $ gem install boson boson-more
+    $ echo "require 'boson/more'" > ~/.bosonrc
+
+Your old boson config and libraries should just work. Please file issues with
+your libraries or any upgrade issues at
+[boson-more](http://github.com/cldwalker/boson-more).
+
+If you've written custom plugins for the old Boson, you most likely have to
+upgrade to the new API.

data/bin/boson

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require File.expand_path(File.join(File.dirname(__FILE__), "..","lib","boson"))
-require 'boson/runners/bin_runner'
+require 'boson'
+require 'boson/bin_runner'
 
 Boson::BinRunner.start

data/lib/boson.rb

@@ -1,31 +1,49 @@
-%w{hirb alias}.each {|e| require e }
-%w{runner runners/console_runner repo manager loader inspector library}.each {|e| require "boson/#{e}" }
-%w{argument method comment}.each {|e| require "boson/inspectors/#{e}_inspector" }
-# order of library subclasses matters
-%w{module file gem require local_file}.each {|e| require "boson/libraries/#{e}_library" }
-(%w{namespace view command util commands option_parser options} +
-  %w{index repo_index scientist option_command pipe pipes version}).each {|e| require "boson/#{e}" }
+require 'boson/bare_runner'
+require 'boson/manager'
+require 'boson/loader'
+require 'boson/inspector'
+require 'boson/library'
+require 'boson/method_inspector'
+require 'boson/runner_library'
+require 'boson/command'
+require 'boson/util'
+require 'boson/option_parser'
+require 'boson/options'
+require 'boson/scientist'
+require 'boson/option_command'
+require 'boson/version'
 
-# This module stores the libraries, commands, repos and main object used throughout Boson.
+# This module stores the libraries, commands and the main_object.
 #
 # Useful documentation links:
-# * Boson::BinRunner - Runs the boson executable
-# * Boson::ConsoleRunner - Runs Boson from the ruby console
-# * Boson::Repo.config - Explains main config file
 # * Boson::Library - All about libraries
-# * Boson::FileLibrary - Explains creating libraries as files
 # * Boson::Loader - Explains library module callbacks
 # * Boson::OptionParser - All about options
 module Boson
-  # Module which is extended by Boson.main_object to give it command functionality.
-  module Universe; include Commands::Namespace; end
-  NAMESPACE = '.' # Delimits namespace from command
   extend self
+
+  # Module which is extended by Boson.main_object to give it command functionality.
+  module Universe;  end
+  # Module under which most library modules are evaluated.
+  module Commands; end
+
+  # Default config
+  CONFIG = {libraries: {}, command_aliases: {}, option_underscore_search: true}
+
   # The object which holds and executes all command functionality
   attr_accessor :main_object
-  attr_accessor :commands, :libraries
   alias_method :higgs, :main_object
 
+  attr_accessor :commands, :libraries, :config
+  # Prints debugging info when set
+  attr_accessor :debug
+  # Returns true if commands are being executed from a non-ruby shell i.e. bash
+  # Returns nil/false if in a ruby shell i.e. irb.
+  attr_accessor :in_shell
+  # Returns true if in commandline with verbose flag or if set explicitly.
+  # Plugins should use this to display more info.
+  attr_accessor :verbose
+
   # Array of loaded Boson::Library objects.
   def libraries
     @libraries ||= Array.new
@@ -36,55 +54,29 @@ module Boson
     @commands ||= Array.new
   end
 
-  # The main required repository which defaults to ~/.boson.
-  def repo
-    @repo ||= Repo.new("#{Util.find_home}/.boson")
-  end
-
-  # An optional local repository which defaults to ./lib/boson or ./.boson.
-  def local_repo
-    @local_repo ||= begin
-      ignored_dirs = (repo.config[:ignore_directories] || []).map {|e| File.expand_path(e) }
-      dir = ["lib/boson", ".boson"].find {|e| File.directory?(e) &&
-          File.expand_path(e) != repo.dir && !ignored_dirs.include?(File.expand_path('.')) }
-      Repo.new(dir) if dir
-    end
-  end
-
-  # The array of loaded repositories containing the main repo and possible local and global repos
-  def repos
-    @repos ||= [repo, local_repo, global_repo].compact
+  # Global config used by most classes
+  def config
+    @config ||= CONFIG
   end
 
-  # Optional global repository at /etc/boson
-  def global_repo
-    File.exists?('/etc/boson') ? Repo.new('/etc/boson') : nil
-  end
-
-  def main_object=(value) #:nodoc:
+  # Sets main_object and extends it with commands from Universe
+  def main_object=(value)
     @main_object = value.extend(Universe)
   end
 
-  def library(query, attribute='name') #:nodoc:
+  # Finds first library that has a value of attribute
+  def library(query, attribute='name')
     libraries.find {|e| e.send(attribute) == query }
   end
 
-  # Start Boson by loading repositories and their configured libraries.
-  # See ConsoleRunner.start for its options.
-  def start(options={})
-    ConsoleRunner.start(options)
-  end
-
   # Invoke an action on the main object.
   def invoke(*args, &block)
     main_object.send(*args, &block)
   end
 
-  # Invoke command string even with namespaces
-  def full_invoke(cmd, args) #:nodoc:
-    command, subcommand = cmd.include?(NAMESPACE) ? cmd.split(NAMESPACE, 2) : [cmd, nil]
-    dispatcher = subcommand ? Boson.invoke(command) : Boson.main_object
-    dispatcher.send(subcommand || command, *args)
+  # Similar to invoke but accepts args as an array
+  def full_invoke(cmd, args)
+    main_object.send(cmd, *args)
   end
 
   # Boolean indicating if the main object can invoke the given method/command.

data/lib/boson/bare_runner.rb

@@ -0,0 +1,83 @@
+module Boson
+  # Base class for runners.
+  class BareRunner
+    DEFAULT_LIBRARIES = []
+    # Default options for parse_args
+    GLOBAL_OPTIONS = {
+      help: { type: :boolean, desc: "Displays this help message" }
+    }
+
+    module API
+      # Loads rc
+      def start(*)
+        @options ||= {}
+        load_rc
+      end
+
+      # Default libraries loaded by init
+      def default_libraries
+        DEFAULT_LIBRARIES
+      end
+
+      def all_libraries
+        default_libraries
+      end
+
+      # Loads default libraries
+      def init
+        Manager.load default_libraries, load_options
+      end
+
+      # Wrapper around abort
+      def abort_with(message)
+        abort message
+      end
+    end
+
+    class<<self
+      include API
+
+      # Executes a command and handles invalid args
+      def execute_command(cmd, args)
+        Boson.full_invoke(cmd, args)
+      rescue ArgumentError
+        raise if !allowed_argument_error?($!, cmd, args)
+        abort_with "'#{cmd}' was called incorrectly.\nUsage: " + Command.usage(cmd)
+      rescue NoMethodError => err
+        raise if !err.backtrace.first.include?('`full_invoke')
+        no_command_error cmd
+      end
+
+      # Use to abort when no command found
+      def no_command_error(cmd)
+        abort_with %[Could not find command "#{cmd}"]
+      end
+
+      # Determines if a user command argument error or an internal Boson one
+      def allowed_argument_error?(err, cmd, args)
+        (err.message[/wrong number of arguments/] &&
+          (cmd_obj = Command.find(cmd)) && cmd_obj.arg_size != args.size)
+      end
+
+      private
+      def parse_args(args)
+        @option_parser = OptionParser.new(self::GLOBAL_OPTIONS)
+        options = @option_parser.parse(args.dup, :opts_before_args=>true)
+        new_args = @option_parser.non_opts
+        [new_args[0], options, new_args[1..-1]]
+      end
+
+      def load_rc
+        rc = ENV['BOSONRC'] || '~/.bosonrc'
+        load(rc) if !rc.empty? && File.exists?(File.expand_path(rc))
+      rescue StandardError, SyntaxError, LoadError => err
+        warn "Error while loading #{rc}:\n"+
+          "#{err.class}: #{err.message}\n    #{err.backtrace.join("\n    ")}"
+      end
+
+      def load_options
+        {:verbose=>@options[:verbose]}
+      end
+    end
+  end
+end