bosonson 0.304.1

data/lib/boson/options.rb

@@ -0,0 +1,146 @@
+module Boson
+  # This module contains the methods used to define the default option types.
+  #
+  # === Creating Your Own Option Type
+  # Defining your own option type simply requires one method (create_@type) to parse the option value and create
+  # the desired object. To create an option type :date, you could create the following create_date method:
+  #   # Drop this in ~/.boson/commands/date_option.rb
+  #   module Boson::Options::Date
+  #     def create_date(value)
+  #       # value should be mm/dd
+  #       Date.parse(value + "/#{Date.today.year}")
+  #     end
+  #   end
+  #   Boson::OptionParser.send :include, Boson::Options::Date
+  #
+  # Modify your config to load this new library by default:
+  #   :defaults:
+  #   - date_option
+  #
+  # In a FileLibrary, we could then use this new option:
+  #   module Calendar
+  #     #@options :day=>:date
+  #     def appointments(options={})
+  #       # ...
+  #     end
+  #   end
+  #   # >> appointments '-d 10/10'   -> {:day=>#<Date: 4910229/2,0,2299161> }
+  # As you can see, a date object is created from the :date option's value and passed into appointments().
+  #
+  # Some additional tips on the create_* method:
+  # * The argument passed to the method is the option value from the user.
+  # * To access the current option name use @current_option.
+  # * To access the hash of attributes the current option has use OptionParser.current_attributes. See
+  #   OptionParser.new for more about option attributes.
+  #
+  # There are two optional methods per option type: validate_@type and usage_for_@type i.e. validate_date and usage_for_date.
+  # Like create_@type, validate_@type takes the option's value. If the value validation fails, raise an
+  # OptionParser::Error with a proper message. All user-defined option types automatically validate for an option value's existence.
+  # The usage_for_* method takes an option's name (i.e. --day) and returns a usage string to be wrapped in '[ ]'. If no usage is defined
+  # the default would look like '[--day=:date]'. Consider using the OptionParser.default_usage helper method for your usage.
+  module Options
+    #:stopdoc:
+    # Parse/create methods
+    def create_string(value)
+      if (values = current_attributes[:values]) && (values = values.sort_by {|e| e.to_s})
+        value = auto_alias_value(values, value)
+        validate_enum_values(values, value)
+      end
+      value
+    end
+
+    def create_boolean(value)
+      if (!@opt_types.key?(dasherize(@current_option)) && @current_option =~ /^no-(\w+)$/)
+        opt = (opt = original_no_opt($1)) ? undasherize(opt) : $1
+        (@current_option.replace(opt) && false)
+      else
+        true
+      end
+    end
+
+    def create_numeric(value)
+      value.index('.') ? value.to_f : value.to_i
+    end
+
+    def create_array(value)
+      splitter = current_attributes[:split] || ','
+      array = value.split(splitter)
+      if (values = current_attributes[:values]) && (values = values.sort_by {|e| e.to_s })
+        if current_attributes[:regexp]
+          array = array.map {|e|
+            (new_values = values.grep(/#{e}/)).empty? ? e : new_values
+          }.compact.flatten.uniq
+        else
+          array.each {|e| array.delete(e) && array += values if e == '*'}
+          array.map! {|e| auto_alias_value(values, e) }
+        end
+        validate_enum_values(values, array)
+      end
+      array
+    end
+
+    def create_hash(value)
+      (keys = current_attributes[:keys]) && keys = keys.sort_by {|e| e.to_s }
+      hash = parse_hash(value, keys)
+      if keys
+        hash = hash.inject({}) {|h,(k,v)|
+          h[auto_alias_value(keys, k)] = v; h
+        }
+        validate_enum_values(keys, hash.keys)
+      end
+      hash
+    end
+
+    def parse_hash(value, keys)
+      splitter = current_attributes[:split] || ','
+      if !value.include?(':') && current_attributes[:default_keys]
+        value = current_attributes[:default_keys].to_s + ":#{value}"
+      end
+
+      # Creates array pairs, grouping array of keys with a value
+      aoa = Hash[*value.split(/(?::)([^#{Regexp.quote(splitter)}]+)#{Regexp.quote(splitter)}?/)].to_a
+      aoa.each_with_index {|(k,v),i| aoa[i][0] = keys.join(splitter) if k == '*' } if keys
+      aoa.inject({}) {|t,(k,v)| k.split(splitter).each {|e| t[e] = v }; t }
+    end
+
+    # Validation methods
+    def validate_string(value)
+      raise OptionParser::Error, "cannot pass '#{value}' as an argument to option '#{@current_option}'" if valid?(value)
+    end
+
+    def validate_numeric(value)
+      unless value =~ OptionParser::NUMERIC and $& == value
+        raise OptionParser::Error, "expected numeric value for option '#{@current_option}'; got #{value.inspect}"
+      end
+    end
+
+    def validate_hash(value)
+      if !value.include?(':') && !current_attributes[:default_keys]
+        raise(OptionParser::Error, "invalid key:value pair for option '#{@current_option}'")
+      end
+    end
+
+    # Usage methods
+    def usage_for_boolean(opt)
+      opt
+    end
+
+    def usage_for_string(opt)
+      default_usage(opt, undasherize(opt).upcase)
+    end
+
+    def usage_for_numeric(opt)
+      default_usage opt, "N"
+    end
+
+    def usage_for_array(opt)
+      default_usage opt, "A,B,C"
+    end
+
+    def usage_for_hash(opt)
+      default_usage opt, "A:B,C:D"
+    end
+    #:startdoc:
+  end
+end
+Boson::OptionParser.send :include, Boson::Options

data/lib/boson/pipe.rb

@@ -0,0 +1,147 @@
+module Boson
+  # This module passes an original command's return value through methods/commands specified as pipe options. Pipe options
+  # are processed in this order:
+  # * A :query option searches an array of objects or hashes using Pipes.query_pipe.
+  # * A :sort option sorts an array of objects or hashes using Pipes.sort_pipe.
+  # * A :reverse_sort pipe option reverses an array.
+  # * A :pipes option takes an array of commands that modify the return value using Pipes.pipes_pipe.
+  # * All user-defined pipe options (:pipe_options key in Repo.config) are processed in random order.
+  #
+  # Some points:
+  # * User-defined pipes call a command (the option's name by default). It's the user's responsibility to have this
+  #   command loaded when used. The easiest way to do this is by adding the pipe command's library to :defaults in main config.
+  # * By default, pipe commands do not modify the value their given. This means you can activate multiple pipes using
+  #   a method's original return value.
+  # * A pipe command expects a command's return value as its first argument. If the pipe option takes an argument, it's passed
+  #   on as a second argument.
+  # * When piping occurs in relation to rendering depends on the Hirb view. With the default Hirb view, piping occurs
+  #   occurs in the middle of the rendering, after Hirb has converted the return value into an array of hashes.
+  #   If using a custom Hirb view, piping occurs before rendering.
+  # * What the pipe command should expect as a return value depends on the type of command. If it's a command rendered with hirb's
+  #   tables, the return value is a an array of hashes. For everything else, it's the method's original return value.
+  #
+  # === User Pipes
+  # User pipes have the following attributes which alter their behavior:
+  # [*:pipe*] Pipe command the pipe executes when called. Default is the pipe's name.
+  # [*:env*] Boolean which enables passing an additional hash to the pipe command. This hash contains information from the first
+  #          command's input with the following keys: :args (command's arguments), :options (command's options),
+  #          :global_options (command's global options) and :config (a command's configuration hash). Default is false.
+  # [*:filter*] Boolean which has the pipe command modify the original command's output with the value it returns. Default is false.
+  # [*:no_render*] Boolean to turn off auto-rendering of the original command's final output. Only applicable to :filter enabled
+  #                pipes. Default is false.
+  # [*:solo*] Boolean to indicate this pipe can't run with other user pipes or pipes from :pipes option.
+  #           If a user calls multiple solo pipes, only the first one detected is called.
+  #
+  # === User Pipes Example
+  # Let's say you want to have two commands, browser and copy, you want to make available as pipe options:
+  #    # Opens url in browser. This command already ships with Boson.
+  #    def browser(url)
+  #      system('open', url)
+  #    end
+  #
+  #    # Copy to clipboard
+  #    def copy(str)
+  #      IO.popen('pbcopy', 'w+') {|clipboard| clipboard.write(str)}
+  #    end
+  #
+  # To configure them, drop the following config in ~/.boson/config/boson.yml:
+  #   :pipe_options:
+  #     :browser:
+  #       :type: :boolean
+  #       :desc: Open in browser
+  #     :copy:
+  #       :type: :boolean
+  #       :desc: Copy to clipboard
+  #
+  # Now for any command that returns a url string, these pipe options can be turned on to execute the url.
+  #
+  # Some examples of these options using commands from {my libraries}[http://github.com/cldwalker/irbfiles]:
+  #    # Creates a gist and then opens url in browser and copies it.
+  #    $ cat some_file | boson gist -bC        # or cat some_file | boson gist --browser --copy
+  #
+  #    # Generates rdoc in current directory and then opens it in browser
+  #    irb>> rdoc '-b'    # or rdoc '--browser'
+  module Pipe
+    extend self
+
+    # Process pipes for Scientist
+    def scientist_process(object, global_opt, env={})
+      @env = env
+      [:query, :sort, :reverse_sort].each {|e| global_opt.delete(e) } unless object.is_a?(Array)
+      process_pipes(object, global_opt)
+    end
+
+    # Main method which processes all pipe commands, both default and user-defined ones.
+    def process_pipes(obj, options)
+      internal_pipes(options).each {|pipe|
+        obj = Pipes.send("#{pipe}_pipe", obj, options[pipe]) if options[pipe]
+      }
+      process_user_pipes(obj, options)
+    end
+
+    # A hash that defines user pipes in the same way as the :pipe_options key in Repo.config.
+    # This method should be called when a pipe's library is loading.
+    def add_pipes(hash)
+      pipe_options.merge! setup_pipes(hash)
+    end
+
+    #:stopdoc:
+    def internal_pipes(global_opt)
+      internals = [:query, :sort, :reverse_sort, :pipes]
+      internals.delete(:pipes) if pipes_to_process(global_opt).any? {|e| pipe(e)[:solo] }
+      internals
+    end
+
+    def pipe_options
+      @pipe_options ||= setup_pipes(Boson.repo.config[:pipe_options] || {})
+    end
+
+    def setup_pipes(hash)
+      hash.each {|k,v| v[:pipe] ||= k }
+    end
+
+    def pipe(key)
+      pipe_options[key] || {}
+    end
+
+    # global_opt can come from Hirb callback or Scientist
+    def process_user_pipes(result, global_opt)
+      pipes_to_process(global_opt).each {|e|
+        args = [pipe(e)[:pipe], result]
+        args << global_opt[e] unless pipe(e)[:type] == :boolean
+        args << get_env(e, global_opt) if pipe(e)[:env]
+        pipe_result = Boson.invoke(*args)
+        result = pipe_result if pipe(e)[:filter]
+      }
+      result
+    end
+
+    def get_env(key, global_opt)
+      { :global_options=>global_opt.merge(:delete_callbacks=>[:z_boson_pipes]),
+        :config=>(@env[:config].dup[key] || {}),
+        :args=>@env[:args],
+        :options=>@env[:options] || {}
+      }
+    end
+
+    def any_no_render_pipes?(global_opt)
+      !(pipes = pipes_to_process(global_opt)).empty? &&
+        pipes.any? {|e| pipe(e)[:no_render] }
+    end
+
+    def pipes_to_process(global_opt)
+      pipes = (global_opt.keys & pipe_options.keys)
+      (solo_pipe = pipes.find {|e| pipe(e)[:solo] }) ? [solo_pipe] : pipes
+    end
+    #:startdoc:
+
+    # Callbacks used by Hirb::Helpers::Table to search,sort and run custom pipe commands on arrays of hashes.
+    module TableCallbacks
+      # Processes boson's pipes
+      def z_boson_pipes_callback(obj, options)
+        Pipe.process_pipes(obj, options)
+      end
+    end
+  end
+end
+Hirb::Helpers::Table.send :include, Boson::Pipe::TableCallbacks

data/lib/boson/pipes.rb

@@ -0,0 +1,75 @@
+module Boson
+  # === Default Pipes: Search and Sort
+  # The default pipe options, :query, :sort and :reverse_sort, are quite useful for searching and sorting arrays:
+  # Some examples using default commands:
+  #   # Searches commands in the full_name field for 'lib' and sorts results by that field.
+  #   $ boson commands -q=f:lib -s=f    # or commands --query=full_name:lib --sort=full_name
+  #
+  #   # Multiple fields can be searched if separated by a ','. This searches the full_name and desc fields.
+  #   $ boson commands -q=f,d:web   # or commands --query=full_name,desc:web
+  #
+  #   # All fields can be queried using a '*'.
+  #   # Searches all library fields and then reverse sorts on name field
+  #   $ boson libraries -q=*:core -s=n -R  # or libraries --query=*:core --sort=name --reverse_sort
+  #
+  #   # Multiple searches can be joined together by ','
+  #   # Searches for libraries that have the name matching core or a library_type matching gem
+  #   $ boson libraries -q=n:core,l:gem   # or libraries --query=name:core,library_type:gem
+  #
+  # In these examples, we queried commands and examples with an explicit --query. However, -q or --query isn't necessary
+  # for these commands because they already default to it when not present. This behavior comes from the default_option
+  # attribute a command can have.
+  module Pipes
+    extend self
+
+    # Case-insensitive search an array of objects or hashes for the :query option.
+    # This option is a hash of fields mapped to their search terms. Searches are OR-ed.
+    # When searching hashes, numerical string keys in query_hash are converted to actual numbers to
+    # interface with Hirb.
+    def query_pipe(object, query_hash)
+      if object[0].is_a?(Hash)
+        query_hash.map {|field,query|
+          field = field.to_i if field.to_s[/^\d+$/]
+          object.select {|e| e[field].to_s =~ /#{query}/i }
+        }.flatten.uniq
+      else
+        query_hash.map {|field,query| object.select {|e| e.send(field).to_s =~ /#{query}/i } }.flatten.uniq
+      end
+    rescue NoMethodError
+      $stderr.puts "Query failed with nonexistant method '#{$!.message[/`(.*)'/,1]}'"
+    end
+
+    # Sorts an array of objects or hashes using a sort field. Sort is reversed with reverse_sort set to true.
+    def sort_pipe(object, sort)
+      sort_lambda = lambda {}
+      if object[0].is_a?(Hash)
+        if sort.to_s[/^\d+$/]
+          sort = sort.to_i
+        elsif object[0].keys.all? {|e| e.is_a?(Symbol) }
+          sort = sort.to_sym
+        end
+        sort_lambda = untouched_sort?(object.map {|e| e[sort] }) ? lambda {|e| e[sort] } : lambda {|e| e[sort].to_s }
+      else
+        sort_lambda = untouched_sort?(object.map {|e| e.send(sort) }) ? lambda {|e| e.send(sort) || ''} :
+          lambda {|e| e.send(sort).to_s }
+      end
+      object.sort_by &sort_lambda
+    rescue NoMethodError, ArgumentError
+      $stderr.puts "Sort failed with nonexistant method '#{sort}'"
+    end
+
+    def untouched_sort?(values) #:nodoc:
+      values.all? {|e| e.respond_to?(:<=>) } && values.map {|e| e.class }.uniq.size == 1
+    end
+
+    # Reverse an object
+    def reverse_sort_pipe(object, extra=nil)
+      object.reverse
+    end
+
+    # Pipes output of multiple commands recursively, given initial object
+    def pipes_pipe(obj, arr)
+      arr.inject(obj) {|acc,e| Boson.full_invoke(e, [acc]) }
+    end
+  end
+end

data/lib/boson/repo.rb

@@ -0,0 +1,107 @@
+%w{yaml fileutils}.each {|e| require e }
+module Boson
+  # A class for repositories. A repository has a root directory with required subdirectories config/ and
+  # commands/ and optional subdirectory lib/. Each repository has a primary config file at config/boson.yml.
+  class Repo
+    def self.commands_dir(dir) #:nodoc:
+      File.join(dir, 'commands')
+    end
+
+    attr_accessor :dir, :config
+    # Creates a repository given a root directory.
+    def initialize(dir)
+      @dir = dir
+    end
+
+    # Points to the config/ subdirectory and is automatically created when called. Used for config files.
+    def config_dir
+      @config_dir ||= FileUtils.mkdir_p(config_dir_path) && config_dir_path
+    end
+
+    def config_dir_path
+      "#{dir}/config"
+    end
+
+    # Path name of main config file. If passed true, parent directory of file is created.
+    def config_file(create_dir=false)
+      File.join((create_dir ? config_dir : config_dir_path), 'boson.yml')
+    end
+
+    # Points to the commands/ subdirectory and is automatically created when called. Used for command libraries.
+    def commands_dir
+      @commands_dir ||= (cdir = self.class.commands_dir(@dir)) && FileUtils.mkdir_p(cdir) && cdir
+    end
+
+    # A hash read from the YAML config file at config/boson.yml.
+    # {See here}[http://github.com/cldwalker/irbfiles/blob/master/boson/config/boson.yml] for an example config file.
+    # Top level config keys, library attributes and config attributes need to be symbols.
+    # ==== Config keys for all repositories:
+    # [:libraries] Hash of libraries mapping their name to attribute hashes. See Library.new for configurable attributes.
+    #               Example:
+    #               :libraries=>{'completion'=>{:namespace=>true}}
+    # [:command_aliases] Hash of commands names and their aliases. Since this is global it will be read by _all_ libraries.
+    #                    This is useful for quickly creating aliases without having to worry about placing them under
+    #                    the correct library config. For non-global aliasing, aliases should be placed under the :command_aliases
+    #                    key of a library entry in :libraries.
+    #                     Example:
+    #                      :command_aliases=>{'libraries'=>'lib', 'commands'=>'com'}
+    # [:defaults] Array of libraries to load at start up for commandline and irb. This is useful for extending boson i.e. adding your
+    #             own option types since these are loaded before any other libraries. Default is no libraries.
+    # [:console_defaults] Array of libraries to load at start up when used in irb. Default is to load all library files and libraries
+    #                     defined in the config.
+    # [:bin_defaults] Array of libraries to load at start up when used from the commandline. Default is no libraries.
+    # [:add_load_path] Boolean specifying whether to add a load path pointing to the lib subdirectory/. This is useful in sharing
+    #                  classes between libraries without resorting to packaging them as gems. Defaults to false if the lib
+    #                  subdirectory doesn't exist in the boson directory.
+    #
+    # ==== Config keys specific to the main repo config ~/.boson/config/boson.yml
+    # [:pipe_options] Hash of options available to all option commands for piping (see Pipe). A pipe option has the
+    #                 {normal option attributes}[link:classes/Boson/OptionParser.html#M000081] and these:
+    #                 * :pipe: Specifies the command to call when piping. Defaults to the pipe's option name.
+    #                 * :filter: Boolean which indicates that the pipe command will modify its input with what it returns.
+    #                   Default is false.
+    # [:render_options] Hash of render options available to all option commands to be passed to a Hirb view (see View). Since
+    #                   this merges with default render options, it's possible to override default render options.
+    # [:error_method_conflicts] Boolean specifying library loading behavior when its methods conflicts with existing methods in
+    #                           the global namespace. When set to false, Boson automatically puts the library in its own namespace.
+    #                           When set to true, the library fails to load explicitly. Default is false.
+    # [:console] Console to load when using --console from commandline. Default is irb.
+    # [:auto_namespace] Boolean which automatically namespaces all user-defined libraries. Be aware this can break libraries which
+    #                   depend on commands from other libraries. Default is false.
+    # [:ignore_directories] Array of directories to ignore when detecting local repositories for Boson.local_repo.
+    # [:no_auto_render] When set, turns off commandline auto-rendering of a command's output. Default is false.
+    # [:option_underscore_search] When set, OptionParser option values (with :values or :keys) are auto aliased with underscore searching.
+    #                             Default is true. See Util.underscore_search.
+    def config(reload=false)
+      if reload || @config.nil?
+        begin
+          @config = {:libraries=>{}, :command_aliases=>{}, :console_defaults=>[], :option_underscore_search=>true}
+          @config.merge!(YAML::load_file(config_file(true))) if File.exists?(config_file)
+        rescue ArgumentError
+          message = $!.message !~ /syntax error on line (\d+)/ ? "Error"+$!.message :
+            "Error: Syntax error in line #{$1} of config file '#{config_file}'"
+          Kernel.abort message
+        end
+      end
+      @config
+    end
+
+    # Updates main config file by passing config into a block to be modified and then saved
+    def update_config
+      yield(config)
+      write_config_file
+    end
+
+    def write_config_file #:nodoc:
+      File.open(config_file, 'w') {|f| f.write config.to_yaml }
+    end
+
+    def detected_libraries #:nodoc:
+      Dir[File.join(commands_dir, '**/*.rb')].map {|e| e.gsub(/^#{commands_dir}\/|\.rb$/, '') }
+    end
+
+    def all_libraries #:nodoc:
+      (detected_libraries + config[:libraries].keys).uniq
+    end
+  end
+end