Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/undr/walle

Simple DSL for building Slack bots.
https://github.com/undr/walle

Last synced: about 1 month ago
JSON representation

Simple DSL for building Slack bots.

Awesome Lists containing this project

README 

        
# Walle



[![Build Status](https://travis-ci.org/undr/walle.svg?branch=master)](https://travis-ci.org/undr/walle)



Simple DSL for building Slack bots.



## Installation



Add this line to your application's Gemfile:



```ruby

gem 'walle'

```



And then execute:



```

$ bundle

```



Or install it yourself as:



```

$ gem install walle

```



## Usage



Example bot class:



```ruby

class Robot < Walle::Robot

  # Use middleware for all events

  use Walle::Middlewares::Logger, Slack.config.logger



  # catch `hello` events

  hello { |env| }



  # catch `start` events

  start { |env| }



  # catch `message` events

  message { |env| }



  # catch `close` events

  close { |env| }



  # catch `closed` events

  closed { |env| }



  routes do

    # Use middleware ONLY for routes

    use SomeCustomMidleware, 'arg1', 'arg2'



    # Equals to match(/(?convert|c)\s+(?\d+)\s*(?[A-Z]{3})\s+into\s+(?[A-Z]{3})/, controller: CurrencyConvertor)

    command 'convert', 'c', amount: /\d+/, from: /[A-Z]{3}/, into: 'into', to: /[A-Z]{3}/, delimiter: /\s+/, controller: CurrencyConvertor



    # Prefix all matches with bot name, eg. <@U2EU6KZDW>

    direct do

      # Matches string like "<@U2EU6KZDW> convert 10000 RUB into EUR"

      match /convert\s+(?\d+)\s*(?[A-Z]{3})\s+into\s+(?[A-Z]{3})/ do |env|

        # env.event   - :message

        # env.client  - Slack::RealTime::Client

        # env.data    - Event data (it can contain extra data that can be added in middlewares)

        #   - type: "message"

        #   - channel: "V2T4X87M5"

        #   - user: "Z005UR62C"

        #   - text: "<@U2EU6KZDW> convert 10000 RUB into EUR"

        #   - ts: "1474580776.000003"

        #   - team: "T020WVADD"

        #   - ...

        # env.matches - MatchData object with captured values:

        #   - amount: 10000

        #   - from: RUB

        #   - to: EUR

      end

    end



    # Add prefix to all routes

    prefix 'Hi (?\w+),\s+' do

      # Matches string like "Hi Dave, blah blah blah" and "Dave" will be captured in env.matches[:name]

      match /.*/, controller: GreetingsController

    end

  end

end

```



Configure Slack client:



```ruby

Slack.configure do |c|

  c.token = 'xxxx-9295867...'

  c.logger = Logger.new(STDOUT)

  c.logger.level = Logger::INFO

end

```



And run the bot: `Robot.run`, `Robot.run(async: true)`.



Also you can manually create the bot and give to him a prepared client:



```ruby

client = Slack::RealTime::Client.new(options)

robot  = Robot.new(client, async: true)

robot.run

```



### Routes



There are three methods for creating routes: `match`, `command` and `default`:



- `match(regexp, options, &block)` - Add route based on regular expression.

  - `regexp` - Regular expression.

  - `options` - Options that adjust route behavior.

    - `prefix` - Add prefix for regular expression, default: `/.*/`. If you want to delete prefix you should use `prefix: false`. `prefix: nil` resets prefix to default value.

    - `direct` -  Uses to create direct route. This’s route that directly address to bot. Messages without `<@botname>` at the start of command will be rejected.

    - `controller` - Any class or object that has `call` method. It can be instance or class method.

  - `block` - It will be used as controller when block is defined.



- `command(*commands, options, block)` - Construct a regular expression using command names and add route using `match`. Check examples.



  ```ruby

  # Equals to: match(/(?convert|c)\s+(?\d+)\s*(?[A-Z]{3})\s+into\s+(?[A-Z]{3})/) { |env| }

  command 'convert', 'c', amount: /\d+/, from: /[A-Z]{3}/, into: 'into', to: /[A-Z]{3}/, delimiter: /\s+/ do |env|

    # "convert 10000 RUB into EUR"

    # `env.matches` is:

    #  - command: "convert"

    #  - amount: 10000

    #  - from: "RUB"

    #  - to: "EUR"

  end

  ```



  Example:



  ```ruby

  command 'add', 'subtract', 'multiply', 'divide', first: /\d+/, second: /\d+/ do |env|

    result = case env.matches[:command]

    when 'add'

      env.matches[:first].to_i + env.matches[:second].to_i

    when 'subtract'

      env.matches[:first].to_i - env.matches[:second].to_i

    when 'multiply'

      env.matches[:first].to_i * env.matches[:second].to_i

    when 'divide'

      env.matches[:first].to_i / env.matches[:second].to_i

    end



    env.client.message(channel: env.data.channel, text: result.to_s)

  end

  ```



- `default(options, block)` - Create default route. It will be used if no one route was matched.



### Controllers



TODO:



### Inheritance



All routes and event handlers from parent class and subclass will be merged when we inherit one bot from another one.



## Contributing



Bug reports and pull requests are welcome on GitHub at https://github.com/undr/walle.



## License



The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).