Name: cognition
Owner: Basecamp
Description: Match text; run commands. Works great for building a chatbot!
Created: 2015-02-20 13:51:59.0
Updated: 2018-03-30 23:51:50.0
Pushed: 2018-02-15 21:57:28.0
Homepage: null
Size: 53
Language: Ruby
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
This is a gem that parses a message, and compares it to various matchers. When it finds the first match, it executes an associated block of code or method, returning the output of whatever was run.
Add this line to your application's Gemfile:
'cognition'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cognition
Instantiate:
= Cognition::Bot.new
Process your message:
lt = bot.process('command I need to process')
You can also include metadata with your message, like user info, or whatever:
lt = bot.process('another command', {user_id: 15, name: 'Bob'})
Internally, Cognition
will turn your values into a Cognition::Message
so
the metadata will be passed along with the message, and arbitrary metadata
is available in the #metadata Hash:
= Cognition::Message('another command', {user_id: 15, name: 'Bob'})
metadata # Returns { user_id: 15, name: 'Bob' }
If you include a callback_url
key in your metadata, we'll give you a
convenience method to reply to it using the reply
method. This will
invoke a HTTParty POST back to the URL with your text sent as the
content
variable.
= Cognition::Message('another command', {
llback_url: "http://foo.bar/baz",
er_id: 15,
me: 'Bob'
reply("foo") # Posts 'content=foo' to http://foo.bar/baz
Creating plugins is easy. Subclass Cognition::Plugins::Base
and setup your
matches and logic that should be run. Your methods will be passed the msg
object and any metadata
you've passed to the bot's process
method. Here's
an example plugin:
s Hello < Cognition::Plugins::Base
Simple string based matcher. Must match *EXACTLY*
tch 'hello', :hello, help: { 'hello' => 'Returns Hello World' }
Advanced Regexp based matcher. Capture groups are made available
via MatchData in the matches method
tch /hello\s*(?<name>.*)/, :hello_person, help: {
'hello <name>' => 'Greets you by name!'
f hello(*)
'Hello World'
d
f hello_person(msg, match_data = nil)
name = match_data[:name]
"Hello #{name}"
d
After you've done that, you will be able to do:
register(Hello)
process("help hello") # "hello <name> - Greets you by name!"
process("hello") # "Hello World"
process("hello foo") # "Hello foo"
Templates are opt-in right now, you need to call render
yourself, and it
will return a string with the rendered contents of a template. What template,
you ask? The default for /path/to/hello.rb
will look for a templates in
/path/to/hello/views/
.
Given the following plugin:
s Hello < Cognition::Plugins::Base
...snipped
f hello(*)
render
d
f hi(*)
render(template: "/path/to/template.html.erb")
d
f hey(*)
render(type: "text", extension: "haml")
d
hello
method will look for /path/to/hello/views/hello.html.erb
hi
method will look for /path/to/template.html.erb
hey
method will look for /path/to/hello/views/hey.text.haml
Setting instance variables or passing locals is up to the plugin creator.
The render
method takes a hash with the following keys:
mplate: "full/path/to/template/file", # FULL path to template file
pe: "type of response" # text, html, json, etc...
tension: "engine file extension" # erb, haml, etc...
cals: {x: "foo", y: "bar"} # local variables, access as x & y
git checkout -b my-new-feature
)git commit -am 'Add some feature'
)git push origin my-new-feature
)