PhoneNumberLib for 1C:Enterprise

Version: 1.0
Platform: 1C:Enterprise 8.3 (English Syntax)
Authors: Alexei Snitkovski (with Gemini 3 and Antigravity)
Inspired by: Google's libphonenumber
Acknowledgments: System and Project prompts for neuro-programming were inspired by and largely based on materials from my friend and AI-coding enthusiast Petr Tsap (Inkasor)

Please, follow our channel-club on Telegram: Yellow AI Vibe

📚 Description

A lightweight, metadata-driven Library for parsing, validating and formatting phone numbers in 1C:Enterprise based solutions - designed to be a robust, zero-dependency alternative to external libraries for specific business needs.

🌍 Supported Countries

Country	ISO	Code	Format Example
Moldova	MD	+373	+373 69 123 456
Romania	RO	+40	+40 721 234 567
Ukraine	UA	+380	+380 50 123 4567
Russia	RU	+7	+7 912 345 6789

✨ Key Features

• Parsing: Extracts country code and national number from raw strings, handling various input formats.
• Validation: Checks length and numeric content based on strict country rules.
• Smart Detection: Automatically resolves conflicts (e.g., distinguishing UA vs RO numbers entered without country code) using LeadingDigits analysis.
• Formatting: Supports E.164, International, and National formats via metadata rules.
• Metadata-Driven: Logic is separated from data. Adding a new country requires NO code changes in algorithms.
• Diagnostic Logging: Built-in tracing for debugging complex cases.

🛠 Public API

ParsePhoneNumber(PhoneNumberString, DefaultCountry, OutputMessages)

Parses a raw string into a structured object

• Returns: Structure (CountryCode, NationalNumber, IsValid, Country, etc.)

ValidatePhoneNumber(PhoneNumber, OutputMessages)

Validates a parsed structure against metadata rules (length, allowed characters)

• Returns: Boolean

FormatPhoneNumber(PhoneNumber, FormatType, OutputMessages)

Formats the number according to the requested standard

• FormatType: "E164", "International", "National"
• Returns: String

IsValidNumber(PhoneNumberString, DefaultCountry, OutputMessages)

Quick helper for one-shot validation

• Returns: Boolean

🚀 Usage Examples

1. Parse and Validate

PhoneNumber = PhoneNumberLib.ParsePhoneNumber("+37369123456", "MD");

If PhoneNumber.IsValid Then
    // Output: Valid phone: +37369123456
    Message("Valid phone: " + PhoneNumber.CountryCode + PhoneNumber.NationalNumber);
EndIf;

2. Smart Detection (Lazy Input)

Handling input like 0721234567 (Romania) when the default context is Ukraine

// Library detects RO based on leading digit '7' (UA doesn't use 7 as first digit)
PhoneNumber = PhoneNumberLib.ParsePhoneNumber("0721234567", "UA"); 

Message(PhoneNumber.Country); 
// Output: RO

3. Formatting

PhoneNumber = PhoneNumberLib.ParsePhoneNumber("+373691234567");

E164 = PhoneNumberLib.FormatPhoneNumber(PhoneNumber, "E164");
// Output: "+373691234567"

International = PhoneNumberLib.FormatPhoneNumber(PhoneNumber, "International");
// Output: "+373 69 123 456"

National = PhoneNumberLib.FormatPhoneNumber(PhoneNumber, "National");
// Output: "069 123 456"

⚙️ Developer Guide: Adding New Countries

To add a new country, you only need to modify GetAllCountriesMetadata() in src/PhoneNumberLib.bsl

1. Create a new Structure for the country
2. Fill in required fields:
   • CountryCode: International code (e.g., "+1")
   • CountryISO: ISO 2-letter code (e.g., "US")
   • MinLength / MaxLength: Length of national number
   • NationalPrefix: Prefix used domestically (e.g., "1")
   • NationalPrefixSpace: True if space needed after prefix
   • LeadingDigits: Comma-separated list of allowed first digits (e.g., "2,3,4") — Critical for Smart Detection
   • FormatGroups: Array of numbers defining digit grouping (e.g., [3, 3, 4])
3. Add to Metadata array: PhonesMetadata.Add(NewCountry)

---

PhoneNumberLib для 1С:Предприятие (Description Russian Version)

Версия: 1.0
Платформа: 1С:Предприятие 8.3 (Английский синтаксис)
Авторы: Алексей Снитковский (совместно с Gemini 3 и Antigravity)
Вдохновлено: Google's libphonenumber
Благодарности: Системные и Проектные промпты для нейро-программирования были вдохновлены и во многом исполнены по материалам моего друга и AI-coding энтузиаста Петр Цап (Inkasor)

Если вам интересна тема вайб-кодинга на 1С (результатом которого является в том числе и данная Библиотека) - подключайтесь к нашему ламповому сообществу в Телеграм-Канале-Клубе Желтый AI Вайб

📚 Описание

Легковесная, управляемая метаданными Библиотека для парсинга, валидации и форматирования телефонных номеров в решениях на Платформе 1С:Предприятие - разработана как надежная альтернатива внешним компонентам, без лишних зависимостей.

🌍 Поддерживаемые Страны

Страна	ISO	Код	Пример формата
Молдова	MD	+373	+373 69 123 456
Румыния	RO	+40	+40 721 234 567
Украина	UA	+380	+380 50 123 4567
Россия	RU	+7	+7 912 345 6789

✨ Ключевые Возможности

• Парсинг: Извлекает код страны и национальный номер из "сырых" строк, обрабатывая различные форматы ввода.
• Валидация: Проверяет длину и состав номера на основе строгих правил для каждой страны.
• Умная Детекция (Smart Detection): Автоматически разрешает конфликты (например, отличает номера UA от RO при вводе без кода страны), используя анализ первых цифр (LeadingDigits).
• Форматирование: Поддерживает форматы E.164, International и National через правила в метаданных.
• Управление Метаданными: Логика отделена от данных. Добавление новой страны НЕ требует изменения программного кода алгоритмов.
• Диагностическое Логирование: Встроенная трассировка для отладки сложных случаев.

🛠 Публичный API

ParsePhoneNumber(PhoneNumberString, DefaultCountry, OutputMessages)

Разбирает строку номера в структуру

• Возвращает: Структуру (CountryCode, NationalNumber, IsValid, Country и др.)

ValidatePhoneNumber(PhoneNumber, OutputMessages)

Проверяет разобранную структуру по правилам метаданных

• Возвращает: Булево

FormatPhoneNumber(PhoneNumber, FormatType, OutputMessages)

Форматирует номер согласно запрошенному стандарту

• FormatType: "E164", "International", "National"
• Возвращает: Строку

IsValidNumber(PhoneNumberString, DefaultCountry, OutputMessages)

Быстрый помощник для проверки номера одной строкой

• Возвращает: Булево

🚀 Примеры Использования

1. Парсинг и Валидация

PhoneNumber = PhoneNumberLib.ParsePhoneNumber("+37369123456", "MD");

If PhoneNumber.IsValid Then
    // Вывод: Valid phone: +37369123456
    Message("Valid phone: " + PhoneNumber.CountryCode + PhoneNumber.NationalNumber);
EndIf;

2. Умная Детекция (Ленивый Ввод)

Обработка ввода вида 0721234567 (Румыния), когда контекст по умолчанию — Украина

// Библиотека определяет RO по первой цифре '7' (в UA номера не начинаются с 7)
PhoneNumber = PhoneNumberLib.ParsePhoneNumber("0721234567", "UA"); 

Message(PhoneNumber.Country); 
// Вывод: RO

3. Форматирование

PhoneNumber = PhoneNumberLib.ParsePhoneNumber("+373691234567");

E164 = PhoneNumberLib.FormatPhoneNumber(PhoneNumber, "E164");
// Вывод: "+373691234567"

International = PhoneNumberLib.FormatPhoneNumber(PhoneNumber, "International");
// Вывод: "+373 69 123 456"

National = PhoneNumberLib.FormatPhoneNumber(PhoneNumber, "National");
// Вывод: "069 123 456"

⚙️ Руководство Разработчика: Добавление Стран

Чтобы добавить новую страну, нужно изменить только функцию GetAllCountriesMetadata() в модуле src/PhoneNumberLib.bsl

1. Создайте новую Структуру для страны
2. Заполните обязательные поля:
   • CountryCode: Международный код (например, "+1")
   • CountryISO: ISO код (например, "US")
   • MinLength / MaxLength: Длина национального номера
   • NationalPrefix: Внутренний префикс (например, "1" или "0")
   • NationalPrefixSpace: True если нужен пробел после префикса
   • LeadingDigits: Список разрешенных первых цифр (например, "2,3,4") — Критично для Умной Детекции
   • FormatGroups: Массив чисел, определяющий группировку цифр (например, [3, 3, 4])
3. Добавьте в массив Metadata: PhonesMetadata.Add(NewCountry)

---

Developed by Alexei Snitkovski in collaboration with Gemini 3 & Antigravity

---

📄 License / Лицензия

This project is licensed under the MIT License - see the LICENSE file for details

Этот проект лицензируется на условиях MIT License - подробности см. в файле LICENSE Вы можете свободно использовать, модифицировать и распространять этот код в личных и коммерческих целях при условии сохранения уведомления об авторстве.