PLUGINS

   1 # Writing rawdog plugins
   2
   3 ## Introduction
   4
   5 As provided, rawdog provides a fairly small set of features. In order to
   6 make it do more complex jobs, rawdog can be extended using plugin
   7 modules written in Python. This document is intended for developers who
   8 want to extend rawdog by writing plugins.
   9
  10 Extensions work by registering hook functions which are called by
  11 various bits of rawdog's core as it runs. These functions can modify
  12 rawdog's internal state in various interesting ways. An arbitrary number
  13 of functions can be attached to each hook; they are called in the order
  14 they were attached. Hook functions take various arguments depending on
  15 where they're called from, and returns a boolean value indicating
  16 whether further functions attached to the same hook should be called.
  17
  18 The "plugindirs" config option gives a list of directories to search for
  19 plugins; all Python modules found in those directories will be loaded by
  20 rawdog. In practice, this means that you need to call your file
  21 something ending in ".py" to have it recognised as a plugin.
  22
  23 ## Hooks
  24
  25 Most hook functions are called with "rawdog" and "config" as their first
  26 two arguments; these are references to the aggregator's Rawdog and
  27 Config objects.
  28
  29 If you need a hook that doesn't currently exist, please contact me.
  30
  31 The following hooks are supported:
  32
  33 ### startup(rawdog, config)
  34
  35 Run when rawdog starts up, after the state file and config file have
  36 been loaded, but before rawdog starts processing command-line arguments.
  37
  38 ### shutdown(rawdog, config)
  39
  40 Run just before rawdog saves the state file and exits.
  41