alina sireneva
690948b8b1
All checks were successful
Build and deploy typedoc / build (push) Successful in 5m15s
Co-authored-by: Kamilla 'ova <me@kamillaova.dev> Co-authored-by: Alina Chebakova <chebakov05@gmail.com> Co-authored-by: Kravets <57632712+kravetsone@users.noreply.github.com> Co-authored-by: starkow <hello@starkow.dev> Co-authored-by: sireneva <150665887+sireneva@users.noreply.github.com>
107 lines
3.2 KiB
Markdown
Executable file
107 lines
3.2 KiB
Markdown
Executable file
# Parse modes
|
||
|
||
You may be familiar with parse modes from the Bot API. Indeed,
|
||
the idea is pretty much the same - parse mode defines the syntax to use
|
||
for formatting entities in messages.
|
||
|
||
However, there's a major difference – in mtcute, the client doesn't know anything about
|
||
how the parse modes are implemented. Instead, it just accepts an object containing
|
||
the `text` and `entities` fields, and sends it to the server:
|
||
|
||
```ts
|
||
await tg.sendText('self', {
|
||
text: 'Hi, User!',
|
||
entities: [
|
||
{ _: 'messageEntityBold', offset: 4, length: 4 }
|
||
]
|
||
})
|
||
```
|
||
|
||
Of course, passing this object manually is not very convenient,
|
||
so mtcute provides a set of *parsers* that can be used to convert
|
||
a string with entities to this structure.
|
||
|
||
For convenience, mtcute itself provides two parsers – for Markdown and HTML.
|
||
They are both implemented as separate packages, and they themselves are tagged template literals,
|
||
which makes it very easy to interpolate variables into the message.
|
||
|
||
|
||
## Markdown
|
||
|
||
Markdown parser is implemented in `@mtcute/markdown-parser` package:
|
||
|
||
```ts
|
||
import { md } from '@mtcute/markdown-parser'
|
||
|
||
dp.onNewMessage(async (msg) => {
|
||
await msg.answerText(md`Hello, **${msg.sender.username}**`)
|
||
})
|
||
```
|
||
|
||
**Note**: the syntax used by this parser is **not** compatible
|
||
with Bot API's Markdown or MarkdownV2 syntax.
|
||
See [documentation](https://ref.mtcute.dev/modules/_mtcute_markdown_parser.html)
|
||
to learn about the syntax.
|
||
|
||
## HTML
|
||
|
||
HTML parser is implemented in `@mtcute/html-parser` package:
|
||
|
||
```ts
|
||
import { html } from '@mtcute/html-parser'
|
||
|
||
dp.onNewMessage(async (msg) => {
|
||
await msg.answerText(html`Hello, <b>${msg.sender.username}</b>`)
|
||
})
|
||
```
|
||
|
||
**Note**: the syntax used by this parser is **not**
|
||
compatible with Bot API's HTML syntax.
|
||
See [documentation](https://ref.mtcute.dev/modules/_mtcute_html_parser.html)
|
||
to learn about the syntax.
|
||
|
||
## Interpolation
|
||
|
||
Both parsers support interpolation of variables into the message,
|
||
as can be seen in the examples above.
|
||
|
||
Both parsers support the following types of interpolation:
|
||
- `string` - **will not** be parsed, and appended to plain text as-is
|
||
- `number` - will be converted to string and appended to plain text as-is
|
||
- `TextWithEntities` or `MessageEntity` - will add the text and its entities to the output.
|
||
This is the type returned by `md` and `html` themselves, so you can even mix and match them:
|
||
```ts
|
||
const greeting = (user) => html`<i>${user.displayName}</i>`
|
||
const text = md`**Hello**, ${user}!`
|
||
```
|
||
- falsy value (i.e. `null`, `undefined`, `false`) - will be ignored
|
||
|
||
### Unsafe interpolation
|
||
|
||
In some cases, you may already have a string with entities, and want to parse it to entities.
|
||
|
||
In this case, you can use the method as a function:
|
||
|
||
```ts
|
||
const text = 'Hello, **User**!'
|
||
|
||
await tg.sendText('self', md(text))
|
||
// or even
|
||
await tg.sendText('self', md`${md(text)} What's new?`)
|
||
```
|
||
|
||
## Un-parsing
|
||
|
||
Both HTML and Markdown parsers also provide an `unparse` method,
|
||
which can be used to convert the message back to the original text:
|
||
|
||
```ts
|
||
import { html } from '@mtcute/html-parser'
|
||
|
||
const msg = await tg.sendText('Hi, <b>User</b>!', { parseMode: 'html' })
|
||
|
||
console.log(msg.text)
|
||
// Hi, User!
|
||
console.log(html.unparse())
|
||
// Hi, <b>User</b>!
|
||
```
|