Browse Source

improved documentation

Vishnu S Iyengar 6 years ago
parent
commit
c75fc4e6b8
7 changed files with 77 additions and 24 deletions
  1. 19
    10
      Readme.md
  2. 2
    2
      modules.coffee
  3. 50
    7
      modules/Readme.md
  4. 1
    1
      modules/google.coffee
  5. 2
    1
      modules/imdb_url_identifier.coffee
  6. 1
    1
      modules/seen.coffee
  7. 2
    2
      modules/tell.coffee

+ 19
- 10
Readme.md View File

@@ -1,20 +1,29 @@
1
-Irc bot written in coffeescript
1
+# Irc bot written in coffeescript #
2 2
 
3
-setup instructions
4
-install node.js and npm
5
-clone the repo
3
+## setup instructions ##
6 4
 
7
-on the commandline
8
-npm install
9
-./bin/setup
10
-edit data/settings.json and fill in the settings
5
+1. install node.js and npm
6
+2.  clone the repo
7
+3.  on the commandline
11 8
 
12
-to run
13
-./bin/bot
9
+> npm install
10
+>
11
+> ./bin/setup
12
+>
13
+> edit data/settings.json and fill in the settings
14 14
 
15
+## to run ##
16
+> ./bin/bot
17
+
18
+## modules ##
15 19
 modules sit inside the modules directory
16 20
 check the Readme there to create new modules
17 21
 
22
+## limitations ##
23
+Currently the bot assumes that you only want to sit in one channel. This assumption
24
+is baked into a lot of the core functionality and modules.
25
+
26
+
18 27
 other dependencies by now
19 28
 libicu-dev
20 29
 libexpat1-dev

+ 2
- 2
modules.coffee View File

@@ -2,8 +2,8 @@ fs = require("fs")
2 2
 modules = (require("./modules/#{f}") for f in fs.readdirSync("./modules") when f.match /\.(?:js|coffee)$/)
3 3
 
4 4
 class Modules
5
-  constructor: (users, settings, emittor) ->
6
-    instances = modules.map (Module_x) -> new Module_x(users, settings, emittor)
5
+  constructor: (users, settings, emitter) ->
6
+    instances = modules.map (Module_x) -> new Module_x(users, settings, emitter)
7 7
     @_commands = _({}).extend(_(instances).pluck('commands')...)
8 8
     @_listeners = _(instances).chain().
9 9
       pluck('listeners').

+ 50
- 7
modules/Readme.md View File

@@ -1,10 +1,53 @@
1
-Modules provide various peices of functionality.
1
+# Modules #
2
+
3
+Modules provide various pieces of functionality.
4
+
5
+## Creating ##
6
+
7
+To create a module, you have to create a new file.
2 8
 Each javascript or coffeescript file in this directory defines a new module.
9
+every module should export a constructor.
10
+your constructor will get called with
11
+
12
+* a reference to the user database which you can use to store and retrieve data
13
+
14
+* the settings so you can retrieve specific settings for your plugin
15
+
16
+* an emitter which you can use to emit text onto the channel
17
+
18
+## Functionality ##
19
+	Any module can provide any combination of the following types of functionality.
20
+
21
+1. any number of commands executed by typing *!<command_name> <arguments>* on the channel.
22
+2. any number of private commands executed by pming the bot.
23
+3. any number of listeners that automatically act on seeing some text.
24
+4. proactively put text in the channel (for example in response to some external stimulus)
25
+
26
+A module is just a discrete chunk of functionality and does not need to be exclusively one
27
+of the above types but any combination that makes sense as a whole.
28
+
29
+### Commands ###
30
+
31
+to expose commands your module must expose a property called *commands* which is a mapping from
32
+the command_name to functions that are invoked when the command is called.
33
+
34
+* the command gets these parameters
35
+	1. receives the nick of the person who invoked it.
36
+	2. the remaining text on that line.
37
+	3. a function that can be invoked to respond to the command.
38
+* if the command function has a property called *_help*, it is automatically displayed when someone
39
+types *!help <command_name>*
40
+* for examples look at the modules **google** or **nicks**
41
+
42
+### Private Commands ###
43
+
44
+TBD
3 45
 
4
-To create a module, you have to export a constructor which is invoked with a copy of the
5
-user database and the settings.
46
+### Listeners ###
6 47
 
7
-a module can provide
8
- 1) a map called commands which are commands invoked from the channel.
9
- 2) a map called privateCommands, which are privateCommands invoked via pm.
10
- 3) an array called listeners which get each line printed on the channel and can respond to it.
48
+* listeners get a copy of every message and can react to them if necessary. When invoked a
49
+listener receives
50
+	1. the nick of the person who sent the message
51
+	2. the remaining text on that line
52
+* the listener does not receive messages emitted by the bot.
53
+* for examples look at the modules **imdb\_url\_identifier** or **tell**

+ 1
- 1
modules/google.coffee View File

@@ -1,7 +1,7 @@
1 1
 _ = require('../utils')
2 2
 
3 3
 class Google
4
-  constructor: (@users, @settings) ->
4
+  constructor: (users, @settings) ->
5 5
     @commands = {g: @command}
6 6
     @command._help = "search google for the terms you're looking for. !g <terms> for the first result. !g x <terms> for the xth result"
7 7
 

+ 2
- 1
modules/imdb_url_identifier.coffee View File

@@ -1,3 +1,4 @@
1
+# Prints out details about an IMDB url
1 2
 _ = require('../utils')
2 3
 RegexUrlMatcher = require("#{__dirname}/base/regex_url_matcher")
3 4
 param_string = _({v: 2,alt: "jsonc"}).stringify()
@@ -10,6 +11,6 @@ class ImdbUrlIdentifier extends RegexUrlMatcher
10 11
     _.request {uri: url}, (error, response, body) =>
11 12
       if not error and response.statusCode is 200
12 13
         {Title, Year, Plot} = JSON.parse(body)
13
-        @emittor "ah #{from} is talking about #{Title} (#{Year}) which is about #{Plot}"
14
+        @emitter "ah #{from} is talking about #{Title} (#{Year}) which is about #{Plot}"
14 15
 
15 16
 module.exports = ImdbUrlIdentifier

+ 1
- 1
modules/seen.coffee View File

@@ -1,7 +1,7 @@
1 1
 _ = require('../utils')
2 2
 
3 3
 class Seen
4
-  constructor: (@users, settings, @emittor) ->
4
+  constructor: (@users, settings, @emitter) ->
5 5
     @commands = {seen: @command}
6 6
     # @listeners = [@listener]
7 7
     @command._help = "let's you know when a user was last seen online and last spoke in the channel. Also should end up triggering his/her nick alert ;) "

+ 2
- 2
modules/tell.coffee View File

@@ -2,7 +2,7 @@ directed_message = require "#{__dirname}/base/directed_message"
2 2
 _ = require('../utils')
3 3
 
4 4
 class Tell
5
-  constructor: (@users, settings, @emittor) ->
5
+  constructor: (@users, settings, @emitter) ->
6 6
     @commands = {tell: @command}
7 7
     @listeners = [@listener]
8 8
     @command._help = "publically passes a message to a user whenever he/she next speaks. usage: !tell <user> <message>"
@@ -17,7 +17,7 @@ class Tell
17 17
     tells = @users.getTells(from)
18 18
     return if _(tells).isEmpty()
19 19
     _(tells).each (item) =>
20
-      @emittor "#{from}:#{item.from} said '#{item.msg}' #{_.date(item.time).fromNow()}"
20
+      @emitter "#{from}:#{item.from} said '#{item.msg}' #{_.date(item.time).fromNow()}"
21 21
     @users.clearTells from
22 22
 
23 23
 module.exports = Tell

Loading…
Cancel
Save