Browse Source

Convert top level docs to asciidoc

tags/v1.1.0
Chris Smith 5 months ago
parent
commit
23c03673c8
4 changed files with 359 additions and 347 deletions
  1. 0
    202
      CHANGELOG
  2. 209
    0
      CHANGELOG.adoc
  3. 20
    20
      LICENCE.adoc
  4. 130
    125
      README.adoc

+ 0
- 202
CHANGELOG View File

@@ -1,202 +0,0 @@
1
-vNEXT (in development)
2
-
3
- * Away support:
4
-   * Added sendAway() method
5
-   * Added UserAway event and fanned-out ChannelAway
6
-   * Away message is now updated in the UserState
7
- * Added IrcClient.localUser property, returning the local User
8
- * Deprecated ServerState.localNickname in favour of localUser.
9
- * (Internal) improved the way byte buffers are used to
10
-   reduce array copying and clean up code
11
-
12
-v1.0.1
13
-
14
- * Fixed issue with very long packets not fitting in buffers
15
-   after TLS decryption.
16
- * Improved error message when IrcClient.connect() is called
17
-   while already connected
18
- * Made IrcClient.disconnect() block until the disconnect has
19
-   been processed. This will be a very short period of time,
20
-   and allows callers to immediately call connect() again
21
-   afterwards if they wish
22
- * Fixed various issues with disconnecting TLS connections
23
-   not behaving correctly
24
-
25
-v1.0.0
26
-
27
- * Replaced Ktor dependency with custom socket handling, which fixes
28
-   fatal issue when connecting to servers over TLS that request a
29
-   client certificate.
30
- * Added NicknameChangeRequired event for the case when a nickname is
31
-   not allowed during connection and *MUST* be changed
32
- * BREAKING: Added 'PreferIPv6' behaviour config, defaulting to true.
33
-   With this configuration KtIrc will try to use IPv6 if the server
34
-   publishes AAAA records.
35
- * BREAKING: Default port is now 6697, TLS is enabled by default
36
-
37
-v0.11.0
38
-
39
- * Added SourcedEvent interface for events that have a user source attached
40
- * Added ChannelJoinFailed event
41
- * Added ChannelMembershipAdjustment interface for events that concern
42
-   users joining/leaving channels
43
- * Added missing user parameter to ModeChangedEvent
44
-
45
-v0.10.3
46
-
47
- * Fix issue parsing CTCPs when the content contained multi-byte chars
48
- * Fixed multiple issues when receiving malformed input from the server:
49
-   * Invalid server-time tags are now ignored and the current time used
50
-   * PRIVMSGs, NOTICEs and TOPICs with no target/message are now ignored
51
-   * CAPs with invalid or missing arguments are now ignored
52
-   * Better handling for duplicate JOIN messages
53
-   * Ignored messages are now logged more consistently
54
-
55
-v0.10.2
56
-
57
- * Fix handling of multiple long lines sometimes dropping part of the line
58
- * Support lines with 8191 bytes of tags, as allowed by the message-tags spec
59
- * Fix a few more instances of occasional ConcurrentModificationExceptions
60
-
61
-v0.10.1
62
-
63
- * Added NickChangeFailed event for when nicknames are in use, banned, etc
64
- * Added sendPart method
65
- * Fix occasional ConcurrentModificationException when adding state
66
- * (Internal) Moved message processors into their own package
67
- * (Internal) Added ExperimentalIrcClient interface for features not yet ready for release
68
-
69
-v0.10.0
70
-
71
- * Batch start and end events are no longer included in BatchReceived events
72
- * Batches now expose complete metadata from their start event
73
- * Added support for labelled-replies capability and label message tags
74
- * Added support for message-tags capability after it moved from draft
75
- * Added new methods for sending raw lines to the IRC server
76
-   * send(tagMap(...), command, arguments) replaces send(line)
77
-   * send(command, arguments) is available if no tags are to be sent
78
-   * the line is built automatically (with spaces/' :' added appropriately)
79
-   * send(line) is deprecated and will be removed after v1.0.0
80
- * Add 'alwaysEchoMessages' behaviour that makes it easier to deal with servers
81
-   that don't support the echo message capability
82
- * Added TargetedEvent, a subclass of IrcEvent, for all events that are
83
-   targeted to a user or channel
84
- * (Internal) Added annotation to track removal of deprecated methods
85
- * (Internal) Migrate unit tests to use Mockk instead of Mockito
86
-
87
-v0.9.0
88
-
89
- * Improve DSL for creating an IrcClient to allow parameters to be passed to server and profile
90
-   e.g. IrcClient { server("irc.example.com", 6667) }
91
- * Add behaviour options
92
-   * requestModesOnJoin - automatically sends a MODE request when joining a channel
93
- * Events now have a `metadata` property instead of a `time` (and time is available in metadata)
94
-   * IrcEvent.time is now deprecated but will remain until after v1.0.0.
95
-   * Metadata now contains the message ID, if any.
96
-     * ActionReceived.messageId and MessageReceived.messageId are now deprecated, to be removed after v1.0.0.
97
-   * Metadata now contains the event's batch ID, if any.
98
- * Added support for batches
99
-   * All events in a batch are buffered until the batch is finished
100
-   * The events are then published together in a single `BatchReceived` event
101
- * Added support for CHGHOST messages
102
- * (Internal) Improve performance when the MessageHandler is finding a processor for a message
103
- * (Internal) Introduced event mutators
104
-   * Event mutators are now responsible for handling changing events in response to state
105
-     e.g. ChannelFanOutMutator creates Channel* events for global quits/nick changes/etc
106
-   * Event handlers now just handle events, and don't return anything
107
-
108
-v0.8.0
109
-
110
- * Added support for SCRAM-SHA-1 and SCRAM-SHA-256 SASL mechanisms
111
- * Added MotdLineReceived event
112
- * Added topic events and state
113
- * Add utility method IrcClient.isChannel(String) to identify if a target is a channel or not
114
- * (Internal) Move event handlers into their own package
115
-
116
-v0.7.0
117
-
118
- * Fixed experimental API warnings when using IrcClient
119
- * BREAKING: IrcClients are now constructed using a DSL
120
-   * Users of the library no longer need to care about the implementing class
121
-   * Facilitates adding more options in the future without breaking existing implementations
122
- * SASL improvements
123
-   * The enabled mechanisms can now be configured (in the SASL DSL)
124
-   * Added support for EXTERNAL mechanism, disabled by default
125
-   * Now attempts to renegotiate if the server doesn't recognise the SASL mechanism that was tried
126
- * Added UserNickChanged and corresponding ChannelNickChanged events
127
- * Added ServerConnectionError, raised when connecting to the server fails
128
- * (Internal) Minor version updates for Gradle, Kotlin and JUnit
129
-
130
-v0.6.0
131
-
132
- * Changed USER command to not send the server name, per modern standards
133
- * Added support for SASL authentication (with PLAIN mechanism)
134
- * Removed some unused test code
135
- * Fixed handling of user mode changes on channels (op/deop/etc)
136
- * Message extensions:
137
-    * Added support for IRCv3 message tags v3.3
138
-    * Exposed message IDs in MessageReceived and ActionReceived events
139
-    * When sending a message you can now indicate what it is in reply to
140
-    * Added sendTagMessage() to send message tags without any content
141
-    * The reply() utility automatically marks messages as a reply
142
-    * Added react() utility to send a reaction client tag
143
- * State is now reset when the client is disconnected, so you can immediately reconnect
144
- * (Internal) improved how coroutines and channels are used in LineBufferedSocket
145
-
146
-v0.5.0
147
-
148
- * Server state:
149
-    * Added ServerConnecting and ServerDisconnected events
150
-    * Server status now starts as Disconnected rather than Connecting
151
-    * Improved error message when features are of an unexpected type
152
- * Channel modes:
153
-    * CHANMODES feature is now stored as an array, not a single comma-separated string
154
-    * Added ChanModeType enum, and method in ServerState to get the type of a mode
155
-    * Added ModeChanged event, for user and channel mode changes and discovery
156
-    * Added modes and modesDiscovered to ChannelState
157
- * Other new events:
158
-    * Added MotdFinished event
159
-    * Added UserAccountChanged event
160
-    * Added ChannelUserKicked event
161
-    * Added NoticeReceived event
162
-    * Added CtcpReplyReceived event
163
- * Improved some documentation
164
-
165
-v0.4.0
166
-
167
- * Added CtcpReceived and ActionReceived events
168
- * Added sendCtcp and sendAction message builders
169
- * Fix issue with messages being sent out of order, which sometimes caused problems connecting to passworded servers
170
- * Added 'network' server feature
171
- * Added serverName field to ServerState
172
-
173
-v0.3.1
174
-
175
- * Added more documentation to public methods/classes
176
- * Fixed exception when sending multiple lines at once (e.g. when connecting!)
177
-
178
-v0.3.0
179
-
180
- * Simplified how messages are constructed.
181
-   Instead of: client.send(joinMessage("#channel"))
182
-   Now use: client.sendJoin("#channel")
183
- * Added reply utility to easily send replies to message events
184
- * Server state improvements:
185
-   * Added status field to ServerState
186
-   * ServerConnected event is emitted as soon as the socket is connected
187
-   * ServerReady event is emitted after logging in, negotiating, etc
188
- * Added extra debugging to show what type of events are being dispatched
189
- * Added ChannelQuit event, raised for each channel a user is in when they quit
190
- * (Internal) Event handlers can now return more events to emit
191
-
192
-v0.2.1
193
-
194
- * Added documentation and reduced visibility of some internal methods/classes
195
- * (Internal) Enabled Travis, Codacy and Coveralls
196
-
197
-v0.2.0
198
-
199
- * Added support for connecting over TLS
200
- * BREAKING: Simplified how event handlers are registered
201
- * BREAKING: Improved use of coroutines so users don't have to worry about them
202
- * (Internal) Upgraded to Gradle 5.1.1

+ 209
- 0
CHANGELOG.adoc View File

@@ -0,0 +1,209 @@
1
+= Changelog
2
+
3
+== Next version (in development)
4
+
5
+* Away support:
6
+** Added sendAway() method
7
+** Added UserAway event and fanned-out ChannelAway
8
+** Away message is now updated in the UserState
9
+* Added IrcClient.localUser property, returning the local User
10
+* Deprecated ServerState.localNickname in favour of localUser.
11
+* (Internal) improved the way byte buffers are used to
12
+  reduce array copying and clean up code
13
+* (Internal) Converted README, LICENCE and CHANGELOG to Asciidoc.
14
+
15
+== v1.0.1
16
+
17
+* Fixed issue with very long packets not fitting in buffers
18
+  after TLS decryption.
19
+* Improved error message when IrcClient.connect() is called
20
+  while already connected
21
+* Made IrcClient.disconnect() block until the disconnect has
22
+  been processed. This will be a very short period of time,
23
+  and allows callers to immediately call connect() again
24
+  afterwards if they wish
25
+* Fixed various issues with disconnecting TLS connections
26
+  not behaving correctly
27
+
28
+== v1.0.0
29
+
30
+* Replaced Ktor dependency with custom socket handling, which fixes
31
+  fatal issue when connecting to servers over TLS that request a
32
+  client certificate.
33
+* Added NicknameChangeRequired event for the case when a nickname is
34
+  not allowed during connection and *MUST* be changed
35
+* BREAKING: Added 'PreferIPv6' behaviour config, defaulting to true.
36
+  With this configuration KtIrc will try to use IPv6 if the server
37
+  publishes AAAA records.
38
+* BREAKING: Default port is now 6697, TLS is enabled by default
39
+
40
+== v0.11.0
41
+
42
+* Added SourcedEvent interface for events that have a user source attached
43
+* Added ChannelJoinFailed event
44
+* Added ChannelMembershipAdjustment interface for events that concern
45
+  users joining/leaving channels
46
+* Added missing user parameter to ModeChangedEvent
47
+
48
+== v0.10.3
49
+
50
+* Fix issue parsing CTCPs when the content contained multi-byte chars
51
+* Fixed multiple issues when receiving malformed input from the server:
52
+  * Invalid server-time tags are now ignored and the current time used
53
+  * PRIVMSGs, NOTICEs and TOPICs with no target/message are now ignored
54
+  * CAPs with invalid or missing arguments are now ignored
55
+  * Better handling for duplicate JOIN messages
56
+  * Ignored messages are now logged more consistently
57
+
58
+== v0.10.2
59
+
60
+* Fix handling of multiple long lines sometimes dropping part of the line
61
+* Support lines with 8191 bytes of tags, as allowed by the message-tags spec
62
+* Fix a few more instances of occasional ConcurrentModificationExceptions
63
+
64
+== v0.10.1
65
+
66
+* Added NickChangeFailed event for when nicknames are in use, banned, etc
67
+* Added sendPart method
68
+* Fix occasional ConcurrentModificationException when adding state
69
+* (Internal) Moved message processors into their own package
70
+* (Internal) Added ExperimentalIrcClient interface for features not yet ready for release
71
+
72
+== v0.10.0
73
+
74
+* Batch start and end events are no longer included in BatchReceived events
75
+* Batches now expose complete metadata from their start event
76
+* Added support for labelled-replies capability and label message tags
77
+* Added support for message-tags capability after it moved from draft
78
+* Added new methods for sending raw lines to the IRC server
79
+** send(tagMap(...), command, arguments) replaces send(line)
80
+** send(command, arguments) is available if no tags are to be sent
81
+** the line is built automatically (with spaces/' :' added appropriately)
82
+** send(line) is deprecated and will be removed after v1.0.0
83
+* Add 'alwaysEchoMessages' behaviour that makes it easier to deal with servers
84
+  that don't support the echo message capability
85
+* Added TargetedEvent, a subclass of IrcEvent, for all events that are
86
+  targeted to a user or channel
87
+* (Internal) Added annotation to track removal of deprecated methods
88
+* (Internal) Migrate unit tests to use Mockk instead of Mockito
89
+
90
+== v0.9.0
91
+
92
+* Improve DSL for creating an IrcClient to allow parameters to be passed to server and profile
93
+  e.g. IrcClient { server("irc.example.com", 6667) }
94
+* Add behaviour options
95
+** requestModesOnJoin - automatically sends a MODE request when joining a channel
96
+* Events now have a `metadata` property instead of a `time` (and time is available in metadata)
97
+** IrcEvent.time is now deprecated but will remain until after v1.0.0.
98
+** Metadata now contains the message ID, if any.
99
+** ActionReceived.messageId and MessageReceived.messageId are now deprecated, to be removed after v1.0.0.
100
+** Metadata now contains the event's batch ID, if any.
101
+* Added support for batches
102
+** All events in a batch are buffered until the batch is finished
103
+** The events are then published together in a single `BatchReceived` event
104
+* Added support for CHGHOST messages
105
+* (Internal) Improve performance when the MessageHandler is finding a processor for a message
106
+* (Internal) Introduced event mutators
107
+** Event mutators are now responsible for handling changing events in response to state
108
+    e.g. ChannelFanOutMutator creates Channel* events for global quits/nick changes/etc
109
+** Event handlers now just handle events, and don't return anything
110
+
111
+== v0.8.0
112
+
113
+* Added support for SCRAM-SHA-1 and SCRAM-SHA-256 SASL mechanisms
114
+* Added MotdLineReceived event
115
+* Added topic events and state
116
+* Add utility method IrcClient.isChannel(String) to identify if a target is a channel or not
117
+* (Internal) Move event handlers into their own package
118
+
119
+== v0.7.0
120
+
121
+* Fixed experimental API warnings when using IrcClient
122
+* BREAKING: IrcClients are now constructed using a DSL
123
+** Users of the library no longer need to care about the implementing class
124
+** Facilitates adding more options in the future without breaking existing implementations
125
+* SASL improvements
126
+** The enabled mechanisms can now be configured (in the SASL DSL)
127
+** Added support for EXTERNAL mechanism, disabled by default
128
+** Now attempts to renegotiate if the server doesn't recognise the SASL mechanism that was tried
129
+* Added UserNickChanged and corresponding ChannelNickChanged events
130
+* Added ServerConnectionError, raised when connecting to the server fails
131
+* (Internal) Minor version updates for Gradle, Kotlin and JUnit
132
+
133
+== v0.6.0
134
+
135
+* Changed USER command to not send the server name, per modern standards
136
+* Added support for SASL authentication (with PLAIN mechanism)
137
+* Removed some unused test code
138
+* Fixed handling of user mode changes on channels (op/deop/etc)
139
+* Message extensions:
140
+** Added support for IRCv3 message tags v3.3
141
+** Exposed message IDs in MessageReceived and ActionReceived events
142
+** When sending a message you can now indicate what it is in reply to
143
+** Added sendTagMessage() to send message tags without any content
144
+** The reply() utility automatically marks messages as a reply
145
+** Added react() utility to send a reaction client tag
146
+* State is now reset when the client is disconnected, so you can immediately reconnect
147
+* (Internal) improved how coroutines and channels are used in LineBufferedSocket
148
+
149
+== v0.5.0
150
+
151
+* Server state:
152
+** Added ServerConnecting and ServerDisconnected events
153
+** Server status now starts as Disconnected rather than Connecting
154
+** Improved error message when features are of an unexpected type
155
+* Channel modes:
156
+** CHANMODES feature is now stored as an array, not a single comma-separated string
157
+** Added ChanModeType enum, and method in ServerState to get the type of a mode
158
+** Added ModeChanged event, for user and channel mode changes and discovery
159
+** Added modes and modesDiscovered to ChannelState
160
+* Other new events:
161
+** Added MotdFinished event
162
+** Added UserAccountChanged event
163
+** Added ChannelUserKicked event
164
+** Added NoticeReceived event
165
+** Added CtcpReplyReceived event
166
+* Improved some documentation
167
+
168
+== v0.4.0
169
+
170
+* Added CtcpReceived and ActionReceived events
171
+* Added sendCtcp and sendAction message builders
172
+* Fix issue with messages being sent out of order, which sometimes caused problems connecting to passworded servers
173
+* Added 'network' server feature
174
+* Added serverName field to ServerState
175
+
176
+== v0.3.1
177
+
178
+* Added more documentation to public methods/classes
179
+* Fixed exception when sending multiple lines at once (e.g. when connecting!)
180
+
181
+== v0.3.0
182
+
183
+* Simplified how messages are constructed.
184
+** Instead of: client.send(joinMessage("#channel"))
185
+** Now use: client.sendJoin("#channel")
186
+* Added reply utility to easily send replies to message events
187
+* Server state improvements:
188
+** Added status field to ServerState
189
+** ServerConnected event is emitted as soon as the socket is connected
190
+** ServerReady event is emitted after logging in, negotiating, etc
191
+* Added extra debugging to show what type of events are being dispatched
192
+* Added ChannelQuit event, raised for each channel a user is in when they quit
193
+* (Internal) Event handlers can now return more events to emit
194
+
195
+== v0.2.1
196
+
197
+* Added documentation and reduced visibility of some internal methods/classes
198
+* (Internal) Enabled Travis, Codacy and Coveralls
199
+
200
+== v0.2.0
201
+
202
+* Added support for connecting over TLS
203
+* BREAKING: Simplified how event handlers are registered
204
+* BREAKING: Improved use of coroutines so users don't have to worry about them
205
+* (Internal) Upgraded to Gradle 5.1.1
206
+
207
+== v0.1.0
208
+
209
+* Initial release

LICENCE → LICENCE.adoc View File

@@ -1,21 +1,21 @@
1
-MIT License
2
-
3
-Copyright (c) Chris Smith 2018-2019
4
-
5
-Permission is hereby granted, free of charge, to any person obtaining a copy
6
-of this software and associated documentation files (the "Software"), to deal
7
-in the Software without restriction, including without limitation the rights
8
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
-copies of the Software, and to permit persons to whom the Software is
10
-furnished to do so, subject to the following conditions:
11
-
12
-The above copyright notice and this permission notice shall be included in all
13
-copies or substantial portions of the Software.
14
-
15
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1
+= MIT License
2
+
3
+Copyright © Chris Smith 2018-2019
4
+
5
+Permission is hereby granted, free of charge, to any person obtaining a copy
6
+of this software and associated documentation files (the "Software"), to deal
7
+in the Software without restriction, including without limitation the rights
8
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+copies of the Software, and to permit persons to whom the Software is
10
+furnished to do so, subject to the following conditions:
11
+
12
+The above copyright notice and this permission notice shall be included in all
13
+copies or substantial portions of the Software.
14
+
15
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 21
 SOFTWARE.

README.md → README.adoc View File

@@ -1,125 +1,130 @@
1
-# KtIrc
2
-
3
-[![Build Status](https://travis-ci.org/csmith/KtIrc.svg?branch=master)](https://travis-ci.org/csmith/KtIrc)
4
-[![Codacy Badge](https://api.codacy.com/project/badge/Grade/c01221cbf9cf413ba4d94cb8c80e334a)](https://www.codacy.com/app/csmith/KtIrc?utm_source=github.com&utm_medium=referral&utm_content=csmith/KtIrc&utm_campaign=Badge_Grade)
5
-[![codecov](https://codecov.io/gh/csmith/KtIrc/branch/master/graph/badge.svg)](https://codecov.io/gh/csmith/KtIrc)
6
-[![Download](https://api.bintray.com/packages/dmdirc/releases/ktirc/images/download.svg)](https://bintray.com/dmdirc/releases/ktirc/_latestVersion)
7
-
8
-KtIrc is a Kotlin JVM library for connecting to and interacting with IRC servers.
9
-It is still in an early stage of development.
10
-
11
-## Features
12
-
13
-#### Built for Kotlin
14
-
15
-KtIrc is written in and designed for use in Kotlin; it uses extension methods,
16
-DSLs, sealed classes, and so on, to make it much easier to use than an
17
-equivalent Java library.
18
-
19
-#### Coroutine-powered
20
-
21
-KtIrc uses co-routines for all of its input/output which lets it deal with
22
-IRC messages in the background while your app does other things, without
23
-the overhead of creating a new thread per IRC client.
24
-
25
-#### Modern IRC standards
26
-
27
-KtIrc supports many IRCv3 features such as SASL authentication, message IDs,
28
-server timestamps, replies, reactions, account tags, and more. These features
29
-(where server support is available) make it easier to develop bots and
30
-clients, and enhance IRC with new user-facing functionality.
31
-
32
-## Setup
33
-
34
-KtIrc is published to JCenter, so adding it to a gradle build is as simple as:
35
-
36
-```groovy
37
-repositories {
38
-    jcenter()
39
-}
40
-
41
-dependencies {
42
-    implementation("com.dmdirc:ktirc:<VERSION>")
43
-}
44
-```
45
-
46
-## Usage
47
-
48
-Clients are created using a DSL and the `IrcClient` function. At a minimum
49
-you must specify a server and a profile. A simple bot might look like:
50
-
51
-```kotlin
52
-val client = IrcClient {
53
-    server {
54
-        host = "my.server.com"
55
-    } 
56
-    profile {
57
-        nickname = "nick"
58
-        username = "username"
59
-        realName = "Hi there"
60
-    }
61
-}
62
-
63
-client.onEvent { event ->
64
-    when (event) {
65
-        is ServerReady ->
66
-            client.sendJoin("#ktirc")
67
-        is ServerDisconnected ->
68
-            client.connect()
69
-        is MessageReceived ->
70
-            if (event.message == "!test")
71
-                client.reply(event, "Test successful!")
72
-    }
73
-}
74
-
75
-client.connect()
76
-```
77
-
78
-## Developing KtIrc
79
-
80
-### Lifecycle of a message
81
-
82
-![architecture diagram](docs/sequence.png) 
83
-
84
-The `LineBufferedSocket` class receives bytes from the IRC server. Whenever it
85
-encounters a complete line (terminated by a `CR`, `LF` or `CRLF`), it passes it
86
-to the `IrcClient` as a `ByteArray`. The `MessageParser` breaks up the line
87
-into its component parts (tags, prefixes, commands, and parameters) and returns
88
-them as an `IrcMessage`.
89
- 
90
-The `IrcMessage` is given to the `MessageHandler`, which tries to find a
91
-processor that can handle the command in the message. The processor's job is
92
-to convert the message into an `IrcEvent` subclass. Processors do not get
93
-given any contextual information or state, their job is simply to convert
94
-the message as received into an event.
95
-
96
-The events are returned to the `MessageHandler` which then passes them on
97
-to all registered event handlers. The job of the event handlers is twofold:
98
-firstly, use the events to update the state of KtIrc (for example, after
99
-receiving a `JOIN` message, the `ChannelStateHandler` will add the user
100
-to the list of users in the channel, while the `UserStateHandler` may update
101
-the user's hostname if we hadn't previously seen it). Secondly, the event
102
-handlers may themselves raise events. This is useful for higher-order
103
-events such as `ServerReady` that depend on a variety of factors and
104
-states.
105
-
106
-Handlers themselves may not keep state, as they will be shared across
107
-multiple instances of `IrcClient` and won't be reset on reconnection.
108
-State is instead stored in the various `*State` properties of the
109
-`IrcClient` such as `serverState` and `channelState`. Fields that
110
-should not be exposed to users of KtIrc can be placed in these
111
-public state objects but marked as `internal`.
112
-
113
-All the generated events (from processors or from event handlers) are
114
-passed to the `IrcClient`, which in turn passes them to the library
115
-user via the delegates passed to the `onEvent` method. 
116
-
117
-### Contributing
118
-
119
-Contributing is welcomed and encouraged! Please try to add unit tests for new features,
120
-and maintain a code style consistent with the existing code.
121
-
122
-### Licence
123
-
124
-The code in this repository is released under the MIT licence. See the
125
-[LICENCE](LICENCE) file for more info.
1
+= KtIrc
2
+Chris Smith
3
+
4
+image:https://travis-ci.org/csmith/KtIrc.svg?branch=master[Build status, link=https://travis-ci.org/csmith/KtIrc]
5
+image:https://api.codacy.com/project/badge/Grade/c01221cbf9cf413ba4d94cb8c80e334a[Code quality, link=https://www.codacy.com/app/csmith/KtIrc]
6
+image:https://codecov.io/gh/csmith/KtIrc/branch/master/graph/badge.svg[Code coverage, link=https://codecov.io/gh/csmith/KtIrc]
7
+image:https://api.bintray.com/packages/dmdirc/releases/ktirc/images/download.svg[Latest version, link=https://bintray.com/dmdirc/releases/ktirc/_latestVersion]
8
+image:https://img.shields.io/badge/documentation-d11n-brightgreen.svg[Documentation, link=https://ktirc.d11n.dev/]
9
+
10
+KtIrc is a Kotlin JVM library for connecting to and interacting with IRC servers.
11
+It is still in an early stage of development.
12
+
13
+== Features
14
+
15
+.Built for Kotlin
16
+KtIrc is written in and designed for use in Kotlin; it uses extension methods,
17
+DSLs, sealed classes, and so on, to make it much easier to use than an
18
+equivalent Java library.
19
+
20
+.Coroutine-powered
21
+KtIrc uses co-routines for all of its input/output which lets it deal with
22
+IRC messages in the background while your app does other things, without
23
+the overhead of creating a new thread per IRC client.
24
+
25
+.Modern IRC standards
26
+KtIrc supports many IRCv3 features such as SASL authentication, message IDs,
27
+server timestamps, replies, reactions, account tags, and more. These features
28
+(where server support is available) make it easier to develop bots and
29
+clients, and enhance IRC with new user-facing functionality.
30
+
31
+== Setup
32
+
33
+KtIrc is published to JCenter, so adding it to a gradle build is as simple as:
34
+
35
+[source,groovy]
36
+----
37
+repositories {
38
+    jcenter()
39
+}
40
+
41
+dependencies {
42
+    implementation("com.dmdirc:ktirc:<VERSION>")
43
+}
44
+----
45
+
46
+== Usage
47
+
48
+Clients are created using a DSL and the `IrcClient` function. At a minimum
49
+you must specify a server and a profile. A simple bot might look like:
50
+
51
+[source,kotlin]
52
+----
53
+val client = IrcClient {
54
+    server {
55
+        host = "my.server.com"
56
+    } 
57
+    profile {
58
+        nickname = "nick"
59
+        username = "username"
60
+        realName = "Hi there"
61
+    }
62
+}
63
+
64
+client.onEvent { event ->
65
+    when (event) {
66
+        is ServerReady ->
67
+            client.sendJoin("#ktirc")
68
+        is ServerDisconnected ->
69
+            client.connect()
70
+        is MessageReceived ->
71
+            if (event.message == "!test")
72
+                client.reply(event, "Test successful!")
73
+    }
74
+}
75
+
76
+client.connect()
77
+----
78
+
79
+== Documentation
80
+
81
+You can view the latest documentation for KtIrc at https://ktirc.d11n.dev/.
82
+
83
+== Developing KtIrc
84
+
85
+=== Lifecycle of a message
86
+
87
+image:docs/sequence.png[Architecture diagram]
88
+
89
+The `LineBufferedSocket` class receives bytes from the IRC server. Whenever it
90
+encounters a complete line (terminated by a `CR`, `LF` or `CRLF`), it passes it
91
+to the `IrcClient` as a `ByteArray`. The `MessageParser` breaks up the line
92
+into its component parts (tags, prefixes, commands, and parameters) and returns
93
+them as an `IrcMessage`.
94
+ 
95
+The `IrcMessage` is given to the `MessageHandler`, which tries to find a
96
+processor that can handle the command in the message. The processor's job is
97
+to convert the message into an `IrcEvent` subclass. Processors do not get
98
+given any contextual information or state, their job is simply to convert
99
+the message as received into an event.
100
+
101
+The events are returned to the `MessageHandler` which then passes them on
102
+to all registered event handlers. The job of the event handlers is twofold:
103
+firstly, use the events to update the state of KtIrc (for example, after
104
+receiving a `JOIN` message, the `ChannelStateHandler` will add the user
105
+to the list of users in the channel, while the `UserStateHandler` may update
106
+the user's hostname if we hadn't previously seen it). Secondly, the event
107
+handlers may themselves raise events. This is useful for higher-order
108
+events such as `ServerReady` that depend on a variety of factors and
109
+states.
110
+
111
+Handlers themselves may not keep state, as they will be shared across
112
+multiple instances of `IrcClient` and won't be reset on reconnection.
113
+State is instead stored in the various `*State` properties of the
114
+`IrcClient` such as `serverState` and `channelState`. Fields that
115
+should not be exposed to users of KtIrc can be placed in these
116
+public state objects but marked as `internal`.
117
+
118
+All the generated events (from processors or from event handlers) are
119
+passed to the `IrcClient`, which in turn passes them to the library
120
+user via the delegates passed to the `onEvent` method. 
121
+
122
+=== Contributing
123
+
124
+Contributing is welcomed and encouraged! Please try to add unit tests for new features,
125
+and maintain a code style consistent with the existing code.
126
+
127
+=== Licence
128
+
129
+The code in this repository is released under the MIT licence. See the
130
+link:LICENCE.adoc[LICENCE] file for more info.

Loading…
Cancel
Save