pry-command-set-registry 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 05d4205804afc01b492f5cb8eb27d6dd04cfdc92
-  data.tar.gz: 2ca8db0ba026143442b230cfb204021ed8023763
+  metadata.gz: f0c78344f62614780aa6a856af8e29daadb08666
+  data.tar.gz: a42f4b777cfc4af3589ac913f9a983487d735370
 SHA512:
-  metadata.gz: d3402499952d253cf878d1c3d6dbc51bab67264b3f6858e4c5e224a9d34b4e3861407a5c082429b3402be15fa98a66c002f90588d33566055d68f80051111153
-  data.tar.gz: d3cffdcf66b28b058032b68dbe3120bc0a145036e711c751ec73e9de4225356123ae9e85566960c0f66f447bc6e284b3cdc909f233d9c5dc923c3bc4b7843be5
+  metadata.gz: 492c4cc1dc6f77b749bd2d3ee30735bb24e5a76da6043209b34fd4c6aa6bcf6a398dbec721d5593e9a317b32024be51b2f9d4f5c0545fd89035310673bd61330
+  data.tar.gz: d76e29736b3c448081dff3e908d8493990f0ef2c7167a2b0b914c88fff1e947aec119bf32c07e0ff59f3ae361c4e86d7572fe6358ccc2a99ab0e814d945b6234

data/Gemfile

@@ -2,6 +2,10 @@ source "https://rubygems.org"
 
 gemspec
 
+group :doc do
+  gem "yard"
+end
+
 group :test do
   gem "guard"
   gem "guard-minitest"

data/lib/pry_command_set_registry.rb

@@ -4,10 +4,58 @@ require "pry_command_set_registry/registry"
 require "pry_command_set_registry/command_set"
 require "pry_command_set_registry/commands"
 
+# The namespace and primary access point for addressing the
+# PryCommandSetRegistry plugin. Home to the Registry singleton, the primary
+# store of registered command sets.
 module PryCommandSetRegistry
   class << self
     extend Forwardable
+    # The registry singleton that stores all defined command sets.
+    # @return [PryCommandSetRegistry::Registry]
     attr_accessor :registry
+
+    # @!method command_set(name)
+    #   Attempts to look up a registered command set with the given name. If the
+    #   name starts with a colon, the colon is removed prior to lookup.
+    #   @param [String,Symbol] name The name of a registered command set to
+    #     attempt to retrieve.
+    #   @return [PryCommandSetRegistry::CommandSet] if a command set with the
+    #     given name was found.
+    #   @return [nil] if no command set with the given name was found.
+    #   @see PryCommandSetRegistry::Registry#command_set
+    # @!method command_sets
+    #   The Hash mapping of all registered command sets.
+    #   @return [Hash{String => PryCommandSetRegistry::CommandSet}]
+    #   @see PryCommandSetRegistry::Registry#command_sets
+    # @!method define_command_set(name, description, options = {}, &block)
+    #   Helper method for defining a command set and registering it immediately.
+    #   All arguments are passed directly to
+    #   {PryCommandSetRegistry::CommandSet#initialize CommandSet#initialize} to
+    #   instantiate a new command set.
+    #
+    #   @param [String,Symbol] name The name that should be given to the command
+    #     set. The provided name will be displayed by the `list-sets` command and
+    #     is used to identify the command set when calling the `import-set`
+    #     command.
+    #   @param [String] description A description of the command set. The provided
+    #     description will be displayed by the `list-sets` command.
+    #   @param [Hash{Symbol=>String}] options Optional arguments.
+    #   @option options [String] group A group name to apply to all commands in
+    #     the command set. This group will be displayed in commands like `help`,
+    #     however depending on the version of pry it may be sentence cased when
+    #     displayed. When no group is provided, Pry will use `(other)` by default.
+    #   @yield The provided block is evaluated by the command set instance and is
+    #     used to define commands and configure the command set in other ways.
+    #   @example Create a new CommandSet with a `hello-world` command
+    #     PryCommandSetRegistry.define_command_set("Examples", "Example Commands", :group => "Examples") do
+    #       command("hello-world", "Greets the world") do
+    #         _pry_.outputter.puts("Hello world!")
+    #       end
+    #     end
+    #   @raise [ArgumentError] if no block is given.
+    #   @return [PryCommandSetRegistry::CommandSet] The command set instance created.
+    #   @see PryCommandSetRegistry::Registry#define_command_set
+    #   @see PryCommandSetRegistry::CommandSet#initialize
     def_delegators :registry, :command_set, :command_sets, :define_command_set
   end
   self.registry ||= Registry.new

data/lib/pry_command_set_registry/command_set.rb

@@ -1,19 +1,61 @@
 module PryCommandSetRegistry
+  # A set of commands that can me imported into a Pry session.
   class CommandSet < Pry::CommandSet
-    attr_reader :commands, :description, :name
+    # The default group name that Pry gives to commands without a group.
+    DEFAULT_GROUP_NAME = "(other)".freeze
 
-    def initialize(name, description, &block)
-      raise "Block required!" unless block_given?
+    # The description of the command set provided at creation.
+    attr_reader :description
+
+    # The group name given to the command set at creation.
+    attr_reader :group
+
+    # The name of the command set provided at creation.
+    attr_reader :name
+
+    # Creates a new command set.
+    #
+    # @param [String,Symbol] name The name that should be given to the command
+    #   set. The provided name will be displayed by the `list-sets` command and
+    #   is used to identify the command set when calling the `import-set`
+    #   command.
+    # @param [String] description A description of the command set. The provided
+    #   description will be displayed by the `list-sets` command.
+    # @param [Hash{Symbol=>String}] options Optional arguments.
+    # @option options [String] group A group name to apply to all commands in
+    #   the command set. This group will be displayed in commands like `help`,
+    #   however depending on the version of pry it may be sentence cased when
+    #   displayed. When no group is provided, Pry will use `(other)` by default.
+    # @yield The provided block is evaluated by the command set instance and is
+    #   used to define commands and configure the command set in other ways.
+    # @example Create a new CommandSet with a `hello-world` command
+    #   CommandSet.new("Examples", "Example Commands", :group => "Examples") do
+    #     command("hello-world", "Greets the world") do
+    #       _pry_.outputter.puts("Hello world!")
+    #     end
+    #   end
+    # @raise [ArgumentError] if no block is given.
+    # @return [PryCommandSetRegistry::CommandSet] The instance created.
+    def initialize(name, description, options = {}, &block)
+      raise ArgumentError, "Block required!" unless block_given?
       super(&block)
       @description = description
       @name = name.to_s
+      @group = options[:group] || DEFAULT_GROUP_NAME
       apply_group_name_to_commands
     end
 
     private
 
+    # If a group name was provided, adds that group to all commands in the
+    # command set.
+    #
+    # @return [true] if the group name was added to all commands.
+    # @return [false] if group no group was provided at instantiation.
     def apply_group_name_to_commands
-      commands.values.each { |command| command.group(name) }
+      return false if group == DEFAULT_GROUP_NAME
+      each { |command_name, command| command.group(group) }
+      true
     end
   end
 end

data/lib/pry_command_set_registry/commands.rb

@@ -1,6 +1,9 @@
 module PryCommandSetRegistry
   desc = "Commands for interacting with the Pry command set registry"
-  Commands = CommandSet.new("PryCommandSetRegistry", desc) do
+
+  # Default commands for interacting with PryCommandSetRegistry imported into
+  # Pry.
+  Commands = CommandSet.new("PryCommandSetRegistry", desc, :group => "Command Set Registry") do
     command("import-set", "Import a Pry command set") do |command_set_name|
       raise Pry::CommandError, "Provide a command set name" if command_set_name.nil?
 

data/lib/pry_command_set_registry/registry.rb

@@ -1,19 +1,60 @@
 module PryCommandSetRegistry
+  # A registry of command sets and descriptions of those command sets.
   class Registry
+    # The Hash mapping of all registered command sets.
+    # @return [Hash{String => PryCommandSetRegistry::CommandSet}]
     attr_reader :command_sets
 
+    # Creates a new command set registry.
+    # @return [PryCommandSetRegistry::Registry] The registry instance.
     def initialize
       @command_sets = {}
     end
 
+    # Attempts to look up a registered command set with the given name. If the
+    # name starts with a colon, the colon is removed prior to lookup.
+    #
+    # @param [String,Symbol] name The name of a registered command set to
+    #   attempt to retrieve.
+    # @return [PryCommandSetRegistry::CommandSet] if a command set with the
+    #   given name was found.
+    # @return [nil] if no command set with the given name was found.
     def command_set(name)
       sanitized_name = name.to_s.sub(/^:/, "")
       command_sets[sanitized_name]
     end
 
-    def define_command_set(name, description, &block)
-      command_set = CommandSet.new(name, description, &block)
+    # Helper method for defining a command set and registering it immediately.
+    # All arguments are passed directly to
+    # {PryCommandSetRegistry::CommandSet#initialize CommandSet#initialize} to
+    # instantiate a new command set.
+    #
+    # @param [String,Symbol] name The name that should be given to the command
+    #   set. The provided name will be displayed by the `list-sets` command and
+    #   is used to identify the command set when calling the `import-set`
+    #   command.
+    # @param [String] description A description of the command set. The provided
+    #   description will be displayed by the `list-sets` command.
+    # @param [Hash{Symbol=>String}] options Optional arguments.
+    # @option options [String] group A group name to apply to all commands in
+    #   the command set. This group will be displayed in commands like `help`,
+    #   however depending on the version of pry it may be sentence cased when
+    #   displayed. When no group is provided, Pry will use `(other)` by default.
+    # @yield The provided block is evaluated by the command set instance and is
+    #   used to define commands and configure the command set in other ways.
+    # @example Create a new CommandSet with a `hello-world` command
+    #   Registry.define_command_set("Examples", "Example Commands", :group => "Examples") do
+    #     command("hello-world", "Greets the world") do
+    #       _pry_.outputter.puts("Hello world!")
+    #     end
+    #   end
+    # @raise [ArgumentError] if no block is given.
+    # @return [PryCommandSetRegistry::CommandSet] The command set instance created.
+    # @see PryCommandSetRegistry::CommandSet#initialize
+    def define_command_set(name, description, options = {}, &block)
+      command_set = CommandSet.new(name, description, options, &block)
       command_sets[command_set.name] = command_set
+      command_set
     end
   end
 end

data/lib/pry_command_set_registry/version.rb

@@ -1,3 +1,4 @@
 module PryCommandSetRegistry
-  VERSION = "0.0.1".freeze
+  # The version of the PryCommandSetRegistry gem.
+  VERSION = "0.1.0".freeze
 end

data/test/unit/command_set_test.rb

@@ -11,6 +11,10 @@ class CommandSetTest < PryCommandSetRegistry::TestCase
         @command_set_proc = default_command_set_proc
       end
 
+      should "raise ArgumentError if no block is given" do
+        assert_raises(ArgumentError) { Subject.new(@name, @description) }
+      end
+
       should "create a new instance from the given arguments" do
         instance = Subject.new(@name, @description, &@command_set_proc)
 
@@ -25,9 +29,15 @@ class CommandSetTest < PryCommandSetRegistry::TestCase
         assert_equal true, @command_set_proc_obj[:command_called]
       end
 
-      should "correctly set group names" do
+      should "should not set group names if no group given" do
         instance = Subject.new(@name, @description, &@command_set_proc)
-        assert_equal @name, instance.commands.values.first.group
+        assert_equal "(other)", instance.each.first.last.group
+      end
+
+      should "correctly set group names if group given" do
+        group = "Test Group"
+        instance = Subject.new(@name, @description, :group => group, &@command_set_proc)
+        assert_equal group, instance.each.first.last.group
       end
     end
   end

data/test/unit/registry_test.rb

@@ -16,11 +16,14 @@ class RegistryTest < PryCommandSetRegistry::TestCase
       should "create a new CommandSet with the given args" do
         name = "foo"
         description = "bar"
+        group = "Test"
+        opts = { :group => group }
         called = false
         command_set_proc = proc { called = true }
-        group = subject.define_command_set(name, description, &command_set_proc)
-        assert_equal name, group.name
-        assert_equal description, group.description
+        command_set = subject.define_command_set(name, description, opts, &command_set_proc)
+        assert_equal name, command_set.name
+        assert_equal description, command_set.description
+        assert_equal group, command_set.group
         assert_equal true, called, "CommandSet proc was not called!"
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pry-command-set-registry
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Danny Guinther
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-04 00:00:00.000000000 Z
+date: 2015-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler