|
@@ -37,15 +37,6 @@ repository and then the KtIrc dependency; you may already be using
|
37
|
37
|
JCenter for other dependencies -- in that case just skip the
|
38
|
38
|
repository configuration!
|
39
|
39
|
|
40
|
|
-[TIP]
|
41
|
|
-====
|
42
|
|
-KtIrc adheres to semantic versioning: you can expect to upgrade between
|
43
|
|
-minor versions without problems (e.g. from `0.1.2` to `0.13.7`); major
|
44
|
|
-version changes may include breaking changes such as the removal of
|
45
|
|
-deprecated methods. You should check the changelog before updating to
|
46
|
|
-a new major version.
|
47
|
|
-====
|
48
|
|
-
|
49
|
40
|
.Gradle (using Kotlin DSL)
|
50
|
41
|
[source,kotlin,subs="attributes"]
|
51
|
42
|
----
|
|
@@ -196,6 +187,30 @@ may need to process. At minimum, when receiving a BatchReceived
|
196
|
187
|
event you should apply your normal processing to all the events
|
197
|
188
|
contained within.
|
198
|
189
|
|
|
190
|
+=== Versioning and deprecation
|
|
191
|
+
|
|
192
|
+As of version 1.0.0, KtIrc adheres to semantic versioning: you can
|
|
193
|
+expect to upgrade between minor versions without problems (e.g. from `1.1.2`
|
|
194
|
+to `1.13.7`); major version changes include breaking changes such as the
|
|
195
|
+removal of methods. You should check the changelog before updating to
|
|
196
|
+a new major version.
|
|
197
|
+
|
|
198
|
+Where at all possible, methods will be deprecated for a full major version
|
|
199
|
+cycle before being removed. e.g., a method deprecated in `0.5.0` will be
|
|
200
|
+present in all `1.x.x` releases and will likely be removed fully in `2.0.0`.
|
|
201
|
+This gives users of the library opportunity to migrate away from deprecated
|
|
202
|
+methods in advance of their removal.
|
|
203
|
+
|
|
204
|
+In KtIrc, we define a breaking change as one that either:
|
|
205
|
+
|
|
206
|
+* removes public methods, classes, or fields; or
|
|
207
|
+* adds required parameters to an existing public method; or
|
|
208
|
+* significantly alters the default behaviour without any API changes
|
|
209
|
+
|
|
210
|
+Note that changes that don't meet this threshold to be classed as "breaking"
|
|
211
|
+may still cause errors in downstream projects. In particular, new enum
|
|
212
|
+values may be added which could cause compilation errors if they are
|
|
213
|
+used exhaustively (e.g. in a `return when` construct with no `else` clause).
|
199
|
214
|
|
200
|
215
|
== IrcClient DSL
|
201
|
216
|
|
|
@@ -1006,25 +1021,89 @@ handle the ChannelAway events, and vice-versa.
|
1006
|
1021
|
|
1007
|
1022
|
=== Channel/User events
|
1008
|
1023
|
|
1009
|
|
-TODO
|
|
1024
|
+These are events that may be targeted to either a channel or a user. You
|
|
1025
|
+can use the <<IsChannel>> method to determine whether the target of one
|
|
1026
|
+of these events is a channel or not.
|
1010
|
1027
|
|
1011
|
1028
|
==== MessageReceived
|
|
1029
|
+* Type: IrcEvent, TargetedEvent, SourcedEvent
|
|
1030
|
+* Properties:
|
|
1031
|
+** `user`: `User` - the user who sent the message
|
|
1032
|
+** `target`: `String` - the channel or user the message was sent to
|
|
1033
|
+** `message`: `String` - the text of the message
|
1012
|
1034
|
|
1013
|
|
-TODO
|
|
1035
|
+Raised whenever we receive a message on a channel or directly to our
|
|
1036
|
+local user. CTCPs and Actions, which are client-side extensions to
|
|
1037
|
+messages will not raise this event; instead they will raise
|
|
1038
|
+<<CtcpReceived>> and <<ActionReceived>> respectively.
|
|
1039
|
+
|
|
1040
|
+The <<Reply>> function can be used to reply to a message,
|
|
1041
|
+automatically selecting the appropriate target and including the
|
|
1042
|
+message ID in the reply where supported by the IRC server.
|
1014
|
1043
|
|
1015
|
1044
|
==== NoticeReceived
|
|
1045
|
+* Type: IrcEvent, TargetedEvent, SourcedEvent
|
|
1046
|
+* Properties:
|
|
1047
|
+** `user`: `User` - the user who sent the notice
|
|
1048
|
+** `target`: `String` - the channel or user the notice was sent to
|
|
1049
|
+** `message`: `String` - the text of the notice
|
1016
|
1050
|
|
1017
|
|
-TODO
|
|
1051
|
+Raised whenever we receive a notice on a channel or directly to our
|
|
1052
|
+local user. CTCP replies, which are client-side extensions to
|
|
1053
|
+notices will not raise this event; instead they will raise
|
|
1054
|
+<<CtcpReplyReceived>>.
|
|
1055
|
+
|
|
1056
|
+During connection, notices may be received which target either the
|
|
1057
|
+magic string `AUTH` or `*`, as the client's nickname is not yet
|
|
1058
|
+known.
|
1018
|
1059
|
|
1019
|
1060
|
==== ActionReceived
|
|
1061
|
+* Type: IrcEvent, TargetedEvent, SourcedEvent
|
|
1062
|
+* Properties:
|
|
1063
|
+** `user`: `User` - the user who sent the action
|
|
1064
|
+** `target`: `String` - the channel or user the action was sent to
|
|
1065
|
+** `action`: `String` - the text of the action
|
1020
|
1066
|
|
1021
|
|
-TODO
|
|
1067
|
+Raised whenever we receive an 'action' message on a channel or
|
|
1068
|
+directly to our local user. Actions are a client-side extension
|
|
1069
|
+to the IRC protocol that allow users to describe something they
|
|
1070
|
+are doing.
|
1022
|
1071
|
|
1023
|
1072
|
==== CtcpReceived
|
|
1073
|
+* Type: IrcEvent, TargetedEvent, SourcedEvent
|
|
1074
|
+* Properties:
|
|
1075
|
+** `user`: `User` - the user who sent the CTCP
|
|
1076
|
+** `target`: `String` - the channel or user the CTCP was sent to
|
|
1077
|
+** `type`: `String` - the type of the CTCP
|
|
1078
|
+** `content`: `String` - the (possibly empty) content of the CTCP
|
1024
|
1079
|
|
1025
|
|
-TODO
|
|
1080
|
+Raised in response to a message that contains a CTCP
|
|
1081
|
+(client-to-client protocol) message other than an action.
|
|
1082
|
+CTCPs have a type, such as `PING`, `VERSION`, and optionally
|
|
1083
|
+some content such as a timestamp or nonce when requesting a PING.
|
|
1084
|
+
|
|
1085
|
+KtIrc does not reply to any CTCPs by itself. Replies to CTCPs are
|
|
1086
|
+by convention sent to the originating user, even if the CTCP is
|
|
1087
|
+sent to a channel.
|
1026
|
1088
|
|
1027
|
1089
|
==== CtcpReplyReceived
|
|
1090
|
+* Type: IrcEvent, TargetedEvent, SourcedEvent
|
|
1091
|
+* Properties:
|
|
1092
|
+** `user`: `User` - the user who sent the CTCP reply
|
|
1093
|
+** `target`: `String` - the channel or user the reply was sent to
|
|
1094
|
+** `type`: `String` - the type of the CTCP reply
|
|
1095
|
+** `content`: `String` - the (possibly empty) content of the CTCP reply
|
|
1096
|
+
|
|
1097
|
+Raised in response to a notice that contains a CTCP
|
|
1098
|
+(client-to-client protocol) reply. This usually occurs after we
|
|
1099
|
+have issued a CTCP request to a user or channel, and the `content`
|
|
1100
|
+argument will contain the remote client's response.
|
|
1101
|
+
|
|
1102
|
+Replies to CTCPs are by convention sent to the originating user,
|
|
1103
|
+even if the CTCP is sent to a channel. The `target` parameter
|
|
1104
|
+should therefore be the local user in most cases.
|
|
1105
|
+
|
|
1106
|
+=== User events
|
1028
|
1107
|
|
1029
|
1108
|
TODO
|
1030
|
1109
|
|
|
@@ -1042,6 +1121,10 @@ for our own user.
|
1042
|
1121
|
If the user is away but we don't know the reason for it, the `message`
|
1043
|
1122
|
property will be empty.
|
1044
|
1123
|
|
|
1124
|
+==== ModeChanged
|
|
1125
|
+
|
|
1126
|
+TODO
|
|
1127
|
+
|
1045
|
1128
|
==== UserQuit
|
1046
|
1129
|
|
1047
|
1130
|
TODO
|
|
@@ -1058,11 +1141,6 @@ TODO
|
1058
|
1141
|
|
1059
|
1142
|
TODO
|
1060
|
1143
|
|
1061
|
|
-==== ModeChanged
|
1062
|
|
-
|
1063
|
|
-TODO
|
1064
|
|
-
|
1065
|
|
-
|
1066
|
1144
|
=== Other events
|
1067
|
1145
|
|
1068
|
1146
|
==== PingReceived
|
|
@@ -1165,6 +1243,10 @@ TODO
|
1165
|
1243
|
|
1166
|
1244
|
TODO
|
1167
|
1245
|
|
|
1246
|
+=== IsChannel
|
|
1247
|
+
|
|
1248
|
+TODO
|
|
1249
|
+
|
1168
|
1250
|
=== IsLocalClient
|
1169
|
1251
|
|
1170
|
1252
|
TODO
|