omlish 0.0.0.dev268__py3-none-any.whl → 0.0.0.dev270__py3-none-any.whl

omlish/formats/toml/parser.py

@@ -57,75 +57,6 @@ TomlPos = int  # ta.TypeAlias
 ##
 
 
-_TOML_TIME_RE_STR = r'([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(?:\.([0-9]{1,6})[0-9]*)?'
-
-TOML_RE_NUMBER = re.compile(
-    r"""
-0
-(?:
-    x[0-9A-Fa-f](?:_?[0-9A-Fa-f])*   # hex
-    |
-    b[01](?:_?[01])*                 # bin
-    |
-    o[0-7](?:_?[0-7])*               # oct
-)
-|
-[+-]?(?:0|[1-9](?:_?[0-9])*)         # dec, integer part
-(?P<floatpart>
-    (?:\.[0-9](?:_?[0-9])*)?         # optional fractional part
-    (?:[eE][+-]?[0-9](?:_?[0-9])*)?  # optional exponent part
-)
-""",
-    flags=re.VERBOSE,
-)
-TOML_RE_LOCALTIME = re.compile(_TOML_TIME_RE_STR)
-TOML_RE_DATETIME = re.compile(
-    rf"""
-([0-9]{{4}})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])  # date, e.g. 1988-10-27
-(?:
-    [Tt ]
-    {_TOML_TIME_RE_STR}
-    (?:([Zz])|([+-])([01][0-9]|2[0-3]):([0-5][0-9]))?  # optional time offset
-)?
-""",
-    flags=re.VERBOSE,
-)
-
-
-def toml_match_to_datetime(match: re.Match) -> ta.Union[datetime.datetime, datetime.date]:
-    """Convert a `RE_DATETIME` match to `datetime.datetime` or `datetime.date`.
-
-    Raises ValueError if the match does not correspond to a valid date or datetime.
-    """
-    (
-        year_str,
-        month_str,
-        day_str,
-        hour_str,
-        minute_str,
-        sec_str,
-        micros_str,
-        zulu_time,
-        offset_sign_str,
-        offset_hour_str,
-        offset_minute_str,
-    ) = match.groups()
-    year, month, day = int(year_str), int(month_str), int(day_str)
-    if hour_str is None:
-        return datetime.date(year, month, day)
-    hour, minute, sec = int(hour_str), int(minute_str), int(sec_str)
-    micros = int(micros_str.ljust(6, '0')) if micros_str else 0
-    if offset_sign_str:
-        tz: ta.Optional[datetime.tzinfo] = toml_cached_tz(
-            offset_hour_str, offset_minute_str, offset_sign_str,
-        )
-    elif zulu_time:
-        tz = datetime.UTC
-    else:  # local date-time
-        tz = None
-    return datetime.datetime(year, month, day, hour, minute, sec, micros, tzinfo=tz)
-
-
 @functools.lru_cache()  # noqa
 def toml_cached_tz(hour_str: str, minute_str: str, sign_str: str) -> datetime.timezone:
     sign = 1 if sign_str == '+' else -1
@@ -137,47 +68,25 @@ def toml_cached_tz(hour_str: str, minute_str: str, sign_str: str) -> datetime.ti
     )
 
 
-def toml_match_to_localtime(match: re.Match) -> datetime.time:
-    hour_str, minute_str, sec_str, micros_str = match.groups()
-    micros = int(micros_str.ljust(6, '0')) if micros_str else 0
-    return datetime.time(int(hour_str), int(minute_str), int(sec_str), micros)
-
-
-def toml_match_to_number(match: re.Match, parse_float: TomlParseFloat) -> ta.Any:
-    if match.group('floatpart'):
-        return parse_float(match.group())
-    return int(match.group(), 0)
-
-
-TOML_ASCII_CTRL = frozenset(chr(i) for i in range(32)) | frozenset(chr(127))
-
-# Neither of these sets include quotation mark or backslash. They are currently handled as separate cases in the parser
-# functions.
-TOML_ILLEGAL_BASIC_STR_CHARS = TOML_ASCII_CTRL - frozenset('\t')
-TOML_ILLEGAL_MULTILINE_BASIC_STR_CHARS = TOML_ASCII_CTRL - frozenset('\t\n')
+def toml_make_safe_parse_float(parse_float: TomlParseFloat) -> TomlParseFloat:
+    """
+    A decorator to make `parse_float` safe.
 
-TOML_ILLEGAL_LITERAL_STR_CHARS = TOML_ILLEGAL_BASIC_STR_CHARS
-TOML_ILLEGAL_MULTILINE_LITERAL_STR_CHARS = TOML_ILLEGAL_MULTILINE_BASIC_STR_CHARS
+    `parse_float` must not return dicts or lists, because these types would be mixed with parsed TOML tables and arrays,
+    thus confusing the parser. The returned decorated callable raises `ValueError` instead of returning illegal types.
+    """
 
-TOML_ILLEGAL_COMMENT_CHARS = TOML_ILLEGAL_BASIC_STR_CHARS
+    # The default `float` callable never returns illegal types. Optimize it.
+    if parse_float is float:
+        return float
 
-TOML_WS = frozenset(' \t')
-TOML_WS_AND_NEWLINE = TOML_WS | frozenset('\n')
-TOML_BARE_KEY_CHARS = frozenset(string.ascii_letters + string.digits + '-_')
-TOML_KEY_INITIAL_CHARS = TOML_BARE_KEY_CHARS | frozenset("\"'")
-TOML_HEXDIGIT_CHARS = frozenset(string.hexdigits)
+    def safe_parse_float(float_str: str) -> ta.Any:
+        float_value = parse_float(float_str)
+        if isinstance(float_value, (dict, list)):
+            raise ValueError('parse_float must not return dicts or lists')  # noqa
+        return float_value
 
-TOML_BASIC_STR_ESCAPE_REPLACEMENTS = types.MappingProxyType(
-    {
-        '\\b': '\u0008',  # backspace
-        '\\t': '\u0009',  # tab
-        '\\n': '\u000A',  # linefeed
-        '\\f': '\u000C',  # form feed
-        '\\r': '\u000D',  # carriage return
-        '\\"': '\u0022',  # quote
-        '\\\\': '\u005C',  # backslash
-    },
-)
+    return safe_parse_float
 
 
 class TomlDecodeError(ValueError):
@@ -202,63 +111,15 @@ def toml_loads(s: str, /, *, parse_float: TomlParseFloat = float) -> ta.Dict[str
         src = s.replace('\r\n', '\n')
     except (AttributeError, TypeError):
         raise TypeError(f"Expected str object, not '{type(s).__qualname__}'") from None
-    pos = 0
-    out = TomlOutput(TomlNestedDict(), TomlFlags())
-    header: TomlKey = ()
+
     parse_float = toml_make_safe_parse_float(parse_float)
 
-    # Parse one statement at a time (typically means one line in TOML source)
-    while True:
-        # 1. Skip line leading whitespace
-        pos = toml_skip_chars(src, pos, TOML_WS)
-
-        # 2. Parse rules. Expect one of the following:
-        #    - end of file
-        #    - end of line
-        #    - comment
-        #    - key/value pair
-        #    - append dict to list (and move to its namespace)
-        #    - create dict (and move to its namespace)
-        # Skip trailing whitespace when applicable.
-        try:
-            char = src[pos]
-        except IndexError:
-            break
-        if char == '\n':
-            pos += 1
-            continue
-        if char in TOML_KEY_INITIAL_CHARS:
-            pos = toml_key_value_rule(src, pos, out, header, parse_float)
-            pos = toml_skip_chars(src, pos, TOML_WS)
-        elif char == '[':
-            try:
-                second_char: ta.Optional[str] = src[pos + 1]
-            except IndexError:
-                second_char = None
-            out.flags.finalize_pending()
-            if second_char == '[':
-                pos, header = toml_create_list_rule(src, pos, out)
-            else:
-                pos, header = toml_create_dict_rule(src, pos, out)
-            pos = toml_skip_chars(src, pos, TOML_WS)
-        elif char != '#':
-            raise toml_suffixed_err(src, pos, 'Invalid statement')
-
-        # 3. Skip comment
-        pos = toml_skip_comment(src, pos)
-
-        # 4. Expect end of line or end of file
-        try:
-            char = src[pos]
-        except IndexError:
-            break
-        if char != '\n':
-            raise toml_suffixed_err(
-                src, pos, 'Expected newline or end of document after a statement',
-            )
-        pos += 1
+    parser = TomlParser(
+        src,
+        parse_float=parse_float,
+    )
 
-    return out.data.dict
+    return parser.parse()
 
 
 class TomlFlags:
@@ -270,6 +131,8 @@ class TomlFlags:
     EXPLICIT_NEST = 1
 
     def __init__(self) -> None:
+        super().__init__()
+
         self._flags: ta.Dict[str, dict] = {}
         self._pending_flags: ta.Set[ta.Tuple[TomlKey, int]] = set()
 
@@ -320,6 +183,8 @@ class TomlFlags:
 
 class TomlNestedDict:
     def __init__(self) -> None:
+        super().__init__()
+
         # The parsed content of the TOML document
         self.dict: ta.Dict[str, ta.Any] = {}
 
@@ -352,476 +217,610 @@ class TomlNestedDict:
             cont[last_key] = [{}]
 
 
-class TomlOutput(ta.NamedTuple):
-    data: TomlNestedDict
-    flags: TomlFlags
+class TomlParser:
+    def __init__(
+            self,
+            src: str,
+            *,
+            parse_float: TomlParseFloat = float,
+    ) -> None:
+        super().__init__()
 
+        self.src = src
 
-def toml_skip_chars(src: str, pos: TomlPos, chars: ta.Iterable[str]) -> TomlPos:
-    try:
-        while src[pos] in chars:
-            pos += 1
-    except IndexError:
-        pass
-    return pos
-
-
-def toml_skip_until(
-        src: str,
-        pos: TomlPos,
-        expect: str,
-        *,
-        error_on: ta.FrozenSet[str],
-        error_on_eof: bool,
-) -> TomlPos:
-    try:
-        new_pos = src.index(expect, pos)
-    except ValueError:
-        new_pos = len(src)
-        if error_on_eof:
-            raise toml_suffixed_err(src, new_pos, f'Expected {expect!r}') from None
+        self.parse_float = parse_float
 
-    if not error_on.isdisjoint(src[pos:new_pos]):
-        while src[pos] not in error_on:
-            pos += 1
-        raise toml_suffixed_err(src, pos, f'Found invalid character {src[pos]!r}')
-    return new_pos
+        self.data = TomlNestedDict()
+        self.flags = TomlFlags()
+        self.pos = 0
 
+    ASCII_CTRL = frozenset(chr(i) for i in range(32)) | frozenset(chr(127))
 
-def toml_skip_comment(src: str, pos: TomlPos) -> TomlPos:
-    try:
-        char: ta.Optional[str] = src[pos]
-    except IndexError:
-        char = None
-    if char == '#':
-        return toml_skip_until(
-            src, pos + 1, '\n', error_on=TOML_ILLEGAL_COMMENT_CHARS, error_on_eof=False,
-        )
-    return pos
+    # Neither of these sets include quotation mark or backslash. They are currently handled as separate cases in the
+    # parser functions.
+    ILLEGAL_BASIC_STR_CHARS = ASCII_CTRL - frozenset('\t')
+    ILLEGAL_MULTILINE_BASIC_STR_CHARS = ASCII_CTRL - frozenset('\t\n')
+
+    ILLEGAL_LITERAL_STR_CHARS = ILLEGAL_BASIC_STR_CHARS
+    ILLEGAL_MULTILINE_LITERAL_STR_CHARS = ILLEGAL_MULTILINE_BASIC_STR_CHARS
 
+    ILLEGAL_COMMENT_CHARS = ILLEGAL_BASIC_STR_CHARS
 
-def toml_skip_comments_and_array_ws(src: str, pos: TomlPos) -> TomlPos:
-    while True:
-        pos_before_skip = pos
-        pos = toml_skip_chars(src, pos, TOML_WS_AND_NEWLINE)
-        pos = toml_skip_comment(src, pos)
-        if pos == pos_before_skip:
-            return pos
+    WS = frozenset(' \t')
+    WS_AND_NEWLINE = WS | frozenset('\n')
+    BARE_KEY_CHARS = frozenset(string.ascii_letters + string.digits + '-_')
+    KEY_INITIAL_CHARS = BARE_KEY_CHARS | frozenset("\"'")
+    HEXDIGIT_CHARS = frozenset(string.hexdigits)
 
+    BASIC_STR_ESCAPE_REPLACEMENTS = types.MappingProxyType({
+        '\\b': '\u0008',  # backspace
+        '\\t': '\u0009',  # tab
+        '\\n': '\u000A',  # linefeed
+        '\\f': '\u000C',  # form feed
+        '\\r': '\u000D',  # carriage return
+        '\\"': '\u0022',  # quote
+        '\\\\': '\u005C',  # backslash
+    })
+
+    def parse(self) -> ta.Dict[str, ta.Any]:  # noqa: C901
+        header: TomlKey = ()
+
+        # Parse one statement at a time (typically means one line in TOML source)
+        while True:
+            # 1. Skip line leading whitespace
+            self.skip_chars(self.WS)
+
+            # 2. Parse rules. Expect one of the following:
+            #    - end of file
+            #    - end of line
+            #    - comment
+            #    - key/value pair
+            #    - append dict to list (and move to its namespace)
+            #    - create dict (and move to its namespace)
+            # Skip trailing whitespace when applicable.
+            try:
+                char = self.src[self.pos]
+            except IndexError:
+                break
+            if char == '\n':
+                self.pos += 1
+                continue
+            if char in self.KEY_INITIAL_CHARS:
+                self.key_value_rule(header)
+                self.skip_chars(self.WS)
+            elif char == '[':
+                try:
+                    second_char: ta.Optional[str] = self.src[self.pos + 1]
+                except IndexError:
+                    second_char = None
+                self.flags.finalize_pending()
+                if second_char == '[':
+                    header = self.create_list_rule()
+                else:
+                    header = self.create_dict_rule()
+                self.skip_chars(self.WS)
+            elif char != '#':
+                raise self.suffixed_err('Invalid statement')
+
+            # 3. Skip comment
+            self.skip_comment()
+
+            # 4. Expect end of line or end of file
+            try:
+                char = self.src[self.pos]
+            except IndexError:
+                break
+            if char != '\n':
+                raise self.suffixed_err('Expected newline or end of document after a statement')
+            self.pos += 1
 
-def toml_create_dict_rule(src: str, pos: TomlPos, out: TomlOutput) -> ta.Tuple[TomlPos, TomlKey]:
-    pos += 1  # Skip "["
-    pos = toml_skip_chars(src, pos, TOML_WS)
-    pos, key = toml_parse_key(src, pos)
+        return self.data.dict
 
-    if out.flags.is_(key, TomlFlags.EXPLICIT_NEST) or out.flags.is_(key, TomlFlags.FROZEN):
-        raise toml_suffixed_err(src, pos, f'Cannot declare {key} twice')
-    out.flags.set(key, TomlFlags.EXPLICIT_NEST, recursive=False)
-    try:
-        out.data.get_or_create_nest(key)
-    except KeyError:
-        raise toml_suffixed_err(src, pos, 'Cannot overwrite a value') from None
-
-    if not src.startswith(']', pos):
-        raise toml_suffixed_err(src, pos, "Expected ']' at the end of a table declaration")
-    return pos + 1, key
-
-
-def toml_create_list_rule(src: str, pos: TomlPos, out: TomlOutput) -> ta.Tuple[TomlPos, TomlKey]:
-    pos += 2  # Skip "[["
-    pos = toml_skip_chars(src, pos, TOML_WS)
-    pos, key = toml_parse_key(src, pos)
-
-    if out.flags.is_(key, TomlFlags.FROZEN):
-        raise toml_suffixed_err(src, pos, f'Cannot mutate immutable namespace {key}')
-    # Free the namespace now that it points to another empty list item...
-    out.flags.unset_all(key)
-    # ...but this key precisely is still prohibited from table declaration
-    out.flags.set(key, TomlFlags.EXPLICIT_NEST, recursive=False)
-    try:
-        out.data.append_nest_to_list(key)
-    except KeyError:
-        raise toml_suffixed_err(src, pos, 'Cannot overwrite a value') from None
-
-    if not src.startswith(']]', pos):
-        raise toml_suffixed_err(src, pos, "Expected ']]' at the end of an array declaration")
-    return pos + 2, key
-
-
-def toml_key_value_rule(
-        src: str,
-        pos: TomlPos,
-        out: TomlOutput,
-        header: TomlKey,
-        parse_float: TomlParseFloat,
-) -> TomlPos:
-    pos, key, value = toml_parse_key_value_pair(src, pos, parse_float)
-    key_parent, key_stem = key[:-1], key[-1]
-    abs_key_parent = header + key_parent
-
-    relative_path_cont_keys = (header + key[:i] for i in range(1, len(key)))
-    for cont_key in relative_path_cont_keys:
-        # Check that dotted key syntax does not redefine an existing table
-        if out.flags.is_(cont_key, TomlFlags.EXPLICIT_NEST):
-            raise toml_suffixed_err(src, pos, f'Cannot redefine namespace {cont_key}')
-        # Containers in the relative path can't be opened with the table syntax or dotted key/value syntax in following
-        # table sections.
-        out.flags.add_pending(cont_key, TomlFlags.EXPLICIT_NEST)
-
-    if out.flags.is_(abs_key_parent, TomlFlags.FROZEN):
-        raise toml_suffixed_err(
-            src,
-            pos,
-            f'Cannot mutate immutable namespace {abs_key_parent}',
-        )
+    def skip_chars(self, chars: ta.Iterable[str]) -> None:
+        try:
+            while self.src[self.pos] in chars:
+                self.pos += 1
+        except IndexError:
+            pass
 
-    try:
-        nest = out.data.get_or_create_nest(abs_key_parent)
-    except KeyError:
-        raise toml_suffixed_err(src, pos, 'Cannot overwrite a value') from None
-    if key_stem in nest:
-        raise toml_suffixed_err(src, pos, 'Cannot overwrite a value')
-    # Mark inline table and array namespaces recursively immutable
-    if isinstance(value, (dict, list)):
-        out.flags.set(header + key, TomlFlags.FROZEN, recursive=True)
-    nest[key_stem] = value
-    return pos
-
-
-def toml_parse_key_value_pair(
-        src: str,
-        pos: TomlPos,
-        parse_float: TomlParseFloat,
-) -> ta.Tuple[TomlPos, TomlKey, ta.Any]:
-    pos, key = toml_parse_key(src, pos)
-    try:
-        char: ta.Optional[str] = src[pos]
-    except IndexError:
-        char = None
-    if char != '=':
-        raise toml_suffixed_err(src, pos, "Expected '=' after a key in a key/value pair")
-    pos += 1
-    pos = toml_skip_chars(src, pos, TOML_WS)
-    pos, value = toml_parse_value(src, pos, parse_float)
-    return pos, key, value
-
-
-def toml_parse_key(src: str, pos: TomlPos) -> ta.Tuple[TomlPos, TomlKey]:
-    pos, key_part = toml_parse_key_part(src, pos)
-    key: TomlKey = (key_part,)
-    pos = toml_skip_chars(src, pos, TOML_WS)
-    while True:
+    def skip_until(
+            self,
+            expect: str,
+            *,
+            error_on: ta.FrozenSet[str],
+            error_on_eof: bool,
+    ) -> None:
         try:
-            char: ta.Optional[str] = src[pos]
+            new_pos = self.src.index(expect, self.pos)
+        except ValueError:
+            new_pos = len(self.src)
+            if error_on_eof:
+                raise self.suffixed_err(f'Expected {expect!r}', pos=new_pos) from None
+
+        if not error_on.isdisjoint(self.src[self.pos:new_pos]):
+            while self.src[self.pos] not in error_on:
+                self.pos += 1
+            raise self.suffixed_err(f'Found invalid character {self.src[self.pos]!r}')
+        self.pos = new_pos
+
+    def skip_comment(self) -> None:
+        try:
+            char: ta.Optional[str] = self.src[self.pos]
         except IndexError:
             char = None
-        if char != '.':
-            return pos, key
-        pos += 1
-        pos = toml_skip_chars(src, pos, TOML_WS)
-        pos, key_part = toml_parse_key_part(src, pos)
-        key += (key_part,)
-        pos = toml_skip_chars(src, pos, TOML_WS)
+        if char == '#':
+            self.pos += 1
+            self.skip_until(
+                '\n',
+                error_on=self.ILLEGAL_COMMENT_CHARS,
+                error_on_eof=False,
+            )
 
+    def skip_comments_and_array_ws(self) -> None:
+        while True:
+            pos_before_skip = self.pos
+            self.skip_chars(self.WS_AND_NEWLINE)
+            self.skip_comment()
+            if self.pos == pos_before_skip:
+                return
 
-def toml_parse_key_part(src: str, pos: TomlPos) -> ta.Tuple[TomlPos, str]:
-    try:
-        char: ta.Optional[str] = src[pos]
-    except IndexError:
-        char = None
-    if char in TOML_BARE_KEY_CHARS:
-        start_pos = pos
-        pos = toml_skip_chars(src, pos, TOML_BARE_KEY_CHARS)
-        return pos, src[start_pos:pos]
-    if char == "'":
-        return toml_parse_literal_str(src, pos)
-    if char == '"':
-        return toml_parse_one_line_basic_str(src, pos)
-    raise toml_suffixed_err(src, pos, 'Invalid initial character for a key part')
-
-
-def toml_parse_one_line_basic_str(src: str, pos: TomlPos) -> ta.Tuple[TomlPos, str]:
-    pos += 1
-    return toml_parse_basic_str(src, pos, multiline=False)
-
-
-def toml_parse_array(src: str, pos: TomlPos, parse_float: TomlParseFloat) -> ta.Tuple[TomlPos, list]:
-    pos += 1
-    array: list = []
-
-    pos = toml_skip_comments_and_array_ws(src, pos)
-    if src.startswith(']', pos):
-        return pos + 1, array
-    while True:
-        pos, val = toml_parse_value(src, pos, parse_float)
-        array.append(val)
-        pos = toml_skip_comments_and_array_ws(src, pos)
-
-        c = src[pos:pos + 1]
-        if c == ']':
-            return pos + 1, array
-        if c != ',':
-            raise toml_suffixed_err(src, pos, 'Unclosed array')
-        pos += 1
-
-        pos = toml_skip_comments_and_array_ws(src, pos)
-        if src.startswith(']', pos):
-            return pos + 1, array
-
-
-def toml_parse_inline_table(src: str, pos: TomlPos, parse_float: TomlParseFloat) -> ta.Tuple[TomlPos, dict]:
-    pos += 1
-    nested_dict = TomlNestedDict()
-    flags = TomlFlags()
-
-    pos = toml_skip_chars(src, pos, TOML_WS)
-    if src.startswith('}', pos):
-        return pos + 1, nested_dict.dict
-    while True:
-        pos, key, value = toml_parse_key_value_pair(src, pos, parse_float)
-        key_parent, key_stem = key[:-1], key[-1]
-        if flags.is_(key, TomlFlags.FROZEN):
-            raise toml_suffixed_err(src, pos, f'Cannot mutate immutable namespace {key}')
+    def create_dict_rule(self) -> TomlKey:
+        self.pos += 1  # Skip "["
+        self.skip_chars(self.WS)
+        key = self.parse_key()
+
+        if self.flags.is_(key, TomlFlags.EXPLICIT_NEST) or self.flags.is_(key, TomlFlags.FROZEN):
+            raise self.suffixed_err(f'Cannot declare {key} twice')
+        self.flags.set(key, TomlFlags.EXPLICIT_NEST, recursive=False)
         try:
-            nest = nested_dict.get_or_create_nest(key_parent, access_lists=False)
+            self.data.get_or_create_nest(key)
         except KeyError:
-            raise toml_suffixed_err(src, pos, 'Cannot overwrite a value') from None
-        if key_stem in nest:
-            raise toml_suffixed_err(src, pos, f'Duplicate inline table key {key_stem!r}')
-        nest[key_stem] = value
-        pos = toml_skip_chars(src, pos, TOML_WS)
-        c = src[pos:pos + 1]
-        if c == '}':
-            return pos + 1, nested_dict.dict
-        if c != ',':
-            raise toml_suffixed_err(src, pos, 'Unclosed inline table')
-        if isinstance(value, (dict, list)):
-            flags.set(key, TomlFlags.FROZEN, recursive=True)
-        pos += 1
-        pos = toml_skip_chars(src, pos, TOML_WS)
-
-
-def toml_parse_basic_str_escape(
-        src: str,
-        pos: TomlPos,
-        *,
-        multiline: bool = False,
-) -> ta.Tuple[TomlPos, str]:
-    escape_id = src[pos:pos + 2]
-    pos += 2
-    if multiline and escape_id in {'\\ ', '\\\t', '\\\n'}:
-        # Skip whitespace until next non-whitespace character or end of the doc. Error if non-whitespace is found before
-        # newline.
-        if escape_id != '\\\n':
-            pos = toml_skip_chars(src, pos, TOML_WS)
-            try:
-                char = src[pos]
-            except IndexError:
-                return pos, ''
-            if char != '\n':
-                raise toml_suffixed_err(src, pos, "Unescaped '\\' in a string")
-            pos += 1
-        pos = toml_skip_chars(src, pos, TOML_WS_AND_NEWLINE)
-        return pos, ''
-    if escape_id == '\\u':
-        return toml_parse_hex_char(src, pos, 4)
-    if escape_id == '\\U':
-        return toml_parse_hex_char(src, pos, 8)
-    try:
-        return pos, TOML_BASIC_STR_ESCAPE_REPLACEMENTS[escape_id]
-    except KeyError:
-        raise toml_suffixed_err(src, pos, "Unescaped '\\' in a string") from None
+            raise self.suffixed_err('Cannot overwrite a value') from None
+
+        if not self.src.startswith(']', self.pos):
+            raise self.suffixed_err("Expected ']' at the end of a table declaration")
+        self.pos += 1
+        return key
+
+    def create_list_rule(self) -> TomlKey:
+        self.pos += 2  # Skip "[["
+        self.skip_chars(self.WS)
+        key = self.parse_key()
+
+        if self.flags.is_(key, TomlFlags.FROZEN):
+            raise self.suffixed_err(f'Cannot mutate immutable namespace {key}')
+        # Free the namespace now that it points to another empty list item...
+        self.flags.unset_all(key)
+        # ...but this key precisely is still prohibited from table declaration
+        self.flags.set(key, TomlFlags.EXPLICIT_NEST, recursive=False)
+        try:
+            self.data.append_nest_to_list(key)
+        except KeyError:
+            raise self.suffixed_err('Cannot overwrite a value') from None
 
+        if not self.src.startswith(']]', self.pos):
+            raise self.suffixed_err("Expected ']]' at the end of an array declaration")
+        self.pos += 2
+        return key
 
-def toml_parse_basic_str_escape_multiline(src: str, pos: TomlPos) -> ta.Tuple[TomlPos, str]:
-    return toml_parse_basic_str_escape(src, pos, multiline=True)
+    def key_value_rule(self, header: TomlKey) -> None:
+        key, value = self.parse_key_value_pair()
+        key_parent, key_stem = key[:-1], key[-1]
+        abs_key_parent = header + key_parent
 
+        relative_path_cont_keys = (header + key[:i] for i in range(1, len(key)))
+        for cont_key in relative_path_cont_keys:
+            # Check that dotted key syntax does not redefine an existing table
+            if self.flags.is_(cont_key, TomlFlags.EXPLICIT_NEST):
+                raise self.suffixed_err(f'Cannot redefine namespace {cont_key}')
+            # Containers in the relative path can't be opened with the table syntax or dotted key/value syntax in
+            # following table sections.
+            self.flags.add_pending(cont_key, TomlFlags.EXPLICIT_NEST)
 
-def toml_parse_hex_char(src: str, pos: TomlPos, hex_len: int) -> ta.Tuple[TomlPos, str]:
-    hex_str = src[pos:pos + hex_len]
-    if len(hex_str) != hex_len or not TOML_HEXDIGIT_CHARS.issuperset(hex_str):
-        raise toml_suffixed_err(src, pos, 'Invalid hex value')
-    pos += hex_len
-    hex_int = int(hex_str, 16)
-    if not toml_is_unicode_scalar_value(hex_int):
-        raise toml_suffixed_err(src, pos, 'Escaped character is not a Unicode scalar value')
-    return pos, chr(hex_int)
+        if self.flags.is_(abs_key_parent, TomlFlags.FROZEN):
+            raise self.suffixed_err(f'Cannot mutate immutable namespace {abs_key_parent}')
 
+        try:
+            nest = self.data.get_or_create_nest(abs_key_parent)
+        except KeyError:
+            raise self.suffixed_err('Cannot overwrite a value') from None
+        if key_stem in nest:
+            raise self.suffixed_err('Cannot overwrite a value')
+        # Mark inline table and array namespaces recursively immutable
+        if isinstance(value, (dict, list)):
+            self.flags.set(header + key, TomlFlags.FROZEN, recursive=True)
+        nest[key_stem] = value
 
-def toml_parse_literal_str(src: str, pos: TomlPos) -> ta.Tuple[TomlPos, str]:
-    pos += 1  # Skip starting apostrophe
-    start_pos = pos
-    pos = toml_skip_until(
-        src, pos, "'", error_on=TOML_ILLEGAL_LITERAL_STR_CHARS, error_on_eof=True,
-    )
-    return pos + 1, src[start_pos:pos]  # Skip ending apostrophe
-
-
-def toml_parse_multiline_str(src: str, pos: TomlPos, *, literal: bool) -> ta.Tuple[TomlPos, str]:
-    pos += 3
-    if src.startswith('\n', pos):
-        pos += 1
-
-    if literal:
-        delim = "'"
-        end_pos = toml_skip_until(
-            src,
-            pos,
-            "'''",
-            error_on=TOML_ILLEGAL_MULTILINE_LITERAL_STR_CHARS,
-            error_on_eof=True,
-        )
-        result = src[pos:end_pos]
-        pos = end_pos + 3
-    else:
-        delim = '"'
-        pos, result = toml_parse_basic_str(src, pos, multiline=True)
-
-    # Add at maximum two extra apostrophes/quotes if the end sequence is 4 or 5 chars long instead of just 3.
-    if not src.startswith(delim, pos):
-        return pos, result
-    pos += 1
-    if not src.startswith(delim, pos):
-        return pos, result + delim
-    pos += 1
-    return pos, result + (delim * 2)
-
-
-def toml_parse_basic_str(src: str, pos: TomlPos, *, multiline: bool) -> ta.Tuple[TomlPos, str]:
-    if multiline:
-        error_on = TOML_ILLEGAL_MULTILINE_BASIC_STR_CHARS
-        parse_escapes = toml_parse_basic_str_escape_multiline
-    else:
-        error_on = TOML_ILLEGAL_BASIC_STR_CHARS
-        parse_escapes = toml_parse_basic_str_escape
-    result = ''
-    start_pos = pos
-    while True:
+    def parse_key_value_pair(self) -> ta.Tuple[TomlKey, ta.Any]:
+        key = self.parse_key()
         try:
-            char = src[pos]
+            char: ta.Optional[str] = self.src[self.pos]
         except IndexError:
-            raise toml_suffixed_err(src, pos, 'Unterminated string') from None
+            char = None
+        if char != '=':
+            raise self.suffixed_err("Expected '=' after a key in a key/value pair")
+        self.pos += 1
+        self.skip_chars(self.WS)
+        value = self.parse_value()
+        return key, value
+
+    def parse_key(self) -> TomlKey:
+        key_part = self.parse_key_part()
+        key: TomlKey = (key_part,)
+        self.skip_chars(self.WS)
+        while True:
+            try:
+                char: ta.Optional[str] = self.src[self.pos]
+            except IndexError:
+                char = None
+            if char != '.':
+                return key
+            self.pos += 1
+            self.skip_chars(self.WS)
+            key_part = self.parse_key_part()
+            key += (key_part,)
+            self.skip_chars(self.WS)
+
+    def parse_key_part(self) -> str:
+        try:
+            char: ta.Optional[str] = self.src[self.pos]
+        except IndexError:
+            char = None
+        if char in self.BARE_KEY_CHARS:
+            start_pos = self.pos
+            self.skip_chars(self.BARE_KEY_CHARS)
+            return self.src[start_pos:self.pos]
+        if char == "'":
+            return self.parse_literal_str()
         if char == '"':
-            if not multiline:
-                return pos + 1, result + src[start_pos:pos]
-            if src.startswith('"""', pos):
-                return pos + 3, result + src[start_pos:pos]
-            pos += 1
-            continue
-        if char == '\\':
-            result += src[start_pos:pos]
-            pos, parsed_escape = parse_escapes(src, pos)
-            result += parsed_escape
-            start_pos = pos
-            continue
-        if char in error_on:
-            raise toml_suffixed_err(src, pos, f'Illegal character {char!r}')
-        pos += 1
-
-
-def toml_parse_value(  # noqa: C901
-        src: str,
-        pos: TomlPos,
-        parse_float: TomlParseFloat,
-) -> ta.Tuple[TomlPos, ta.Any]:
-    try:
-        char: ta.Optional[str] = src[pos]
-    except IndexError:
-        char = None
-
-    # IMPORTANT: order conditions based on speed of checking and likelihood
-
-    # Basic strings
-    if char == '"':
-        if src.startswith('"""', pos):
-            return toml_parse_multiline_str(src, pos, literal=False)
-        return toml_parse_one_line_basic_str(src, pos)
-
-    # Literal strings
-    if char == "'":
-        if src.startswith("'''", pos):
-            return toml_parse_multiline_str(src, pos, literal=True)
-        return toml_parse_literal_str(src, pos)
-
-    # Booleans
-    if char == 't':
-        if src.startswith('true', pos):
-            return pos + 4, True
-    if char == 'f':
-        if src.startswith('false', pos):
-            return pos + 5, False
-
-    # Arrays
-    if char == '[':
-        return toml_parse_array(src, pos, parse_float)
-
-    # Inline tables
-    if char == '{':
-        return toml_parse_inline_table(src, pos, parse_float)
-
-    # Dates and times
-    datetime_match = TOML_RE_DATETIME.match(src, pos)
-    if datetime_match:
+            return self.parse_one_line_basic_str()
+        raise self.suffixed_err('Invalid initial character for a key part')
+
+    def parse_one_line_basic_str(self) -> str:
+        self.pos += 1
+        return self.parse_basic_str(multiline=False)
+
+    def parse_array(self) -> list:
+        self.pos += 1
+        array: list = []
+
+        self.skip_comments_and_array_ws()
+        if self.src.startswith(']', self.pos):
+            self.pos += 1
+            return array
+        while True:
+            val = self.parse_value()
+            array.append(val)
+            self.skip_comments_and_array_ws()
+
+            c = self.src[self.pos:self.pos + 1]
+            if c == ']':
+                self.pos += 1
+                return array
+            if c != ',':
+                raise self.suffixed_err('Unclosed array')
+            self.pos += 1
+
+            self.skip_comments_and_array_ws()
+            if self.src.startswith(']', self.pos):
+                self.pos += 1
+                return array
+
+    def parse_inline_table(self) -> dict:
+        self.pos += 1
+        nested_dict = TomlNestedDict()
+        flags = TomlFlags()
+
+        self.skip_chars(self.WS)
+        if self.src.startswith('}', self.pos):
+            self.pos += 1
+            return nested_dict.dict
+        while True:
+            key, value = self.parse_key_value_pair()
+            key_parent, key_stem = key[:-1], key[-1]
+            if flags.is_(key, TomlFlags.FROZEN):
+                raise self.suffixed_err(f'Cannot mutate immutable namespace {key}')
+            try:
+                nest = nested_dict.get_or_create_nest(key_parent, access_lists=False)
+            except KeyError:
+                raise self.suffixed_err('Cannot overwrite a value') from None
+            if key_stem in nest:
+                raise self.suffixed_err(f'Duplicate inline table key {key_stem!r}')
+            nest[key_stem] = value
+            self.skip_chars(self.WS)
+            c = self.src[self.pos:self.pos + 1]
+            if c == '}':
+                self.pos += 1
+                return nested_dict.dict
+            if c != ',':
+                raise self.suffixed_err('Unclosed inline table')
+            if isinstance(value, (dict, list)):
+                flags.set(key, TomlFlags.FROZEN, recursive=True)
+            self.pos += 1
+            self.skip_chars(self.WS)
+
+    def parse_basic_str_escape(self, multiline: bool = False) -> str:
+        escape_id = self.src[self.pos:self.pos + 2]
+        self.pos += 2
+        if multiline and escape_id in {'\\ ', '\\\t', '\\\n'}:
+            # Skip whitespace until next non-whitespace character or end of the doc. Error if non-whitespace is found
+            # before newline.
+            if escape_id != '\\\n':
+                self.skip_chars(self.WS)
+                try:
+                    char = self.src[self.pos]
+                except IndexError:
+                    return ''
+                if char != '\n':
+                    raise self.suffixed_err("Unescaped '\\' in a string")
+                self.pos += 1
+            self.skip_chars(self.WS_AND_NEWLINE)
+            return ''
+        if escape_id == '\\u':
+            return self.parse_hex_char(4)
+        if escape_id == '\\U':
+            return self.parse_hex_char(8)
         try:
-            datetime_obj = toml_match_to_datetime(datetime_match)
-        except ValueError as e:
-            raise toml_suffixed_err(src, pos, 'Invalid date or datetime') from e
-        return datetime_match.end(), datetime_obj
-    localtime_match = TOML_RE_LOCALTIME.match(src, pos)
-    if localtime_match:
-        return localtime_match.end(), toml_match_to_localtime(localtime_match)
-
-    # Integers and "normal" floats. The regex will greedily match any type starting with a decimal char, so needs to be
-    # located after handling of dates and times.
-    number_match = TOML_RE_NUMBER.match(src, pos)
-    if number_match:
-        return number_match.end(), toml_match_to_number(number_match, parse_float)
-
-    # Special floats
-    first_three = src[pos:pos + 3]
-    if first_three in {'inf', 'nan'}:
-        return pos + 3, parse_float(first_three)
-    first_four = src[pos:pos + 4]
-    if first_four in {'-inf', '+inf', '-nan', '+nan'}:
-        return pos + 4, parse_float(first_four)
-
-    raise toml_suffixed_err(src, pos, 'Invalid value')
-
-
-def toml_suffixed_err(src: str, pos: TomlPos, msg: str) -> TomlDecodeError:
-    """Return a `TomlDecodeError` where error message is suffixed with coordinates in source."""
-
-    def coord_repr(src: str, pos: TomlPos) -> str:
-        if pos >= len(src):
+            return self.BASIC_STR_ESCAPE_REPLACEMENTS[escape_id]
+        except KeyError:
+            raise self.suffixed_err("Unescaped '\\' in a string") from None
+
+    def parse_basic_str_escape_multiline(self) -> str:
+        return self.parse_basic_str_escape(multiline=True)
+
+    @classmethod
+    def is_unicode_scalar_value(cls, codepoint: int) -> bool:
+        return (0 <= codepoint <= 55295) or (57344 <= codepoint <= 1114111)
+
+    def parse_hex_char(self, hex_len: int) -> str:
+        hex_str = self.src[self.pos:self.pos + hex_len]
+        if len(hex_str) != hex_len or not self.HEXDIGIT_CHARS.issuperset(hex_str):
+            raise self.suffixed_err('Invalid hex value')
+        self.pos += hex_len
+        hex_int = int(hex_str, 16)
+        if not self.is_unicode_scalar_value(hex_int):
+            raise self.suffixed_err('Escaped character is not a Unicode scalar value')
+        return chr(hex_int)
+
+    def parse_literal_str(self) -> str:
+        self.pos += 1  # Skip starting apostrophe
+        start_pos = self.pos
+        self.skip_until("'", error_on=self.ILLEGAL_LITERAL_STR_CHARS, error_on_eof=True)
+        end_pos = self.pos
+        self.pos += 1
+        return self.src[start_pos:end_pos]  # Skip ending apostrophe
+
+    def parse_multiline_str(self, *, literal: bool) -> str:
+        self.pos += 3
+        if self.src.startswith('\n', self.pos):
+            self.pos += 1
+
+        if literal:
+            delim = "'"
+            start_pos = self.pos
+            self.skip_until(
+                "'''",
+                error_on=self.ILLEGAL_MULTILINE_LITERAL_STR_CHARS,
+                error_on_eof=True,
+            )
+            result = self.src[start_pos:self.pos]
+            self.pos += 3
+        else:
+            delim = '"'
+            result = self.parse_basic_str(multiline=True)
+
+        # Add at maximum two extra apostrophes/quotes if the end sequence is 4 or 5 chars long instead of just 3.
+        if not self.src.startswith(delim, self.pos):
+            return result
+        self.pos += 1
+        if not self.src.startswith(delim, self.pos):
+            return result + delim
+        self.pos += 1
+        return result + (delim * 2)
+
+    def parse_basic_str(self, *, multiline: bool) -> str:
+        if multiline:
+            error_on = self.ILLEGAL_MULTILINE_BASIC_STR_CHARS
+            parse_escapes = self.parse_basic_str_escape_multiline
+        else:
+            error_on = self.ILLEGAL_BASIC_STR_CHARS
+            parse_escapes = self.parse_basic_str_escape
+        result = ''
+        start_pos = self.pos
+        while True:
+            try:
+                char = self.src[self.pos]
+            except IndexError:
+                raise self.suffixed_err('Unterminated string') from None
+            if char == '"':
+                if not multiline:
+                    end_pos = self.pos
+                    self.pos += 1
+                    return result + self.src[start_pos:end_pos]
+                if self.src.startswith('"""', self.pos):
+                    end_pos = self.pos
+                    self.pos += 3
+                    return result + self.src[start_pos:end_pos]
+                self.pos += 1
+                continue
+            if char == '\\':
+                result += self.src[start_pos:self.pos]
+                parsed_escape = parse_escapes()
+                result += parsed_escape
+                start_pos = self.pos
+                continue
+            if char in error_on:
+                raise self.suffixed_err(f'Illegal character {char!r}')
+            self.pos += 1
+
+    def parse_value(self) -> ta.Any:  # noqa: C901
+        try:
+            char: ta.Optional[str] = self.src[self.pos]
+        except IndexError:
+            char = None
+
+        # IMPORTANT: order conditions based on speed of checking and likelihood
+
+        # Basic strings
+        if char == '"':
+            if self.src.startswith('"""', self.pos):
+                return self.parse_multiline_str(literal=False)
+            return self.parse_one_line_basic_str()
+
+        # Literal strings
+        if char == "'":
+            if self.src.startswith("'''", self.pos):
+                return self.parse_multiline_str(literal=True)
+            return self.parse_literal_str()
+
+        # Booleans
+        if char == 't':
+            if self.src.startswith('true', self.pos):
+                self.pos += 4
+                return True
+        if char == 'f':
+            if self.src.startswith('false', self.pos):
+                self.pos += 5
+                return False
+
+        # Arrays
+        if char == '[':
+            return self.parse_array()
+
+        # Inline tables
+        if char == '{':
+            return self.parse_inline_table()
+
+        # Dates and times
+        datetime_match = self.RE_DATETIME.match(self.src, self.pos)
+        if datetime_match:
+            try:
+                datetime_obj = self.match_to_datetime(datetime_match)
+            except ValueError as e:
+                raise self.suffixed_err('Invalid date or datetime') from e
+            self.pos = datetime_match.end()
+            return datetime_obj
+        localtime_match = self.RE_LOCALTIME.match(self.src, self.pos)
+        if localtime_match:
+            self.pos = localtime_match.end()
+            return self.match_to_localtime(localtime_match)
+
+        # Integers and "normal" floats. The regex will greedily match any type starting with a decimal char, so needs to
+        # be located after handling of dates and times.
+        number_match = self.RE_NUMBER.match(self.src, self.pos)
+        if number_match:
+            self.pos = number_match.end()
+            return self.match_to_number(number_match, self.parse_float)
+
+        # Special floats
+        first_three = self.src[self.pos:self.pos + 3]
+        if first_three in {'inf', 'nan'}:
+            self.pos += 3
+            return self.parse_float(first_three)
+        first_four = self.src[self.pos:self.pos + 4]
+        if first_four in {'-inf', '+inf', '-nan', '+nan'}:
+            self.pos += 4
+            return self.parse_float(first_four)
+
+        raise self.suffixed_err('Invalid value')
+
+    def coord_repr(self, pos: TomlPos) -> str:
+        if pos >= len(self.src):
             return 'end of document'
-        line = src.count('\n', 0, pos) + 1
+        line = self.src.count('\n', 0, pos) + 1
         if line == 1:
             column = pos + 1
         else:
-            column = pos - src.rindex('\n', 0, pos)
+            column = pos - self.src.rindex('\n', 0, pos)
         return f'line {line}, column {column}'
 
-    return TomlDecodeError(f'{msg} (at {coord_repr(src, pos)})')
-
+    def suffixed_err(self, msg: str, *, pos: ta.Optional[TomlPos] = None) -> TomlDecodeError:
+        """Return a `TomlDecodeError` where error message is suffixed with coordinates in source."""
 
-def toml_is_unicode_scalar_value(codepoint: int) -> bool:
-    return (0 <= codepoint <= 55295) or (57344 <= codepoint <= 1114111)
+        if pos is None:
+            pos = self.pos
+        return TomlDecodeError(f'{msg} (at {self.coord_repr(pos)})')
 
+    _TIME_RE_STR = r'([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(?:\.([0-9]{1,6})[0-9]*)?'
 
-def toml_make_safe_parse_float(parse_float: TomlParseFloat) -> TomlParseFloat:
-    """A decorator to make `parse_float` safe.
-
-    `parse_float` must not return dicts or lists, because these types would be mixed with parsed TOML tables and arrays,
-    thus confusing the parser. The returned decorated callable raises `ValueError` instead of returning illegal types.
-    """
-    # The default `float` callable never returns illegal types. Optimize it.
-    if parse_float is float:
-        return float
+    RE_NUMBER = re.compile(
+        r"""
+        0
+        (?:
+            x[0-9A-Fa-f](?:_?[0-9A-Fa-f])*   # hex
+            |
+            b[01](?:_?[01])*                 # bin
+            |
+            o[0-7](?:_?[0-7])*               # oct
+        )
+        |
+        [+-]?(?:0|[1-9](?:_?[0-9])*)         # dec, integer part
+        (?P<floatpart>
+            (?:\.[0-9](?:_?[0-9])*)?         # optional fractional part
+            (?:[eE][+-]?[0-9](?:_?[0-9])*)?  # optional exponent part
+        )
+        """,
+        flags=re.VERBOSE,
+    )
 
-    def safe_parse_float(float_str: str) -> ta.Any:
-        float_value = parse_float(float_str)
-        if isinstance(float_value, (dict, list)):
-            raise ValueError('parse_float must not return dicts or lists')  # noqa
-        return float_value
+    RE_LOCALTIME = re.compile(_TIME_RE_STR)
+
+    RE_DATETIME = re.compile(
+        rf"""
+        ([0-9]{{4}})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])  # date, e.g. 1988-10-27
+        (?:
+            [Tt ]
+            {_TIME_RE_STR}
+            (?:([Zz])|([+-])([01][0-9]|2[0-3]):([0-5][0-9]))?  # optional time offset
+        )?
+        """,
+        flags=re.VERBOSE,
+    )
 
-    return safe_parse_float
+    @classmethod
+    def match_to_datetime(cls, match: re.Match) -> ta.Union[datetime.datetime, datetime.date]:
+        """
+        Convert a `RE_DATETIME` match to `datetime.datetime` or `datetime.date`.
+
+        Raises ValueError if the match does not correspond to a valid date or datetime.
+        """
+
+        (
+            year_str,
+            month_str,
+            day_str,
+            hour_str,
+            minute_str,
+            sec_str,
+            micros_str,
+            zulu_time,
+            offset_sign_str,
+            offset_hour_str,
+            offset_minute_str,
+        ) = match.groups()
+        year, month, day = int(year_str), int(month_str), int(day_str)
+        if hour_str is None:
+            return datetime.date(year, month, day)
+        hour, minute, sec = int(hour_str), int(minute_str), int(sec_str)
+        micros = int(micros_str.ljust(6, '0')) if micros_str else 0
+        if offset_sign_str:
+            tz: ta.Optional[datetime.tzinfo] = toml_cached_tz(
+                offset_hour_str, offset_minute_str, offset_sign_str,
+            )
+        elif zulu_time:
+            tz = datetime.UTC
+        else:  # local date-time
+            tz = None
+        return datetime.datetime(year, month, day, hour, minute, sec, micros, tzinfo=tz)
+
+    @classmethod
+    def match_to_localtime(cls, match: re.Match) -> datetime.time:
+        hour_str, minute_str, sec_str, micros_str = match.groups()
+        micros = int(micros_str.ljust(6, '0')) if micros_str else 0
+        return datetime.time(int(hour_str), int(minute_str), int(sec_str), micros)
+
+    @classmethod
+    def match_to_number(cls, match: re.Match, parse_float: TomlParseFloat) -> ta.Any:
+        if match.group('floatpart'):
+            return parse_float(match.group())
+        return int(match.group(), 0)