Skip to content

Commit 3ea0628

Browse files
ForteScarletForteScarlet
committedJul 18, 2024··
简单调整README
·
v0.0.12v0.0.7
1 parent cfa3474 commit 3ea0628

File tree

3 files changed

+237
-36
lines changed

3 files changed

+237
-36
lines changed
 

‎README.md

+232-31
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,7 @@ It is also a component library of [Simple Robot v4][simbot4 gh] (simbot), which
4242
With the capabilities provided by the simbot core library, it can support more advanced encapsulation,
4343
as well as component collaboration, Spring support, and more.
4444

45-
It can be used as aid as a low-level API/SDK dependency or as a lightweight framework
46-
that can be developed quickly with the help of the simbot core library!
47-
48-
Serialization and network requests are based on [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization) and [Ktor](https://ktor.io/).
45+
> Serialization and network requests are based on [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization) and [Ktor](https://ktor.io/).
4946
5047
## Documentation
5148

@@ -54,55 +51,259 @@ Serialization and network requests are based on [Kotlin serialization](https://g
5451
- **API Documentation**: [**The KDoc of Telegram Component**](https://docs.simbot.forte.love/components/telegram) in the [**document guide site**](https://docs.simbot.forte.love).
5552
- [**Communities**](https://simbot.forte.love/communities.html): Have fun interacting with us and other developers!
5653

57-
## Modules
58-
### ⭐ Type module
54+
## Setup
55+
56+
To use the simbot component library, you first need to add the core implementation of simbot
57+
(such as the core library (`simbot-core`) or Spring Boot starter (`simbot-core-spring-boot-starter`)),
58+
and then add the component library dependencies of the Telegram (`simbot-component-telegram-core`).
59+
60+
> [!note]
61+
> The version of the simbot core implementation library (`SIMBOT_VERSION` below)
62+
> goes [here](https://github.com/simple-robot/simpler-robot/releases) for reference;
63+
>
64+
> Telegram Component library versions (`VERSION` below) go to the [release](https://github.com/simple-robot/simbot-component-telegram/releases) reference.
65+
66+
**With simbot core**
67+
68+
### Gradle
69+
70+
`build.gradle.kts`
5971

60-
Provides definitions for most types in Telegram and supports serialization based on
61-
[Kotlin Serialization](https://github.com/Kotlin/kotlinx.serialization).
72+
```kotlin
73+
plugins {
74+
kotlin("...") version "..."
75+
}
6276

63-
👉 [Go to the module](simbot-component-telegram-type) to learn more.
77+
dependencies {
78+
implementation("love.forte.simbot:simbot-core:${SIMBOT_VERSION}")
79+
implementation("love.forte.simbot.component:simbot-component-telegram-core:$VERSION")
80+
}
81+
```
82+
83+
### Maven
84+
85+
`pom.xml`
86+
87+
```xml
88+
<dependencies>
89+
<dependency>
90+
<groupId>love.forte.simbot</groupId>
91+
<artifactId>simbot-core-jvm</artifactId>
92+
<version>${SIMBOT_VERSION}</version>
93+
</dependency>
94+
<dependency>
95+
<groupId>love.forte.simbot.component</groupId>
96+
<artifactId>simbot-component-telegram-core-jvm</artifactId>
97+
<version>${VERSION}</version>
98+
</dependency>
99+
</dependencies>
100+
```
64101

65-
### ⭐ API module
102+
**With simbot spring boot starter**
66103

67-
Based on [Type module](simbot-component-telegram-type)
68-
and [Ktor](https://ktor.io/)'s
69-
[KMP][KMP] implementation for [Telegram Bot API][telegram bot doc],
70-
is a simple, efficient and lightweight API implementation module.
104+
### Gradle
71105

72-
This module provides very little extra implementation.
73-
The goal is to preserve the feel of the original API as much as possible without overwrapping it.
106+
`build.gradle.kts`
74107

75-
👉 [Go to the module](simbot-component-telegram-api) to learn more.
108+
```kotlin
109+
plugins {
110+
kotlin("jvm") version "..."
111+
}
76112

77-
### ⭐ Stdlib module
113+
dependencies {
114+
implementation("love.forte.simbot:simbot-core-spring-boot-starter:${SIMBOT_VERSION}")
115+
implementation("love.forte.simbot.component:simbot-component-telegram-core:$VERSION")
116+
}
117+
```
78118

79-
Based on [API module](simbot-component-telegram-api),
80-
for the implementation of authentication, subscription events and other related functions in bot.
119+
### Maven
120+
121+
`pom.xml`
122+
123+
```xml
124+
<dependencies>
125+
<dependency>
126+
<groupId>love.forte.simbot</groupId>
127+
<artifactId>simbot-core-spring-boot-starter</artifactId>
128+
<version>${SIMBOT_VERSION}</version>
129+
</dependency>
130+
<dependency>
131+
<groupId>love.forte.simbot.component</groupId>
132+
<artifactId>simbot-component-telegram-core-jvm</artifactId>
133+
<version>${VERSION}</version>
134+
</dependency>
135+
</dependencies>
136+
```
81137

82-
The `stdlib` module can be thought of as a lightweight SDK implementation library.
138+
### Ktor client engine
83139

84-
This module provides an implementation of event-related functionality based on the API module,
85-
including the ability to subscribe to events.
140+
The Telegram component uses Ktor as the HTTP client implementation,
141+
but does not rely on any specific engine by default.
86142

87-
Again, the goal is to provide as much of the feel of the original API as possible without overwrapping it.
143+
Therefore, you need to choose and use a Ktor Client engine implementation.
88144

89-
👉 [Go to the module](simbot-component-telegram-stdlib) to learn more.
145+
You can go to the [Ktor documentation](https://ktor.io/docs/client-engines.html)
146+
to select a suitable Client Engine for your platform.
90147

91-
### ⭐ Core Component module
148+
Take the JVM platform as an example:
92149

93-
A component implementation of the [simbot4 core library][simbot4 gh] based on [standard library module](simbot-component-telegram-stdlib).
150+
<details open><summary>Gradle</summary>
94151

95-
Is a relatively highly encapsulated module that provides most of the capabilities of simbot4,
96-
including event listeners, multi-component coordination, Spring Boot starter, and more.
152+
```kotlin
153+
runtimeOnly("io.ktor:ktor-client-java:$ktor_version")
154+
```
97155

98-
👉 [Go to Modules](simbot-component-telegram-core) to learn more.
156+
</details>
157+
158+
<details ><summary>Maven</summary>
159+
160+
```xml
161+
<dependency>
162+
<groupId>io.ktor</groupId>
163+
<artifactId>ktor-client-java-jvm</artifactId>
164+
<version>${ktor_version}</version>
165+
<scope>runtime</scope>
166+
</dependency>
167+
```
168+
169+
</details>
170+
171+
## Examples
172+
173+
**simbot core**
174+
175+
```Kotlin
176+
suspend fun main() {
177+
val app = launchSimpleApplication {
178+
useTelegram() // install Telegram Component
179+
}
180+
181+
// subscribe to events
182+
app.listeners {
183+
// subscribe to ChatGroupMessageEvent
184+
listen<ChatGroupMessageEvent> { event ->
185+
// process event...
186+
event.reply("Hello!")
187+
event.reply(At(event.authorId) + "Where are you?".toText())
188+
189+
// Required an result
190+
EventResult.empty()
191+
}
192+
193+
// subscribe to ChatGroupMessageEvent
194+
process<TelegramPrivateMessageEvent> { event ->
195+
// process event...
196+
event.content().send("Welcome, " + At(event.member().id))
197+
198+
// Without result in `process<T>`
199+
}
200+
}
201+
202+
// register bots
203+
app.telegramBots {
204+
// register a bot via token
205+
val bot = register(token = "botaaabbb.123123444") {
206+
// Config...
207+
// The source stdlib bot config
208+
botConfiguration {
209+
apiClientConfigurer {
210+
engine {
211+
// A proxy?
212+
proxy = ProxyBuilder.http("http://127.0.0.1:7790")
213+
}
214+
}
215+
216+
// Enable longPolling?
217+
longPolling = LongPolling(
218+
limit = 100,
219+
timeout = 10.minutes.inWholeSeconds.toInt(),
220+
allowedUpdates = setOf(UpdateValues.MESSAGE_NAME),
221+
// Enable retry?
222+
retry = LongPolling.Retry()
223+
)
224+
}
225+
}
226+
227+
// start the bot
228+
bot.start()
229+
}
230+
231+
232+
app.join()
233+
}
234+
```
235+
236+
**simbot Spring Boot starter**
237+
238+
```Kotlin
239+
@SpringBootApplication
240+
@EnableSimbot // enable
241+
class App
242+
243+
fun main(args: Array<String>) {
244+
runApplication<App>(*args)
245+
}
246+
247+
@Component
248+
class MyHandles {
249+
250+
@Listener // subscribe to ChatGroupMemberIncreaseEvent
251+
suspend fun handleMemberIncrease(event: ChatGroupMemberIncreaseEvent) {
252+
// ...
253+
}
254+
255+
@Filter("Hello.*")
256+
@Listener // subscribe to ChatGroupMessageEvent
257+
suspend fun handleGroupMessage(event: ChatGroupMessageEvent) {
258+
event.reply("Hello!")
259+
}
260+
}
261+
```
262+
The configuration file `*.bot.json`
263+
264+
> Comments are not supported.
265+
> Remember to clean them up when you use them.
266+
267+
```json5
268+
{
269+
"component": "simbot.telegram",
270+
"ticket": {
271+
"token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
272+
},
273+
// config and its properties are optional and default to `null`.
274+
"config": {
275+
"server": null,
276+
"proxy": null,
277+
"longPolling": null
278+
}
279+
}
280+
```
281+
282+
283+
```json5
284+
{
285+
"component": "simbot.telegram",
286+
"ticket": {
287+
"token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
288+
},
289+
// config and its properties are optional and default to `null`.
290+
"config": {
291+
"server": null,
292+
"proxy": null,
293+
// config the `longPolling` to subscribe evnets
294+
"longPolling": {
295+
"limit": 100
296+
}
297+
}
298+
}
299+
```
99300

100301
## CONTRIBUTING
101302

102303
See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for more information!
103304

104305
We welcome you and look forward to it
105-
[feed back](https://github.com/simple-robot/simbot-component-telegram/issues)
306+
[feedback](https://github.com/simple-robot/simbot-component-telegram/issues)
106307
or
107308
[pull request](https://github.com/simple-robot/simbot-component-telegram/pulls),
108309
Thank you for your contribution and support!

‎simbot-component-telegram-core/README.md

+2-3
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,6 @@ runtimeOnly("io.ktor:ktor-client-java:$ktor_version")
119119

120120
</details>
121121

122-
123122
## Examples
124123

125124
**simbot core**
@@ -220,7 +219,7 @@ The configuration file `*.bot.json`
220219
{
221220
"component": "simbot.telegram",
222221
"ticket": {
223-
"token": "Your Bot Token"
222+
"token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
224223
},
225224
// config and its properties are optional and default to `null`.
226225
"config": {
@@ -236,7 +235,7 @@ The configuration file `*.bot.json`
236235
{
237236
"component": "simbot.telegram",
238237
"ticket": {
239-
"token": "Your Bot Token"
238+
"token": "Your FULL Bot Token, e.g. Bot123456789:aaaabbbbcccc"
240239
},
241240
// config and its properties are optional and default to `null`.
242241
"config": {

‎simbot-component-telegram-stdlib/README.md

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# Stdlib module
22

33
> [!caution]
4-
> WIP
4+
> WIP, and this module will remove
55
66
## Setup
77

88
> [!note]
9-
> Version (`VERSION` below) goes to the [releases](https://github.com/simple-robot/simbot-component-telegram/releases) reference.
9+
> Version (`VERSION` below) goes to the [release](https://github.com/simple-robot/simbot-component-telegram/releases)
10+
> reference.
1011
1112
### Gradle
1213

0 commit comments

Comments
 (0)
Please sign in to comment.