telegram_entities 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59bea042c497fc78acc233e6226d4e74fedd0350b98f5c04d532352531106f9f
-  data.tar.gz: f01c66585462f4f3e49f32739907a8777b9e2fbeefa056b95ce5c5f7ab20e086
+  metadata.gz: 0b280cc27c741aacc2169e8bc5138b1f2a7886d46b17637962a0e02f6bbc6c07
+  data.tar.gz: 3542dc2cef1dbbe23be909c1f865d7c1801f2fecb8e154bcef9256342fb51863
 SHA512:
-  metadata.gz: 7fa8daab2f8252ce3792be80892beea8e6eab0c2af9ffcf0d5f8978fc0eb7c0d2af64344f2a943fcd56575ef1cf75ba706ca40e657117c3388a974fadc4d2389
-  data.tar.gz: 26a866427a665ae4198a0c863dbe6a96dd5db423d84a186bdfbe3708e5295cfa798b29d5ecb177719a0a7100a6bb0fa2f781adf0e1936e2e7de6439e5dd3dc6e
+  metadata.gz: 06d4410adf179fded1205e9c36acd1aadab8668ab3a195c1916b5fb83c3b8bed30dd1bda96a45f393c6b6c70522fcf5b6c7b00459dcaa73ca6276c4e943c7ca1
+  data.tar.gz: 72601b0445e91bd68dc66c51bc0fbb6c76bdae163955ced4db96dde08de3a16d14f468f7a4f662df35c0f2f776587615788510b1f2cd0d78d7e431f064139944

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-12-04
+
+### Added
+- New method `to_bot_html` for formatting HTML specifically for Telegram Bot API `parse_mode: 'HTML'`
+- Automatic replacement of `<br>` and `<br/>` tags with `\n` characters
+- Automatic removal of wrappers for hashtags, cashtags, bot commands, media timestamps, and bank card numbers (these are automatically processed by Telegram)
+- Proper HTML entity escaping for `<`, `>`, `&`, and `"` symbols
+- Support for named HTML entities (`&lt;`, `&gt;`, `&amp;`, `&quot;`)
+- Support for numeric HTML entities (decimal and hexadecimal)
+
+### Changed
+- Improved documentation with examples for `to_bot_html` method
+- Added reference to Telegram Bot API HTML Style documentation
+
 ## [0.1.0] - 2025-11-22
 
+### Added
 - Initial release
+- Support for all Telegram MessageEntity types
+- Conversion from Markdown to Telegram entities (`from_markdown`)
+- Conversion from HTML to Telegram entities (`from_html`)
+- Conversion from Telegram entities to HTML (`to_html`)
+- Support for Telegram-specific HTML tags (`allow_telegram_tags` option)
+- UTF-16 offset/length handling for all entity types
+- Support for TDLib formattedText conversion (`from_tdlib_formatted_text`)

data/README.md

@@ -126,6 +126,33 @@ puts html
 # => "<strong>Hello</strong> <em>world</em>"
 ```
 
+### Converting Entities to Telegram Bot API HTML Format
+
+For sending messages via Telegram Bot API with `parse_mode: 'HTML'`, use `to_bot_html`:
+
+> 📖 See [Telegram Bot API HTML Style documentation](https://core.telegram.org/bots/api#html-style) for complete formatting rules.
+
+```ruby
+entities = TelegramEntities.new('Check #hashtag and /start command', [
+  {'type' => 'hashtag', 'offset' => 6, 'length' => 8},
+  {'type' => 'bot_command', 'offset' => 19, 'length' => 7}
+])
+
+html = entities.to_bot_html
+puts html
+# => "Check #hashtag and /start command"
+# Note: hashtags and bot commands are sent without wrappers (automatically processed by Telegram)
+
+# Use in Telegram Bot API
+# bot.send_message(chat_id: chat_id, text: html, parse_mode: 'HTML')
+```
+
+The `to_bot_html` method:
+- Replaces `<br>` tags with `\n`
+- Removes wrappers for hashtags, cashtags, bot commands, media timestamps, and bank card numbers
+- Keeps `tg-spoiler` and `tg-emoji` tags as-is
+- Properly escapes HTML symbols (`<`, `>`, `&`, `"`)
+
 ### Telegram-Specific Tags
 
 When sending HTML to Telegram Bot API, use `allow_telegram_tags: true` to get Telegram-compatible tags. This is especially important for special entity types like spoilers, custom emojis, and cashtags:
@@ -163,6 +190,7 @@ puts html_telegram
 **When to use each mode:**
 - **Standard HTML** (`allow_telegram_tags: false`): For displaying in web browsers or general HTML rendering
 - **Telegram Tags** (`allow_telegram_tags: true`): For sending messages via Telegram Bot API using `parse_mode: 'HTML'`
+- **`to_bot_html`**: Recommended method for Telegram Bot API - automatically formats HTML according to Telegram's requirements (removes auto-processed entity wrappers, replaces `<br>` with `\n`, etc.)
 
 ### Real-World Example
 

data/lib/telegram_entities/entities.rb

@@ -5,6 +5,7 @@ require "nokogiri"
 module TelegramEntities
   # Class that represents a message + set of Telegram entities.
   class Entities
+    include TgBotHtmlParseModeFormat
     attr_accessor :message, :entities
 
     # Creates an Entities container using a message and a list of entities.

data/lib/telegram_entities/tg_bot_html_parse_mode_format.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TelegramEntities
+  # doc: https://core.telegram.org/bots/api#html-style
+  module TgBotHtmlParseModeFormat
+    # Format HTML for Telegram Bot API parse_mode: 'HTML'
+    #
+    # According to Telegram Bot API documentation:
+    # - All <br>, <br/> tags are replaced with \n
+    # - Hashtags, cashtags, bot commands, media timestamps, and bank card numbers
+    #   are sent without wrappers (they are automatically processed by the bot)
+    # - tg-spoiler and tg-emoji tags are left as-is
+    # - All <, >, &, " symbols that are not part of a tag or HTML entity
+    #   are replaced with corresponding HTML entities (&lt;, &gt;, &amp;, &quot;)
+    # - All numerical HTML entities are supported (e.g., &#60;, &#x3C;)
+    # - Named HTML entities are supported: &lt;, &gt;, &amp;, &quot;
+    #
+    # @return [String] Formatted HTML text for Telegram Bot API
+    def to_bot_html
+      html = to_html(true)
+
+      # Replace all <br> and <br/> tags with \n
+      html = html.gsub(/<br\s*\/?>/i, "\n")
+
+      # Remove wrappers for hashtags, cashtags, bot commands, media timestamps, and bank card numbers
+      # These are automatically processed by Telegram, so we just extract the text content
+      html = html.gsub(/<tg-hashtag>(.*?)<\/tg-hashtag>/i) { |_| $1 }
+      html = html.gsub(/<tg-cashtag>(.*?)<\/tg-cashtag>/i) { |_| $1 }
+      html = html.gsub(/<tg-bot-command>(.*?)<\/tg-bot-command>/i) { |_| $1 }
+      html = html.gsub(/<tg-media-timestamp[^>]*>(.*?)<\/tg-media-timestamp>/i) { |_| $1 }
+      html = html.gsub(/<tg-bank-card-number>(.*?)<\/tg-bank-card-number>/i) { |_| $1 }
+
+      html
+    end
+  end
+end

data/lib/telegram_entities/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TelegramEntities
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/telegram_entities.rb

@@ -2,6 +2,7 @@
 
 require_relative "telegram_entities/version"
 require_relative "telegram_entities/entity_tools"
+require_relative "telegram_entities/tg_bot_html_parse_mode_format"
 require_relative "telegram_entities/entities"
 require_relative "telegram_entities/tdlib_converter"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: telegram_entities
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kirill Bobykin
@@ -41,6 +41,7 @@ files:
 - lib/telegram_entities/entities.rb
 - lib/telegram_entities/entity_tools.rb
 - lib/telegram_entities/tdlib_converter.rb
+- lib/telegram_entities/tg_bot_html_parse_mode_format.rb
 - lib/telegram_entities/version.rb
 - sig/telegram_entities.rbs
 homepage: https://github.com/qelphybox/telegram_entities_rb