generaltranslation-icu-messageformat-parser 0.0.0__tar.gz

generaltranslation_icu_messageformat_parser-0.0.0/LICENSE.md

@@ -0,0 +1,123 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 General Translation, Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+---
+
+## Third-Party Attribution
+
+This software includes code derived from
+[pyicumessageformat](https://github.com/SirStendec/pyicumessageformat),
+Copyright (c) 2021 Mike deBeaubien, licensed under the MIT License:
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.

generaltranslation_icu_messageformat_parser-0.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: generaltranslation-icu-messageformat-parser
+Version: 0.0.0
+Summary: ICU MessageFormat parser with whitespace-preserving AST and string reconstruction
+Author: General Translation, Inc.
+Author-email: General Translation, Inc. <support@generaltranslation.com>
+License-Expression: FSL-1.1-ALv2
+License-File: LICENSE.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# generaltranslation-icu-messageformat-parser
+
+A pure-Python ICU MessageFormat parser with whitespace-preserving AST and string reconstruction. Python equivalent of [`@formatjs/icu-messageformat-parser`](https://www.npmjs.com/package/@formatjs/icu-messageformat-parser).
+
+Derived from [pyicumessageformat](https://github.com/SirStendec/pyicumessageformat) by Mike deBeaubien (MIT license).
+
+## Installation
+
+```bash
+pip install generaltranslation-icu-messageformat-parser
+```
+
+No dependencies. Pure Python. Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from generaltranslation_icu_messageformat_parser import Parser, print_ast
+
+parser = Parser()
+ast = parser.parse("{count, plural, one {# item} other {# items}}")
+# [{'name': 'count', 'type': 'plural', 'offset': 0, 'options': {'one': [{'type': 'number', 'name': 'count', 'hash': True}, ' item'], 'other': [{'type': 'number', 'name': 'count', 'hash': True}, ' items']}}]
+```
+
+## API
+
+### `Parser(options=None)`
+
+Create a parser instance with optional configuration.
+
+**Options dict keys:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `subnumeric_types` | `list[str]` | `['plural', 'selectordinal']` | Types that support `#` hash replacement |
+| `submessage_types` | `list[str]` | `['plural', 'selectordinal', 'select']` | Types with sub-message branches |
+| `maximum_depth` | `int` | `50` | Maximum nesting depth |
+| `allow_tags` | `bool` | `False` | Enable XML-style `<tag>` parsing |
+| `strict_tags` | `bool` | `False` | Strict tag parsing mode |
+| `tag_prefix` | `str \| None` | `None` | Required tag name prefix |
+| `tag_type` | `str` | `'tag'` | AST node type string for tags |
+| `include_indices` | `bool` | `False` | Include `start`/`end` positions in AST nodes |
+| `loose_submessages` | `bool` | `False` | Allow loose submessage parsing |
+| `allow_format_spaces` | `bool` | `True` | Allow spaces in format strings |
+| `require_other` | `bool` | `True` | Require `other` branch in plural/select |
+| `preserve_whitespace` | `bool` | `False` | Store whitespace in `_ws` dict on AST nodes for lossless round-trips |
+
+### `Parser.parse(input, tokens=None)`
+
+Parse an ICU MessageFormat string into an AST.
+
+**Args:**
+- `input` (`str`): The ICU MessageFormat string to parse.
+- `tokens` (`list | None`): Optional list to populate with token objects for low-level analysis.
+
+**Returns:** `list` — A list of AST nodes (strings and dicts).
+
+**Raises:** `SyntaxError` on malformed input, `TypeError` if input is not a string.
+
+### `print_ast(ast)`
+
+Reconstruct an ICU MessageFormat string from an AST.
+
+**Args:**
+- `ast` (`list`): The AST as returned by `Parser.parse()`.
+
+**Returns:** `str` — The reconstructed ICU MessageFormat string.
+
+When the AST contains `_ws` whitespace metadata (from `preserve_whitespace=True`), reconstruction is lossless — the output exactly matches the original input. Without whitespace metadata, normalized spacing is used.
+
+## AST Node Types
+
+### String literal
+Plain strings appear directly in the AST list:
+```python
+parser.parse("Hello world")
+# ["Hello world"]
+```
+
+### Simple variable `{name}`
+```python
+{"name": "username"}
+```
+
+### Typed placeholder `{name, type, style}`
+```python
+{"name": "amount", "type": "number", "format": "::currency/USD"}
+```
+
+### Plural / selectordinal `{n, plural, ...}`
+```python
+{
+    "name": "count",
+    "type": "plural",          # or "selectordinal"
+    "offset": 0,               # offset value (0 if none)
+    "options": {
+        "one": [{"type": "number", "name": "count", "hash": True}, " item"],
+        "other": [{"type": "number", "name": "count", "hash": True}, " items"],
+        "=0": ["no items"],    # exact match keys
+    }
+}
+```
+
+### Select `{gender, select, ...}`
+```python
+{
+    "name": "gender",
+    "type": "select",
+    "options": {
+        "male": ["He"],
+        "female": ["She"],
+        "other": ["They"],
+    }
+}
+```
+
+### Hash `#` (inside plural/selectordinal)
+```python
+{"type": "number", "name": "count", "hash": True}
+```
+
+### With `include_indices=True`
+All dict nodes gain `start` and `end` integer fields indicating byte positions in the original string.
+
+### With `preserve_whitespace=True`
+Dict nodes gain a `_ws` dict storing whitespace at each structural position, enabling lossless `print_ast()` round-trips.
+
+## Supported ICU Features
+
+- Simple variable interpolation: `{name}`
+- Plural with CLDR categories: `{n, plural, one {...} other {...}}`
+- Exact match: `{n, plural, =0 {...} =1 {...} other {...}}`
+- Plural offset: `{n, plural, offset:1 ...}`
+- Selectordinal: `{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`
+- Select: `{gender, select, male {...} female {...} other {...}}`
+- Nested expressions: plural inside select, select inside plural, etc.
+- Typed placeholders: `{amount, number}`, `{d, date, short}`
+- ICU escape sequences: `''` for literal quote, `'{...}'` for literal braces
+- Hash `#` replacement inside plural/selectordinal branches
+- XML-style tags (opt-in): `<bold>text</bold>`
+
+## Known Limitations
+
+- **Escape sequences are consumed during parsing.** `''` becomes `'` and `'{...}'` becomes `{...}` in the AST. These cannot be reconstructed by `print_ast()`. This matches the behavior of `@formatjs/icu-messageformat-parser`.

generaltranslation_icu_messageformat_parser-0.0.0/README.md

@@ -0,0 +1,144 @@
+# generaltranslation-icu-messageformat-parser
+
+A pure-Python ICU MessageFormat parser with whitespace-preserving AST and string reconstruction. Python equivalent of [`@formatjs/icu-messageformat-parser`](https://www.npmjs.com/package/@formatjs/icu-messageformat-parser).
+
+Derived from [pyicumessageformat](https://github.com/SirStendec/pyicumessageformat) by Mike deBeaubien (MIT license).
+
+## Installation
+
+```bash
+pip install generaltranslation-icu-messageformat-parser
+```
+
+No dependencies. Pure Python. Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from generaltranslation_icu_messageformat_parser import Parser, print_ast
+
+parser = Parser()
+ast = parser.parse("{count, plural, one {# item} other {# items}}")
+# [{'name': 'count', 'type': 'plural', 'offset': 0, 'options': {'one': [{'type': 'number', 'name': 'count', 'hash': True}, ' item'], 'other': [{'type': 'number', 'name': 'count', 'hash': True}, ' items']}}]
+```
+
+## API
+
+### `Parser(options=None)`
+
+Create a parser instance with optional configuration.
+
+**Options dict keys:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `subnumeric_types` | `list[str]` | `['plural', 'selectordinal']` | Types that support `#` hash replacement |
+| `submessage_types` | `list[str]` | `['plural', 'selectordinal', 'select']` | Types with sub-message branches |
+| `maximum_depth` | `int` | `50` | Maximum nesting depth |
+| `allow_tags` | `bool` | `False` | Enable XML-style `<tag>` parsing |
+| `strict_tags` | `bool` | `False` | Strict tag parsing mode |
+| `tag_prefix` | `str \| None` | `None` | Required tag name prefix |
+| `tag_type` | `str` | `'tag'` | AST node type string for tags |
+| `include_indices` | `bool` | `False` | Include `start`/`end` positions in AST nodes |
+| `loose_submessages` | `bool` | `False` | Allow loose submessage parsing |
+| `allow_format_spaces` | `bool` | `True` | Allow spaces in format strings |
+| `require_other` | `bool` | `True` | Require `other` branch in plural/select |
+| `preserve_whitespace` | `bool` | `False` | Store whitespace in `_ws` dict on AST nodes for lossless round-trips |
+
+### `Parser.parse(input, tokens=None)`
+
+Parse an ICU MessageFormat string into an AST.
+
+**Args:**
+- `input` (`str`): The ICU MessageFormat string to parse.
+- `tokens` (`list | None`): Optional list to populate with token objects for low-level analysis.
+
+**Returns:** `list` — A list of AST nodes (strings and dicts).
+
+**Raises:** `SyntaxError` on malformed input, `TypeError` if input is not a string.
+
+### `print_ast(ast)`
+
+Reconstruct an ICU MessageFormat string from an AST.
+
+**Args:**
+- `ast` (`list`): The AST as returned by `Parser.parse()`.
+
+**Returns:** `str` — The reconstructed ICU MessageFormat string.
+
+When the AST contains `_ws` whitespace metadata (from `preserve_whitespace=True`), reconstruction is lossless — the output exactly matches the original input. Without whitespace metadata, normalized spacing is used.
+
+## AST Node Types
+
+### String literal
+Plain strings appear directly in the AST list:
+```python
+parser.parse("Hello world")
+# ["Hello world"]
+```
+
+### Simple variable `{name}`
+```python
+{"name": "username"}
+```
+
+### Typed placeholder `{name, type, style}`
+```python
+{"name": "amount", "type": "number", "format": "::currency/USD"}
+```
+
+### Plural / selectordinal `{n, plural, ...}`
+```python
+{
+    "name": "count",
+    "type": "plural",          # or "selectordinal"
+    "offset": 0,               # offset value (0 if none)
+    "options": {
+        "one": [{"type": "number", "name": "count", "hash": True}, " item"],
+        "other": [{"type": "number", "name": "count", "hash": True}, " items"],
+        "=0": ["no items"],    # exact match keys
+    }
+}
+```
+
+### Select `{gender, select, ...}`
+```python
+{
+    "name": "gender",
+    "type": "select",
+    "options": {
+        "male": ["He"],
+        "female": ["She"],
+        "other": ["They"],
+    }
+}
+```
+
+### Hash `#` (inside plural/selectordinal)
+```python
+{"type": "number", "name": "count", "hash": True}
+```
+
+### With `include_indices=True`
+All dict nodes gain `start` and `end` integer fields indicating byte positions in the original string.
+
+### With `preserve_whitespace=True`
+Dict nodes gain a `_ws` dict storing whitespace at each structural position, enabling lossless `print_ast()` round-trips.
+
+## Supported ICU Features
+
+- Simple variable interpolation: `{name}`
+- Plural with CLDR categories: `{n, plural, one {...} other {...}}`
+- Exact match: `{n, plural, =0 {...} =1 {...} other {...}}`
+- Plural offset: `{n, plural, offset:1 ...}`
+- Selectordinal: `{n, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}`
+- Select: `{gender, select, male {...} female {...} other {...}}`
+- Nested expressions: plural inside select, select inside plural, etc.
+- Typed placeholders: `{amount, number}`, `{d, date, short}`
+- ICU escape sequences: `''` for literal quote, `'{...}'` for literal braces
+- Hash `#` replacement inside plural/selectordinal branches
+- XML-style tags (opt-in): `<bold>text</bold>`
+
+## Known Limitations
+
+- **Escape sequences are consumed during parsing.** `''` becomes `'` and `'{...}'` becomes `{...}` in the AST. These cannot be reconstructed by `print_ast()`. This matches the behavior of `@formatjs/icu-messageformat-parser`.

generaltranslation_icu_messageformat_parser-0.0.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "generaltranslation-icu-messageformat-parser"
+version = "0.0.0"
+description = "ICU MessageFormat parser with whitespace-preserving AST and string reconstruction"
+readme = "README.md"
+authors = [
+    { name = "General Translation, Inc.", email = "support@generaltranslation.com" }
+]
+requires-python = ">=3.10"
+license = "FSL-1.1-ALv2"
+license-files = ["LICENSE.md"]
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.10.8,<0.11.0"]
+build-backend = "uv_build"

generaltranslation_icu_messageformat_parser-0.0.0/src/generaltranslation_icu_messageformat_parser/__init__.py

@@ -0,0 +1,13 @@
+"""ICU MessageFormat parser with whitespace-preserving AST and string reconstruction.
+
+A Python equivalent of ``@formatjs/icu-messageformat-parser``. Parses ICU
+MessageFormat strings into ASTs and reconstructs strings from ASTs.
+
+Derived from `pyicumessageformat <https://github.com/SirStendec/pyicumessageformat>`_
+by Mike deBeaubien (MIT license).
+"""
+
+from generaltranslation_icu_messageformat_parser._parser import Parser
+from generaltranslation_icu_messageformat_parser._printer import print_ast
+
+__all__ = ["Parser", "print_ast"]

generaltranslation_icu_messageformat_parser-0.0.0/src/generaltranslation_icu_messageformat_parser/_constants.py

@@ -0,0 +1,38 @@
+"""ICU MessageFormat parser constants.
+
+Derived from pyicumessageformat by Mike deBeaubien (MIT).
+"""
+
+CHAR_OPEN = "{"
+CHAR_CLOSE = "}"
+CHAR_TAG_OPEN = "<"
+CHAR_TAG_CLOSE = "/"
+CHAR_TAG_END = ">"
+CHAR_SEP = ","
+CHAR_HASH = "#"
+CHAR_ESCAPE = "'"
+
+OFFSET = "offset:"
+
+VAR_CHARS = [CHAR_OPEN, CHAR_CLOSE]
+
+TAG_CHARS = [CHAR_TAG_OPEN, CHAR_TAG_CLOSE, CHAR_TAG_END]
+
+TAG_CLOSING = CHAR_TAG_CLOSE + CHAR_TAG_END
+TAG_END = CHAR_TAG_OPEN + CHAR_TAG_CLOSE
+
+SPACE_CHARS = [
+    0x20,
+    0x85,
+    0xA0,
+    0x180E,
+    0x2028,
+    0x2029,
+    0x202F,
+    0x205F,
+    0x2060,
+    0x3000,
+    0xFEFF,
+]
+
+CLOSE_TAG = {}

generaltranslation_icu_messageformat_parser-0.0.0/src/generaltranslation_icu_messageformat_parser/_parser.py

@@ -0,0 +1,686 @@
+"""ICU MessageFormat parser.
+
+Derived from pyicumessageformat by Mike deBeaubien (MIT).
+Enhanced with whitespace-preserving AST support.
+"""
+
+from __future__ import annotations
+
+from . import _constants as constants
+
+SEP_OR_CLOSE = f"{constants.CHAR_SEP} or {constants.CHAR_CLOSE}"
+
+
+def _append_token(context: dict, type: str, text: str) -> None:
+    if "tokens" in context:
+        context["tokens"].append({"type": type, "text": text})
+
+
+def _is_alpha(char: str) -> bool:
+    if not char:
+        return False
+    code = ord(char)
+    return (97 <= code <= 122) or (65 <= code <= 90)
+
+
+def _is_digit(char: str) -> bool:
+    if not char:
+        return False
+    code = ord(char)
+    return 0x30 <= code <= 0x39
+
+
+def _is_space(char: str) -> bool:
+    if not char:
+        return False
+    code = ord(char)
+    return (
+        code in constants.SPACE_CHARS
+        or (0x09 <= code <= 0x0D)
+        or (0x2000 <= code <= 0x200D)
+    )
+
+
+def _skip_space(context: dict, ret: bool = False) -> str:
+    msg = context["msg"]
+    length = context["length"]
+    start = context["i"]
+    if start >= length:
+        return ""
+
+    while context["i"] < length and _is_space(msg[context["i"]]):
+        context["i"] += 1
+
+    captured = msg[start : context["i"]]
+    if ret:
+        return captured
+    elif start < context["i"]:
+        _append_token(context, "space", captured)
+    return captured
+
+
+def _recursion(context: dict) -> SyntaxError:
+    return SyntaxError(f"Too much recursion at position {context['i']}")
+
+
+def _unexpected(char, index=None) -> SyntaxError:
+    if isinstance(char, dict):
+        index = char["i"]
+        c = char["msg"][index] if index < char["length"] else "<EOF>"
+        return _unexpected(c, index)
+    return SyntaxError(f'Unexpected "{char}" at position {index}')
+
+
+def _expected(char, found, index=None) -> SyntaxError:
+    if isinstance(found, dict):
+        index = found["i"]
+        f = found["msg"][index] if index < found["length"] else "<EOF>"
+        return _expected(char, f, index)
+    return SyntaxError(
+        f'Expected {char} at position {index} but found "{found if found else "<EOF>"}"'
+    )
+
+
+class Parser:
+    """ICU MessageFormat parser.
+
+    Parses ICU MessageFormat strings into ASTs (list of dicts/strings).
+
+    Args:
+        options: Parser configuration dict. Supported keys:
+
+            - ``subnumeric_types``: Types that support ``#`` (default: ``['plural', 'selectordinal']``)
+            - ``submessage_types``: Types with sub-messages (default: ``['plural', 'selectordinal', 'select']``)
+            - ``maximum_depth``: Max nesting depth (default: ``50``)
+            - ``allow_tags``: Enable XML-style tag parsing (default: ``False``)
+            - ``strict_tags``: Strict tag parsing mode (default: ``False``)
+            - ``tag_prefix``: Required tag name prefix (default: ``None``)
+            - ``tag_type``: AST node type for tags (default: ``'tag'``)
+            - ``include_indices``: Include ``start``/``end`` in AST nodes (default: ``False``)
+            - ``loose_submessages``: Allow loose submessage parsing (default: ``False``)
+            - ``allow_format_spaces``: Allow spaces in format strings (default: ``True``)
+            - ``require_other``: Require ``other`` branch (default: ``True``)
+            - ``preserve_whitespace``: Store whitespace in ``_ws`` dict on AST nodes (default: ``False``)
+    """
+
+    def __init__(self, options: dict | None = None) -> None:
+        self.options = {
+            "subnumeric_types": ["plural", "selectordinal"],
+            "submessage_types": ["plural", "selectordinal", "select"],
+            "maximum_depth": 50,
+            "allow_tags": False,
+            "strict_tags": False,
+            "tag_prefix": None,
+            "tag_type": "tag",
+            "include_indices": False,
+            "loose_submessages": False,
+            "allow_format_spaces": True,
+            "require_other": True,
+            "preserve_whitespace": False,
+        }
+        if isinstance(options, dict):
+            self.options.update(options)
+
+    def parse(self, input: str, tokens: list | None = None) -> list:
+        """Parse an ICU MessageFormat string into an AST.
+
+        Args:
+            input: The ICU MessageFormat string to parse.
+            tokens: Optional list to populate with token objects.
+
+        Returns:
+            A list of AST nodes (strings and dicts).
+        """
+        if not isinstance(input, str):
+            raise TypeError("input must be string")
+
+        context = {
+            "msg": input,
+            "length": len(input),
+            "i": 0,
+            "depth": 0,
+        }
+
+        if tokens is not None:
+            if not isinstance(tokens, list):
+                raise TypeError("tokens must be list or None")
+            context["tokens"] = tokens
+
+        try:
+            return self._parse_ast(context, None)
+        except RecursionError:
+            raise _recursion(context)
+        except IndexError:
+            raise SyntaxError
+
+    def _parse_ast(self, context: dict, parent: dict | None) -> list:
+        msg = context["msg"]
+        length = context["length"]
+        start = context["i"]
+        out: list = []
+
+        text = self._parse_text(context, parent)
+        if text:
+            out.append(text)
+            _append_token(context, "text", msg[start : context["i"]])
+
+        while context["i"] < length:
+            i = context["i"]
+            char = msg[i]
+            if char == constants.CHAR_CLOSE:
+                if not parent:
+                    raise _unexpected(context)
+                break
+
+            if (
+                parent
+                and self.options["allow_tags"]
+                and msg[i : i + len(constants.TAG_END)] == constants.TAG_END
+                and self._can_read_tag(context, parent, True)
+            ):
+                break
+
+            out.append(self._parse_placeholder(context, parent))
+            start = context["i"]
+            text = self._parse_text(context, parent)
+            if text:
+                out.append(text)
+                _append_token(context, "text", msg[start : context["i"]])
+
+        return out
+
+    def _can_read_tag(
+        self, context: dict, parent: dict | None, require_closing: bool = False
+    ) -> bool:
+        msg = context["msg"]
+        length = context["length"]
+        current = context["i"]
+        if not self.options["allow_tags"]:
+            return False
+
+        char = msg[current] if current < length else None
+        if char != constants.CHAR_TAG_OPEN:
+            return False
+
+        if self.options["strict_tags"] and not require_closing:
+            return True
+
+        current += 1
+        char = msg[current] if current < length else None
+
+        if char == constants.CHAR_TAG_CLOSE:
+            if self.options["strict_tags"]:
+                return True
+            current += 1
+            char = msg[current] if current < length else None
+        elif require_closing:
+            return False
+
+        if self.options["tag_prefix"]:
+            prefix = self.options["tag_prefix"]
+            return prefix == msg[current : current + len(prefix)]
+        elif _is_alpha(char):
+            return True
+
+        return False
+
+    def _parse_text(
+        self,
+        context: dict,
+        parent: dict | None,
+        is_arg_style: bool = False,
+    ) -> str:
+        msg = context["msg"]
+        length = context["length"]
+        start = context["i"]
+        is_hash_special = (
+            parent and parent["type"] in self.options["subnumeric_types"]
+        )
+        is_tag_special = self.options["allow_tags"]
+        allow_arg_spaces = self.options["allow_format_spaces"]
+
+        text = ""
+        trailing_space = 0
+
+        while context["i"] < length:
+            char = msg[context["i"]]
+            is_sp = _is_space(char)
+
+            if (
+                char in constants.VAR_CHARS
+                or (is_hash_special and char == constants.CHAR_HASH)
+                or (
+                    is_tag_special
+                    and char == constants.CHAR_TAG_OPEN
+                    and self._can_read_tag(context, parent)
+                )
+                or (is_arg_style and not allow_arg_spaces and is_sp)
+            ):
+                break
+
+            if is_sp:
+                trailing_space += 1
+            else:
+                trailing_space = 0
+
+            if char == constants.CHAR_ESCAPE:
+                context["i"] += 1
+                if context["i"] < length:
+                    char = msg[context["i"]]
+                    if char == constants.CHAR_ESCAPE:
+                        text += char
+                        context["i"] += 1
+                    elif (
+                        char in constants.VAR_CHARS
+                        or (is_hash_special and char == constants.CHAR_HASH)
+                        or char == constants.CHAR_TAG_OPEN
+                        or char == constants.CHAR_TAG_END
+                        or is_arg_style
+                    ):
+                        text += char
+                        context["i"] += 1
+                        while context["i"] < length:
+                            nxt = msg[context["i"]]
+                            if nxt == constants.CHAR_ESCAPE:
+                                context["i"] += 1
+                                if (
+                                    context["i"] < length
+                                    and msg[context["i"]] == constants.CHAR_ESCAPE
+                                ):
+                                    text += nxt
+                                else:
+                                    break
+                            else:
+                                text += nxt
+                            context["i"] += 1
+                    else:
+                        context["i"] += 1
+                        text += constants.CHAR_ESCAPE + char
+                else:
+                    text += char
+            else:
+                text += char
+                context["i"] += 1
+
+        if is_arg_style and trailing_space:
+            trimmed = len(text) - trailing_space
+            if trimmed <= 0:
+                context["i"] = start
+                return ""
+            else:
+                context["i"] -= trailing_space
+                return text[:trimmed]
+
+        return text
+
+    def _token_indices(self, token: dict, start: int, end: int) -> dict:
+        if self.options["include_indices"]:
+            token["start"] = start
+            token["end"] = end
+        return token
+
+    def _parse_placeholder(self, context: dict, parent: dict | None) -> dict:
+        msg = context["msg"]
+        length = context["length"]
+        preserve_ws = self.options["preserve_whitespace"]
+        is_hash_special = (
+            parent and parent["type"] in self.options["subnumeric_types"]
+        )
+
+        start_idx = context["i"]
+        char = msg[start_idx] if start_idx < length else None
+        if is_hash_special and char == constants.CHAR_HASH:
+            _append_token(context, "hash", char)
+            context["i"] += 1
+            return self._token_indices(
+                {"type": "number", "name": parent["name"], "hash": True},
+                start_idx,
+                context["i"],
+            )
+
+        tag = self._parse_tag(context, parent)
+        if tag:
+            return tag
+
+        if char != constants.CHAR_OPEN:
+            raise _expected(constants.CHAR_OPEN, context)
+
+        _append_token(context, "syntax", char)
+        context["i"] += 1
+
+        ws: dict = {}
+        ws_before_name = _skip_space(context, ret=preserve_ws)
+        if preserve_ws:
+            ws["before_name"] = ws_before_name
+
+        name = self._parse_name(context)
+        if not name:
+            raise _expected("placeholder name", context)
+
+        _append_token(context, "name", name)
+        token: dict = {"name": name}
+
+        ws_after_name = _skip_space(context, ret=preserve_ws)
+        if preserve_ws:
+            ws["after_name"] = ws_after_name
+
+        char = msg[context["i"]] if context["i"] < length else None
+
+        if char == constants.CHAR_CLOSE:
+            _append_token(context, "syntax", char)
+            context["i"] += 1
+            if preserve_ws and ws:
+                token["_ws"] = ws
+            return self._token_indices(token, start_idx, context["i"])
+
+        if char != constants.CHAR_SEP:
+            raise _expected(SEP_OR_CLOSE, context)
+
+        _append_token(context, "syntax", char)
+        context["i"] += 1
+
+        ws_after_type_sep = _skip_space(context, ret=preserve_ws)
+        if preserve_ws:
+            ws["after_type_sep"] = ws_after_type_sep
+
+        ttype = self._parse_name(context)
+        if not ttype:
+            raise _expected("placeholder type", context)
+
+        _append_token(context, "type", ttype)
+        token["type"] = ttype
+
+        ws_after_type = _skip_space(context, ret=preserve_ws)
+        if preserve_ws:
+            ws["after_type"] = ws_after_type
+
+        char = msg[context["i"]] if context["i"] < length else None
+        if char == constants.CHAR_CLOSE:
+            _append_token(context, "syntax", char)
+            if ttype in self.options["submessage_types"]:
+                raise _expected(f"{ttype} sub-messages", context)
+            context["i"] += 1
+            if preserve_ws and ws:
+                token["_ws"] = ws
+            return self._token_indices(token, start_idx, context["i"])
+
+        if char != constants.CHAR_SEP:
+            raise _expected(SEP_OR_CLOSE, context)
+
+        _append_token(context, "syntax", char)
+        context["i"] += 1
+
+        ws_after_style_sep = _skip_space(context, ret=preserve_ws)
+        if preserve_ws:
+            ws["after_style_sep"] = ws_after_style_sep
+
+        if ttype in self.options["subnumeric_types"]:
+            offset = self._parse_offset(context)
+            token["offset"] = offset if offset else 0
+            if offset:
+                _skip_space(context)
+
+        if ttype in self.options["submessage_types"]:
+            messages = self._parse_submessages(context, token)
+            if not messages:
+                raise _expected(f"{ttype} sub-messages", context)
+            token["options"] = messages
+        else:
+            start = context["i"]
+            fmt = self._parse_text(context, token, True)
+            if not fmt:
+                raise _expected("placeholder style", context)
+
+            end = context["i"]
+            spaces = _skip_space(context, True)
+
+            if (
+                self.options["loose_submessages"]
+                and context["i"] < length
+                and msg[context["i"]] == constants.CHAR_OPEN
+            ):
+                context["i"] = start
+                messages = self._parse_submessages(context, token)
+                if not messages:
+                    raise _expected(f"{ttype} sub-messages", context)
+                token["options"] = messages
+            else:
+                token["format"] = fmt
+                _append_token(context, "style", msg[start:end])
+                if spaces:
+                    _append_token(context, "space", spaces)
+
+        ws_before_close = _skip_space(context, ret=preserve_ws)
+        if preserve_ws:
+            ws["before_close"] = ws_before_close
+
+        char = msg[context["i"]] if context["i"] < length else None
+        if char != constants.CHAR_CLOSE:
+            raise _expected(constants.CHAR_CLOSE, context)
+
+        _append_token(context, "syntax", char)
+        context["i"] += 1
+
+        if preserve_ws and ws:
+            token["_ws"] = ws
+
+        return self._token_indices(token, start_idx, context["i"])
+
+    def _parse_tag(self, context: dict, parent: dict | None) -> dict | None:
+        if not self.options["allow_tags"]:
+            return None
+
+        if not self._can_read_tag(context, parent):
+            return None
+
+        msg = context["msg"]
+        length = context["length"]
+        i = context["i"]
+        start_idx = i
+        char = msg[i] if i < length else None
+
+        if char != constants.CHAR_TAG_OPEN:
+            return None
+
+        if msg[i : i + len(constants.TAG_END)] == constants.TAG_END:
+            raise _unexpected(constants.TAG_END, i)
+
+        context["i"] += 1
+        name = self._parse_name(context, True)
+        if not name:
+            if not self.options["strict_tags"]:
+                context["i"] = start_idx
+                return None
+            raise _expected("tag name", context)
+
+        _append_token(context, "syntax", char)
+        token: dict = {"type": self.options["tag_type"], "name": name}
+        _append_token(context, "name", name)
+        _skip_space(context)
+
+        i = context["i"]
+        if (
+            i < length
+            and msg[i : i + len(constants.TAG_CLOSING)] == constants.TAG_CLOSING
+        ):
+            _append_token(context, "syntax", constants.TAG_CLOSING)
+            context["i"] += len(constants.TAG_CLOSING)
+            return self._token_indices(token, start_idx, context["i"])
+
+        char = msg[i] if i < length else None
+        if char != constants.CHAR_TAG_END:
+            raise _expected(
+                constants.CHAR_TAG_END + " or " + constants.TAG_CLOSING, context
+            )
+
+        _append_token(context, "syntax", char)
+        context["i"] += 1
+
+        children = self._parse_ast(context, token)
+        if children:
+            token["contents"] = children
+        end = context["i"]
+
+        if (
+            end < length
+            and msg[end : end + len(constants.TAG_END)] != constants.TAG_END
+        ):
+            raise _expected(constants.TAG_END, context)
+
+        _append_token(context, "syntax", constants.TAG_END)
+        context["i"] += len(constants.TAG_END)
+
+        close_name = self._parse_name(context, True)
+        if close_name:
+            _append_token(context, "name", close_name)
+        if close_name != name:
+            raise _expected(
+                constants.TAG_END + name + constants.CHAR_TAG_END,
+                msg[end] if end < length else "<EOF>",
+                end,
+            )
+
+        _skip_space(context)
+        char = msg[context["i"]] if context["i"] < length else None
+        if char != constants.CHAR_TAG_END:
+            raise _expected(constants.CHAR_TAG_END, context)
+
+        _append_token(context, "syntax", char)
+        context["i"] += 1
+        return self._token_indices(token, start_idx, context["i"])
+
+    def _parse_name(self, context: dict, is_tag: bool = False) -> str:
+        msg = context["msg"]
+        length = context["length"]
+        name = ""
+
+        while context["i"] < length:
+            char = msg[context["i"]]
+            if (
+                char in constants.VAR_CHARS
+                or char == constants.CHAR_SEP
+                or char == constants.CHAR_HASH
+                or char == constants.CHAR_ESCAPE
+                or _is_space(char)
+                or (is_tag and char in constants.TAG_CHARS)
+            ):
+                break
+            name += char
+            context["i"] += 1
+
+        return name
+
+    def _parse_offset(self, context: dict) -> int:
+        msg = context["msg"]
+        length = context["length"]
+        start = context["i"]
+
+        if start >= length or msg[start : start + len(constants.OFFSET)] != constants.OFFSET:
+            return 0
+
+        _append_token(context, "offset", constants.OFFSET)
+        context["i"] += len(constants.OFFSET)
+        _skip_space(context)
+
+        start = context["i"]
+        while context["i"] < length and (
+            _is_digit(msg[context["i"]])
+            or (context["i"] == start and msg[context["i"]] == "-")
+        ):
+            context["i"] += 1
+
+        if start == context["i"]:
+            raise _expected("offset number", context)
+
+        offset = msg[start : context["i"]]
+        _append_token(context, "number", offset)
+        return int(offset, 10)
+
+    def _parse_submessages(self, context: dict, parent: dict) -> dict | None:
+        msg = context["msg"]
+        length = context["length"]
+        preserve_ws = self.options["preserve_whitespace"]
+        options: dict = {}
+
+        context["depth"] += 1
+
+        while context["i"] < length and msg[context["i"]] != constants.CHAR_CLOSE:
+            # Save position before consuming space so we can rewind if we hit }
+            pre_space_pos = context["i"]
+            ws_before_selector = _skip_space(context, ret=preserve_ws) if preserve_ws else _skip_space(context)
+
+            if context["i"] >= length or msg[context["i"]] == constants.CHAR_CLOSE:
+                # Rewind: this trailing space belongs to the outer placeholder's before_close
+                if preserve_ws:
+                    context["i"] = pre_space_pos
+                break
+
+            selector = self._parse_name(context)
+            if not selector:
+                raise _expected("sub-message selector", context)
+            _append_token(context, "selector", selector)
+
+            ws_after_selector = _skip_space(context, ret=preserve_ws) if preserve_ws else _skip_space(context)
+
+            submessage = self._parse_submessage(context, parent)
+
+            if preserve_ws:
+                # Store whitespace metadata on the submessage list
+                # We use a wrapper dict so we can attach _ws
+                options[selector] = submessage
+                # Store selector whitespace as metadata on the options dict
+                if "_ws" not in options:
+                    options["_ws"] = {}
+                options["_ws"][selector] = {
+                    "before_selector": ws_before_selector or "",
+                    "after_selector": ws_after_selector or "",
+                }
+            else:
+                options[selector] = submessage
+
+            if not preserve_ws:
+                _skip_space(context)
+
+        context["depth"] -= 1
+
+        if not options or (len(options) == 1 and "_ws" in options):
+            return None
+
+        req = self.options["require_other"]
+        ttype = parent["type"] if parent else None
+        if req == "all":
+            req = True
+        elif req == "subnumeric":
+            req = self.options["subnumeric_types"]
+        elif req and not isinstance(req, list):
+            req = self.options["submessage_types"]
+        if isinstance(req, list):
+            req = ttype in req
+
+        if req and "other" not in options:
+            raise _expected(f"{ttype} sub-message other", context)
+
+        return options
+
+    def _parse_submessage(self, context: dict, parent: dict) -> list:
+        if context["depth"] >= self.options["maximum_depth"]:
+            raise _recursion(context)
+
+        msg = context["msg"]
+        length = context["length"]
+        if context["i"] >= length or msg[context["i"]] != constants.CHAR_OPEN:
+            raise _expected(constants.CHAR_OPEN, context)
+
+        _append_token(context, "syntax", constants.CHAR_OPEN)
+        context["i"] += 1
+
+        message = self._parse_ast(context, parent)
+
+        char = msg[context["i"]] if context["i"] < length else None
+        if char != constants.CHAR_CLOSE:
+            raise _expected(constants.CHAR_CLOSE, context)
+
+        _append_token(context, "syntax", constants.CHAR_CLOSE)
+        context["i"] += 1
+
+        return message

generaltranslation_icu_messageformat_parser-0.0.0/src/generaltranslation_icu_messageformat_parser/_printer.py

@@ -0,0 +1,168 @@
+"""AST to ICU MessageFormat string reconstruction.
+
+Reconstructs an ICU MessageFormat string from an AST produced by
+:class:`Parser`. When the AST contains ``_ws`` whitespace metadata
+(from ``preserve_whitespace=True``), the reconstruction is lossless.
+Otherwise, normalized whitespace (single spaces) is used.
+"""
+
+from __future__ import annotations
+
+import re
+
+from . import _constants as constants
+
+_BRACE_RE = re.compile(r"([{}](?:[\s\S]*[{}])?)")
+
+
+def print_ast(ast: list) -> str:
+    """Reconstruct an ICU MessageFormat string from an AST.
+
+    Args:
+        ast: The AST as returned by :meth:`Parser.parse`.
+
+    Returns:
+        The reconstructed ICU MessageFormat string.
+    """
+    return _print_nodes(ast)
+
+
+def _escape_message(message: str) -> str:
+    """Wrap the first region containing ``{`` or ``}`` in single quotes.
+
+    Port of JS ``printEscapedMessage``.
+    """
+    return _BRACE_RE.sub(r"'\1'", message, count=1)
+
+
+def _print_literal(
+    value: str, is_in_plural: bool, is_first: bool, is_last: bool
+) -> str:
+    """Re-escape a literal text node for safe ICU round-tripping.
+
+    Port of JS ``printLiteralElement``.
+    """
+    escaped = value
+
+    # Double leading ' when not first element (prevents mis-parse after })
+    if not is_first and escaped and escaped[0] == "'":
+        escaped = "''" + escaped[1:]
+
+    # Double trailing ' when not last element (prevents mis-parse before {)
+    if not is_last and escaped and escaped[-1] == "'":
+        escaped = escaped[:-1] + "''"
+
+    # Re-escape {} regions
+    escaped = _escape_message(escaped)
+
+    # Re-escape # in plural context
+    if is_in_plural:
+        escaped = escaped.replace("#", "'#'")
+
+    return escaped
+
+
+def _print_nodes(nodes: list, is_in_plural: bool = False) -> str:
+    parts: list[str] = []
+    for i, node in enumerate(nodes):
+        if isinstance(node, str):
+            parts.append(
+                _print_literal(node, is_in_plural, i == 0, i == len(nodes) - 1)
+            )
+        elif isinstance(node, dict):
+            parts.append(_print_node(node))
+    return "".join(parts)
+
+
+def _print_node(node: dict) -> str:
+    ws = node.get("_ws", {})
+
+    # Hash replacement node (#)
+    if node.get("hash"):
+        return constants.CHAR_HASH
+
+    name = node.get("name", "")
+    node_type = node.get("type")
+
+    # Tag node
+    if node_type == "tag" or (node_type and node.get("contents") is not None):
+        contents = node.get("contents", [])
+        return (
+            constants.CHAR_TAG_OPEN
+            + name
+            + constants.CHAR_TAG_END
+            + _print_nodes(contents)
+            + constants.TAG_END
+            + name
+            + constants.CHAR_TAG_END
+        )
+
+    # Simple variable: {name}
+    if node_type is None and "options" not in node and "format" not in node:
+        before = ws.get("before_name", "")
+        after = ws.get("after_name", "")
+        return constants.CHAR_OPEN + before + name + after + constants.CHAR_CLOSE
+
+    # Typed placeholder
+    # JS printAST uses no spaces after commas for select/plural but spaces
+    # for simple format types (number, date, time).
+    has_options = "options" in node
+    default_sep = "" if has_options else " "
+
+    before_name = ws.get("before_name", "")
+    after_name = ws.get("after_name", "")
+    after_type_sep = ws.get("after_type_sep", default_sep)
+    after_type = ws.get("after_type", "")
+    after_style_sep = ws.get("after_style_sep", default_sep)
+    before_close = ws.get("before_close", "")
+
+    result = constants.CHAR_OPEN + before_name + name + after_name
+
+    if node_type:
+        result += constants.CHAR_SEP + after_type_sep + node_type + after_type
+
+    # Format string (e.g. {n, number, ::currency/USD})
+    if "format" in node:
+        result += constants.CHAR_SEP + after_style_sep + node["format"]
+        result += before_close + constants.CHAR_CLOSE
+        return result
+
+    # Submessages (plural, select, selectordinal)
+    if "options" in node:
+        result += constants.CHAR_SEP + after_style_sep
+
+        # Offset for plural/selectordinal
+        offset = node.get("offset", 0)
+        if offset:
+            result += f"offset:{offset} "
+
+        options = node["options"]
+        options_ws = options.get("_ws", {}) if isinstance(options.get("_ws"), dict) else {}
+
+        child_in_plural = node_type in ("plural", "selectordinal")
+
+        first = True
+        for key, value in options.items():
+            if key == "_ws":
+                continue
+
+            selector_ws = options_ws.get(key, {})
+            before_sel = selector_ws.get("before_selector", "" if first else " ")
+            after_sel = selector_ws.get("after_selector", "")
+
+            if not first:
+                result += before_sel
+            else:
+                first = False
+
+            result += key + after_sel
+            result += constants.CHAR_OPEN
+            if isinstance(value, list):
+                result += _print_nodes(value, is_in_plural=child_in_plural)
+            result += constants.CHAR_CLOSE
+
+        result += before_close + constants.CHAR_CLOSE
+        return result
+
+    result += before_close + constants.CHAR_CLOSE
+    return result