Class Boson::Library

  1. lib/boson/library.rb
Parent: Object

A library is a group of commands (Command objects) usually grouped together by a module. Libraries are loaded from different sources depending on the library subclass. Default library subclasses are FileLibrary, GemLibrary, RequireLibrary, ModuleLibrary and LocalFileLibrary. See Loader for callbacks a library’s module can have.

Naming a Library Module

Although you can name a library module almost anything, here’s the fine print:

  • A module can have any name if it’s the only module in a library.
  • If there are multiple modules in a file library, the module’s name must be a camelized version of the file’s basename i.e. ~/.boson/commands/ruby_core.rb -> RubyCore.
  • Although modules are evaluated under the Boson::Commands namespace, Boson will warn you about creating modules whose name is the same as a top level class/module. The warning is to encourage users to stay away from error-prone libraries. Once you introduce such a module, all libraries assume the nested module over the top level module and the top level module has to be prefixed with ’::’ everywhere.

Configuration

Libraries and their commands can be configured in different ways in this order:

  • If library is a FileLibrary, commands be configured with a config method attribute (see Inspector).
  • If a library has a module, you can set library + command attributes via the config() callback (see Loader).
  • All libraries can be configured by passing a hash of library attributes under the :libraries key to the main config file ~/.boson/config/boson.yml. For most libraries this may be the only way to configure a library’s commands. An example of a GemLibrary config: 
    :libraries:
  httparty:
   :class_commands:
     delete: HTTParty.delete
   :commands:
     delete:
       :alias: d
       :desc: Http delete a given url

When installing a third-party library, use the config file as a way to override default library and command attributes without modifying the library.

Creating Your Own Library

To create your own subclass you need to define what sources the subclass can handle with handles(). If handles() returns true then the subclass is chosen to load. See Loader to see what instance methods to override for a subclass.

Methods

public class

  1. new

public instance

  1. library_type
  2. namespace
  3. namespace_object

Included modules

  1. Loader

Constants

ATTRIBUTES = [:gems, :dependencies, :commands, :loaded, :module, :name, :namespace, :indexed_namespace]   Public attributes for use outside of Boson.

Attributes

class_commands [R] Private attribute for use within Boson.
lib_file [R] Private attribute for use within Boson.
namespace [W] Optional namespace name for a library. When enabled defaults to a library’s name.
new_commands [R] Private attribute for use within Boson.
new_module [R] Private attribute for use within Boson.
no_alias_creation [R] Private attribute for use within Boson.
repo_dir [R] Private attribute for use within Boson.

Public class methods

new (hash)

Creates a library object with a hash of attributes which must include a :name attribute. Each hash pair maps directly to an instance variable and value. Defaults for attributes are read from config[:libraries][@library_name][@attribute]. When loading libraries, attributes can also be set via a library module’s config() method (see Loader).

Attributes that can be configured:

:dependencies
An array of libraries that this library depends on. A library won’t load unless its dependencies are loaded first.
:commands
A hash or array of commands that belong to this library. A hash configures command attributes for the given commands with command names pointing to their configs. See Command.new for a command’s configurable attributes. If an array, the commands are set for the given library, overidding default command detection. Example: 
:commands=>{'commands'=>{:desc=>'Lists commands', :alias=>'com'}}
:class_commands
A hash of commands to create. A hash key-pair can map command names to any string of ruby code that ends with a method call. Or a key-pair can map a class to an array of its class methods to create commands of the same name. Example: 
:class_commands=>{'spy'=>'Bond.spy', 'create'=>'Alias.manager.create',
 'Boson::Util'=>['detect', 'any_const_get']}
:force
Boolean which forces a library to ignore when a library’s methods are overriding existing ones. Use with caution. Default is false.
:object_methods
Boolean which detects any Object/Kernel methods created when loading a library and automatically adds them to a library’s commands. Default is true.
:namespace
Boolean or string which namespaces a library. When true, the library is automatically namespaced to the library’s name. When a string, the library is namespaced to the string. Default is nil. To control the namespacing of all libraries see Boson::Repo.config.
:no_alias_creation
Boolean which doesn’t create aliases for a library. Useful for libraries that configure command aliases outside of Boson’s control. Default is false.
[show source] 
# File lib/boson/library.rb, line 87
    def initialize(hash)
      repo = set_repo
      @repo_dir = repo.dir
      @name = set_name(hash.delete(:name)) or raise ArgumentError, "Library missing required key :name"
      @loaded = false
      @commands_hash = {}
      @commands = []
      set_config (repo.config[:libraries][@name] || {}).merge(hash), true
      set_command_aliases(repo.config[:command_aliases])
    end

Public instance methods

library_type ()

A concise symbol version of a library type i.e. FileLibrary -> :file.

[show source] 
# File lib/boson/library.rb, line 99
    def library_type
      str = self.class.to_s[/::(\w+)Library$/, 1] || 'library'
      str.downcase.to_sym
    end
namespace (orig=@namespace)
[show source] 
# File lib/boson/library.rb, line 104
    def namespace(orig=@namespace)
      @namespace = [String,FalseClass].include?(orig.class) ? orig : begin
        if (@namespace == true || (Boson.repo.config[:auto_namespace] && !@index))
          @namespace = clean_name
        else
          @namespace = false
        end
      end
    end
namespace_object ()

The object a library uses for executing its commands.

[show source] 
# File lib/boson/library.rb, line 115
    def namespace_object
      @namespace_object ||= namespace ? Boson.invoke(namespace) : Boson.main_object
    end