cinch-commands 0.1.0

data/.document

@@ -0,0 +1,3 @@
+- 
+ChangeLog.*
+LICENSE.txt

data/.gitignore

@@ -0,0 +1,2 @@
+doc/
+pkg/

data/.rspec

@@ -0,0 +1 @@
+--colour --format documentation

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "cinch-commands Documentation" --protected

data/ChangeLog.md

@@ -0,0 +1,9 @@
+### 0.1.0 / 2013-06-02
+
+* Initial release:
+  * Argument types.
+  * `!help` command with detailed output:
+    * Usages
+    * Summaries
+    * Descriptions
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2013 Hal Brodigan
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,59 @@
+# cinch-commands
+
+* [Source](https://github.com/postmodern/cinch-commands)
+* [Issues](https://github.com/postmodern/cinch-commands/issues)
+* [Documentation](http://rubydoc.info/gems/cinch-commands/frames)
+
+## Description
+
+Allows defining multiple commands within a Cinch Plugin.
+
+## Features
+
+* Argument types.
+* `!help` command with detailed output:
+  * Usages
+  * Summaries
+  * Descriptions
+
+## Examples
+
+    require 'cinch/commands'
+
+    class MyPlugin
+
+      include Cinch::Plugin
+      include Cinch::Commands
+
+      command :foo, {arg1: :string, arg2: :integer},
+                    summary:     "Does foo",
+                    description: %{
+                      ...
+                    }
+
+      command :bar, {name: :string},
+              aliases: [:b]
+
+      def foo(m,arg1,arg2)
+      end
+
+      def bar(m,name)
+      end
+
+    end
+
+## Requirements
+
+* [cinch][1] ~> 2.0
+
+## Install
+
+    $ gem install cinch-commands
+
+## Copyright
+
+Copyright (c) 2012-2013 Hal Brodigan
+
+See {file:LICENSE.txt} for details.
+
+[1]: https://github.com/cinchrb/cinch#readme

data/Rakefile

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'rake'
+
+begin
+  gem 'rubygems-tasks', '~> 0.1'
+  require 'rubygems/tasks'
+
+  Gem::Tasks.new
+rescue LoadError => e
+  warn e.message
+  warn "Run `gem install rubygems-tasks` to install 'rubygems/tasks'."
+end
+
+begin
+  gem 'rspec', '~> 2.4'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new
+rescue LoadError => e
+  task :spec do
+    abort "Please run `gem install rspec` to install RSpec."
+  end
+end
+
+task :test => :spec
+task :default => :spec
+
+begin
+  gem 'yard', '~> 0.7'
+  require 'yard'
+
+  YARD::Rake::YardocTask.new  
+rescue LoadError => e
+  task :yard do
+    abort "Please run `gem install yard` to install YARD."
+  end
+end
+task :doc => :yard

data/cinch-commands.gemspec

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+require 'yaml'
+
+Gem::Specification.new do |gem|
+  gemspec = YAML.load_file('gemspec.yml')
+
+  gem.name    = gemspec.fetch('name')
+  gem.version = gemspec.fetch('version') do
+                  lib_dir = File.join(File.dirname(__FILE__),'lib')
+                  $LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+
+                  require 'cinch/commands/version'
+                  Cinch::Commands::VERSION
+                end
+
+  gem.summary     = gemspec['summary']
+  gem.description = gemspec['description']
+  gem.licenses    = Array(gemspec['license'])
+  gem.authors     = Array(gemspec['authors'])
+  gem.email       = gemspec['email']
+  gem.homepage    = gemspec['homepage']
+
+  glob = lambda { |patterns| gem.files & Dir[*patterns] }
+
+  gem.files = `git ls-files`.split($/)
+  gem.files = glob[gemspec['files']] if gemspec['files']
+
+  gem.executables = gemspec.fetch('executables') do
+    glob['bin/*'].map { |path| File.basename(path) }
+  end
+  gem.default_executable = gem.executables.first if Gem::VERSION < '1.7.'
+
+  gem.extensions       = glob[gemspec['extensions'] || 'ext/**/extconf.rb']
+  gem.test_files       = glob[gemspec['test_files'] || '{test/{**/}*_test.rb']
+  gem.extra_rdoc_files = glob[gemspec['extra_doc_files'] || '*.{txt,md}']
+
+  gem.require_paths = Array(gemspec.fetch('require_paths') {
+    %w[ext lib].select { |dir| File.directory?(dir) }
+  })
+
+  gem.requirements              = gemspec['requirements']
+  gem.required_ruby_version     = gemspec['required_ruby_version']
+  gem.required_rubygems_version = gemspec['required_rubygems_version']
+  gem.post_install_message      = gemspec['post_install_message']
+
+  split = lambda { |string| string.split(/,\s*/) }
+
+  if gemspec['dependencies']
+    gemspec['dependencies'].each do |name,versions|
+      gem.add_dependency(name,split[versions])
+    end
+  end
+
+  if gemspec['development_dependencies']
+    gemspec['development_dependencies'].each do |name,versions|
+      gem.add_development_dependency(name,split[versions])
+    end
+  end
+end

data/gemspec.yml

@@ -0,0 +1,18 @@
+name: cinch-commands
+summary: Define multiple commands within a Cinch Plugin
+description: |
+  Allows defining multiple commands within a Cinch Plugin.
+  Also provides a !help command with detailed output.
+
+license: MIT
+authors: Postmodern
+email: postmodern.mod3@gmail.com
+homepage: https://github.com/postmodern/cinch-commands#readme
+
+dependencies:
+  cinch: ~> 2.0
+
+development_dependencies:
+  rubygems-tasks: ~> 0.2
+  rspec: ~> 2.4
+  yard: ~> 0.7

data/lib/cinch/commands.rb

@@ -0,0 +1,3 @@
+require 'cinch/commands/commands'
+require 'cinch/commands/help'
+require 'cinch/commands/version'

data/lib/cinch/commands/command.rb

@@ -0,0 +1,118 @@
+module Cinch
+  module Commands
+    #
+    # @api semipublic
+    #
+    class Command
+
+      # Argument formats
+      ARG_FORMATS = {
+        string:  /\S+/,
+        integer: /\d+/,
+        float:   /\d*\.\d+/,
+        text:    /.+/
+      }
+
+      # Name of the command
+      attr_reader :name
+      
+      # Argument names/formats
+      attr_reader :arguments
+      
+      # Short summary of the command
+      attr_reader :summary
+      
+      # Long description of the command
+      attr_reader :description
+
+      #
+      # Creates a new command.
+      #
+      # @param [Symbol] name
+      #   Name of the command.
+      #
+      # @param [Hash{Symbol => Symbol,Regexp,String,Array}] arguments
+      #   Arguments names and their formats or possible values.
+      #
+      # @param [Hash] options
+      #   Additional options.
+      #
+      # @option options [Array] :aliases
+      #   Additiona aliases for the command.
+      #
+      # @option options [String] :summary
+      #   Short summary of the command.
+      #
+      # @option options [String] :description
+      #   Long description of the command.
+      #
+      def initialize(name,arguments,options={})
+        @name        = name.to_s
+        @arguments   = arguments
+        @aliases     = options.fetch(:aliases,[]).map(&:to_s)
+
+        @summary     = options[:summary]
+        @description = options[:description]
+      end
+
+      #
+      # The names for the command.
+      #
+      # @return [Array<String>]
+      #   Command names.
+      #
+      def names
+        [@name] + @aliases
+      end
+
+      #
+      # Creates a Regular Expression that matches invocations of the command.
+      #
+      # @return [Regexp]
+      #   A Regular Expression that matches the command and captures it's
+      #   arguments.
+      #
+      def regexp
+        pattern = '(?:' + Regexp.union([@name] + @aliases).source + ')'
+
+        @arguments.each_value do |format|
+          arg_regexp = case format
+                       when Array  then Regexp.union(format)
+                       when Regexp then format
+                       when Symbol then ARG_FORMATS.fetch(format)
+                       else             Regexp.escape(format.to_s)
+                       end
+
+          pattern << ' (' << arg_regexp.source << ')'
+        end
+
+        # match the full message
+        pattern << '$'
+
+        return Regexp.new(pattern)
+      end
+
+      #
+      # The usage string for the command.
+      #
+      # @return [String]
+      #   The usage string for the command and it's arguments.
+      #
+      def usage
+        usage = "#{@name}"
+
+        @arguments.each do |arg,format|
+          usage << ' ' << case format
+                          when Array  then "[#{format.join('|')}]"
+                          when Regexp then format.source
+                          when Symbol then arg.to_s.upcase
+                          else             format.to_s
+                          end
+        end
+
+        return usage
+      end
+
+    end
+  end
+end

data/lib/cinch/commands/commands.rb

@@ -0,0 +1,66 @@
+require 'cinch/commands/command'
+
+require 'cinch/helpers'
+require 'cinch/plugin'
+
+module Cinch
+  module Commands
+
+    def self.included(base)
+      base.send :include, Cinch::Plugin
+      base.send :extend, ClassMethods
+    end
+
+    module ClassMethods
+      #
+      # All registered commands.
+      #
+      # @return [Array<Command>]
+      #   The registered commands.
+      #
+      # @api semipublic
+      #
+      def commands
+        @commands ||= []
+      end
+
+      protected
+
+      #
+      # Registers a command.
+      #
+      # @param [Symbol] name
+      #
+      # @param [Hash{Symbol => Symbol,Regexp}] arguments
+      #
+      # @param [Hash] options
+      #   Additional options.
+      #
+      # @option options [String] :summary
+      #   The short summary for the command.
+      #
+      # @option options [String] :description
+      #   The long description for the command.
+      #
+      # @return [Command]
+      #   The new command.
+      #
+      # @example
+      #   command :grant, {name: :string, :level: :integer},
+      #                   summary: "Grants access",
+      #                   description: %{
+      #                     Grants a certain level of access to the user
+      #                   }
+      #
+      def command(name,arguments={},options={})
+        new_command = Command.new(name,arguments,options)
+
+        match(new_command.regexp, method: name)
+
+        commands << new_command
+        return new_command
+      end
+    end
+
+  end
+end

data/lib/cinch/commands/help.rb

@@ -0,0 +1,95 @@
+require 'cinch/commands/commands'
+
+module Cinch
+  module Commands
+    #
+    # Generic `!help` command that lists all commands.
+    #
+    class Help
+
+      include Cinch::Commands
+
+      command :help, {command: :string},
+              summary:     %{Displays help information for the COMMAND},
+              description: %{
+                Finds the COMMAND and prints the usage and description for the
+                COMMAND.
+              }
+
+      command :help, {},
+              summary: "Lists available commands",
+              description: %{
+                If no COMMAND argument is given, then all commands will be listed.
+              }
+
+      #
+      # Displays a list of commands or the help information for a specific
+      # command.
+      #
+      # @param [Cinch::Message]
+      #   The message that invoked `!help`.
+      #
+      # @param [String] command
+      #   The specific command to list help information for.
+      #
+      def help(m,command=nil)
+        if command
+          found = commands_named(command)
+
+          if found.empty?
+            m.reply "help: Unknown command #{command.dump}"
+          else
+            # print all usages
+            found.each { |cmd| m.reply cmd.usage }
+
+            # print the description of the first command
+            m.reply ''
+            m.reply found.first.description
+          end
+        else
+          each_command do |cmd|
+            m.reply "#{cmd.usage} - #{cmd.summary}"
+          end
+        end
+      end
+
+      protected
+
+      #
+      # Enumerates over every command.
+      #
+      # @yield [command]
+      #   The given block will be passed every command.
+      #
+      # @yieldparam [Command] command
+      #   A command.
+      #
+      # @return [Enumerator]
+      #   If no block is given, an Enumerator will be returned.
+      #
+      def each_command(&block)
+        return enum_for(__method__) unless block_given?
+
+        bot.config.plugins.plugins.each do |plugin|
+          if plugin < Cinch::Commands
+            plugin.commands.each(&block)
+          end
+        end
+      end
+
+      #
+      # Finds all commands with a similar name.
+      #
+      # @param [String] name
+      #   The name to search for.
+      #
+      # @return [Array<Command>]
+      #   The commands with the matching name.
+      #
+      def commands_named(name)
+        each_command.select { |command| command.name == name }
+      end
+
+    end
+  end
+end

data/lib/cinch/commands/version.rb

@@ -0,0 +1,6 @@
+module Cinch
+  module Commands
+    # cinch-commands version
+    VERSION = "0.1.0"
+  end
+end

data/spec/command_spec.rb

@@ -0,0 +1,73 @@
+require 'spec_helper'
+require 'cinch/commands/command'
+
+describe Cinch::Commands::Command do
+  let(:command_name) { 'foo' }
+  let(:arguments)    { {name: :string, level: :integer, flag: %w[a o v]} }
+
+  let(:summary)     { 'Foo command' }
+  let(:description) { 'This is the foo command' }
+
+  describe "#regexp" do
+    let(:command_alias) { :fu }
+
+    let(:command) do
+      described_class.new(
+        command_name, arguments,
+        summary:     summary,
+        description: description,
+        aliases:     [command_alias]
+      )
+    end
+
+    let(:name_arg)  { 'bob' }
+    let(:level_arg) { '20'  }
+    let(:flag_arg)  { 'o'  }
+    let(:args)      { "#{name_arg} #{level_arg} #{flag_arg}" }
+
+    subject { command.regexp }
+
+    it { should be_kind_of(Regexp) }
+
+    it "should match the primary command-name" do
+      "#{command_name} #{args}".should =~ subject
+    end
+
+    it "should match the command-name aliases" do
+      "#{command_alias} #{args}".should =~ subject
+    end
+
+    it "should capture the arguments" do
+      match = "#{command_name} #{args}".match(subject)
+
+      match[1].should == name_arg
+      match[2].should == level_arg
+      match[3].should == flag_arg
+    end
+
+    it "should match the formats of the arguments" do
+      "#{command_name} xxxxx xxxx xxxxx".should_not =~ subject
+    end
+  end
+
+  describe "#usage" do
+    let(:command) do
+      described_class.new(
+        command_name, arguments,
+        summary:     summary,
+        description: description
+                          
+      )
+    end
+
+    subject { command.usage }
+
+    it "should include the command name" do
+      subject.start_with?(command_name).should be_true
+    end
+
+    it "should include the upper-case argument names" do
+      subject.should include("NAME LEVEL")
+    end
+  end
+end

data/spec/commands_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+require 'cinch/commands'
+
+describe Cinch::Commands do
+  it "should have a VERSION constant" do
+    subject.const_get('VERSION').should_not be_empty
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+gem 'rspec', '~> 2.4'
+require 'rspec'
+require 'cinch/commands/version'
+
+include Cinch::Commands

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: cinch-commands
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Postmodern
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-06-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: cinch
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: ! 'Allows defining multiple commands within a Cinch Plugin.
+
+  Also provides a !help command with detailed output.
+
+'
+email: postmodern.mod3@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+files:
+- .document
+- .gitignore
+- .rspec
+- .yardopts
+- ChangeLog.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- cinch-commands.gemspec
+- gemspec.yml
+- lib/cinch/commands.rb
+- lib/cinch/commands/command.rb
+- lib/cinch/commands/commands.rb
+- lib/cinch/commands/help.rb
+- lib/cinch/commands/version.rb
+- spec/command_spec.rb
+- spec/commands_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/postmodern/cinch-commands#readme
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Define multiple commands within a Cinch Plugin
+test_files: []