pry-command-set-registry 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1bc4e47b4fe6de4fd01ea656dc1b5b30f901c2c8
-  data.tar.gz: d117d60905175b6b40a17e7ae02b71fbd7d9d12b
+  metadata.gz: d66c39fac051c68eb25c6b359e765cdb9e1911ed
+  data.tar.gz: becc29a1efe602bcd26bdc0f915263183f5266d2
 SHA512:
-  metadata.gz: 85515d27354c4246fda7a4b148678dd9abf0f4c4a3d91871fb5fd27fd65d31f7ecab11fbd17adea09c662bad36470cfc4a650ad47c182b8e9b55aaaaaf6938c7
-  data.tar.gz: 984954420617368b4fad4f497573ccebdd9862756163754e1728f6f2baa309f4e485554561274885770ba341478b5f6dc1531ca9a644e4692bea1dad4f5764cb
+  metadata.gz: 9f8c0108a095b1d2ed833dbd1489336534f52e1880967cad7f6d711458b3d1da15c09eee34e04172d02605185bf9cdbb967102a82a0fffc97db3fc6f11f6ff9c
+  data.tar.gz: 66ac3d4fa32f2a9eb37129922faaf97a810b7ad555ccfb165dd2151272033624eb0c9931d32329f7f345684cbbe3183bd19b3ce33658aeb4c3ee22d46510be24

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - 2.2.0
+  - jruby-19mode
+  - jruby-head
+  - rbx-19mode
+  - rbx-2

data/Gemfile

@@ -7,8 +7,10 @@ group :doc do
 end
 
 group :test do
+  gem "coveralls", :require => false
   gem "guard"
   gem "guard-minitest"
   gem "minitest", ">= 3.0"
   gem "mocha"
+  gem "simplecov", :require => false
 end

data/README.md

@@ -1,29 +1,207 @@
 # PryCommandSetRegistry
+[![Gem Version](https://badge.fury.io/rb/pry-command-set-registry.svg)](http://badge.fury.io/rb/pry-command-set-registry)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/pry-command-set-registry)
+[![Build Status](https://travis-ci.org/tdg5/pry-command-set-registry.svg)](https://travis-ci.org/tdg5/pry-command-set-registry)
+[![Coverage Status](https://coveralls.io/repos/tdg5/pry-command-set-registry/badge.svg)](https://coveralls.io/r/tdg5/pry-command-set-registry)
+[![Code Climate](https://codeclimate.com/github/tdg5/pry-command-set-registry/badges/gpa.svg)](https://codeclimate.com/github/tdg5/pry-command-set-registry)
+[![Dependency Status](https://gemnasium.com/tdg5/pry-command-set-registry.svg)](https://gemnasium.com/tdg5/pry-command-set-registry)
 
-Plugin for managing registration and loading of command sets in pry.
+Plugin facilitating easy definition and importation of command sets for
+[Pry](https://github.com/pry/pry). Creates a central registry for command sets 
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'pry-command-set-registry'
+```bash
+gem 'pry-command-set-registry'
+```
 
 And then execute:
 
-    $ bundle
+```bash
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install pry-command-set-registry
+```bash
+$ gem install pry-command-set-registry
+```
 
 ## Usage
 
-Require library file:
+`Pry` should handle loading the plugin automatically. If not, you can require the
+plugin like so:
+
+```ruby
+require "pry-command-set-registry"
+```
+
+### Commands and Command Set Definition
+
+Once the plugin has been loaded you can view the commands it adds to `pry` using
+the `help` command in `pry`:
+
+```
+$ pry
+[1] pry(main)> help
+# ... Skipping unrelated commands ...
+
+Command set registry
+  import-set         Import a pry command set
+  list-sets          List registered command sets
+
+[2] pry(main)>
+```
+
+The `import-set` and `list-sets` commands are the primary means of interacting
+with the command set registry in `Pry`.
+
+#### The `list-sets` command
+
+The `list-sets` command displays a list of all registered command sets. Unless
+you define your own command sets or include another library or plugin that
+registers a command set, this list will be empty initially:
+
+```
+[2] pry(main)> list-sets
+Registered Command Sets:
+
+[3] pry(main)>
+```
+
+#### Defining a command set
+
+Defining and registering a command set can be accomplished via the
+`PryCommandSetRegistry` constant. In particular,
+[`PryCommandSetRegistry.define_command_set`](http://www.rubydoc.info/gems/pry-command-set-registry/PryCommandSetRegistry.define_command_set)
+provides a thin wrapper around [`Pry::CommandSet#block_command`](http://www.rubydoc.info/github/pry/pry/Pry/CommandSet:block_command)
+allowing for the definition of new command sets.
+
+Consider the following command set definition complimenting [Pry's poetic
+side](https://github.com/pry/pry/blob/5e8d69e8b38b5df4c520e5faff74533c16f531a0/lib/pry/commands/easter_eggs.rb#L41)
+with something a little more punk rock:
 
 ```ruby
-  require "pry-command-set-registry"
+PryCommandSetRegistry.define_command_set("PunkRock", "Pry, but more punk rock", :group => "PunkRock") do
+  london_calling = <<-LONDON_CALLING
+  --
+  London calling to the faraway towns
+  Now war is declared and battle come down
+
+  London calling to the underworld
+  Come out of the cupboard, you boys and girls
+
+  London calling, now don't look to us
+  Phony Beatlemania has bitten the dust
+
+  London calling, see we ain't got no swing
+  'Cept for the ring of that truncheon thing
+
+  The ice age is coming, the sun is zooming in
+  Meltdown expected, the wheat is growin' thin
+  Engines stop running, but I have no fear
+  'Cause London is drowning, and I, I live by the river
+
+                        -- The Clash
+  LONDON_CALLING
+  command("london-calling", "If you have to ask then you need more help than Pry can provide") do
+    output.puts(london_calling)
+  end
+end
 ```
 
+If we copy and paste the above into `Pry`, we'll have defined and registered our
+first command set! Once a command set has been registered, it will appear when
+the `list-sets` command is invoked:
+
+```
+[4] pry(main)> list-sets
+Registered Command Sets:
+  PunkRock  -  Pry, but more punk rock
+
+[5] pry(main)>
+```
+
+#### The `import-set` command
+
+To import a registered command set into the current `Pry` session, use the
+`import-set` command. The `import-set` command is a [built-in `Pry` command](https://github.com/pry/pry/blob/5e8d69e8b38b5df4c520e5faff74533c16f531a0/lib/pry/commands/import_set.rb),
+but it's worth noting that `PryCommandSetRegistry` overrides the default command
+to include fallback behavior for retrieving command sets from the registry
+[[source]](https://github.com/tdg5/pry-command-set-registry/blob/4f9914969dcfa4a826c9672bd152e12d2e7e37f6/lib/pry_command_set_registry/commands.rb#L7).
+This extended behavior allows command sets to be included in a variety of
+formats. For example, each of the following will all import the `PunkRock`
+command set into the current `Pry` session:
+
+```
+[5] pry(main)> import-set PunkRock
+[6] pry(main)> import-set "PunkRock"
+[7] pry(main)> import-set :PunkRock
+```
+
+Even when a constant is defined with the same name as a command set, a constant
+style name can still be used. This is possible because `PryCommandSetRegistry`
+uses a registry that is separate from Ruby's constants. At lookup time if
+`PryCommandSetRegistry` evaluates the given name as a constant, but that constant
+doesn't look like a command set, it will fallback to checking the registry for a
+command set with the same name. For example, ignoring the fact that we've already
+imported the `PunkRock` command set three times, the following would still work
+as expected:
+
+```
+[8] pry(main)> PunkRock = "Never Mind the Bollocks"
+[9] pry(main)> import-set PunkRock
+```
+
+Now that we've imported the `PunkRock` command set, the commands it provides
+will appear when the `help` command is invoked:
+
+```
+[10] pry(main)> help
+# ... Skipping unrelated commands ...
+PunkRock
+  london-calling     If you have to ask then you need more help than Pry can provide
+
+[11] pry(main)>
+```
+
+Finally, we can invoke the added command by name:
+
+```
+[11] pry(main)> london-calling
+  --
+  London calling to the faraway towns
+  Now war is declared and battle come down
+
+  London calling to the underworld
+  Come out of the cupboard, you boys and girls
+
+  London calling, now don't look to us
+  Phony Beatlemania has bitten the dust
+
+  London calling, see we ain't got no swing
+  'Cept for the ring of that truncheon thing
+
+  The ice age is coming, the sun is zooming in
+  Meltdown expected, the wheat is growin' thin
+  Engines stop running, but I have no fear
+  'Cause London is drowning, and I, I live by the river
+
+                        -- The Clash
+
+[12] pry(main)>
+```
+
+### Pry on, dude!
+
+That's about it for basic usage of `PryCommandSetRegistry`. Make sure to check
+out the [`PryCommandSetRegistry` docs](http://www.rubydoc.info/gems/pry-command-set-registry)
+for more in-depth coverage of the inner workings of `PryCommandSetRegistry`.
+Also make sure to check out the excellent [page on custom commands in the
+`Pry` wiki](https://github.com/pry/pry/wiki/Custom-commands)!
+
 ## Contributing
 
 1. Fork it ( https://github.com/tdg5/pry-command-set-registry/fork )

data/lib/pry_command_set_registry/command_set.rb

@@ -45,6 +45,33 @@ module PryCommandSetRegistry
       apply_group_name_to_commands
     end
 
+    # @overload extend(*modules)
+    #   Adds the instance methods from each module given as a parameter to the
+    #   command set. If both a block and modules are provided an ArgumentError
+    #   will be raised.
+    #   @param [Module] *modules One or more modules to extend the command set
+    #     with.
+    #   @return [PryCommandSetRegistry::CommandSet] Returns the command set
+    #     object.
+    #   @raise [ArgumentError] if called with modules and block or called with
+    #     neither modules nor block.
+    # @overload extend
+    #   Evaluates the block in the context of the command set instance. If both
+    #   a block and arguments are provided an ArgumentError will be raised.
+    #   @yield [] The given block is evaluated on the command set instance.
+    #   @return [PryCommandSetRegistry::CommandSet] Returns the command set
+    #     object.
+    #   @raise [ArgumentError] if called with modules and block or called with
+    #     neither modules nor block.
+    def extend(*modules)
+      if modules.any?
+        return super unless block_given?
+        raise ArgumentError, "Cannot call extend with block and modules!"
+      end
+      instance_eval(&Proc.new)
+      self
+    end
+
     private
 
     # If a group name was provided, adds that group to all commands in the

data/lib/pry_command_set_registry/version.rb

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

data/test/test_helper.rb

@@ -1,3 +1,11 @@
+if ENV["CI"]
+  require "simplecov"
+  require "coveralls"
+  Coveralls.wear!
+  SimpleCov.formatter = Coveralls::SimpleCov::Formatter
+  SimpleCov.root(File.expand_path("../..", __FILE__))
+end
+
 require "minitest/autorun"
 require "mocha/setup"
 require "pry_command_set_registry"

data/test/unit/command_set_test.rb

@@ -40,6 +40,47 @@ class CommandSetTest < PryCommandSetRegistry::TestCase
         assert_equal group, instance.each.first.last.group
       end
     end
+
+    context "#extend" do
+      subject { @subject }
+
+      setup do
+        @name = "Foo"
+        description = "Bar"
+        @subject = Subject.new(@name, description, &default_command_set_proc)
+      end
+
+      should "raise ArgumentError if neither arguments nor block are given" do
+        assert_raises(ArgumentError) { subject.extend }
+      end
+
+      should "raise ArgumentError if arguments and block are given" do
+        block_called = false
+        block = lambda { block_called = true }
+        dummy = Module.new
+        subject.expects(:instance_eval).never
+        assert_raises(ArgumentError) do
+          subject.extend(dummy, &block)
+        end
+        refute_kind_of(dummy, subject)
+        refute(block_called, "Expected block given to extend with arguments not to be called!")
+      end
+
+      should "yield to super if any arguments are given and no block given" do
+        dummy = Module.new
+        subject.expects(:instance_eval).never
+        result = subject.extend(dummy)
+        assert_kind_of(dummy, subject)
+        assert_equal subject, result
+      end
+
+      should "execute the block in the context of the command set if no arguments are given" do
+        receiver_in_block = nil
+        result = subject.extend { receiver_in_block = self }
+        assert_equal subject, receiver_in_block
+        assert_equal subject, result
+      end
+    end
   end
 
   # Proc is called with instance eval, so closure must be used to allow

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pry-command-set-registry
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Danny Guinther
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-05 00:00:00.000000000 Z
+date: 2015-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -60,6 +60,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - Guardfile
 - LICENSE