boson 0.0.1

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT LICENSE
+
+Copyright (c) 2009 Gabriel Horner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,133 @@
+== Description
+A command/task framework similar to rake and thor that opens your ruby universe to the commandline
+and irb. For my libraries that use this, see {irbfiles}[http://github.com/cldwalker/irbfiles].
+
+== Features
+* Commands are just methods that are extended by the toplevel object, main.
+* Commands are accessible from the commandline or irb.
+* Command libraries can be written as plain ruby which allows for easy testing and use outside of boson.
+* Commands can be full-blown commandline apps thanks to automatic views from hirb and powerful
+  options similar to thor's.
+* Command libraries are social as a user can install them from a url and then customize command
+  names and options without changing the original library.
+* Namespaces are optional and when used are methods which allows for method_missing magic.
+
+== Irb Example
+
+To use in irb, drop this in your irbrc:
+    require 'boson'
+    Boson.start :verbose=>true
+
+Let's start up irb:
+
+  bash> irb
+  Loaded library core
+  Loaded library web_core
+
+  # List default libraries
+  >> libraries
+  +----------+----------+------+--------------+
+  | name     | commands | gems | library_type |
+  +----------+----------+------+--------------+
+  | core     | 6        |      | module       |
+  | web_core | 3        |      | module       |
+  +----------+----------+------+--------------+
+  2 rows in set
+
+  # List default commands
+  >> commands
+  +--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
+  | full_name    | lib      | alias | usage                                      | description                                                                 |
+  +--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
+  | usage        | core     |       | [name][--verbose]                          | Print a command's usage                                                     |
+  | libraries    | core     |       | [query=''][--index] [--query_fields=A,B,C] | List or search libraries                                                    |
+  | render       | core     |       | [object] [options={}]                      | Render any object using Hirb                                                |
+  | load_library | core     |       | [library][--verbose] [--reload]            | Load/reload a library                                                       |
+  | commands     | core     |       | [query=''][--index] [--query_fields=A,B,C] | List or search commands                                                     |
+  | menu         | core     |       | [output] [options={}] [&block]             | Provide a menu to multi-select elements from a given array                  |
+  | get          | web_core |       | [url]                                      | Gets the body of a url                                                      |
+  | install      | web_core |       | [url][--force] [--name=NAME]               | Installs a library by url. Library should then be loaded with load_library. |
+  | browser      | web_core |       | [*urls]                                    | Opens urls in a browser                                                     |
+  +--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
+  9 rows in set
+
+  # Boson commands can behave like shell commands:
+
+  # Basic help
+  >> commands '-h'
+  commands [query=''][--index] [--query_fields=A,B,C]
+
+  # Search the lib column for web
+  >> commands 'web -q=lib' # or 'web --query_fields=lib'
+  +-----------+----------+-------+------------------------------+-----------------------------------------------------------------------------+
+  | full_name | lib      | alias | usage                        | description                                                                 |
+  +-----------+----------+-------+------------------------------+-----------------------------------------------------------------------------+
+  | get       | web_core |       | [url]                        | Gets the body of a url                                                      |
+  | install   | web_core |       | [url][--force] [--name=NAME] | Installs a library by url. Library should then be loaded with load_library. |
+  | browser   | web_core |       | [*urls]                      | Opens urls in a browser                                                     |
+  +-----------+----------+-------+------------------------------+-----------------------------------------------------------------------------+
+  3 rows in set
+
+== Commandline Example
+
+   # Just like in irb
+    bash> boson libraries
+    +----------+----------+------+--------------+
+    | name     | commands | gems | library_type |
+    +----------+----------+------+--------------+
+    | core     | 6        |      | module       |
+    | web_core | 3        |      | module       |
+    +----------+----------+------+--------------+
+    2 rows in set
+
+    # Let's install another library
+    bash> boson install http://github.com/cldwalker/irbfiles/raw/master/boson/commands/irb_core.rb
+    Saved to /Users/bozo/.boson/commands/irb_core.rb
+
+    # Let's start irb ...
+    bash> irb
+
+    >> commands
+    +-------------------------------+----------+------------+--------------------------------------------+-----------------------------------------------------------------------------+
+    | full_name                     | lib      | alias      | usage                                      | description                                                                 |
+    +-------------------------------+----------+------------+--------------------------------------------+-----------------------------------------------------------------------------+
+    | usage                         | core     |            | [name][--verbose]                          | Print a command's usage                                                     |
+    | libraries                     | core     |            | [query=''][--index] [--query_fields=name]  | List or search libraries                                                    |
+    | render                        | core     |            | [object] [options={}]                      | Render any object using Hirb                                                |
+    | load_library                  | core     |            | [library][--verbose] [--reload]            | Load/reload a library                                                       |
+    | commands                      | core     |            | [query=''][--index] [--query_fields=A,B,C] | List or search commands                                                     |
+    | menu                          | core     |            | [output] [options={}] [&block]             | Provide a menu to multi-select elements from a given array                  |
+    | get                           | web_core |            | [url]                                      | Gets the body of a url                                                      |
+    | install                       | web_core |            | [url][--force] [--name=NAME]               | Installs a library by url. Library should then be loaded with load_library. |
+    | browser                       | web_core |            | [*urls]                                    | Opens urls in a browser                                                     |
+    | irb_pop_workspace             | irb_core | popws      |                                            | Pops current workspace and changes to next workspace in context             |
+    | irb_require                   | irb_core |            |                                            | Evals file like require line by line                                        |
+    | public                        | irb_core |            |                                            | Works same as module#public                                                 |
+    | private                       | irb_core |            |                                            | Works same as module#private                                                |
+    | irb                           | irb_core |            |                                            | Starts a new workspace/subsession                                           |
+    | irb_push_workspace            | irb_core | pushws     |                                            | Creates a workspace for given object and pushes it into the current context |
+    | irb_load                      | irb_core |            |                                            | Evals file like load line by line                                           |
+    | irb_change_workspace          | irb_core | cws        |                                            | Changes current workspace to given object                                   |
+    | irb_source                    | irb_core | source     |                                            | Evals full path file line by line                                           |
+    | irb_jobs                      | irb_core | jobs       |                                            | List workspaces/subsessions                                                 |
+    | irb_fg                        | irb_core | fg         |                                            | Switch to a workspace/subsession                                            |
+    | irb_help                      | irb_core | help       |                                            | Ri based help                                                               |
+    | irb_kill                      | irb_core | kill       |                                            | Kills a given workspace/subsession                                          |
+    | include                       | irb_core |            |                                            | Works same as module#include                                                |
+    | irb_exit                      | irb_core | exit       |                                            | Kills the current workspace/subsession                                      |
+    | irb_workspaces                | irb_core | workspaces |                                            | Array of workspaces for current context                                     |
+    | irb_context                   | irb_core | conf       |                                            | Displays configuration for current workspace/subsession                     |
+    | install_alias_method          | irb_core |            |                                            | Aliases given method, allows lazy loading of dependent file                 |
+    | irb_current_working_workspace | irb_core | cwws       |                                            | Prints current workspace                                                    |
+    +-------------------------------+----------+------------+--------------------------------------------+-----------------------------------------------------------------------------+
+    28 rows in set
+
+    # Sweet! Now we have a list and description of commands that come with irb.
+
+== Creating commands
+TODO: Explain library format
+
+== Todo
+* More docs
+* More tests
+* Add tags to libraries + commands

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts = ["-T -x '/Library/Ruby/*'"]
+    t.verbose = true
+  end
+rescue LoadError
+  puts "Rcov not available. Install it for rcov-related tasks with: sudo gem install rcov"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "boson"
+    s.description = "A command/task framework similar to rake and thor that opens your ruby universe to the commandline and irb."
+    s.summary =  "Although similar to rake and thor, it's focus is not on per-project tasks. Rather it provides users with the power to turn any ruby method, into a full-fledged commandline tool. Boson achieves this with powerful options (borrowed from thor) and views (thanks to hirb). Some other unique features that differentiate it from rake and thor include being accessible from irb and the commandline, being able to write boson commands in non-dsl ruby and toggling a pretty view of a command's output without additional view code."
+    s.email = "gabriel.horner@gmail.com"
+    s.homepage = "http://github.com/cldwalker/boson"
+    s.authors = ["Gabriel Horner"]
+    s.has_rdoc = true
+    s.rubyforge_project = 'tagaholic'
+    s.add_dependency 'hirb', '>= 0.2.6'
+    s.add_dependency 'alias', '>= 0.2.1'
+    s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
+    s.files = FileList["Rakefile", "VERSION.yml", "README.rdoc", "LICENSE.txt", "{bin,lib,test}/**/*"]
+  end
+
+rescue LoadError
+  puts "Jeweler not available. Install it for jeweler-related tasks with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'test'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+task :default => :test

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 0
+:patch: 1

data/bin/boson

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

data/lib/boson.rb

@@ -0,0 +1,72 @@
+$:.unshift File.dirname(__FILE__) unless $:.include? File.expand_path(File.dirname(__FILE__))
+%w{hirb alias}.each {|e| require e }
+%w{runner runners/repl_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}.each {|e| require "boson/libraries/#{e}_library" }
+%w{namespace view command util commands option_parser index scientist}.each {|e| require "boson/#{e}" }
+
+# This module stores the libraries, commands, repos and main object used throughout Boson.
+module Boson
+  # Module which is extended by Boson.main_object to give it command functionality.
+  module Universe; include Commands::Namespace; end
+  extend self
+  # The object which holds and executes all command functionality
+  attr_accessor :main_object
+  attr_accessor :commands, :libraries
+  alias_method :higgs, :main_object
+
+  # Array of loaded Boson::Library objects.
+  def libraries
+    @libraries ||= Array.new
+  end
+
+  # Array of loaded Boson::Command objects.
+  def commands
+    @commands ||= Array.new
+  end
+
+  # The main required repository which defaults to ~/.boson.
+  def repo
+    @repo ||= Repo.new("#{ENV['HOME']}/.boson")
+  end
+
+  # An optional local repository which defaults to ./lib/boson or ./.boson.
+  def local_repo
+    @local_repo ||= begin
+      dir = ["lib/boson", ".boson"].find {|e| File.directory?(e) &&
+         File.expand_path(e) != repo.dir }
+      Repo.new(dir) if dir
+    end
+  end
+
+  # The array of loaded repositories.
+  def repos
+    @repos ||= [repo, local_repo].compact
+  end
+
+  def main_object=(value) #:nodoc:
+    @main_object = value.extend(Universe)
+  end
+
+  def library(query, attribute='name') #:nodoc:
+    libraries.find {|e| e.send(attribute) == query }
+  end
+
+  # Start Boson by loading repositories and their configured libraries.
+  def start(options={})
+    ReplRunner.start(options)
+  end
+
+  # Invoke an action on the main object.
+  def invoke(*args, &block)
+    main_object.send(*args, &block)
+  end
+
+  # Boolean indicating if the main object can invoke the given method/command.
+  def can_invoke?(meth)
+    Boson.main_object.respond_to? meth
+  end
+end
+
+Boson.main_object = self

data/lib/boson/command.rb

@@ -0,0 +1,117 @@
+module Boson
+  # A command maps the functionality of a ruby method with the added benefits of options, render_options, etc.
+  class Command
+    # Creates a command given its name and a library.
+    def self.create(name, library)
+      new (library.commands_hash[name] || {}).merge({:name=>name, :lib=>library.name, :namespace=>library.namespace})
+    end
+
+    # Finds a command, namespaced or not and aliased or not. If found returns the
+    # command object, otherwise returns nil.
+    def self.find(command, commands=Boson.commands)
+      command, subcommand = command.to_s.split('.', 2)
+      is_namespace_command = lambda {|current_command|
+        [current_command.name, current_command.alias].include?(subcommand) &&
+        current_command.library && (current_command.library.namespace == command)
+      }
+      find_lambda = subcommand ? is_namespace_command : lambda {|e| [e.name, e.alias].include?(command)}
+      commands.find(&find_lambda)
+    end
+
+    ATTRIBUTES = [:name, :lib, :alias, :description, :options, :args]
+    attr_accessor *(ATTRIBUTES + [:render_options, :namespace])
+    # A hash of attributes which map to instance variables and values. :name
+    # and :lib are required keys.
+    def initialize(hash)
+      @name = hash[:name] or raise ArgumentError
+      @lib = hash[:lib] or raise ArgumentError
+      @alias = hash[:alias] if hash[:alias]
+      @description = hash[:description] if hash[:description]
+      @render_options = hash[:render_options] if hash[:render_options]
+      @options = hash[:options] if hash[:options]
+      @namespace = hash[:namespace] if hash[:namespace]
+      if hash[:args]
+        if hash[:args].is_a?(Array)
+          @args = hash[:args]
+        elsif hash[:args].to_s[/^\d+/]
+          @arg_size = hash[:args].to_i
+        elsif hash[:args] == '*'
+          @args = [['*args']]
+        end
+      end
+    end
+
+    # Library object a command belongs to.
+    def library
+      @library ||= Boson.library(@lib)
+    end
+
+    # Array of array args with optional defaults. Scraped with ArgumentInspector.
+    def args(lib=library)
+      @args ||= begin
+        if lib && File.exists?(lib.library_file || '')
+          @file_parsed_args = true
+          file_string = Boson::FileLibrary.read_library_file(lib.library_file)
+          ArgumentInspector.scrape_with_text(file_string, @name)
+        end
+      end
+    end
+
+    # Option parser for command as defined by @options.
+    def option_parser
+      @option_parser ||= (@options ? OptionParser.new(@options) : nil)
+    end
+
+    # Help string for options if a command has it.
+    def option_help
+      @options ? option_parser.to_s : ''
+    end
+
+    # Usage string for command, created from options and args.
+    def usage
+      return '' if options.nil? && args.nil?
+      usage_args = args && @options ? args[0..-2] : args
+      str = args ? usage_args.map {|e|
+        (e.size < 2) ? "[#{e[0]}]" : "[#{e[0]}=#{@file_parsed_args ? e[1] : e[1].inspect}]"
+      }.join(' ') : '[*unknown]'
+      str + option_help
+    end
+
+    # Full name is only different than name if a command has a namespace.
+    # The full name should be what you would type to execute the command.
+    def full_name
+      @namespace ? "#{@namespace}.#{@name}" : @name
+    end
+
+    #:stopdoc:
+    def has_splat_args?
+      @args && @args.any? {|e| e[0][/^\*/] }
+    end
+
+    def option_command?
+      options || render_options
+    end
+
+    def arg_size
+      @arg_size = args ? args.size : nil unless instance_variable_defined?("@arg_size")
+      @arg_size
+    end
+
+    def file_parsed_args?
+      @file_parsed_args
+    end
+
+    def marshal_dump
+      if @args && @args.any? {|e| e[1].is_a?(Module) }
+        @args.map! {|e| e.size == 2 ? [e[0], e[1].inspect] : e }
+        @file_parsed_args = true
+      end
+      [@name, @alias, @lib, @description, @options, @render_options, @args]
+    end
+
+    def marshal_load(ary)
+      @name, @alias, @lib, @description, @options, @render_options, @args = ary
+    end
+    #:startdoc:
+  end
+end

data/lib/boson/commands.rb

@@ -0,0 +1,7 @@
+# Module under which most library modules are evaluated.
+module Boson::Commands
+  # Used for defining namespaces.
+  module Namespace; end
+end
+require 'boson/commands/core'
+require 'boson/commands/web_core'

data/lib/boson/commands/core.rb

@@ -0,0 +1,66 @@
+module Boson::Commands::Core #:nodoc:
+  def self.config
+    command_attributes = Boson::Command::ATTRIBUTES + [:usage, :full_name, :render_options]
+    library_attributes = Boson::Library::ATTRIBUTES + [:library_type]
+
+    commands = {
+      'render'=>{:description=>"Render any object using Hirb"},
+      'menu'=>{:description=>"Provide a menu to multi-select elements from a given array"},
+      'usage'=>{:description=>"Print a command's usage", :options=>{:verbose=>:boolean}},
+      'commands'=>{ :description=>"List or search commands",
+        :options=>{:query_fields=>{:default=>['full_name'], :values=>command_attributes},
+          :index=>{:type=>:boolean, :desc=>"Searches index"}},
+        :render_options=>{:fields=>{:default=>[:full_name, :lib, :alias, :usage, :description], :values=>command_attributes} }
+      },
+      'libraries'=>{ :description=>"List or search libraries",
+        :options=>{:query_fields=>{:default=>['name'], :values=>library_attributes},
+          :index=>{:type=>:boolean, :desc=>"Searches index"} },
+        :render_options=>{
+          :fields=>{:default=>[:name, :commands, :gems, :library_type], :values=>library_attributes},
+          :filters=>{:default=>{:gems=>[:join, ','],:commands=>:size}} }
+      },
+      'load_library'=>{:description=>"Load/reload a library", :options=>{:reload=>:boolean, :verbose=>true}}
+    }
+
+    {:library_file=>File.expand_path(__FILE__), :commands=>commands}
+  end
+
+  def commands(query='', options={})
+    query_fields = options[:query_fields] || ['full_name']
+    Boson::Index.read if options[:index]
+    commands = options[:index] ? Boson::Index.commands : Boson.commands
+    query_fields.map {|e| commands.select {|f| f.send(e).to_s =~ /#{query}/i } }.flatten
+  end
+
+  def libraries(query='', options={})
+    Boson::Index.read if options[:index]
+    libraries = options[:index] ? Boson::Index.libraries : Boson.libraries
+    options[:query_fields].map {|e| libraries.select {|f| f.send(e).to_s =~ /#{query}/i } }.flatten
+  end
+
+  def load_library(library, options={})
+    options[:reload] ? Boson::Manager.reload(library, options) :
+      Boson::Manager.load(library, options)
+  end
+
+  def render(object, options={})
+    Boson::View.render(object, options)
+  end
+
+  def menu(output, options={}, &block)
+    Hirb::Console.format_output(output, options.merge(:class=>"Hirb::Menu"), &block)
+  end
+
+  def usage(name, options={})
+    msg = (command = Boson::Command.find(name)) ? "#{name} #{command.usage}" : "Command '#{name}' not found"
+    puts msg
+    if command && options[:verbose]
+      if command.options && !command.options.empty?
+        puts "\nCOMMAND OPTIONS"
+        command.option_parser.print_usage_table
+      end
+      puts "\nGLOBAL/RENDER OPTIONS"
+      Boson::Scientist.render_option_parser(command).print_usage_table
+    end
+  end
+end