graw

README

graw

go get github.com/turnage/graw

graw is a library for building Reddit bots that takes care of everything you don't want to. Read the tutorial book!

As of major version 1, the API promise is: no breaking changes, ever. Details below. This applies to all (library) subpackages of graw.

Usage

The design of graw is that your bot is a handler for events, Reddit is a source of events, and graw connects the two. If you want to announce all the new posts in a given subreddit, this is your bot:

type announcer struct {}

func (a *announcer) Post(post *reddit.Post) error {
        fmt.Printf(`%s posted "%s"\n`, post.Author, post.Title)
        return nil
}

Give this to graw with an api handle from the reddit package and a tell it what events you want to subscribe to; graw will take care of the rest. See the godoc and tutorial book for more information.

Features

The primary feature of graw is robust event streams. graw supports many exciting event streams:

• New posts in subreddits.
• New comments in subreddits.
• New posts or comments by users.
• Private messages sent to the bot.
• Replies to the bot's posts.
• Replies to the bot's comments.
• Mentions of the bot's username.

Processing all of these events is as as simple as implementing a method to receive them!

graw also provides two lower level packages for developers to tackle other interactions with Reddit like one-shot scripts and bot actions. See subdirectories in the godoc.

API Promise

As of version 1.0.0, the graw API is stable. I will not make any backwards incompatible changes, ever. The only exceptions are:

• I may add methods to an interface. This will only break you if you embed it and implement a method with the same name as the one I add.
• I may add fields to the Config struct. This will only break you if you embed it and add a field with the same name as the one I add, or initialize it positionally.

I don't foresee anyone having a reason to do either of these things.

Documentation

Overview

Package graw is a high level, easy to use, Reddit bot library.

graw will take a low level handle from the graw/reddit package and manage everything for you. You just specify in a config what events you want to listen to on Reddit, and graw will take care of maintaining the event stream and calling the handler methods of your bot whenever new events occur.

Announcing new posts in /r/self is as simple as:

type announcer struct{}

func (a *announcer) Post(post *reddit.Post) error {
  fmt.Printf(`%s posted "%s"\n`, post.Author, post.Title)
  return nil
}

.....

// Get an api handle to reddit for a logged out (script) program,
// which forwards this user agent on all requests and issues a request at
// most every 5 seconds.
apiHandle := reddit.NewScript("your user agent", 5 * time.Second)

// Create a configuration specifying what event sources on Reddit graw
// should connect to the bot.
cfg := graw.Config{Subreddits: []string{"self"}}

// launch a graw scan in a goroutine using the bot, handle, and config. The
// returned "stop" and "wait" are functions. "stop" will stop the graw run
// at any time, and "wait" will block until it finishes.
stop, wait, err := graw.Scan(&announcer{}, apiHandle, cfg)

// This time, let's block so the bot will announce (ideally) forever.
if err := wait(); err != nil {
  fmt.Printf("graw run encountered an error: %v\n", err)
}

graw can handle many event sources on Reddit; see the Config struct for the complete set of offerings.

graw has one other function that behaves like Scan(), which is Run(). Scan() is for logged-out bots (what Reddit calls "scripts"). Run() handles logged in bots, which can subscribe to logged-in event sources in the bot's account inbox like mentions and private messages.

Index

• func Run(handler interface{}, bot reddit.Bot, cfg Config) (func(), func() error, error)
• func Scan(handler interface{}, script reddit.Script, cfg Config) (func(), func() error, error)
• type Config

Functions

func Run

func Run(handler interface{}, bot reddit.Bot, cfg Config) (
	func(),
	func() error,
	error,
)

Run connects a handler to any requested event sources and makes requests with the given bot api handle. It launches a goroutine for the run. It returns two functions, a stop() function to terminate the graw run at any time, and a wait() function to block until the graw run fails.

func Scan

func Scan(handler interface{}, script reddit.Script, cfg Config) (
	func(),
	func() error,
	error,
)

Scan connects any requested logged-out event sources to the given handler, making requests with the given script handle. It launches a goroutine for the scan. It returns two functions: a stop() function to stop the scan at any time, and a wait() function to block until the scan fails.

Types

type Config

type Config struct {
	// New posts in all subreddits named here will be forwarded to the bot's
	// PostHandler.
	Subreddits []string
	// New comments in all subreddits named here will be forwarded to the
	// bot's CommentHandler.
	SubredditComments []string
	// New posts and comments made by all users named here will be forwarded
	// to the bot's UserHandler. Note that since a separate monitor must be
	// construced for every user, unlike subreddits, subscribing to the
	// actions of many users can delay updates from other event sources.
	Users []string
	// When true, replies to posts made by the bot's account will be
	// forwarded to the bot's PostReplyHandler.
	PostReplies bool
	// When true, replies to comments made by the bot's account will be
	// forwarded to the bot's CommentReplyHandler.
	CommentReplies bool
	// When true, mentions of the bot's username  will be forwarded to the
	// bot's MentionHandler.
	Mentions bool
	// When true, messages sent to the bot's inbox will be forwarded to the
	// bot's MessageHandler.
	Messages bool
	// If set, internal messages will be logged here. This is a spammy log
	// used for debugging graw.
	Logger *log.Logger
}

Config configures a graw run or scan by specifying event sources. Each event type has a corresponding handler defined in graw/botfaces. The bot must be able to handle requested event types.