cogy 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +9 -0
- data/README.md +76 -36
- data/app/controllers/cogy/cogy_controller.rb +10 -12
- data/config/routes.rb +1 -1
- data/lib/cogy/command.rb +45 -13
- data/lib/cogy/context.rb +21 -21
- data/lib/cogy/version.rb +1 -1
- data/lib/cogy.rb +20 -32
- data/test/dummy/log/test.log +5154 -0
- data/test/integration/builtin_helpers_test.rb +3 -3
- data/test/integration/command_test.rb +8 -8
- data/test/integration/error_template_test.rb +2 -2
- data/test/integration/helpers_test.rb +2 -2
- data/test/integration/json_response_test.rb +2 -2
- data/test/support/helpers.rb +4 -0
- data/test/test_helper.rb +1 -1
- metadata +6 -6
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 0d68c05583565f05400bafb31ec6487ed3ed72d2
|
4
|
+
data.tar.gz: a693a5479f2ea5c0a74ebcca4d17a1ea5ac7e5b5
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 115ffd20c179abbdf00324759778b7ad5945213c91f6724b5e41e0f3f0f860ebd0c1c9412b5380d7bdbebd3f47876f3c22468cc52ae75f4abad235a4b55786c5
|
7
|
+
data.tar.gz: 02c5c9aec2d01c167a6b29e027b787988d627e27692ea24370c45491b7a0f8b0583631d0b4955eb143d6dea9ceca3c0b1a9a30359f7f9b091508ee492c710c33
|
data/CHANGELOG.md
CHANGED
@@ -2,6 +2,15 @@
|
|
2
2
|
|
3
3
|
## master (unreleased)
|
4
4
|
|
5
|
+
## 0.4.0 (2016-12-05)
|
6
|
+
|
7
|
+
This release requires the [cogy-bundle](https://github.com/skroutz/cogy-bundle)
|
8
|
+
to be at version 0.4.0 or later.
|
9
|
+
|
10
|
+
### Changed
|
11
|
+
|
12
|
+
- The 'user' parameter no longer exists in the incoming request path ([#60](https://github.com/skroutz/cogy/issues/60))
|
13
|
+
|
5
14
|
## 0.3.0 (2016-11-29)
|
6
15
|
|
7
16
|
This release requires the [cogy-bundle](https://github.com/skroutz/cogy-bundle)
|
data/README.md
CHANGED
@@ -11,18 +11,19 @@ See the API documentation [here](http://www.rubydoc.info/github/skroutz/cogy).
|
|
11
11
|
|
12
12
|
Refer to the [Changelog](CHANGELOG.md) to see what's changed between releases.
|
13
13
|
|
14
|
-
##
|
15
|
-
|
16
|
-
Cogy is still in public alpha.
|
14
|
+
## Features
|
17
15
|
|
18
|
-
|
19
|
-
|
16
|
+
- Write commands inside your Rails app, using Ruby (see [_Usage_](#usage))
|
17
|
+
- The bundle config is generated automatically
|
18
|
+
- Commands are installed _automatically_ when you deploy (see [_Deployment_](#deployment))
|
19
|
+
- Support for JSON responses and Templates (see [_Returning JSON to COG_](#returning-json-to-cog))
|
20
|
+
- Customizable error templates (see [_Error template_](#error-template))
|
20
21
|
|
21
|
-
|
22
|
+
...and more on the way!
|
22
23
|
|
23
24
|
## Why
|
24
25
|
|
25
|
-
Creating
|
26
|
+
Creating ChatOps commands that talk with a Rails app typically involves writing
|
26
27
|
a route, maybe a controller, an action and code to handle the command arguments
|
27
28
|
and options.
|
28
29
|
|
@@ -30,9 +31,9 @@ This is a tedious and repetitive task and involves a lot of boilerplate
|
|
30
31
|
code each time someone wants to add a new command.
|
31
32
|
|
32
33
|
Cogy is an opinionated library that provides a way to get rid of all the
|
33
|
-
|
34
|
+
boilerplate stuff so you can focus on just the actual commands.
|
34
35
|
|
35
|
-
|
36
|
+
Deploying a new command is as simple as writing:
|
36
37
|
|
37
38
|
```ruby
|
38
39
|
# in cogy/my_commands.rb
|
@@ -42,15 +43,15 @@ on "foo", desc: "Echo a foo bar back at you!" do
|
|
42
43
|
end
|
43
44
|
```
|
44
45
|
|
45
|
-
...and deploying!
|
46
|
+
...and deploying!
|
46
47
|
|
47
48
|
## How it works
|
48
49
|
|
49
50
|
Cogy is essentially three things:
|
50
51
|
|
51
52
|
1. An opinionated way to write, manage & ship commands: All Cogy commands are
|
52
|
-
defined in your Rails app and end up invoking a
|
53
|
-
Relay. Cogy also provides bundle versioning and dynamically generates the
|
53
|
+
defined in your Rails app and end up invoking a single executable within the
|
54
|
+
Relay (see below). Cogy also provides bundle versioning and dynamically generates the
|
54
55
|
installable bundle config, which is also served by your Rails application
|
55
56
|
and consumed by the [`cogy:install`](https://github.com/skroutz/cogy-bundle)
|
56
57
|
command that installs the new Cogy-generated bundle when you deploy your
|
@@ -68,14 +69,22 @@ Cogy is essentially three things:
|
|
68
69
|
to the user. It also contains the `cogy:install` command for automating
|
69
70
|
the task of installing the new bundle when a command is added/modified.
|
70
71
|
|
71
|
-
Take a look at the relevant [diagrams](diagrams/) for
|
72
|
-
Cogy works.
|
72
|
+
Take a look at the relevant [diagrams](diagrams/) for a detailed illustration.
|
73
73
|
|
74
74
|
## Requirements
|
75
75
|
|
76
|
-
* [cogy bundle](https://github.com/skroutz/cogy-bundle)
|
76
|
+
* [cogy bundle v0.3.0+](https://github.com/skroutz/cogy-bundle)
|
77
77
|
* Ruby 2.1+
|
78
|
-
*
|
78
|
+
* Rails 4.2 (support for Rails 5 is on the way)
|
79
|
+
|
80
|
+
## Status
|
81
|
+
|
82
|
+
Cogy is still in public alpha.
|
83
|
+
|
84
|
+
While we use it in production, it's still under heavy development.
|
85
|
+
This means that there are a few rough edges and things change fast.
|
86
|
+
|
87
|
+
However we'd love any [feedback, suggestions or ideas](https://github.com/skroutz/cogy/issues/new).
|
79
88
|
|
80
89
|
## Install
|
81
90
|
|
@@ -120,14 +129,14 @@ on "add", args: [:a, :b], desc: "Add two numbers" do
|
|
120
129
|
end
|
121
130
|
```
|
122
131
|
|
123
|
-
Inside the block there are the following
|
132
|
+
Inside the block there are the following helpers available:
|
124
133
|
|
125
134
|
* `args`: an array containing the arguments passed to the command
|
126
135
|
* arguments can also be accessed by their names as local variables
|
127
136
|
* `opts`: a hash containing the options passed to the command
|
128
137
|
* `handle`: the chat handle of the user who called the command
|
129
|
-
* `env`: a hash containing the
|
130
|
-
|
138
|
+
* `env`: a hash containing the Relay environment as available in the cogy
|
139
|
+
bundle
|
131
140
|
|
132
141
|
For instructions on defining your own helpers, see [Helpers](#helpers).
|
133
142
|
|
@@ -158,7 +167,8 @@ on "foo", desc: "Just a JSON" do
|
|
158
167
|
end
|
159
168
|
```
|
160
169
|
|
161
|
-
The hash automatically
|
170
|
+
The hash is automatically converted to JSON. The above command would return
|
171
|
+
the following response to Cog:
|
162
172
|
|
163
173
|
```
|
164
174
|
COG_TEMPLATE: foo
|
@@ -166,7 +176,8 @@ JSON
|
|
166
176
|
{"a":3}
|
167
177
|
```
|
168
178
|
|
169
|
-
To customize the Cog [template](#Templates) to be used,
|
179
|
+
To customize the Cog [template](#Templates) to be used, use the `template`
|
180
|
+
option:
|
170
181
|
|
171
182
|
```ruby
|
172
183
|
on "foo", desc: "Just a JSON", template: "bar" do
|
@@ -232,7 +243,7 @@ Cogy.configure do |config|
|
|
232
243
|
config.bundle = {
|
233
244
|
# The bundle name.
|
234
245
|
#
|
235
|
-
# Default: "
|
246
|
+
# Default: "myapp"
|
236
247
|
name: "myapp",
|
237
248
|
|
238
249
|
# The bundle description
|
@@ -281,11 +292,12 @@ $ bin/rails g cogy:config
|
|
281
292
|
|
282
293
|
### Helpers
|
283
294
|
|
284
|
-
It is possible to define helpers that can be used throughout commands.
|
285
|
-
|
286
|
-
|
295
|
+
It is possible to define helpers that can be used throughout commands. This is
|
296
|
+
useful for DRYing repetitive code.
|
297
|
+
|
298
|
+
They are defined during configuration and may also accept arguments.
|
287
299
|
|
288
|
-
Let's define a helper that fetches
|
300
|
+
Let's define a helper that fetches the `address` of a `Shop` record:
|
289
301
|
command:
|
290
302
|
|
291
303
|
```ruby
|
@@ -297,7 +309,7 @@ end
|
|
297
309
|
*(Note that custom helpers also have access to the default helpers like
|
298
310
|
`handle`, `args` etc.)*
|
299
311
|
|
300
|
-
Then we could have a command
|
312
|
+
Then we could have a command that makes use of the helper:
|
301
313
|
|
302
314
|
```ruby
|
303
315
|
on "shop_address", desc: "Returns the user's Shop address" do
|
@@ -305,7 +317,7 @@ on "shop_address", desc: "Returns the user's Shop address" do
|
|
305
317
|
end
|
306
318
|
```
|
307
319
|
|
308
|
-
|
320
|
+
Helpers may also accept arguments:
|
309
321
|
|
310
322
|
```ruby
|
311
323
|
Cogy.configure do |c|
|
@@ -313,7 +325,7 @@ Cogy.configure do |c|
|
|
313
325
|
end
|
314
326
|
```
|
315
327
|
|
316
|
-
|
328
|
+
This helper could be called like so:
|
317
329
|
|
318
330
|
```ruby
|
319
331
|
on "foo", desc: "Nothing special" do
|
@@ -321,11 +333,12 @@ on "foo", desc: "Nothing special" do
|
|
321
333
|
end
|
322
334
|
```
|
323
335
|
|
324
|
-
Rails
|
336
|
+
Rails URL helpers (ie. `foo_url`) are also available inside the commands.
|
325
337
|
|
326
338
|
## Error template
|
327
339
|
|
328
|
-
When a command throws an error the
|
340
|
+
When a command throws an error the
|
341
|
+
[default error template](https://github.com/skroutz/cogy/blob/master/app/views/cogy/error.text.erb) is rendered, which
|
329
342
|
is the following:
|
330
343
|
|
331
344
|
@<%= @user %>: Command '<%= @cmd %>' returned an error.
|
@@ -337,12 +350,39 @@ is the following:
|
|
337
350
|
It can be overriden in the application by creating a view in
|
338
351
|
`app/views/cogy/error.text.erb`.
|
339
352
|
|
353
|
+
## Installation Trigger
|
354
|
+
|
355
|
+
In order to automate the process of installing the new bundle versions
|
356
|
+
(eg. after a new command is added), you must create a [Cog Trigger](https://cog-book.operable.io/#_developing_a_trigger)
|
357
|
+
that will perform the installation, which will be called when you deploy your
|
358
|
+
app.
|
359
|
+
|
360
|
+
The trigger will look this:
|
361
|
+
|
362
|
+
```shell
|
363
|
+
$ cogctl triggers
|
364
|
+
Name ID Enabled Pipeline
|
365
|
+
ReleaseUrlTrigger d10df83b-a737-4fc4-8d9b-bf9627412d0a true cogy:install --url $body.url > chat://#general
|
366
|
+
```
|
367
|
+
|
368
|
+
It essentially uses the [cogy bundle](https://github.com/skroutz/cogy-bundle)
|
369
|
+
and installs the bundle config which is served by your application
|
370
|
+
(ie. http://your-app.com/cogy/inventory).
|
371
|
+
|
372
|
+
See [_Deployment_](#deployment) on information about how this trigger is
|
373
|
+
invoked.
|
374
|
+
|
340
375
|
## Deployment
|
341
376
|
|
342
|
-
Cogy provides
|
343
|
-
|
344
|
-
|
345
|
-
|
377
|
+
Cogy provides integration with Capistrano 2 and 3.
|
378
|
+
|
379
|
+
There is the just one task, `cogy:notify_cog`, which just executes the
|
380
|
+
[installation Trigger](#installation-trigger).
|
381
|
+
|
382
|
+
The task should run
|
383
|
+
*after* the application server is restarted, so that the new commands
|
384
|
+
are picked up and served by the Inventory endpoint. In Capistrano 2 for
|
385
|
+
example, it should run after the built-in `deploy:restart` task.
|
346
386
|
|
347
387
|
The following options need to be set:
|
348
388
|
|
@@ -354,7 +394,7 @@ The following options need to be set:
|
|
354
394
|
You can also configure the timeout value for the request to the Trigger by
|
355
395
|
setting the `cogy_trigger_timeout` option (default: 7).
|
356
396
|
|
357
|
-
The task can be found [here](https://github.com/skroutz/cogy/blob/master/lib/cogy/capistrano/cogy.rake).
|
397
|
+
The code of the task can be found [here](https://github.com/skroutz/cogy/blob/master/lib/cogy/capistrano/cogy.rake).
|
358
398
|
|
359
399
|
### Capistrano 2
|
360
400
|
|
@@ -1,22 +1,21 @@
|
|
1
1
|
require_dependency "cogy/application_controller"
|
2
2
|
|
3
3
|
module Cogy
|
4
|
+
# This is the entry point to the host application.
|
5
|
+
#
|
6
|
+
# All Cogy-command invocations of the users end up being served by this
|
7
|
+
# controller ({#command}).
|
4
8
|
class CogyController < ApplicationController
|
5
|
-
# POST
|
9
|
+
# POST /<mount_path>/cmd/:cmd
|
6
10
|
#
|
7
|
-
#
|
8
|
-
# https://github.com/skroutz/cogy-bundle hits. It executes the requested
|
9
|
-
# {Command} and responds back the result, which is then printed to the user
|
10
|
-
# by the cogy executable.
|
11
|
-
#
|
12
|
-
# See https://github.com/skroutz/cogy-bundle.
|
11
|
+
# Executes the requested {Command} and returns the result.
|
13
12
|
def command
|
14
13
|
cmd = params[:cmd]
|
15
14
|
args = params.select { |k, _| k.start_with?("COG_ARGV_") }
|
16
15
|
.sort_by { |k, _| k.match(/\d+\z/)[0] }.to_h.values
|
17
16
|
opts = params.select { |k, _| k.start_with?("COG_OPT_") }
|
18
17
|
.transform_keys { |k| k.sub("COG_OPT_", "").downcase }
|
19
|
-
user = params[
|
18
|
+
user = params["COG_CHAT_HANDLE"]
|
20
19
|
cog_env = request.request_parameters
|
21
20
|
|
22
21
|
begin
|
@@ -43,11 +42,10 @@ module Cogy
|
|
43
42
|
end
|
44
43
|
end
|
45
44
|
|
46
|
-
# GET
|
45
|
+
# GET /<mount_path>/inventory
|
47
46
|
#
|
48
|
-
#
|
49
|
-
#
|
50
|
-
# `cogy:install` command (see https://github.com/skroutz/cogy-bundle).
|
47
|
+
# Returns the bundle config in YAML format, which is installable by Cog.
|
48
|
+
# It is typically hit by `cogy:install` (https://github.com/skroutz/cogy-bundle).
|
51
49
|
def inventory
|
52
50
|
render text: Cogy.bundle_config.to_yaml, content_type: "application/x-yaml"
|
53
51
|
end
|
data/config/routes.rb
CHANGED
data/lib/cogy/command.rb
CHANGED
@@ -1,27 +1,59 @@
|
|
1
1
|
module Cogy
|
2
|
-
# {Command} represents a user-defined registered command that can be used
|
3
|
-
# in the chat. It contains
|
4
|
-
# needs to be in the bundle config) and
|
5
|
-
# the result (
|
2
|
+
# {Command} represents a user-defined, registered command that can be used
|
3
|
+
# in the chat. It contains information about Cog-related stuff (ie. everything that
|
4
|
+
# needs to be in the bundle config like args & opts) and the block that will
|
5
|
+
# return the result ({Command#handler}).
|
6
6
|
class Command
|
7
|
-
# The name of the command. Also used in {Cogy.bundle_config}.
|
8
|
-
#
|
9
7
|
# @return [String]
|
10
8
|
attr_reader :name
|
11
9
|
|
12
|
-
# The code that will run when the command is invoked
|
13
|
-
#
|
14
10
|
# @return [Proc]
|
15
11
|
attr_reader :handler
|
16
12
|
|
17
|
-
#
|
18
|
-
attr_reader :args
|
13
|
+
# @return [Array]
|
14
|
+
attr_reader :args
|
15
|
+
|
16
|
+
# @return [Hash{Symbol=>Hash}]
|
17
|
+
attr_reader :opts
|
18
|
+
|
19
|
+
# @return [String]
|
20
|
+
attr_reader :desc
|
21
|
+
|
22
|
+
# @return [String]
|
23
|
+
attr_reader :long_desc
|
24
|
+
|
25
|
+
# @return [String]
|
26
|
+
attr_reader :examples
|
19
27
|
|
20
|
-
#
|
28
|
+
# @return [Array]
|
29
|
+
attr_reader :rules
|
30
|
+
|
31
|
+
# @return [String]
|
21
32
|
attr_reader :template
|
22
33
|
|
23
|
-
#
|
24
|
-
|
34
|
+
# This is typically used via {Cogy.on} which also registers the newly
|
35
|
+
# created {Command}.
|
36
|
+
#
|
37
|
+
# @param name [String, Symbol] the name of the command. This is how the
|
38
|
+
# command will be invoked in the chat.
|
39
|
+
#
|
40
|
+
# @param handler [Proc] the code that will run when the command is invoked
|
41
|
+
#
|
42
|
+
# @param args [Array<Symbol, String>, Symbol, String] the arguments
|
43
|
+
# accepted by the command
|
44
|
+
#
|
45
|
+
# @param opts [Hash{Symbol=>Hash}] the options accepted by the command
|
46
|
+
# @param desc [String] the description
|
47
|
+
# @param long_desc [String] the long description
|
48
|
+
# @param examples [String] usage examples of the command
|
49
|
+
# @param rules [Array] the command rules
|
50
|
+
# @param template [String] the name of the template to use
|
51
|
+
#
|
52
|
+
# @raise [ArgumentError] if {#opts} are invalid
|
53
|
+
#
|
54
|
+
# @see Cogy.on
|
55
|
+
def initialize(name, handler, args: [], opts: {}, desc:, long_desc: nil,
|
56
|
+
examples: nil, rules: nil, template: nil)
|
25
57
|
@name = name.to_s
|
26
58
|
@handler = handler
|
27
59
|
@args = [args].flatten.map!(&:to_s)
|
data/lib/cogy/context.rb
CHANGED
@@ -1,39 +1,39 @@
|
|
1
1
|
module Cogy
|
2
2
|
# {Context} represents a particular invocation request of a {Command}
|
3
|
-
# performed by a user. It holds state like the
|
3
|
+
# performed by a user. It holds state like the given arguments, options etc.
|
4
4
|
# In other words, it provides the context in which a {Command} should be
|
5
5
|
# invoked.
|
6
6
|
#
|
7
|
-
# A {Context} essentially is an HTTP request performed by
|
8
|
-
#
|
9
|
-
# You can think of it as the equivalent of the ActionPack's `Request`
|
7
|
+
# A {Context} essentially is an HTTP request performed by `cogy:cogy`
|
8
|
+
# (https://github.com/skroutz/cogy-bundle) on behalf of the user.
|
9
|
+
# You can think of it as the equivalent of the ActionPack's `Request` object.
|
10
10
|
class Context
|
11
|
-
# @return [Command]
|
11
|
+
# @return [Command]
|
12
12
|
attr_reader :command
|
13
13
|
|
14
|
-
# @return [Array]
|
15
|
-
# invoked the command.
|
16
|
-
#
|
17
|
-
# @see https://cog-book.operable.io/#_arguments
|
14
|
+
# @return [Array]
|
18
15
|
attr_reader :args
|
19
16
|
|
20
|
-
# @return [Hash]
|
21
|
-
# invoked the command
|
22
|
-
#
|
23
|
-
# @see https://cog-book.operable.io/#_options
|
17
|
+
# @return [Hash]
|
24
18
|
attr_reader :opts
|
25
19
|
|
26
|
-
# @return [String]
|
27
|
-
#
|
28
|
-
# @see https://cog-book.operable.io/#_general_metadata
|
20
|
+
# @return [String]
|
29
21
|
attr_reader :handle
|
30
22
|
|
31
|
-
# @return [Hash]
|
32
|
-
# the Relay executable that start with 'COGY_')
|
33
|
-
#
|
34
|
-
# @see https://github.com/skroutz/cogy-bundle/blob/master/commands/cogy
|
23
|
+
# @return [Hash]
|
35
24
|
attr_reader :env
|
36
25
|
|
26
|
+
# @param command [Command] the {Command} to be invoked
|
27
|
+
# @param args [Array] the arguments as provided by the user
|
28
|
+
# @param opts [Hash] the options as provided by the user
|
29
|
+
# @param handle [String] the chat handle of the user
|
30
|
+
# @param env [Hash] the Cog Relay environment
|
31
|
+
#
|
32
|
+
# @see https://cog-book.operable.io/#_arguments
|
33
|
+
# @see https://cog-book.operable.io/#_options
|
34
|
+
# @see https://cog-book.operable.io/#_command_environment_variables
|
35
|
+
#
|
36
|
+
# @note By 'user' we refer to the user who invoked the command in chat.
|
37
37
|
def initialize(command, args, opts, handle, env)
|
38
38
|
@command = command
|
39
39
|
@args = args
|
@@ -44,7 +44,7 @@ module Cogy
|
|
44
44
|
define_arg_helpers
|
45
45
|
end
|
46
46
|
|
47
|
-
# Invokes the {
|
47
|
+
# Invokes the command pointed by {#command}.
|
48
48
|
#
|
49
49
|
# @return [Object] the result of the command. This is what will get printed
|
50
50
|
# back to the user that invoked the command and is effectively the return
|
data/lib/cogy/version.rb
CHANGED
data/lib/cogy.rb
CHANGED
@@ -4,21 +4,18 @@ require "cogy/context"
|
|
4
4
|
|
5
5
|
module Cogy
|
6
6
|
# The supported Cog bundle config version.
|
7
|
-
#
|
8
|
-
# @see http://docs.operable.io/docs/bundle-configs
|
9
7
|
COG_BUNDLE_VERSION = 4
|
10
8
|
|
11
9
|
# Holds all the registered {Command} objects. Not to be messed with.
|
12
10
|
@@commands = {}
|
13
11
|
mattr_accessor :commands
|
14
12
|
|
15
|
-
# Configuration related to the Cog bundle. Used in {Cogy.bundle_config}
|
16
|
-
# in order to generate the bundle config YAML.
|
13
|
+
# Configuration related to the Cog bundle. Used in {Cogy.bundle_config}.
|
17
14
|
#
|
18
15
|
# @see https://cog-book.operable.io/#_the_config_file
|
19
16
|
@@bundle = {
|
20
17
|
# The bundle name
|
21
|
-
name: "
|
18
|
+
name: "myapp",
|
22
19
|
|
23
20
|
# The bundle description
|
24
21
|
description: "Cog commands generated from Cogy",
|
@@ -40,8 +37,6 @@ module Cogy
|
|
40
37
|
mattr_accessor :bundle
|
41
38
|
|
42
39
|
# The Cog templates. Used in {Cogy.bundle_config}.
|
43
|
-
#
|
44
|
-
# @see https://cog-book.operable.io/#_templates
|
45
40
|
@@templates = {}
|
46
41
|
mattr_accessor :templates
|
47
42
|
|
@@ -50,29 +45,23 @@ module Cogy
|
|
50
45
|
@@command_load_paths = ["cogy"]
|
51
46
|
mattr_accessor :command_load_paths
|
52
47
|
|
53
|
-
#
|
54
|
-
# generating the bundle config
|
55
|
-
# is the code that will get executed when the command is invoked.
|
48
|
+
# Initializes a new {Command} and registers it. All the options passed are
|
49
|
+
# used when generating the bundle config in {Cogy.bundle_config}.
|
56
50
|
#
|
57
|
-
# The
|
58
|
-
#
|
59
|
-
#
|
51
|
+
# The given block is the code that will execute when the command is invoked.
|
52
|
+
# The return value of that block is what will get returned as a result
|
53
|
+
# back to Cog.
|
60
54
|
#
|
61
|
-
# Inside the command block
|
62
|
-
# available.
|
55
|
+
# Inside the command block the public attributes of {Context} are
|
56
|
+
# available in addition to any user-defined handlers.
|
63
57
|
#
|
64
58
|
# @param cmd_name [String, Symbol] the name of the command. This is how the
|
65
59
|
# command will be invoked in the chat.
|
66
|
-
# @param [Hash]
|
60
|
+
# @param opts [Hash] the options to create the command with. All these options
|
67
61
|
# are used solely for generating the bundle config for Cog, thus they map
|
68
62
|
# directly to Cog's bundle config format.
|
69
63
|
# See https://cog-book.operable.io/#_the_config_file for more information.
|
70
|
-
#
|
71
|
-
# @option opts [Hash{Symbol=>Hash}] :opts ({})
|
72
|
-
# @option opts [String] :desc required
|
73
|
-
# @option opts [String] :long_desc (nil)
|
74
|
-
# @option opts [String] :examples (nil)
|
75
|
-
# @option opts [Array] :rules (["allow"])
|
64
|
+
# For documentation on what's supported right now see {Command#initialize}.
|
76
65
|
#
|
77
66
|
# @example
|
78
67
|
# Cogy.on "calc",
|
@@ -90,11 +79,10 @@ module Cogy
|
|
90
79
|
# "Hello #{user}, the answer is: #{result}"
|
91
80
|
# end
|
92
81
|
#
|
93
|
-
# @return [
|
82
|
+
# @return [Command] the created command
|
94
83
|
#
|
95
|
-
# @note
|
96
|
-
#
|
97
|
-
# work in Ruby.
|
84
|
+
# @note to return early inside a command block, `next` should be used instead
|
85
|
+
# of `return` due to the way Proc objects work in Ruby.
|
98
86
|
def self.on(cmd_name, opts = {}, &handler)
|
99
87
|
cmd = Command.new(cmd_name, handler, opts)
|
100
88
|
cmd.register!
|
@@ -102,7 +90,7 @@ module Cogy
|
|
102
90
|
|
103
91
|
# Generates the bundle config
|
104
92
|
#
|
105
|
-
# @return [Hash]
|
93
|
+
# @return [Hash] the bundle config
|
106
94
|
def self.bundle_config
|
107
95
|
version = if bundle[:version].respond_to?(:call)
|
108
96
|
bundle[:version].call
|
@@ -161,14 +149,11 @@ module Cogy
|
|
161
149
|
|
162
150
|
# Defines a user helper method that can be used throughout commands.
|
163
151
|
#
|
164
|
-
# @param [Symbol]
|
165
|
-
# @param [Proc]
|
152
|
+
# @param name [Symbol] the name of the helper
|
153
|
+
# @param blk [Proc] the helper body
|
166
154
|
#
|
167
155
|
# @return [void]
|
168
156
|
#
|
169
|
-
# @note User helpers also have access to the default helpers like `user`, `env`
|
170
|
-
# etc.
|
171
|
-
#
|
172
157
|
# @example
|
173
158
|
# Cogy.configure do |c|
|
174
159
|
# helper(:user) { User.find_by(slack_handle: handle) }
|
@@ -176,6 +161,9 @@ module Cogy
|
|
176
161
|
# # a helper that accepts an argument
|
177
162
|
# helper(:format) { |answer| answer.titleize }
|
178
163
|
# end
|
164
|
+
#
|
165
|
+
# @note User helpers also have access to the default helpers like `user`, `env`
|
166
|
+
# etc.
|
179
167
|
def self.helper(name, &blk)
|
180
168
|
Context.class_eval { define_method(name, blk) }
|
181
169
|
end
|