boson 0.0.1 → 0.1.0

data/README.rdoc

@@ -1,24 +1,28 @@
 == 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].
+Works with Ruby 1.8.6 and 1.9.1.
 
 == 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.
+* 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).
+* Command libraries, which are just modules, are written in non-dsl ruby which allows for easy testing
+  and use outside of boson (Boson::FileLibrary).
+* 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).
 * 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.
+* Namespaces are optional and when used are methods which allow for method_missing magic.
 
 == Irb Example
 
-To use in irb, drop this in your irbrc:
+To use in irb, drop this in your ~/.irbrc:
     require 'boson'
-    Boson.start :verbose=>true
+    Boson.start
 
-Let's start up irb:
+Having done that, let's start up irb:
 
   bash> irb
   Loaded library core
@@ -124,10 +128,23 @@ Let's start up irb:
 
     # Sweet! Now we have a list and description of commands that come with irb.
 
-== Creating commands
-TODO: Explain library format
+== Creating Command Libraries
+See Boson::FileLibrary or here[http://tagaholic.me/boson/doc/classes/Boson/FileLibrary.html].
 
 == Todo
 * More docs
 * More tests
-* Add tags to libraries + commands
+* 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
+
+== Motivation
+My {tagging obsession}[http://github.com/cldwalker/tag-tree] from the ruby console.
+
+== Acknowledgements
+Boson stands on the shoulders of these people and their ideas:
+* 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)
+* Chris Wanstrath for inspiring Boson's libraries with Rip's packages.

data/Rakefile

@@ -19,13 +19,13 @@ begin
   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.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.authors = ["Gabriel Horner"]
     s.has_rdoc = true
     s.rubyforge_project = 'tagaholic'
-    s.add_dependency 'hirb', '>= 0.2.6'
+    s.add_dependency 'hirb', '>= 0.2.7'
     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: 0
-:patch: 1
+:minor: 1
+:patch: 0

data/lib/boson.rb

@@ -1,6 +1,6 @@
 $:.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{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}.each {|e| require "boson/libraries/#{e}_library" }
@@ -40,7 +40,7 @@ module Boson
     end
   end
 
-  # The array of loaded repositories.
+  # The array of loaded repositories
   def repos
     @repos ||= [repo, local_repo].compact
   end
@@ -54,8 +54,9 @@ module Boson
   end
 
   # Start Boson by loading repositories and their configured libraries.
+  # See ConsoleRunner.start for its options.
   def start(options={})
-    ReplRunner.start(options)
+    ConsoleRunner.start(options)
   end
 
   # Invoke an action on the main object.

data/lib/boson/command.rb

@@ -1,5 +1,5 @@
 module Boson
-  # A command maps the functionality of a ruby method with the added benefits of options, render_options, etc.
+  # A command starts with the functionality of a ruby method and adds benefits with options, render_options, etc.
   class Command
     # Creates a command given its name and a library.
     def self.create(name, library)
@@ -22,6 +22,16 @@ module Boson
     attr_accessor *(ATTRIBUTES + [:render_options, :namespace])
     # A hash of attributes which map to instance variables and values. :name
     # and :lib are required keys.
+    #
+    # Attributes that can be configured:
+    # * *:description*: Description that shows up in command listings
+    # * *:alias*: Alternative name for command
+    # * *:options*: Hash of options passed to OptionParser
+    # * *:render_options*: Hash of rendering options passed to OptionParser
+    # * *:args*: Should only be set if not automatically set. This attribute is only
+    #   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.
     def initialize(hash)
       @name = hash[:name] or raise ArgumentError
       @lib = hash[:lib] or raise ArgumentError

data/lib/boson/commands/core.rb

@@ -6,20 +6,20 @@ module Boson::Commands::Core #:nodoc:
     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}},
+      '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},
+        :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} }
       },
       'libraries'=>{ :description=>"List or search libraries",
-        :options=>{:query_fields=>{:default=>['name'], :values=>library_attributes},
+        :options=>{:query_fields=>{:default=>['name'], :values=>library_attributes, :desc=>"Searchable fields"},
           :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}}
+      'load_library'=>{:description=>"Load/reload a library", :options=>{:reload=>:boolean, [:verbose,:V]=>true}}
     }
 
     {:library_file=>File.expand_path(__FILE__), :commands=>commands}
@@ -29,13 +29,13 @@ module Boson::Commands::Core #:nodoc:
     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
+    query_fields.map {|e| commands.select {|f| f.send(e).to_s =~ /#{query}/i } }.flatten.uniq
   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
+    options[:query_fields].map {|e| libraries.select {|f| f.send(e).to_s =~ /#{query}/i } }.flatten.uniq
   end
 
   def load_library(library, options={})

data/lib/boson/commands/web_core.rb

@@ -2,9 +2,12 @@ module Boson::Commands::WebCore #:nodoc:
   def self.config
     descriptions = {
       :install=>"Installs a library by url. Library should then be loaded with load_library.",
-      :browser=>"Opens urls in a browser", :get=>"Gets the body of a url" }
+      :browser=>"Opens urls in a browser on a Mac", :get=>"Gets the body of a url" }
     commands = descriptions.inject({}) {|h,(k,v)| h[k.to_s] = {:description=>v}; h}
-    commands['install'][:options] = {:name=>:string, :force=>:boolean}
+    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}
   end
 
@@ -17,10 +20,20 @@ module Boson::Commands::WebCore #:nodoc:
 
   def install(url, options={})
     options[:name] ||= strip_name_from_url(url)
-    return puts("Please give a library name with this url.") unless options[:name]
+    return puts("Please give a library name for this url.") if options[:name].empty?
     filename = File.join Boson.repo.commands_dir, "#{options[:name]}.rb"
     return puts("Library name #{options[:name]} already exists. Try a different name.") if File.exists?(filename) && !options[:force]
     File.open(filename, 'w') {|f| f.write get(url) }
+
+    if options[:method_wrap] || options[:module_wrap]
+      file_string = File.read(filename)
+      file_string = "def #{options[:name]}\n#{file_string}\nend" if options[:method_wrap]
+      unless (mod_name = Boson::Util.camelize(options[:name]))
+        return puts("Can't wrap install with name #{options[:name]}")
+      end
+      file_string = "module #{mod_name}\n#{file_string}\nend"
+      File.open(filename, 'w') {|f| f.write file_string }
+    end
     puts "Saved to #{filename}."
   end
 
@@ -31,6 +44,6 @@ module Boson::Commands::WebCore #:nodoc:
 
   private
   def strip_name_from_url(url)
-    url[/\/([^\/.]+)(\.[a-z]+)?$/, 1]
+    url[/\/([^\/.]+)(\.[a-z]+)?$/, 1].to_s.gsub('-', '_').gsub(/[^a-zA-Z_]/, '')
   end
 end

data/lib/boson/index.rb

@@ -1,17 +1,11 @@
 require 'digest/md5'
 module Boson
+  # Used in all things indexing i.e. saving state for boson's commandline.
   module Index
     extend self
     attr_reader :libraries, :commands
 
-    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)}
-    end
-
+    # Updates the index.
     def update(options={})
       options[:all] = true if !exists? && !options.key?(:all)
       libraries_to_update = options[:all] ? Runner.all_libraries : changed_libraries
@@ -25,23 +19,43 @@ module Boson
       write
     end
 
-    def exists?
-      File.exists? marshal_file
+    # Reads and initializes index.
+    def read
+      return if @read
+      @libraries, @commands, @lib_hashes = exists? ? Marshal.load(File.read(marshal_file)) : [[], [], {}]
+      delete_stale_libraries_and_commands
+      set_latest_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])
     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)}
+    end
+
+    def exists?
+      File.exists? marshal_file
+    end
+
     def save_marshal_index(marshal_string)
       File.open(marshal_file, 'w') {|f| f.write marshal_string }
     end
 
-    def read
-      return if @read
-      @libraries, @commands, @lib_hashes = exists? ? Marshal.load(File.read(marshal_file)) : [[], [], {}]
-      set_latest_namespaces
-      @read = true
+    def delete_stale_libraries_and_commands
+      cached_libraries = @lib_hashes.keys
+      libs_to_delete = @libraries.select {|e| !cached_libraries.include?(e.name) && e.is_a?(FileLibrary) }
+      names_to_delete = libs_to_delete.map {|e| e.name }
+      libs_to_delete.each {|e| @libraries.delete(e) }
+      @commands.delete_if {|e| names_to_delete.include? e.lib }
     end
 
     # get latest namespaces from config files
@@ -91,5 +105,6 @@ module Boson
         h
       }
     end
+    #:startdoc:
   end
 end

data/lib/boson/inspector.rb

@@ -1,5 +1,5 @@
 module Boson
-  # Scrapes and processes method metadata with the inspectors (MethodInspector, CommentInspector
+  # Scrapes and processes method attributes with the inspectors (MethodInspector, CommentInspector
   # and ArgumentInspector) and hands off the usable data to FileLibrary objects.
   module Inspector
     extend self
@@ -34,7 +34,7 @@ module Boson
       @enabled = false
     end
 
-    # Adds method data scraped for the library's module to the library's commands.
+    # Adds method attributes scraped for the library's module to the library's commands.
     def add_method_data_to_library(library)
       @commands_hash = library.commands_hash
       @library_file = library.library_file

data/lib/boson/inspectors/argument_inspector.rb

@@ -6,7 +6,7 @@ module Boson::ArgumentInspector
   # Returns same argument arrays as scrape_with_eval but argument defaults haven't been evaluated.
   def scrape_with_text(file_string, meth)
     tabspace = "[ \t]"
-    if match = /^#{tabspace}*def#{tabspace}+#{meth}#{tabspace}*($|\(?\s*([^\)]+)\s*\)?\s*$)/.match(file_string)
+    if match = /^#{tabspace}*def#{tabspace}+#{meth}\b#{tabspace}*($|\(?\s*([^\)]+)\s*\)?\s*$)/.match(file_string)
       (match.to_a[2] || '').split(/\s*,\s*/).map {|e| e.split(/\s*=\s*/)}
     end
   end
@@ -20,7 +20,7 @@ module Boson::ArgumentInspector
   #   def meth2(*args) -> [['*args']]
   def scrape_with_eval(meth, klass, object)
     unless %w[initialize].include?(meth.to_s)
-      return if class << object; private_instance_methods(true) end.include?(meth.to_s)
+      return if class << object; private_instance_methods(true).map {|e| e.to_s } end.include?(meth.to_s)
     end
     params, values, arity, num_args = trace_method_args(meth, klass, object)
     return if local_variables == params # nothing new found
@@ -40,9 +40,9 @@ module Boson::ArgumentInspector
         [a << ["*#{x}"], i+1]
       else
         if arity < 0 && i >= arity.abs - 1
-          [a << [x, values[i]], i + 1]
+          [a << [x.to_s, values[i]], i + 1]
         else
-          [a << [x], i+1]
+          [a << [x.to_s], i+1]
         end
       end
     end.first

data/lib/boson/inspectors/comment_inspector.rb

@@ -1,6 +1,6 @@
 module Boson
-  # Scrapes comments right before a method for its metadata. Metadata attributes are the
-  # same as MethodInspector: desc, options, render_options. Attributes must begin with '@' i.e.:
+  # Scrapes comments right before a method for its attributes. Metadata attributes are the
+  # same as MethodInspector : desc, options, render_options. Attributes must begin with '@' i.e.:
   #
   #    # @desc Does foo
   #    # @options :verbose=>true

data/lib/boson/inspectors/method_inspector.rb

@@ -1,9 +1,10 @@
 module Boson
-  # Allows for defining method metadata with new_method_added and the
+  # Gathers method attributes with new_method_added and the
   # following Module methods:
-  # * desc: Defines a description for a method/command
+  # * desc: Defines a description for a method/command.
   # * options: Defines an OptionParser object for a method's options.
-  # * render_options: Defines an OptionParser object for a method's rendering options.
+  # * render_options: Defines an OptionParser object for a method's rendering options. These options
+  #   are passed to View.render when rendering a command.
   #
   # These method calls must come immediately before a method i.e.:
   #
@@ -11,7 +12,7 @@ module Boson
   #     options :verbose=>:boolean
   #     def foo(options={})
   #
-  # This module also allows for defining method metadata as comments. Although the actual
+  # This module also allows for defining method attributes as comments. Although the actual
   # scraping of comments is handled by CommentInspector, MethodInspector gather's the method
   # location it needs with with find_method_locations().
   module MethodInspector
@@ -21,7 +22,7 @@ module Boson
     @mod_store ||= {}
     METHODS = [:desc, :options, :render_options]
 
-    # The method_added used while scraping method metadata.
+    # The method_added used while scraping method attributes.
     def new_method_added(mod, meth)
       return unless mod.name[/^Boson::Commands::/]
       self.current_module = mod
@@ -59,10 +60,11 @@ module Boson
       end
     end
 
+    CALLER_REGEXP = RUBY_VERSION < '1.9' ? /in `load_source'/ : /in `<module:.*>'/
     # Returns an array of the file and line number at which a method starts using
     # a caller array. Necessary information for CommentInspector to function.
     def find_method_locations(stack)
-      if (line = stack.find {|e| e =~ /in `load_source'/ })
+      if (line = stack.find {|e| e =~ CALLER_REGEXP })
         (line =~ /^(.*):(\d+)/) ? [$1, $2.to_i] : nil
       end
     end

data/lib/boson/libraries/file_library.rb

@@ -1,7 +1,64 @@
 module Boson
-  # This library loads a file in the commands subdirectory of a Boson::Repo. This library looks for files
-  # in repositories in the order given by Boson.repos.
-  # TODO: explain file format, modules, inspectors
+  # This library is based on a file of the same name under the commands directory of a repository.
+  # 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.
+  #
+  # Take for example a library brain.rb:
+  #   module Brain
+  #     def take_over(destination)
+  #       puts "Pinky, it's time to take over the #{destination}!"
+  #     end
+  #   end
+  #
+  # Once loaded, this library can be run from the commandline or irb:
+  #  bash> boson take_over world
+  #  irb>> take_over 'world'
+  #
+  # If the library is namespaced, the command would be run as brain.take_over.
+  #
+  # Let's give Brain an option in his conquest:
+  #   module Brain
+  #     options :execute=>:string
+  #     def take_over(destination, options={})
+  #       puts "Pinky, it's time to take over the #{destination}!"
+  #       system(options[:execute]) if options[:execute]
+  #     end
+  #   end
+  #
+  # From the commandline and irb this runs as:
+  #   bash> boson take_over world -e initiate_brainiac
+  #   irb>> take_over 'world -e initiate_brainiac'
+  #
+  # To learn more about the depth of option types available to a command, see OptionParser.
+  #
+  # Since boson aims to make your libraries just standard ruby, we can achieve the above
+  # by placing options in comments above a method:
+  #   module Brain
+  #     # @options :execute=>:string
+  #     # Help Brain live the dream
+  #     def take_over(destination, options={})
+  #       puts "Pinky, it's time to take over the #{destination}!"
+  #       system(options[:execute]) if options[:execute]
+  #     end
+  #   end
+  #
+  # Some points about the above:
+  # * A '@' must prefix options and other method calls that become comments.
+  # * Note the comment above the method. One-line comments right before a method set a command's description.
+  # * See MethodInspector for other command attributes, like options, that can be placed above a method.
+  # * See CommentInspector for the rules about commenting command attributes.
+  #
+  # Once a command has a defined option, a command can also recognize a slew of global options:
+  #   irb>> take_over '-h'
+  #   take_over [destination] [--execute=STRING]
+  #
+  #   # prints much more verbose help
+  #   irb>> take_over '-hv'
+  #
+  # For more about these global options see Scientist.
   class FileLibrary < Library
     #:stopdoc:
     def self.library_file(library, dir)