parsemode

package
v1.0.0-beta23 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2026 License: GPL-3.0 Imports: 8 Imported by: 0

Documentation

Overview

Package parsemode provides robust parsing for Telegram message formatting. It supports HTML, MarkdownV2, and None parse modes with thread-safe operations.

Package parsemode provides robust parsing for Telegram message formatting. It supports HTML, MarkdownV2, and None parse modes with thread-safe operations.

Basic usage: 

result, err := Parse("<b>Hello</b>", ModeHTML)
if err != nil {
    // handle error
}
text := result.Text
entities := result.Entities

The package is thread-safe and all parsers can be used concurrently.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func ByteOffsetToUTF16Offset 

func ByteOffsetToUTF16Offset(s string, byteOffset int) int32

ByteOffsetToUTF16Offset converts a byte offset to a UTF-16 code unit offset.

func EntitiesToText 

func EntitiesToText(text string, entities []tg.MessageEntityClass, mode ParseMode) string

EntitiesToText converts Telegram entities back to formatted text. This is useful for displaying received messages with formatting.

func EscapeHTML 

func EscapeHTML(text string) string

func EscapeMarkdownV2 

func EscapeMarkdownV2(text string) string

func FormatEntity 

func FormatEntity(entityType string, content string, attrs map[string]string) string

FormatEntity formats a single entity as HTML.

Example

ExampleFormatEntity demonstrates FormatEntity usage. 

// Format bold text
html := FormatEntity(string(EntityTypeBold), "hello", nil)
fmt.Println(html)

// Format code with language
html = FormatEntity(string(EntityTypePre), "code", map[string]string{"language": "go"})
fmt.Println(html)

// Format link
html = FormatEntity(string(EntityTypeTextURL), "Click here", map[string]string{"url": "https://example.com"})
fmt.Println(html)

Output:

<b>hello</b>
<pre class="language-go">code</pre>
<a href="https://example.com">Click here</a>

func FormatText 

func FormatText(input string, mode ParseMode) string

FormatText formats the input text according to the given parse mode. For ModeNone, this returns the text as-is. For ModeHTML, this returns the text as-is (no formatting needed). For ModeMarkdown, this escapes special characters.

func HTMLToMarkdownV2 

func HTMLToMarkdownV2(html string) string

HTMLToMarkdownV2 converts HTML to MarkdownV2 format.

func IsValidParseMode 

func IsValidParseMode(mode ParseMode) bool

IsValidParseMode checks if the given parse mode is valid.

func StripFormatting 

func StripFormatting(text string, entities []tg.MessageEntityClass) string

StripFormatting removes all formatting from text. This is useful for getting plain text from formatted messages.

func SubstringByUTF16Offset 

func SubstringByUTF16Offset(s string, start, end int32) string

SubstringByUTF16Offset extracts a substring using UTF-16 offsets. Returns empty string if offsets are invalid.

func TextToEntities 

func TextToEntities(text string, entities []tg.MessageEntityClass) (string, []tg.MessageEntityClass)

TextToEntities converts text with entities to the format expected by Telegram API. This is a convenience function for sending messages.

func UTF16OffsetToByteOffset 

func UTF16OffsetToByteOffset(s string, utf16Offset int32) int

UTF16OffsetToByteOffset converts a UTF-16 code unit offset to a byte offset. Returns -1 if the offset is invalid.

func UTF16RuneCountInString 

func UTF16RuneCountInString(s string) int32

UTF16RuneCountInString returns the number of UTF-16 code units in the string. Telegram uses UTF-16 for calculating entity offsets and lengths.

Example

ExampleUTF16RuneCountInString demonstrates UTF-16 counting. 

// ASCII strings have the same length in UTF-8 and UTF-16
ascii := "hello"
fmt.Printf("ASCII: %d\n", UTF16RuneCountInString(ascii))

// Emoji require 2 UTF-16 code units (surrogate pair)
emoji := "🎉"
fmt.Printf("Emoji: %d\n", UTF16RuneCountInString(emoji))

Output:

ASCII: 5
Emoji: 2

Types

type EntityBuilder 

type EntityBuilder struct {
	// contains filtered or unexported fields
}

EntityBuilder builds Telegram message entities.

Example

ExampleEntityBuilder demonstrates EntityBuilder usage. 

builder := NewEntityBuilder()

// Add entities
builder.Add(&tg.MessageEntityBold{Offset: 0, Length: 4})
builder.Add(&tg.MessageEntityItalic{Offset: 5, Length: 6})

entities := builder.Build()
fmt.Printf("Built %d entities\n", len(entities))

// Clone the builder
cloned := builder.Clone()
fmt.Printf("Cloned builder has %d entities\n", len(cloned.Build()))

// Reset
builder.Reset()
fmt.Printf("After reset: %d entities\n", len(builder.Build()))

Output:

Built 2 entities
Cloned builder has 2 entities
After reset: 0 entities

func NewEntityBuilder 

func NewEntityBuilder() *EntityBuilder

NewEntityBuilder creates a new entity builder.

func (*EntityBuilder) Add 

func (b *EntityBuilder) Add(entity tg.MessageEntityClass)

Add adds an entity to the builder.

func (*EntityBuilder) Build 

func (b *EntityBuilder) Build() []tg.MessageEntityClass

Build returns the built entities slice.

func (*EntityBuilder) Clone 

func (b *EntityBuilder) Clone() *EntityBuilder

Clone creates a deep copy of the entity builder.

func (*EntityBuilder) Reset 

func (b *EntityBuilder) Reset()

Reset clears all entities from the builder.

type EntityType 

type EntityType string

EntityType represents the type of a message entity. 

const (
	EntityTypeBold               EntityType = "bold"
	EntityTypeItalic             EntityType = "italic"
	EntityTypeUnderline          EntityType = "underline"
	EntityTypeStrike             EntityType = "strike"
	EntityTypeSpoiler            EntityType = "spoiler"
	EntityTypeCode               EntityType = "code"
	EntityTypePre                EntityType = "pre"
	EntityTypeTextURL            EntityType = "text_url"
	EntityTypeURL                EntityType = "url"
	EntityTypeEmail              EntityType = "email"
	EntityTypeMention            EntityType = "mention"
	EntityTypeMentionName        EntityType = "mention_name"
	EntityTypeCustomEmoji        EntityType = "custom_emoji"
	EntityTypeBlockquote         EntityType = "blockquote"
	EntityTypeTextAnchor         EntityType = "text_anchor"
	EntityTypeCashtag            EntityType = "cashtag"
	EntityTypeHashtag            EntityType = "hashtag"
	EntityTypeBotCommand         EntityType = "bot_command"
	EntityTypePhone              EntityType = "phone"
	EntityTypeBankCard           EntityType = "bank_card"
	EntityTypeExpandedBlockquote EntityType = "expanded_blockquote"
)

type FormatHelper 

type FormatHelper struct {
	// contains filtered or unexported fields
}

FormatHelper provides methods to format text with Telegram entities.

func NewFormatHelper 

func NewFormatHelper(mode FormatterMode) *FormatHelper

NewFormatHelper creates a new format helper with the specified mode.

func (*FormatHelper) AddBlockquote 

func (h *FormatHelper) AddBlockquote(text string) string

AddBlockquote wraps text with blockquote formatting markers.

func (*FormatHelper) AddBold 

func (h *FormatHelper) AddBold(text string) string

AddBold wraps text with bold formatting markers based on formatter mode.

func (*FormatHelper) AddCode 

func (h *FormatHelper) AddCode(text string) string

AddCode wraps text with code formatting markers.

func (*FormatHelper) AddExpandableBlockquote 

func (h *FormatHelper) AddExpandableBlockquote(text string) string

AddExpandableBlockquote wraps text with expandable blockquote formatting markers.

func (*FormatHelper) AddItalic 

func (h *FormatHelper) AddItalic(text string) string

AddItalic wraps text with italic formatting markers.

func (*FormatHelper) AddPre 

func (h *FormatHelper) AddPre(text, language string) string

AddPre wraps text with pre-formatted code block markers.

func (*FormatHelper) AddSpoiler 

func (h *FormatHelper) AddSpoiler(text string) string

AddSpoiler wraps text with spoiler formatting markers.

func (*FormatHelper) AddStrikethrough 

func (h *FormatHelper) AddStrikethrough(text string) string

AddStrikethrough wraps text with strikethrough formatting markers.

func (*FormatHelper) AddUnderline 

func (h *FormatHelper) AddUnderline(text string) string

AddUnderline wraps text with underline formatting markers.

func (*FormatHelper) Blockquote 

func (h *FormatHelper) Blockquote(text string) FormattedText

Blockquote creates a block quotation.

func (*FormatHelper) Bold 

func (h *FormatHelper) Bold(text string) FormattedText

Bold formats text as bold.

func (*FormatHelper) Code 

func (h *FormatHelper) Code(text string) FormattedText

Code formats text as inline code.

func (*FormatHelper) CreateCustomEmoji 

func (h *FormatHelper) CreateCustomEmoji(emoji string, emojiID int64) string

CreateCustomEmoji creates a custom emoji link. emoji is the emoji character, emojiID is the custom emoji ID from Telegram. 

func (h *FormatHelper) CreateEmbedLink(text, link string) string

CreateEmbedLink creates a clickable link/mention for Telegram. For user mentions: link should be "tg://user?id=USERID" For URLs: link should be "https://example.com" 

func (h *FormatHelper) CreateLink(text, url string) string

CreateLink creates a hyperlink with the specified URL.

func (*FormatHelper) CreateUserMention 

func (h *FormatHelper) CreateUserMention(displayName string, userID int64) string

CreateUserMention creates a mention link for a Telegram user. The displayName is the visible text, userID is the user's Telegram ID.

func (*FormatHelper) CustomEmoji 

func (h *FormatHelper) CustomEmoji(emoji string, emojiID int64) FormattedText

CustomEmoji creates a custom emoji.

func (*FormatHelper) ExpandableBlockquote 

func (h *FormatHelper) ExpandableBlockquote(text string) FormattedText

ExpandableBlockquote creates an expandable block quotation.

func (*FormatHelper) Italic 

func (h *FormatHelper) Italic(text string) FormattedText

Italic formats text as italic.

func (*FormatHelper) Mention 

func (h *FormatHelper) Mention(text string, userID int64) FormattedText

Mention creates an inline mention of a user.

func (*FormatHelper) Pre 

func (h *FormatHelper) Pre(text string) FormattedText

Pre formats text as pre-formatted code block.

func (*FormatHelper) PreWithLanguage 

func (h *FormatHelper) PreWithLanguage(text, language string) FormattedText

PreWithLanguage formats text as pre-formatted code block with language.

func (*FormatHelper) Spoiler 

func (h *FormatHelper) Spoiler(text string) FormattedText

Spoiler formats text as spoiler.

func (*FormatHelper) Strikethrough 

func (h *FormatHelper) Strikethrough(text string) FormattedText

Strikethrough formats text as strikethrough. 

func (h *FormatHelper) TextLink(text, url string) FormattedText

TextLink creates an inline URL link.

func (*FormatHelper) Underline 

func (h *FormatHelper) Underline(text string) FormattedText

Underline formats text as underlined.

type FormattedText 

type FormattedText struct {
	Text     string
	Entities []tg.MessageEntityClass
}

FormattedText represents text with its Telegram entities.

func Combine 

func Combine(formatted ...FormattedText) FormattedText

Combine combines multiple formatted texts into one. It properly adjusts the entity offsets.

type FormatterMode 

type FormatterMode string

FormatterMode represents the formatting style (Markdown or HTML). 

const (
	// FormatterMarkdown uses MarkdownV2 style formatting.
	FormatterMarkdown FormatterMode = "markdown"
	// FormatterHTML uses HTML style formatting.
	FormatterHTML FormatterMode = "html"
)

type HTMLParser 

type HTMLParser struct{}

HTMLParser implements the Parser interface for HTML formatting. It is thread-safe and can be used concurrently.

Example

ExampleHTMLParser demonstrates basic HTML parsing. 

parser := NewHTMLParser()

// Simple bold text
result, _ := parser.Parse("<b>Hello, World!</b>")
fmt.Println(result.Text)
// Mixed formatting
result, _ = parser.Parse("<b>Bold</b> and <i>italic</i> text")
fmt.Println(result.Text)
// Link
result, _ = parser.Parse(`<a href="https://example.com">Click here</a>`)
fmt.Println(result.Text)

Output:

Hello, World!
Bold and italic text
Click here
Example (Blockquote)

ExampleHTMLParser_blockquote demonstrates blockquote parsing. 

parser := NewHTMLParser()

// Regular blockquote
result, _ := parser.Parse("<blockquote>This is a quote</blockquote>")
fmt.Println(result.Text)

// Collapsed blockquote
result, _ = parser.Parse(`<blockquote collapsed="true">Hidden content</blockquote>`)
fmt.Println(result.Text)

Output:

This is a quote
Hidden content
Example (Code)

ExampleHTMLParser_code demonstrates code parsing. 

parser := NewHTMLParser()

// Inline code
result, _ := parser.Parse("<code>fmt.Println()</code>")
fmt.Println(result.Text)

// Code block with language
result, _ = parser.Parse(`<pre class="language-go">func main() {}</pre>`)
fmt.Println(result.Text)

pre := result.Entities[0].(*tg.MessageEntityPre)
fmt.Println(pre.Language)

Output:

fmt.Println()
func main() {}
go
Example (CustomEmoji)

ExampleHTMLParser_customEmoji demonstrates custom emoji parsing. 

parser := NewHTMLParser()

result, _ := parser.Parse(`<emoji id="12345">🎉</emoji>`)
fmt.Println(result.Text)

Output:

🎉
Example (Spoiler)

ExampleHTMLParser_spoiler demonstrates spoiler parsing. 

parser := NewHTMLParser()

result, _ := parser.Parse("<spoiler>Secret message</spoiler>")
fmt.Println(result.Text)

Output:

Secret message

func NewHTMLParser 

func NewHTMLParser() *HTMLParser

NewHTMLParser creates a new HTML parser instance.

func (*HTMLParser) Format 

func (p *HTMLParser) Format(input string) string

Format formats text as HTML (no-op for HTML parser, returns input as-is).

func (*HTMLParser) Parse 

func (p *HTMLParser) Parse(input string) (*ParseResult, error)

Parse parses HTML formatted text and returns the result with Telegram entities.

type MarkdownParser 

type MarkdownParser struct {
	// contains filtered or unexported fields
}

MarkdownParser implements the Parser interface for MarkdownV2 formatting. It is thread-safe and can be used concurrently.

Example (Blockquote)

ExampleMarkdownParser_blockquote demonstrates blockquote parsing in Markdown. 

parser := NewMarkdownParser()

// Regular blockquote
result, _ := parser.Parse("> This is a quote")
fmt.Println(result.Text)

// Collapsed blockquote
result, _ = parser.Parse(">>> Hidden content")
fmt.Println(result.Text)

Output:

This is a quote
Hidden content
Example (Bold)

ExampleMarkdownParser_bold demonstrates bold text in Markdown. 

parser := NewMarkdownParser()

// Double asterisk
result, _ := parser.Parse("**Bold text**")
fmt.Println(result.Text)

// Double underscore
result, _ = parser.Parse("__Also bold__")
fmt.Println(result.Text)

Output:

Bold text
Also bold
Example (Code)

ExampleMarkdownParser_code demonstrates code parsing in Markdown. 

parser := NewMarkdownParser()

// Inline code
result, _ := parser.Parse("`code`")
fmt.Println(result.Text)

// Code block
result, _ = parser.Parse("```\ncode block\n```")
fmt.Println(result.Text)

// Code block with language
result, _ = parser.Parse("```go\nfunc main() {}\n```")
fmt.Println(result.Text)

Output:

code
code block
func main() {}
Example (CustomEmoji)

ExampleMarkdownParser_customEmoji demonstrates custom emoji parsing in Markdown. 

parser := NewMarkdownParser()

result, _ := parser.Parse("::12345::")
fmt.Printf("Text: '%s', Emoji ID present: %v\n", result.Text, len(result.Entities) > 0)

Output:

Text: '', Emoji ID present: true
Example (Italic)

ExampleMarkdownParser_italic demonstrates italic text in Markdown. 

parser := NewMarkdownParser()

// Single asterisk
result, _ := parser.Parse("*Italic text*")
fmt.Println(result.Text)

// Single underscore
result, _ = parser.Parse("_Also italic_")
fmt.Println(result.Text)

Output:

Italic text
Also italic
Example (Spoiler)

ExampleMarkdownParser_spoiler demonstrates spoiler parsing in Markdown. 

parser := NewMarkdownParser()

result, _ := parser.Parse("||Spoiler content||")
fmt.Println(result.Text)

Output:

Spoiler content

func NewMarkdownParser 

func NewMarkdownParser() *MarkdownParser

NewMarkdownParser creates a new Markdown parser instance.

func (*MarkdownParser) Format 

func (p *MarkdownParser) Format(input string) string

Format formats text as MarkdownV2 (escapes special characters).

func (*MarkdownParser) MarkdownToHTML 

func (p *MarkdownParser) MarkdownToHTML(markdown string) string

MarkdownToHTML converts MarkdownV2 syntax to HTML.

func (*MarkdownParser) Parse 

func (p *MarkdownParser) Parse(input string) (*ParseResult, error)

Parse parses MarkdownV2 formatted text and returns the result with Telegram entities.

type ParseMode 

type ParseMode string

ParseMode represents the type of formatting to apply to a message.

Example

ExampleParseMode demonstrates ParseMode usage. 

// Different parse modes
modes := []ParseMode{
	ModeNone,
	ModeHTML,
	ModeMarkdown,
}

for _, mode := range modes {
	fmt.Printf("Mode: %s, Valid: %v\n", mode, mode.IsValid())
}

Output:

Mode: , Valid: true
Mode: HTML, Valid: true
Mode: MarkdownV2, Valid: true

const (
	// ModeNone indicates no formatting should be applied.
	ModeNone ParseMode = ""
	// ModeHTML indicates HTML formatting should be parsed.
	ModeHTML ParseMode = "HTML"
	// ModeMarkdown indicates MarkdownV2 formatting should be parsed.
	ModeMarkdown ParseMode = "MarkdownV2"
)

func GetParseModeFromString 

func GetParseModeFromString(s string) ParseMode

GetParseModeFromString converts a string to a ParseMode. Returns ModeNone if the string is not recognized.

func ParseModeFromEntities 

func ParseModeFromEntities(entities []tg.MessageEntityClass) ParseMode

ParseModeFromEntities determines the best parse mode from existing entities. This is useful when you want to re-format a message.

func (ParseMode) IsValid 

func (p ParseMode) IsValid() bool

IsValid returns true if the parse mode is valid.

func (ParseMode) String 

func (p ParseMode) String() string

String returns the string representation of the parse mode.

type ParseResult 

type ParseResult struct {
	// Text is the cleaned/parsed text content.
	Text string
	// Entities are the parsed message entities.
	Entities []tg.MessageEntityClass
}

ParseResult contains the parsed text and entities.

func Parse 

func Parse(input string, mode ParseMode) (*ParseResult, error)

Parse parses the input text according to the given parse mode. This is the main entry point for the package.

Parameters:

  • input: The formatted text to parse
  • mode: The parse mode (ModeHTML, ModeMarkdown, or ModeNone)

Returns:

  • *ParseResult: The parsed text and entities
  • error: Any parsing error (currently always returns nil on parse errors, instead returning the original text with no entities)

func ParseHTML 

func ParseHTML(input string) (*ParseResult, error)

ParseHTML parses HTML formatted text.

func ParseMarkdown 

func ParseMarkdown(input string) (*ParseResult, error)

ParseMarkdown parses MarkdownV2 formatted text.

type Parser 

type Parser interface {
	// Parse parses the input text and returns the result with entities.
	Parse(input string) (*ParseResult, error)
}

Parser is the interface for parsing formatted text into Telegram entities.

type TextFormatter 

type TextFormatter interface {
	// Format formats the input text according to the parse mode.
	Format(input string) string
}

TextFormatter formats text with the given parse mode.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.