cksh_commander 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 921acc643549e603aa612742d7fd73c4c6e49389
-  data.tar.gz: 64670007c67675f60e1cbd7359002df75d8c8c61
+  metadata.gz: fc237603bb3d1579fcf9ae3700e17207a2e2f901
+  data.tar.gz: 7a77d47f54af6d498763704a43c8f53a304e0c65
 SHA512:
-  metadata.gz: 06cb6b5a144fb04bf23a189f92f7d40b88f2ab79c1d568d3927138e0e704fc07eda38030ff16eadb034c4e65bcff6e6028d8da36e5fc410253571c184af07045
-  data.tar.gz: 7a09443da85a65eae2f75ffa9008bb02cdd36fb39d7050af90892c50e58afd010ee5bfc36113e8df40778dedbb90fa0c85862b2dc140edd66fea63c8851498b8
+  metadata.gz: 72540f0185bff479bed0aa697be2c02ab9b445e0dd948ac5edf23f9cfb00daec314eab88f79a1dfc2c1694dcc309f7095c677a3066c7cd98088cd77c7d10657e
+  data.tar.gz: a6848cad5216d2afacec0feeb90dd6e0952d56d54920c11126e773d1751d4ef0ec4c8af1081dbba8c338ec698d1d0ee9dfb6b50246580f4de65e9d0486a2d427

data/README.md

@@ -5,17 +5,26 @@
 CKSHCommander is a Ruby gem that simplifies the task of processing [Slack slash
 commands](https://api.slack.com/slash-commands). It provides a class-based
 convention for authoring command handlers, and it supports basic subcommands and
-arguments.
+arguments. Check out the
+[cksh_command_api](https://github.com/openarcllc/cksh_commander_api) repository to see a dead simple Sinatra API
+that comes bootstrapped with everything you need to process Slack slash
+commands using this gem.
 
-## Installation
+### Installation
 
-You can install `cksh_commander` via RubyGems.
+You can install `cksh_commander` via RubyGems. In your Gemfile:
 
 ```ruby
 gem 'cksh_commander'
 ```
 
-## Usage
+Or from a command line:
+
+```
+gem install cksh_commander
+```
+
+### Usage
 
 Defining a custom command is easy. First, create a `commands/` directory and tell
 `CKSHCommander` where it can find your commands. Let's say we've created a `commands/`
@@ -62,18 +71,21 @@ module Example
 
     # Subcommand with no arguments
     # SLACK: /example test0
+    desc "test0", "Subcommand 0 description."
     def test0
       set_response_text("Subcommand: test0")
     end
 
     # Subcommand with one argument
     # SLACK: /example test1 text
+    desc "test1 [TEXT]", "Subcommand 1 description."
     def test1(text)
       set_response_text("Subcommand: test1; Text: #{text}")
     end
 
     # No subcommand with one argument
     # SLACK: /example text
+    desc "[TEXT]", "Root command description."
     def ___(text)
       set_response_text("Root command; Text: #{text}")
     end
@@ -84,8 +96,18 @@ end
 We set our slash command authentication token at the class level, and define
 methods for processing subcommands. Attachments (which take the form of a hash)
 can be added using `add_response_attachment(attachment)`. You can also set the
-response to `'in_channel'` at the method level with `respond_in_channel!`. See
-`CKSHCommander::Command` for the full implementation.
+response to `'in_channel'` at the method level with `respond_in_channel!`.
+
+Similar to [Thor](http://whatisthor.com/), we are able to document our
+command's API with the class-level `desc` method—as is shown in the example
+above. CKSHCommander provides a `help` subcommand out of the box, and this will
+echo the documentation back to the Slack user.
+
+```
+/example test0         # Subcommand 0 description.
+/example test1 [TEXT]  # Subcommand 1 description.
+/example [TEXT]        # Root command description.
+```
 
 To run a command, we use `CKSHCommander::Runner`. In the example below, we've
 created a simple Sinatra app to illustrate its usage with the standard Slack
@@ -111,12 +133,12 @@ post "/" do
 end
 ```
 
-## Development
+### Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
+### Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/openarcllc/cksh_commander.

data/lib/cksh_commander/command.rb

@@ -4,12 +4,20 @@ module CKSHCommander
   class Command
     class << self
       attr_accessor :token
+      attr_reader :docs
 
       def set(opts)
         opts.each do |k,v|
-          send("#{k}=", v) if respond_to?(k)
+          send("#{k}=", v) if respond_to?("#{k}=")
         end
       end
+
+      # Define command usage/description documentation
+      # for output in 'help' command.
+      def desc(usage, description)
+        @docs ||= []
+        @docs << { usage: usage, desc: description }
+      end
     end
 
     attr_accessor :data
@@ -62,6 +70,14 @@ module CKSHCommander
       @response
     end
 
+    def help
+      if self.class.docs.any?
+        set_response_text(help_output)
+      else
+        set_response_text("Add some documentation!")
+      end
+    end
+
     def authenticated?
       self.class.token && self.class.token == data.token
     end
@@ -85,7 +101,25 @@ module CKSHCommander
     private
 
     def subcommand_methods
-      methods - CKSHCommander::Command.new.methods
+      custom = (methods - CKSHCommander::Command.new.methods)
+      custom.concat([:help])
+    end
+
+    def help_output
+      docs = self.class.docs
+      output = "```\n"
+
+      # Ensure that descriptions are justified properly.
+      just = docs.max_by { |d|
+        d[:usage].size
+      }[:usage].size + @data.command.size + 3
+
+      # Add output for each documented command.
+      docs.each do |d|
+        output += "#{@data.command} #{d[:usage]}".ljust(just) + "# #{d[:desc]}\n"
+      end
+
+      output += "```"
     end
   end
 end

data/lib/cksh_commander/version.rb

@@ -1,3 +1,3 @@
 module CKSHCommander
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cksh_commander
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Travis Loncar
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-09 00:00:00.000000000 Z
+date: 2015-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler