Sfoglia il codice sorgente

Adds the README with instructions.

Abhinav Sarkar 7 anni fa
parent
commit
b2de146bfb
1 ha cambiato i file con 146 aggiunte e 0 eliminazioni
  1. 146
    0
      README.md

+ 146
- 0
README.md Vedi File

@@ -0,0 +1,146 @@
1
+#Hircarra
2
+
3
+> hircarra (plural hircarras)
4
+> (historical, India) A messenger, especially one who delivers a personal message.
5
+
6
+Hircarra is a Haskell library to write [IRC][1] bots. It is meant to be very easy to use and completely extensible. It provides a core on which users can add support for their own IRC messages and replies and handlers. It also comes with a set of handlers (in the hircarra-handlers package) which provide a varied set of functionalities.
7
+
8
+
9
+## Example Usage
10
+
11
+To start an IRC with no handlers:
12
+
13
+```
14
+$ cabal repl
15
+*Network.IRC> let botConfig = newBotConfig "irc.freenode.net" 6667 "#hircarra" (Nick "hibot") 130 DEBUG
16
+*Network.IRC> runBot botConfig
17
+[2015-06-29 17:37:33] Network.IRC.Client DEBUG Connecting ...
18
+[2015-06-29 17:37:33] Network.IRC.Client DEBUG Connected
19
+[2015-06-29 17:37:33] Network.IRC.Client DEBUG Loading msg handler: help
20
+[2015-06-29 17:37:33] Network.IRC.Client DEBUG Loading msg handler: pingpong
21
+[2015-06-29 17:37:33] Network.IRC.Client DEBUG Running with config:
22
+BotConfig {
23
+server = "irc.freenode.net"
24
+port = 6667
25
+channel = "#hircarra"
26
+nick = hibot
27
+timeout = 130
28
+handlers = ["help","pingpong"] }
29
+[2015-06-29 17:37:33] Network.IRC.Bot INFO > NICK hibot
30
+[2015-06-29 17:37:33] Network.IRC.Bot INFO > USER hibot 0 * :hibot
31
+[2015-06-29 17:37:33] Network.IRC.Bot INFO < :sinisalo.freenode.net NOTICE * :*** Looking up your hostname...
32
+[2015-06-29 17:37:33] Network.IRC.Bot INFO < :sinisalo.freenode.net NOTICE * :*** Checking Ident
33
+[2015-06-29 17:37:33] Network.IRC.Bot INFO < :sinisalo.freenode.net NOTICE * :*** Couldn't look up your hostname
34
+[2015-06-29 17:37:39] Network.IRC.Bot INFO < :sinisalo.freenode.net NOTICE * :*** No Ident response
35
+[2015-06-29 17:37:39] Network.IRC.Bot INFO < :sinisalo.freenode.net 001 hibot :Welcome to the freenode Internet Relay Chat Network hibot
36
+[2015-06-29 17:37:39] Network.IRC.Bot INFO < :hibot MODE hibot :+i
37
+[2015-06-29 17:37:39] Network.IRC.Bot INFO > JOIN #hircarra
38
+[2015-06-29 17:37:45] Network.IRC.Bot INFO < :hibot!~hibot@106.51.139.38 JOIN #hircarra
39
+[2015-06-29 17:37:45] Network.IRC.Bot INFO Joined
40
+[2015-06-29 17:37:45] Network.IRC.Bot INFO < :sinisalo.freenode.net 353 hibot @ #hircarra :hibot @abh
41
+[2015-06-29 17:37:45] Network.IRC.Bot INFO < :sinisalo.freenode.net 366 hibot #hircarra :End of /NAMES list.
42
+[2015-06-29 17:38:40] Network.IRC.Bot INFO > PING :1435599520
43
+[2015-06-29 17:38:40] Network.IRC.Bot INFO < :sinisalo.freenode.net PONG sinisalo.freenode.net :1435599520
44
+[2015-06-29 17:39:46] Network.IRC.Bot INFO > PING :1435599586
45
+[2015-06-29 17:39:47] Network.IRC.Bot INFO < :sinisalo.freenode.net PONG sinisalo.freenode.net :1435599586
46
+[2015-06-29 17:40:08] Network.IRC.Bot INFO < :abh!~znc@128.199.183.32 PRIVMSG #hircarra :hi hibot
47
+^C[2015-06-29 17:40:13] Network.IRC.Client DEBUG User interrupt
48
+[2015-06-29 17:40:13] Network.IRC.Client DEBUG Disconnecting ...
49
+[2015-06-29 17:40:13] Network.IRC.Client DEBUG Stopping msg handler: pingpong
50
+[2015-06-29 17:40:13] Network.IRC.Client DEBUG Stopping msg handler: help
51
+[2015-06-29 17:40:13] Network.IRC.Bot INFO > QUIT
52
+[2015-06-29 17:40:14] Network.IRC.Bot INFO < :hibot!~hibot@106.51.139.38 QUIT :Client Quit
53
+[2015-06-29 17:40:14] Network.IRC.Client DEBUG Disconnected
54
+```
55
+
56
+## Features
57
+
58
+Core features:
59
+
60
+1. Very simple interface. Just create a `BotConfig` and call `runBot` with it.
61
+2. Automatically handles disconnetions and reconnections.
62
+3. Automatically changes nick if not available and recovers the original nick when it becomes available.
63
+4. Comes with standard IRC command support built in but users can extend it to add support for custom IRC commands.
64
+5. Users can add handlers which can react to IRC commands from channels and from private messages.
65
+
66
+## Writing Handlers
67
+
68
+Let's write a simple echo handler:
69
+
70
+```
71
+$ ghci -package-db=./.cabal-sandbox/x86_64-osx-ghc-7.8.3-packages.conf.d            
72
+GHCi, version 7.8.3: http://www.haskell.org/ghc/  :? for help
73
+Loading package ghc-prim ... linking ... done.
74
+Loading package integer-gmp ... linking ... done.
75
+Loading package base ... linking ... done.
76
+Prelude> :m +Data.Map
77
+Prelude Data.Map> :m +Network.IRC
78
+Prelude Data.Map Network.IRC> :set +m
79
+Prelude Data.Map Network.IRC> :set -XOverloadedStrings
80
+Prelude Data.Map Network.IRC> let echoHandler = MsgHandlerMaker "echo" $ \ _ _ -> return $ newMsgHandler {
81
+Prelude Data.Map Network.IRC|   onMessage = \ Message { message = message } ->
82
+Prelude Data.Map Network.IRC|     case fromMessage message of
83
+Prelude Data.Map Network.IRC|       Just (ChannelMsg _ msg) -> do
84
+Prelude Data.Map Network.IRC|         reply <- newMessage (ChannelMsgReply msg)
85
+Prelude Data.Map Network.IRC|         return [reply]
86
+Prelude Data.Map Network.IRC|       _ -> return []
87
+Prelude Data.Map Network.IRC| }
88
+Prelude Data.Map Network.IRC|
89
+Prelude Data.Map Network.IRC> let botConfig = newBotConfig "irc.freenode.net" 6667 "#hircarra" (Nick "hibot") 130 DEBUG
90
+Prelude Data.Map Network.IRC> let botConfigWithHandler = botConfig { msgHandlerMakers = singleton "echo" echoHandler, msgHandlerInfo = singleton "echo" empty }
91
+Prelude Data.Map Network.IRC|
92
+Prelude Data.Map Network.IRC> runBot botConfigWithHandler
93
+[2015-06-29 18:28:43] Network.IRC.Client DEBUG Connecting ...
94
+[2015-06-29 18:28:43] Network.IRC.Client DEBUG Connected
95
+[2015-06-29 18:28:43] Network.IRC.Client DEBUG Loading msg handler: echo
96
+[2015-06-29 18:28:43] Network.IRC.Client DEBUG Loading msg handler: help
97
+[2015-06-29 18:28:43] Network.IRC.Client DEBUG Loading msg handler: pingpong
98
+[2015-06-29 18:28:43] Network.IRC.Client DEBUG Running with config:
99
+BotConfig {
100
+server = "irc.freenode.net"
101
+port = 6667
102
+channel = "#hircarra"
103
+nick = hibot
104
+timeout = 130
105
+handlers = ["echo","help","pingpong"] }
106
+[2015-06-29 18:28:43] Network.IRC.Bot INFO > NICK hibot
107
+[2015-06-29 18:28:43] Network.IRC.Bot INFO > USER hibot 0 * :hibot
108
+[2015-06-29 18:28:44] Network.IRC.Bot INFO < :wilhelm.freenode.net NOTICE * :*** Looking up your hostname...
109
+[2015-06-29 18:28:44] Network.IRC.Bot INFO < :wilhelm.freenode.net NOTICE * :*** Checking Ident
110
+[2015-06-29 18:28:44] Network.IRC.Bot INFO < :wilhelm.freenode.net NOTICE * :*** Couldn't look up your hostname
111
+[2015-06-29 18:28:50] Network.IRC.Bot INFO < :wilhelm.freenode.net NOTICE * :*** No Ident response
112
+[2015-06-29 18:28:50] Network.IRC.Bot INFO < :wilhelm.freenode.net 001 hibot :Welcome to the freenode Internet Relay Chat Network hibot
113
+[2015-06-29 18:28:50] Network.IRC.Bot INFO < :hibot MODE hibot :+i
114
+[2015-06-29 18:28:50] Network.IRC.Bot INFO > JOIN #hircarra
115
+[2015-06-29 18:28:56] Network.IRC.Bot INFO < :hibot!~hibot@106.51.139.38 JOIN #hircarra
116
+[2015-06-29 18:28:56] Network.IRC.Bot INFO Joined
117
+[2015-06-29 18:28:56] Network.IRC.Bot INFO < :wilhelm.freenode.net 353 hibot @ #hircarra :hibot @abh
118
+[2015-06-29 18:28:56] Network.IRC.Bot INFO < :wilhelm.freenode.net 366 hibot #hircarra :End of /NAMES list.
119
+[2015-06-29 18:29:00] Network.IRC.Bot INFO < :abh!~znc@128.199.183.32 PRIVMSG #hircarra :test test
120
+[2015-06-29 18:29:00] Network.IRC.Bot INFO > PRIVMSG #hircarra :test test
121
+[2015-06-29 18:29:06] Network.IRC.Bot INFO < :abh!~znc@128.199.183.32 PRIVMSG #hircarra :repeater
122
+[2015-06-29 18:29:06] Network.IRC.Bot INFO > PRIVMSG #hircarra :repeater
123
+^C[2015-06-29 18:29:10] Network.IRC.Client DEBUG User interrupt
124
+[2015-06-29 18:29:10] Network.IRC.Client DEBUG Disconnecting ...
125
+[2015-06-29 18:29:10] Network.IRC.Client DEBUG Stopping msg handler: echo
126
+[2015-06-29 18:29:10] Network.IRC.Client DEBUG Stopping msg handler: help
127
+[2015-06-29 18:29:10] Network.IRC.Client DEBUG Stopping msg handler: pingpong
128
+[2015-06-29 18:29:10] Network.IRC.Bot INFO > QUIT
129
+[2015-06-29 18:29:11] Network.IRC.Client DEBUG Disconnected
130
+```
131
+
132
+Here is how the conversation looked in an IRC client:
133
+
134
+> [23:58:56] 	hibot (~hibot@106.51.139.38) joined the channel
135
+> 
136
+> [23:58:59]  <@abh>	test test
137
+> 
138
+> [23:59:00]  <hibot>	test test
139
+> 
140
+> [23:59:05]  <@abh>	repeater
141
+> 
142
+> [23:59:06]  <hibot>	repeater
143
+> 
144
+> [23:59:11] 	hibot (~hibot@106.51.139.38) left IRC (Client Quit)
145
+
146
+[1]: https://en.wikipedia.org/wiki/Irc

Loading…
Annulla
Salva