skit

package module
Version: v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 14, 2021 License: MIT Imports: 11 Imported by: 0

README

skit

GoDoc Build Status Go Report Card

Skit is a simple tool/library written in Go (or Golang) for building Slack bots. Skit pre-compiled binary is good enough to build simple slack bots. For more complex usecases skit can be used as a library as well.

Installation

Simply download the pre-built binary for your platform from the Releases section.

Usage

Pre-compiled Binary

Release archive will contain a skit.toml file with some sample handlers setup. To run this default setup:

  1. Create a bot on slack by following Documentation
  2. Set slack token generated for the bot in skit.toml
  3. Run skit -c skit.toml
  4. Go to slack and find the bot which you created and chat!
skit.toml configuration file

Following skit.toml file can be used to setup a simple slack bot that passes any message sent to it to a shell script bot.sh. The output of this script will be sent back as the response.

token = "your-token-here"
log_level = "info"

[[handlers]]
name = "matcha_all"
type = "command"
match = [
  ".*"
]
cmd = "./bot.sh"
args = [
  "{{ .event.Text }}"
]

See examples/ for samples of different handler configurations.

As a library

Following sample shows how to build a simple bot that echo's everything you say to it!

sk:= skit.New("your-token", logrus.New())
sk.Register("echo_all", skit.SimpleHandler("{{.event.Text}}",  ".*"))
sk.Listen(context.Background())

Handlers

A handler is an implementation of skit.Handler interface. A handler is responsible for consuming event, processing and responding to it when applicable. Currently 3 types of handlers are available.

1. simple
  • simple handler can be used to build simple regex based conversational bot.

  • Following sample shows how to configure simple handler:

    [[handlers]]
    name = "simple_bot"
    type = "simple"
    match = [
      "my name is (?P<name>.*)"
    ]
    message = "Hello there {{ .name }}!"
    
2. command
  • command handler can be used to delegate the message handling responsibility to external command

  • This allows building bots which are more complex than the ones built with simple

  • Following sample shows how to configure command handler:

    [[handlers]]
    name = "external_command"
    type = "command"
    match = [
      ".*"
    ]
    cmd = "./hello.sh"
    args = [
      "{{ .event.Text }}"
    ]
    timeout = "5s"
    
3. lua
  • lua allows writing handlers using Lua script which will be executed using embedded Gopher-Lua

  • Lua code will have access to skit instance and its APIs and can be used build complex bots.

  • You can provide paths to be added to LUA_PATH as paths in the following config.

  • In the config sample below, source can be any valid lua code. So you can put your handler code in a file (e.g., handler.lua) under one of the paths and use source="require('handler')" in the handler config.

  • Following sample shows how to configure lua handler:

    [[handlers]]
    name = "lua_handler"
    type = "lua"
    handler = "handle_event"
    paths = []
    source = """
      function handle_event(ctx, sk, event)
        sk:SendText(ctx, "Hello from Lua!", event.Channel)
        return true
      end
    """
    

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CaptureAll

func CaptureAll(regEx *regexp.Regexp, s string) map[string]interface{}

CaptureAll matches s with the regex and returns all named capture values. Returns nil if the s was not a match.

func ParseExprs

func ParseExprs(exprs []string) ([]*regexp.Regexp, error)

ParseExprs parses given list of regular expressions and returns the compiled objects.

func Render

func Render(tpl template.Template, data interface{}) (string, error)

Render executes the template with data and returns the rendered string.

func RenderAll

func RenderAll(tpls []template.Template, data interface{}) ([]string, error)

RenderAll executes all templates passed in with the data and returns the rendered strings. Returns nil and an error on first execution failure.

func RenderString added in v0.0.5

func RenderString(tplStr string, data interface{}) (string, error)

RenderString creates template from tplStr and executes the template with data and returns the rendered string.

Types

type Command

type Command struct {
	Timeout     time.Duration
	RedirectErr bool
	WorkingDir  string
	// contains filtered or unexported fields
}

Command runs configured command when the message matches the regular expressions.

func CommandHandler

func CommandHandler(cmd string, args []string, patterns []string) (*Command, error)

CommandHandler executes a configured command when input message matches one of the regex patterns. cmd and args both will be parsed as golang text templates. Named captures from pattern that matches the input message will be used as data for rendering command name and every argument.

func (*Command) Handle

func (cmd *Command) Handle(ctx context.Context, sk *Skit, ev *MessageEvent) bool

Handle executes the command when the message matches the regular expressions.

type Handler

type Handler interface {

	// Handle should return true if the message event was handled by it. If this
	// function returns false, skit will execute the next Handler available and
	// so on.
	Handle(ctx context.Context, sk *Skit, ev *MessageEvent) bool
}

Handler is responsible for handling slack message events.

func SimpleHandler

func SimpleHandler(tplStr string, exps ...string) (Handler, error)

SimpleHandler responds with a simple message if the input message matches one of the regular expressions. The message (argument tplStr) can be a golang text template. Named captures from the regex that matches the input message will be used as data for rendering the message template.

type HandlerFunc

type HandlerFunc func(ctx context.Context, sk *Skit, ev *MessageEvent) bool

HandlerFunc implements Handler interface using function type.

func (HandlerFunc) Handle

func (hf HandlerFunc) Handle(ctx context.Context, sk *Skit, ev *MessageEvent) bool

Handle dispatches the call to the wrapped function.

type Logger

type Logger interface {
	Debugf(msg string, args ...interface{})
	Infof(msg string, args ...interface{})
	Warnf(msg string, args ...interface{})
	Errorf(msg string, args ...interface{})
}

Logger implementation is responsible for providing logging functions.

type MessageEvent

type MessageEvent slack.MessageEvent

MessageEvent represents a slack message event.

type Skit

type Skit struct {
	Logger

	NoHandler          template.Template
	RouteGroupMessages bool
	Client             *slack.Client
	// contains filtered or unexported fields
}

Skit represents an instance of skit.

func New

func New(token string, logger Logger) *Skit

New initializes an instance of skit with default event handlers.

func (*Skit) Listen

func (sk *Skit) Listen(ctx context.Context) error

Listen connects to slack with the given configurations and starts the event loop

func (*Skit) Register

func (sk *Skit) Register(name string, handler Handler)

Register a handler to handle message events. Handlers will be executed in the order they are registered in.

func (*Skit) SendText

func (sk *Skit) SendText(ctx context.Context, msg string, channel string) error

SendText sends the given message to the channel.

Directories

Path Synopsis
cmd
handlers
lua

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL