108 lines
3.2 KiB
Markdown
108 lines
3.2 KiB
Markdown
|
# 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>!
|
|||
|
|
```
|