boson 0.1.0 → 0.2.0

data/README.rdoc

@@ -3,6 +3,8 @@ A command/task framework similar to rake and thor that opens your ruby universe
 and irb. For my libraries that use this, see {irbfiles}[http://github.com/cldwalker/irbfiles].
 Works with Ruby 1.8.6 and 1.9.1.
 
+Note: To read a linkable version of this README, {see here}[http://tagaholic.me/boson/doc/].
+
 == Features
 * Commands are just methods extended for a given object, the default being the top level object, main.
 * Commands are accessible from the commandline (Boson::BinRunner) or irb (Boson::ConsoleRunner).
@@ -11,7 +13,9 @@ Works with Ruby 1.8.6 and 1.9.1.
 * Comes with default commands to load, search, list and install commands and libraries (Boson::Commands::Core).
 * Commands can be full-blown commandline apps thanks to powerful options (Boson::OptionParser)
   and hirb's views.
-* Commands can have views toggled without adding view code to your original command (Boson::Scientist).
+* There are 5 default option types: boolean, array, string, hash and numeric. Custom option types
+  can be defined to map to any Ruby class with one method (Boson::Options).
+* Commands can have views toggled without adding view code to the original command (Boson::Scientist).
 * 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 allow for method_missing magic.
@@ -85,7 +89,7 @@ Having done that, let's start up irb:
     2 rows in set
 
     # Let's install another library
-    bash> boson install http://github.com/cldwalker/irbfiles/raw/master/boson/commands/irb_core.rb
+    bash> boson install http://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/irb_core.rb
     Saved to /Users/bozo/.boson/commands/irb_core.rb
 
     # Let's start irb ...
@@ -132,18 +136,26 @@ Having done that, let's start up irb:
 See Boson::FileLibrary or here[http://tagaholic.me/boson/doc/classes/Boson/FileLibrary.html].
 
 == Todo
-* More docs
 * More tests
 * Making commands out of existing gems easier and more powerful
 * Better local repositories, perhaps a BosonFile
 * Consider managing extensions to core and standard libraries
 * Consider dropping alias gem dependency if not using its full potential
 
+== Bugs/Issues
+Please report them {on github}[http://github.com/cldwalker/boson/issues].
+
 == Motivation
 My {tagging obsession}[http://github.com/cldwalker/tag-tree] from the ruby console.
 
+== Links
+* http://tagaholic.me/2009/10/14/boson-command-your-ruby-universe.html
+* http://tagaholic.me/2009/10/15/boson-and-hirb-interactions.html
+* http://tagaholic.me/2009/10/19/how-boson-enhances-your-irb-experience.html
+
 == Acknowledgements
 Boson stands on the shoulders of these people and their ideas:
+* Yehuda Katz for inspiring me with Thor's power and elegant design
 * Yehuda Katz and Daniel Berger for an awesome option parser (Boson::OptionParser)
 * Dave Thomas for scraping a method's comments (Boson::CommentInspector)
 * Mauricio Fernandez for scraping a method's arguments (Boson::ArgumentInspector)

data/Rakefile

@@ -21,11 +21,11 @@ begin
     s.description = "A command/task framework similar to rake and thor that opens your ruby universe to the commandline and irb."
     s.summary =  "Boson 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.homepage = "http://tagaholic.me/boson/"
     s.authors = ["Gabriel Horner"]
     s.has_rdoc = true
     s.rubyforge_project = 'tagaholic'
-    s.add_dependency 'hirb', '>= 0.2.7'
+    s.add_dependency 'hirb', '>= 0.2.8'
     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}/**/*"]

data/VERSION.yml

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

data/lib/boson.rb

@@ -4,9 +4,20 @@ $:.unshift File.dirname(__FILE__) unless $:.include? File.expand_path(File.dirna
 %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}" }
+(%w{namespace view command util commands option_parser options} +
+  %w{index scientist}).each {|e| require "boson/#{e}" }
 
 # This module stores the libraries, commands, repos and main object used throughout Boson.
+#
+# 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
+# * Boson::Scientist - Explains how commands can be both shell-commands and normal ruby methods
 module Boson
   # Module which is extended by Boson.main_object to give it command functionality.
   module Universe; include Commands::Namespace; end
@@ -28,7 +39,7 @@ module Boson
 
   # The main required repository which defaults to ~/.boson.
   def repo
-    @repo ||= Repo.new("#{ENV['HOME']}/.boson")
+    @repo ||= Repo.new("#{Util.find_home}/.boson")
   end
 
   # An optional local repository which defaults to ./lib/boson or ./.boson.
@@ -64,9 +75,16 @@ module Boson
     main_object.send(*args, &block)
   end
 
+  # Invoke command string even with namespaces
+  def full_invoke(cmd, args) #:nodoc:
+    command, subcommand = cmd.include?('.') ? cmd.split('.', 2) : [cmd, nil]
+    dispatcher = subcommand ? Boson.invoke(command) : Boson.main_object
+    dispatcher.send(subcommand || command, *args)
+  end
+
   # Boolean indicating if the main object can invoke the given method/command.
-  def can_invoke?(meth)
-    Boson.main_object.respond_to? meth
+  def can_invoke?(meth, priv=true)
+    Boson.main_object.respond_to? meth, priv
   end
 end
 

data/lib/boson/command.rb

@@ -19,7 +19,7 @@ module Boson
     end
 
     ATTRIBUTES = [:name, :lib, :alias, :description, :options, :args]
-    attr_accessor *(ATTRIBUTES + [:render_options, :namespace])
+    attr_accessor *(ATTRIBUTES + [:render_options, :namespace, :default_option])
     # A hash of attributes which map to instance variables and values. :name
     # and :lib are required keys.
     #
@@ -32,6 +32,11 @@ module Boson
     #   important for commands that have options/render_options. Its value can be an array
     #   (as ArgumentInspector.scrape_with_eval produces), a number representing
     #   the number of arguments or '*' if the command has a variable number of arguments.
+    # * *:default_option* Only for an option command that has one argument. This treats the given
+    #   option as an optional first argument. Example:
+    #     # For a command with default option 'query' and options --query and -v
+    #     'some -v'   -> '--query=some -v'
+    #     '-v'        -> '-v'
     def initialize(hash)
       @name = hash[:name] or raise ArgumentError
       @lib = hash[:lib] or raise ArgumentError
@@ -40,6 +45,7 @@ module Boson
       @render_options = hash[:render_options] if hash[:render_options]
       @options = hash[:options] if hash[:options]
       @namespace = hash[:namespace] if hash[:namespace]
+      @default_option = hash[:default_option] if hash[:default_option]
       if hash[:args]
         if hash[:args].is_a?(Array)
           @args = hash[:args]
@@ -80,7 +86,9 @@ module Boson
     # 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
+      usage_args = args && @options && !has_splat_args? ?
+        (@default_option ? [[@default_option.to_s, @file_parsed_args ? ''.inspect : '']] + args[0..-2] :
+        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]'
@@ -116,11 +124,11 @@ module Boson
         @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]
+      [@name, @alias, @lib, @description, @options, @render_options, @args, @default_option]
     end
 
     def marshal_load(ary)
-      @name, @alias, @lib, @description, @options, @render_options, @args = ary
+      @name, @alias, @lib, @description, @options, @render_options, @args, @default_option = ary
     end
     #:startdoc:
   end

data/lib/boson/commands/core.rb

@@ -1,5 +1,7 @@
 module Boson::Commands::Core #:nodoc:
-  def self.config
+  extend self
+
+  def config
     command_attributes = Boson::Command::ATTRIBUTES + [:usage, :full_name, :render_options]
     library_attributes = Boson::Library::ATTRIBUTES + [:library_type]
 
@@ -7,35 +9,33 @@ module Boson::Commands::Core #:nodoc:
       '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, :V]=>:boolean}},
-      'commands'=>{ :description=>"List or search commands",
-        :options=>{:query_fields=>{:default=>['full_name'], :values=>command_attributes, :desc=>"Searchable fields"},
-          :index=>{:type=>:boolean, :desc=>"Searches index"}},
-        :render_options=>{:fields=>{:default=>[:full_name, :lib, :alias, :usage, :description], :values=>command_attributes} }
+      'commands'=>{
+        :description=>"List or search commands", :default_option=>'query',
+        :options=>{ :index=>{:type=>:boolean, :desc=>"Searches index"}},
+        :render_options=>{
+          :query=>{:keys=>command_attributes, :default_keys=>'full_name'},
+          :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, :desc=>"Searchable fields"},
-          :index=>{:type=>:boolean, :desc=>"Searches index"} },
+      'libraries'=>{
+        :description=>"List or search libraries", :default_option=>'query',
+        :options=>{ :index=>{:type=>:boolean, :desc=>"Searches index"} },
         :render_options=>{
+          :query=>{:keys=>library_attributes, :default_keys=>'name'},
           :fields=>{:default=>[:name, :commands, :gems, :library_type], :values=>library_attributes},
-          :filters=>{:default=>{:gems=>[:join, ','],:commands=>:size}} }
+          :filters=>{:default=>{:gems=>[:join, ','],:commands=>:size}, :desc=>"Filters to apply to library fields" }}
       },
       'load_library'=>{:description=>"Load/reload a library", :options=>{:reload=>:boolean, [:verbose,:V]=>true}}
     }
 
-    {:library_file=>File.expand_path(__FILE__), :commands=>commands}
+    {:namespace=>false, :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.uniq
+  def commands(options={})
+    options[:index] ? (Boson::Index.read || true) && Boson::Index.commands : Boson.commands
   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.uniq
+  def libraries(options={})
+    options[:index] ? (Boson::Index.read || true) && Boson::Index.libraries : Boson.libraries
   end
 
   def load_library(library, options={})

data/lib/boson/commands/web_core.rb

@@ -1,23 +1,36 @@
 module Boson::Commands::WebCore #:nodoc:
-  def self.config
+  extend self
+
+  def config
     descriptions = {
       :install=>"Installs a library by url. Library should then be loaded with load_library.",
-      :browser=>"Opens urls in a browser on a Mac", :get=>"Gets the body of a url" }
+      :browser=>"Opens urls in a browser on a Mac", :get=>"Gets the body of a url", :post=>'Posts to url' }
     commands = descriptions.inject({}) {|h,(k,v)| h[k.to_s] = {:description=>v}; h}
     commands['install'][:options] = {:name=>{:type=>:string, :desc=>"Library name to save to"},
       :force=>{:type=>:boolean, :desc=>'Overwrites an existing library'},
       :module_wrap=>{:type=>:boolean, :desc=>"Wraps a module around install using library name"},
       :method_wrap=>{:type=>:boolean, :desc=>"Wraps a method and module around installe library using library name"}}
-    {:library_file=>File.expand_path(__FILE__), :commands=>commands}
+    {:library_file=>File.expand_path(__FILE__), :commands=>commands, :namespace=>false}
   end
 
-  def get(url)
+  def get(url, options={})
     %w{uri net/http}.each {|e| require e }
-    Net::HTTP.get(URI.parse(url))
+    if options[:success_only]
+      url = URI.parse(url)
+      res = Net::HTTP.start(url.host, url.port) {|http| http.get(url.request_uri) }
+      res.code == '200' ? res.body : nil
+    else
+      Net::HTTP.get(URI.parse(url))
+    end
   rescue
     raise "Error opening #{url}"
   end
 
+  def post(url, options={})
+    %w{uri net/http}.each {|e| require e }
+    Net::HTTP.post_form(URI.parse(url), options)
+  end
+
   def install(url, options={})
     options[:name] ||= strip_name_from_url(url)
     return puts("Please give a library name for this url.") if options[:name].empty?

data/lib/boson/index.rb

@@ -1,22 +1,30 @@
 require 'digest/md5'
 module Boson
-  # Used in all things indexing i.e. saving state for boson's commandline.
+  # This class is used by BinRunner to index/store all of Boson's commands and libraries. When this index updates,
+  # it detects library files whose md5 hash have changed and reindexes them. The index is stored with Marshal
+  # at ~/.boson/config/index.marshal. Since the index is marshaled, putting lambdas/procs in it will break it.
+  # If your index gets corrupted, simply delete it and next time Boson needs it, the index will be recreated.
   module Index
     extend self
     attr_reader :libraries, :commands
 
     # Updates the index.
     def update(options={})
-      options[:all] = true if !exists? && !options.key?(:all)
-      libraries_to_update = options[:all] ? Runner.all_libraries : changed_libraries
+      libraries_to_update = !exists? ? Runner.all_libraries : options[:libraries] || changed_libraries
       read_and_transfer(libraries_to_update)
       if options[:verbose]
-        puts options[:all] ? "Generating index for all #{libraries_to_update.size} libraries. Patience ... is a bitch" :
+        puts !exists? ? "Generating index for all #{libraries_to_update.size} libraries. Patience ... is a bitch" :
           (libraries_to_update.empty? ? "No libraries indexed" :
           "Indexing the following libraries: #{libraries_to_update.join(', ')}")
       end
-      Manager.load(libraries_to_update, options.merge(:index=>true)) unless libraries_to_update.empty?
-      write
+      Manager.failed_libraries = []
+      unless libraries_to_update.empty?
+        Manager.load(libraries_to_update, options.merge(:index=>true))
+        unless Manager.failed_libraries.empty?
+          $stderr.puts("Error: These libraries failed to load while indexing: #{Manager.failed_libraries.join(', ')}")
+        end
+      end
+      write(Manager.failed_libraries)
     end
 
     # Reads and initializes index.
@@ -24,22 +32,25 @@ module Boson
       return if @read
       @libraries, @commands, @lib_hashes = exists? ? Marshal.load(File.read(marshal_file)) : [[], [], {}]
       delete_stale_libraries_and_commands
-      set_latest_namespaces
+      set_command_namespaces
       @read = true
     end
 
     # Writes/saves current index to config/index.marshal.
-    def write
-      save_marshal_index Marshal.dump([Boson.libraries, Boson.commands, latest_hashes])
+    def write(failed_libraries=[])
+      latest = latest_hashes
+      failed_libraries.each {|e| latest.delete(e) }
+      save_marshal_index Marshal.dump([Boson.libraries, Boson.commands, latest])
     end
 
     #:stopdoc:
     def read_and_transfer(ignored_libraries=[])
       read
       existing_libraries = (Boson.libraries.map {|e| e.name} + ignored_libraries).uniq
-      Boson.libraries += @libraries.select {|e| !existing_libraries.include?(e.name)}
-      existing_commands = Boson.commands.map {|e| e.name} #td: consider namespace
-      Boson.commands += @commands.select {|e| !existing_commands.include?(e.name) && !ignored_libraries.include?(e.lib)}
+      libraries_to_add = @libraries.select {|e| !existing_libraries.include?(e.name)}
+      Boson.libraries += libraries_to_add
+      # depends on saved commands being correctly associated with saved libraries
+      Boson.commands += libraries_to_add.map {|e| e.command_objects(e.commands, @commands) }.flatten
     end
 
     def exists?
@@ -58,21 +69,19 @@ module Boson
       @commands.delete_if {|e| names_to_delete.include? e.lib }
     end
 
-    # get latest namespaces from config files
-    def set_latest_namespaces
-      namespace_libs = Boson.repo.config[:auto_namespace] ? @libraries.map {|e| [e.name, {:namespace=>true}]} :
-        Boson.repo.config[:libraries].select {|k,v| v && v[:namespace] }
+    # set namespaces for commands
+    def set_command_namespaces
       lib_commands = @commands.inject({}) {|t,e| (t[e.lib] ||= []) << e; t }
-      namespace_libs.each {|name, hash|
-        if (lib = @libraries.find {|l| l.name == name})
-          lib.namespace = (hash[:namespace] == true) ? lib.clean_name : hash[:namespace]
-          (lib_commands[lib.name] || []).each {|e| e.namespace = lib.namespace }
-        end
+      namespace_libs = @libraries.select {|e| e.namespace(e.indexed_namespace) }
+      namespace_libs.each {|lib|
+        (lib_commands[lib.name] || []).each {|e| e.namespace = lib.namespace }
       }
     end
 
     def namespaces
-      @libraries.map {|e| e.namespace }.compact
+      nsps = @libraries.map {|e| e.namespace }.compact
+      nsps.delete(false)
+      nsps
     end
 
     def all_main_methods

data/lib/boson/inspector.rb

@@ -49,20 +49,26 @@ module Boson
       (MethodInspector::METHODS + [:method_args]).each do |e|
         key = command_key(e)
         (@store[e] || []).each do |cmd, val|
-          if no_command_config_for(cmd, key)
-            (@commands_hash[cmd] ||= {})[key] = val
-          end
+          @commands_hash[cmd] ||= {}
+          add_scraped_data_to_config(key, val, cmd)
         end
       end
     end
 
+    def add_scraped_data_to_config(key, value, cmd)
+      if value.is_a?(Hash)
+        @commands_hash[cmd][key] = Util.recursive_hash_merge value, @commands_hash[cmd][key] || {}
+      else
+        @commands_hash[cmd][key] ||= value
+      end
+    end
+
     def add_comment_scraped_data
       (@store[:method_locations] || []).select {|k,(f,l)| f == @library_file }.each do |cmd, (file, lineno)|
         scraped = CommentInspector.scrape(FileLibrary.read_library_file(file), lineno, MethodInspector.current_module)
+        @commands_hash[cmd] ||= {}
         MethodInspector::METHODS.each do |e|
-          if no_command_config_for(cmd, e)
-            (@commands_hash[cmd] ||= {})[command_key(e)] = scraped[e]
-          end
+          add_scraped_data_to_config(command_key(e), scraped[e], cmd)
         end
       end
     end
@@ -71,10 +77,6 @@ module Boson
     def command_key(key)
       {:method_args=>:args, :desc=>:description}[key] || key
     end
-
-    def no_command_config_for(cmd, attribute)
-      !@commands_hash[cmd] || (@commands_hash[cmd] && !@commands_hash[cmd].key?(attribute))
-    end
     #:startdoc:
   end
 end

data/lib/boson/inspectors/method_inspector.rb

@@ -43,7 +43,7 @@ module Boson
 
     METHODS.each do |e|
       define_method(e) do |mod, val|
-        store(mod)[e] ||= {}
+        (@mod_store[mod] ||= {})[e] ||= {}
         (store(mod)[:temp] ||= {})[e] = val
       end
     end

data/lib/boson/libraries/file_library.rb

@@ -3,8 +3,8 @@ module Boson
   # Since there can be multiple repositories, a library's file is looked for in the order given by
   # Boson.repos.
   #
-  # To create this library, simply create a file with a module and some methods. Non-private methods
-  # are automatically loaded as a library's commands.
+  # To create this library, simply create a file with a module and some methods (See Library
+  # for naming a module). Non-private methods are automatically loaded as a library's commands.
   #
   # Take for example a library brain.rb:
   #   module Brain
@@ -83,30 +83,47 @@ module Boson
     end
 
     handles {|source|
-      @repo = Boson.repos.find {|e|
-        File.exists? library_file(source.to_s, e.dir)
-      }
+      @repo = Boson.repos.find {|e| File.exists? library_file(source.to_s, e.dir) } ||
+       Boson.repos.find {|e|
+        Dir["#{e.commands_dir}/**/*.rb"].grep(/\/#{source}\.rb/).size == 1
+        }
       !!@repo
     }
 
-    def library_file
-      self.class.library_file(@name, @repo_dir)
+    def library_file(name=@name)
+      self.class.library_file(name, @repo_dir)
     end
 
     def set_repo
       self.class.matched_repo
     end
 
+    def set_name(name)
+      @lib_file = File.exists?(library_file(name.to_s)) ? library_file(name.to_s) :
+        Dir[self.class.matched_repo.commands_dir.to_s+'/**/*.rb'].find {|e| e =~ /\/#{name}\.rb$/}
+      super @lib_file.gsub(/^#{self.class.matched_repo.commands_dir}\/|\.rb$/, '')
+    end
+
     def load_source(reload=false)
-      library_string = self.class.read_library_file(library_file, reload)
+      library_string = self.class.read_library_file(@lib_file, reload)
+      @base_module = @name.include?('/') ? create_module_from_path : Commands
       Inspector.enable
-      Commands.module_eval(library_string, library_file)
+      @base_module.module_eval(library_string, @lib_file)
       Inspector.disable
     end
 
+    def create_module_from_path
+      @name.split('/')[0..-2].inject(Boson::Commands) {|base, e|
+        base.const_defined?(sub_mod = Util.camelize(e)) ? base.const_get(sub_mod) :
+          Util.create_module(base, e)
+      }
+    end
+
     def load_source_and_set_module
       detected = detect_additions(:modules=>true) { load_source }
       @module = determine_lib_module(detected[:modules]) unless @module
+      #without this, module's class methods weren't showing up
+      @module = Util.constantize(@module) if @base_module != Commands
     end
 
     def reload_source_and_set_module
@@ -122,8 +139,11 @@ module Boson
       when 1 then lib_module = detected_modules[0]
       when 0 then raise LoaderError, "Can't detect module. Make sure at least one module is defined in the library."
       else
-        unless ((lib_module = Util.constantize("boson/commands/#{@name}")) && lib_module.to_s[/^Boson::Commands/])
-          raise LoaderError, "Can't detect module. Specify a module in this library's config."
+        unless (lib_module = Util.constantize("boson/commands/#{@name}")) && lib_module.to_s[/^Boson::Commands/]
+          command_modules = detected_modules.map {|e| e.to_s}.grep(/^#{@base_module}::/)
+          unless command_modules.size == 1 && (lib_module = command_modules[0])
+            raise LoaderError, "Can't detect module. Specify a module in this library's config."
+          end
         end
       end
       lib_module