handler.py

#!/usr/bin/env python3
import abc
import functools
import os
import re
import sys
import textwrap
import warnings
from collections.abc import Iterable
from typing import Any
from typing import Callable
from typing import Dict
from typing import List
from typing import Optional
from typing import Set
from typing import Tuple

from parsimonious import Grammar
from parsimonious import ParseError
from parsimonious.nodes import Node
from parsimonious.nodes import NodeVisitor

from . import result
from ..connection import Connection
from ..warnings import PreviewFeatureWarning

CORE_GRAMMAR = r'''
    ws = ~r"(\s+|(\s*/\*.*\*/\s*)+)"
    qs = ~r"\"([^\"]*)\"|'([^\']*)'|([A-Za-z0-9_\-\.]+)|`([^\`]+)`" ws*
    number = ~r"[-+]?(\d*\.)?\d+(e[-+]?\d+)?"i ws*
    integer = ~r"-?\d+" ws*
    comma = ws* "," ws*
    eq = ws* "=" ws*
    open_paren = ws* "(" ws*
    close_paren = ws* ")" ws*
    open_repeats = ws* ~r"[\(\[\{]" ws*
    close_repeats = ws* ~r"[\)\]\}]" ws*
    statement = ~r"[\s\S]*" ws*
    table = ~r"(?:([A-Za-z0-9_\-]+)|`([^\`]+)`)(?:\.(?:([A-Za-z0-9_\-]+)|`([^\`]+)`))?" ws*
    column = ~r"(?:([A-Za-z0-9_\-]+)|`([^\`]+)`)(?:\.(?:([A-Za-z0-9_\-]+)|`([^\`]+)`))?" ws*
    link_name = ~r"(?:([A-Za-z0-9_\-]+)|`([^\`]+)`)(?:\.(?:([A-Za-z0-9_\-]+)|`([^\`]+)`))?" ws*
    catalog_name = ~r"(?:([A-Za-z0-9_\-]+)|`([^\`]+)`)(?:\.(?:([A-Za-z0-9_\-]+)|`([^\`]+)`))?" ws*

    json = ws* json_object ws*
    json_object = ~r"{\s*" json_members? ~r"\s*}"
    json_members = json_mapping (~r"\s*,\s*" json_mapping)*
    json_mapping = json_string ~r"\s*:\s*" json_value
    json_array = ~r"\[\s*" json_items? ~r"\s*\]"
    json_items = json_value (~r"\s*,\s*" json_value)*
    json_value = json_object / json_array / json_string / json_true_val / json_false_val / json_null_val / json_number
    json_true_val = "true"
    json_false_val = "false"
    json_null_val = "null"
    json_string = ~r"\"[ !#-\[\]-\U0010ffff]*(?:\\(?:[\"\\/bfnrt]|u[0-9A-Fa-f]{4})[ !#-\[\]-\U0010ffff]*)*\""
    json_number = ~r"-?(0|[1-9][0-9]*)(\.\d*)?([eE][-+]?\d+)?"
'''  # noqa: E501

BUILTINS = {
    '<order-by>': r'''
    order_by = ORDER BY order_by_key_,...
    order_by_key_ = '<key>' [ ASC | DESC ]
    ''',
    '<like>': r'''
    like = LIKE '<pattern>'
    ''',
    '<extended>': r'''
    extended = EXTENDED
    ''',
    '<limit>': r'''
    limit = LIMIT <integer>
    ''',
    '<integer>': '',
    '<number>': '',
    '<json>': '',
    '<table>': '',
    '<column>': '',
    '<catalog-name>': '',
    '<link-name>': '',
    '<file-type>': r'''
    file_type = { FILE | FOLDER }
    ''',
    '<statement>': '',
}

BUILTIN_DEFAULTS = {  # type: ignore
    'order_by': {'by': []},
    'like': None,
    'extended': False,
    'limit': None,
    'json': {},
}

_json_unesc_re = re.compile(r'\\(["/\\bfnrt]|u[0-9A-Fa-f])')
_json_unesc_map = {
    '"': '"',
    '/': '/',
    '\\': '\\',
    'b': '\b',
    'f': '\f',
    'n': '\n',
    'r': '\r',
    't': '\t',
}


def _json_unescape(m: Any) -> str:
    c = m.group(1)
    if c[0] == 'u':
        return chr(int(c[1:], 16))
    c2 = _json_unesc_map.get(c)
    if not c2:
        raise ValueError(f'invalid escape sequence: {m.group(0)}')
    return c2


def json_unescape(s: str) -> str:
    return _json_unesc_re.sub(_json_unescape, s[1:-1])


def get_keywords(grammar: str) -> Tuple[str, ...]:
    """Return all all-caps words from the beginning of the line."""
    m = re.match(r'^\s*((?:[@A-Z0-9_]+)(\s+|$|;))+', grammar)
    if not m:
        return tuple()
    return tuple(re.split(r'\s+', m.group(0).replace(';', '').strip()))


def is_bool(grammar: str) -> bool:
    """Determine if the rule is a boolean."""
    return bool(re.match(r'^[@A-Z0-9_\s*]+$', grammar))


def process_optional(m: Any) -> str:
    """Create options or groups of options."""
    sql = m.group(1).strip()
    if '|' in sql:
        return f'( {sql} )*'
    return f'( {sql} )?'


def process_alternates(m: Any) -> str:
    """Make alternates mandatory groups."""
    sql = m.group(1).strip()
    if '|' in sql:
        return f'( {sql} )'
    raise ValueError(f'alternates must contain "|": {sql}')


def process_repeats(m: Any) -> str:
    """Add repeated patterns."""
    sql = m.group(1).strip()
    return f'open_repeats? {sql} ws* ( comma {sql} ws* )* close_repeats?'


def lower_and_regex(m: Any) -> str:
    """Lowercase and convert literal to regex."""
    start = m.group(1) or ''
    sql = m.group(2)
    return f'~"{start}{sql.lower()}"i'


def split_unions(grammar: str) -> str:
    """
    Convert grammar in the form '[ x ] [ y ]' to '[ x | y ]'.

    Parameters
    ----------
    grammar : str
        SQL grammar

    Returns
    -------
    str

    """
    in_alternate = False
    out = []
    for c in grammar:
        if c == '{':
            in_alternate = True
            out.append(c)
        elif c == '}':
            in_alternate = False
            out.append(c)
        elif not in_alternate and c == '|':
            out.append(']')
            out.append(' ')
            out.append('[')
        else:
            out.append(c)
    return ''.join(out)


def expand_rules(rules: Dict[str, str], m: Any) -> str:
    """
    Return expanded grammar syntax for given rule.

    Parameters
    ----------
    ops : Dict[str, str]
        Dictionary of rules in grammar

    Returns
    -------
    str

    """
    txt = m.group(1)
    if txt in rules:
        return f' {rules[txt]} '
    return f' <{txt}> '


def build_cmd(grammar: str) -> str:
    """Pre-process grammar to construct top-level command."""
    if ';' not in grammar:
        raise ValueError('a semi-colon exist at the end of the primary rule')

    # Pre-space
    m = re.match(r'^\s*', grammar)
    space = m.group(0) if m else ''

    # Split on ';' on a line by itself
    begin, end = grammar.split(';', 1)

    # Get statement keywords
    keywords = get_keywords(begin)
    cmd = '_'.join(x.lower() for x in keywords) + '_cmd'

    # Collapse multi-line to one
    begin = re.sub(r'\s+', r' ', begin)

    return f'{space}{cmd} ={begin}\n{end}'


def build_syntax(grammar: str) -> str:
    """Construct full syntax."""
    if ';' not in grammar:
        raise ValueError('a semi-colon exist at the end of the primary rule')

    # Split on ';' on a line by itself
    cmd, end = grammar.split(';', 1)

    name = ''
    rules: Dict[str, Any] = {}
    for line in end.split('\n'):
        line = line.strip()
        if line.startswith('&'):
            rules[name] += '\n' + line
            continue
        if not line:
            continue
        name, value = line.split('=', 1)
        name = name.strip()
        value = value.strip()
        rules[name] = value

    while re.search(r' [a-z0-9_]+\b', cmd):
        cmd = re.sub(r' ([a-z0-9_]+)\b', functools.partial(expand_rules, rules), cmd)

    def add_indent(m: Any) -> str:
        return '    ' + (len(m.group(1)) * '    ')

    # Indent line-continuations
    cmd = re.sub(r'^(\&+)\s*', add_indent, cmd, flags=re.M)

    cmd = textwrap.dedent(cmd).rstrip() + ';'
    cmd = re.sub(r'(\S)  +', r'\1 ', cmd)
    cmd = re.sub(r'<comma>', ',', cmd)
    cmd = re.sub(r'\s+,\s*\.\.\.', ',...', cmd)

    return cmd


def _format_examples(ex: str) -> str:
    """Convert examples into sections."""
    return re.sub(r'(^Example\s+\d+.*$)', r'### \1', ex, flags=re.M)


def _format_arguments(arg: str) -> str:
    """Format arguments as subsections."""
    out = []
    for line in arg.split('\n'):
        if line.startswith('<'):
            out.append(f'### {line.replace("<", "&lt;").replace(">", "&gt;")}')
            out.append('')
        else:
            out.append(line.strip())
    return '\n'.join(out)


def _to_markdown(txt: str) -> str:
    """Convert formatting to markdown."""
    txt = re.sub(r'`([^`]+)\s+\<([^\>]+)>`_', r'[\1](\2)', txt)
    txt = txt.replace('``', '`')

    # Format code blocks
    lines = re.split(r'\n', txt)
    out = []
    while lines:
        line = lines.pop(0)
        if line.endswith('::'):
            out.append(line[:-2] + '.')
            code = []
            while lines and (not lines[0].strip() or lines[0].startswith(' ')):
                code.append(lines.pop(0).rstrip())
            code_str = re.sub(r'^\s*\n', r'', '\n'.join(code).rstrip())
            out.extend([f'```sql\n{code_str}\n```\n'])
        else:
            out.append(line)

    return '\n'.join(out)


def build_help(syntax: str, grammar: str) -> str:
    """Build full help text."""
    cmd = re.match(r'([A-Z0-9_ ]+)', syntax.strip())
    if not cmd:
        raise ValueError(f'no command found: {syntax}')

    out = [f'# {cmd.group(1)}\n\n']

    sections: Dict[str, str] = {}
    grammar = textwrap.dedent(grammar.rstrip())
    desc_re = re.compile(r'^([A-Z][\S ]+)\s*^\-\-\-\-+\s*$', flags=re.M)
    if desc_re.search(grammar):
        _, *txt = desc_re.split(grammar)
        txt = [x.strip() for x in txt]
        sections = {}
        while txt:
            key = txt.pop(0)
            value = txt.pop(0)
            sections[key.lower()] = _to_markdown(value).strip()

    if 'description' in sections:
        out.extend([sections['description'], '\n\n'])

    out.append(f'## Syntax\n\n```sql{syntax}\n```\n\n')

    if 'arguments' in sections:
        out.extend([
            '## Arguments\n\n',
            _format_arguments(sections['arguments']),
            '\n\n',
        ])
    if 'argument' in sections:
        out.extend([
            '## Argument\n\n',
            _format_arguments(sections['argument']),
            '\n\n',
        ])

    if 'remarks' in sections:
        out.extend(['## Remarks\n\n', sections['remarks'], '\n\n'])

    if 'examples' in sections:
        out.extend(['## Examples\n\n', _format_examples(sections['examples']), '\n\n'])
    elif 'example' in sections:
        out.extend(['## Example\n\n', _format_examples(sections['example']), '\n\n'])

    if 'see also' in sections:
        out.extend(['## See Also\n\n', sections['see also'], '\n\n'])

    return ''.join(out).rstrip() + '\n'


def strip_comments(grammar: str) -> str:
    """Strip comments from grammar."""
    desc_re = re.compile(r'(^\s*Description\s*^\s*-----------\s*$)', flags=re.M)
    grammar = desc_re.split(grammar, maxsplit=1)[0]
    return re.sub(r'^\s*#.*$', r'', grammar, flags=re.M)


def get_rule_info(grammar: str) -> Dict[str, Any]:
    """Compute metadata about rule used in coallescing parsed output."""
    return dict(
        n_keywords=len(get_keywords(grammar)),
        repeats=',...' in grammar,
        default=False if is_bool(grammar) else [] if ',...' in grammar else None,
    )


def inject_builtins(grammar: str) -> str:
    """Inject complex builtin rules."""
    for k, v in BUILTINS.items():
        if re.search(k, grammar):
            grammar = re.sub(
                k,
                k.replace('<', '').replace('>', '').replace('-', '_'),
                grammar,
            )
            grammar += v
    return grammar


def process_grammar(
    grammar: str,
) -> Tuple[Grammar, Tuple[str, ...], Dict[str, Any], str, str]:
    """
    Convert SQL grammar to a Parsimonious grammar.

    Parameters
    ----------
    grammar : str
        The SQL grammar

    Returns
    -------
    (Grammar, Tuple[str, ...], Dict[str, Any], str) - Grammar is the parsimonious
    grammar object. The tuple is a series of the keywords that start the command.
    The dictionary is a set of metadata about each rule. The final string is
    a human-readable version of the grammar for documentation and errors.

    """
    out = []
    rules = {}
    rule_info = {}

    full_grammar = grammar
    grammar = strip_comments(grammar)
    grammar = inject_builtins(grammar)
    command_key = get_keywords(grammar)
    syntax_txt = build_syntax(grammar)
    help_txt = build_help(syntax_txt, full_grammar)
    grammar = build_cmd(grammar)

    # Remove line-continuations
    grammar = re.sub(r'\n\s*&+', r'', grammar)

    # Make sure grouping characters all have whitespace around them
    grammar = re.sub(r' *(\[|\{|\||\}|\]) *', r' \1 ', grammar)

    grammar = re.sub(r'\(', r' open_paren ', grammar)
    grammar = re.sub(r'\)', r' close_paren ', grammar)

    for line in grammar.split('\n'):
        if not line.strip():
            continue

        op, sql = line.split('=', 1)
        op = op.strip()
        sql = sql.strip()
        sql = split_unions(sql)

        rules[op] = sql
        rule_info[op] = get_rule_info(sql)

        # Convert consecutive optionals to a union
        sql = re.sub(r'\]\s+\[', r' | ', sql)

        # Lower-case keywords and make them case-insensitive
        sql = re.sub(r'(\b|@+)([A-Z0-9_]+)\b', lower_and_regex, sql)

        # Convert literal strings to 'qs'
        sql = re.sub(r"'[^']+'", r'qs', sql)

        # Convert special characters to literal tokens
        sql = re.sub(r'([=]) ', r' eq ', sql)

        # Convert [...] groups to (...)*
        sql = re.sub(r'\[([^\]]+)\]', process_optional, sql)

        # Convert {...} groups to (...)
        sql = re.sub(r'\{([^\}]+)\}', process_alternates, sql)

        # Convert <...> to ... (<...> is the form for core types)
        sql = re.sub(r'<([a-z0-9_]+)>', r'\1', sql)

        # Insert ws between every token to allow for whitespace and comments
        sql = ' ws '.join(re.split(r'\s+', sql)) + ' ws'

        # Remove ws in optional groupings
        sql = sql.replace('( ws', '(')
        sql = sql.replace('| ws', '|')

        # Convert | to /
        sql = sql.replace('|', '/')

        # Remove ws after operation names, all operations contain ws at the end
        sql = re.sub(r'(\s+[a-z0-9_]+)\s+ws\b', r'\1', sql)

        # Convert foo,... to foo ("," foo)*
        sql = re.sub(r'(\S+),...', process_repeats, sql)

        # Remove ws before / and )
        sql = re.sub(r'(\s*\S+\s+)ws\s+/', r'\1/', sql)
        sql = re.sub(r'(\s*\S+\s+)ws\s+\)', r'\1)', sql)

        # Make sure every operation ends with ws
        sql = re.sub(r'\s+ws\s+ws$', r' ws', sql + ' ws')
        sql = re.sub(r'(\s+ws)*\s+ws\*$', r' ws*', sql)
        sql = re.sub(r'\s+ws$', r' ws*', sql)
        sql = re.sub(r'\s+ws\s+\(', r' ws* (', sql)
        sql = re.sub(r'\)\s+ws\s+', r') ws* ', sql)
        sql = re.sub(r'\s+ws\s+', r' ws* ', sql)
        sql = re.sub(r'\?\s+ws\+', r'? ws*', sql)

        # Remove extra ws around eq
        sql = re.sub(r'ws\+\s*eq\b', r'eq', sql)

        # Remove optional groupings when mandatory groupings are specified
        sql = re.sub(r'open_paren\s+ws\*\s+open_repeats\?', r'open_paren', sql)
        sql = re.sub(r'close_repeats\?\s+ws\*\s+close_paren', r'close_paren', sql)
        sql = re.sub(r'open_paren\s+open_repeats\?', r'open_paren', sql)
        sql = re.sub(r'close_repeats\?\s+close_paren', r'close_paren', sql)

        out.append(f'{op} = {sql}')

    for k, v in list(rules.items()):
        while re.search(r' ([a-z0-9_]+) ', v):
            v = re.sub(r' ([a-z0-9_]+) ', functools.partial(expand_rules, rules), v)
        rules[k] = v

    for k, v in list(rules.items()):
        while re.search(r' <([a-z0-9_]+)> ', v):
            v = re.sub(r' <([a-z0-9_]+)> ', r' \1 ', v)
        rules[k] = v

    cmds = ' / '.join(x for x in rules if x.endswith('_cmd'))
    cmds = f'init = ws* ( {cmds} ) ws* ";"? ws*\n'

    grammar = cmds + CORE_GRAMMAR + '\n'.join(out)

    try:
        return (
            Grammar(grammar), command_key,
            rule_info, syntax_txt, help_txt,
        )
    except ParseError:
        print(grammar, file=sys.stderr)
        raise


def flatten(items: Iterable[Any]) -> List[Any]:
    """Flatten a list of iterables."""
    out = []
    for x in items:
        if isinstance(x, (str, bytes, dict)):
            out.append(x)
        elif isinstance(x, Iterable):
            for sub_x in flatten(x):
                if sub_x is not None:
                    out.append(sub_x)
        elif x is not None:
            out.append(x)
    return out


def merge_dicts(items: List[Dict[str, Any]]) -> Dict[str, Any]:
    """Merge list of dictionaries together."""
    out: Dict[str, Any] = {}
    for x in items:
        if isinstance(x, dict):
            same = list(set(x.keys()).intersection(set(out.keys())))
            if same:
                raise ValueError(f"found duplicate rules for '{same[0]}'")
            out.update(x)
    return out


class SQLHandler(NodeVisitor):
    """Base class for all SQL handler classes."""

    #: Parsimonious grammar object
    grammar: Grammar = Grammar(CORE_GRAMMAR)

    #: SQL keywords that start the command
    command_key: Tuple[str, ...] = ()

    #: Metadata about the parse rules
    rule_info: Dict[str, Any] = {}

    #: Syntax string for use in error messages
    syntax: str = ''

    #: Full help for the command
    help: str = ''

    #: Rule validation functions
    validators: Dict[str, Callable[..., Any]] = {}

    _grammar: str = CORE_GRAMMAR
    _is_compiled: bool = False
    _enabled: bool = True
    _preview: bool = False

    def __init__(self, connection: Connection):
        self.connection = connection
        self._handled: Set[str] = set()

    @classmethod
    def compile(cls, grammar: str = '') -> None:
        """
        Compile the grammar held in the docstring.

        This method modifies attributes on the class: ``grammar``,
        ``command_key``, ``rule_info``, ``syntax``, and ``help``.

        Parameters
        ----------
        grammar : str, optional
            Grammar to use instead of docstring

        """
        if cls._is_compiled:
            return

        cls.grammar, cls.command_key, cls.rule_info, cls.syntax, cls.help = \
            process_grammar(grammar or cls.__doc__ or '')

        cls._grammar = grammar or cls.__doc__ or ''
        cls._is_compiled = True

    @classmethod
    def register(cls, overwrite: bool = False) -> None:
        """
        Register the handler class.

        Paraemeters
        -----------
        overwrite : bool, optional
            Overwrite an existing command with the same name?

        """
        if not cls._enabled and \
                os.environ.get('SINGLESTOREDB_FUSION_ENABLE_HIDDEN', '0').lower() not in \
                ['1', 't', 'true', 'y', 'yes']:
            return

        from . import registry
        cls.compile()
        registry.register_handler(cls, overwrite=overwrite)

    def create_result(self) -> result.FusionSQLResult:
        """
        Create a new result object.

        Returns
        -------
        FusionSQLResult
            A new result object for this handler

        """
        return result.FusionSQLResult()

    def execute(self, sql: str) -> result.FusionSQLResult:
        """
        Parse the SQL and invoke the handler method.

        Parameters
        ----------
        sql : str
            SQL statement to execute

        Returns
        -------
        DummySQLResult

        """
        if type(self)._preview:
            warnings.warn(
                'This is a preview Fusion SQL command. '
                'The options and syntax may change in the future.',
                PreviewFeatureWarning, stacklevel=2,
            )

        type(self).compile()
        self._handled = set()
        try:
            params = self.visit(type(self).grammar.parse(sql))
            for k, v in params.items():
                params[k] = self.validate_rule(k, v)

            res = self.run(params)

            self._handled = set()

            if res is not None:
                res.format_results(self.connection)
                return res

            res = result.FusionSQLResult()
            res.set_rows([])
            res.format_results(self.connection)
            return res

        except ParseError as exc:
            s = str(exc)
            msg = ''
            m = re.search(r'(The non-matching portion.*$)', s)
            if m:
                msg = ' ' + m.group(1)
            m = re.search(r"(Rule) '.+?'( didn't match at.*$)", s)
            if m:
                msg = ' ' + m.group(1) + m.group(2)
            raise ValueError(
                f'Could not parse statement.{msg} '
                'Expecting:\n' + textwrap.indent(type(self).syntax, '  '),
            )

    @abc.abstractmethod
    def run(self, params: Dict[str, Any]) -> Optional[result.FusionSQLResult]:
        """
        Run the handler command.

        Parameters
        ----------
        params : Dict[str, Any]
            Values parsed from the SQL query. Each rule in the grammar
            results in a key/value pair in the ``params` dictionary.

        Returns
        -------
        SQLResult - tuple containing the column definitions and
            rows of data in the result

        """
        raise NotImplementedError

    def visit_qs(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Quoted strings."""
        if node is None:
            return None
        return flatten(visited_children)[0]

    def visit_compound(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Compound name."""
        print(visited_children)
        return flatten(visited_children)[0]

    def visit_number(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Numeric value."""
        return float(flatten(visited_children)[0])

    def visit_integer(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Integer value."""
        return int(flatten(visited_children)[0])

    def visit_ws(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Whitespace and comments."""
        return

    def visit_eq(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Equals sign."""
        return

    def visit_comma(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Single comma."""
        return

    def visit_open_paren(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Open parenthesis."""
        return

    def visit_close_paren(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Close parenthesis."""
        return

    def visit_open_repeats(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Open repeat grouping."""
        return

    def visit_close_repeats(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Close repeat grouping."""
        return

    def visit_init(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Entry point of the grammar."""
        _, out, *_ = visited_children
        return out

    def visit_statement(self, node: Node, visited_children: Iterable[Any]) -> Any:
        out = ' '.join(flatten(visited_children)).strip()
        return {'statement': out}

    def visit_order_by(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """Handle ORDER BY."""
        by = []
        ascending = []
        data = [x for x in flatten(visited_children)[2:] if x]
        for item in data:
            value = item.popitem()[-1]
            if not isinstance(value, list):
                value = [value]
            value.append('A')
            by.append(value[0])
            ascending.append(value[1].upper().startswith('A'))
        return {'order_by': {'by': by, 'ascending': ascending}}

    def _delimited(self, node: Node, children: Iterable[Any]) -> Any:
        children = list(children)
        items = [children[0]]
        items.extend(item for _, item in children[1])
        return items

    def _atomic(self, node: Node, children: Iterable[Any]) -> Any:
        return list(children)[0]

    # visitors
    visit_json_value = _atomic
    visit_json_members = visit_json_items = _delimited

    def visit_json_object(self, node: Node, children: Iterable[Any]) -> Any:
        _, members, _ = children
        if isinstance(members, list):
            members = members[0]
        else:
            members = []
        members = [x for x in members if x != '']
        return dict(members)

    def visit_json_array(self, node: Node, children: Iterable[Any]) -> Any:
        _, values, _ = children
        if isinstance(values, list):
            values = values[0]
        else:
            values = []
        return values

    def visit_json_mapping(self, node: Node, children: Iterable[Any]) -> Any:
        key, _, value = children
        return key, value

    def visit_json_string(self, node: Node, children: Iterable[Any]) -> Any:
        return json_unescape(node.text)

    def visit_json_number(self, node: Node, children: Iterable[Any]) -> Any:
        if '.' in node.text:
            return float(node.text)
        return int(node.text)

    def visit_json_true_val(self, node: Node, children: Iterable[Any]) -> Any:
        return True

    def visit_json_false_val(self, node: Node, children: Iterable[Any]) -> Any:
        return False

    def visit_json_null_val(self, node: Node, children: Iterable[Any]) -> Any:
        return None

    def generic_visit(self, node: Node, visited_children: Iterable[Any]) -> Any:
        """
        Handle all undefined rules.

        This method processes all user-defined rules. Each rule results in
        a dictionary with a single key corresponding to the rule name, with
        a value corresponding to the data value following the rule keywords.

        If no value exists, the value True is used. If the rule is not a
        rule with possible repeated values, a single value is used. If the
        rule can have repeated values, a list of values is returned.

        """
        if node.expr_name.startswith('json'):
            return visited_children or node.text

        # Call a grammar rule
        if node.expr_name in type(self).rule_info:
            n_keywords = type(self).rule_info[node.expr_name]['n_keywords']
            repeats = type(self).rule_info[node.expr_name]['repeats']

            # If this is the top-level command, create the final result
            if node.expr_name.endswith('_cmd'):
                final = merge_dicts(flatten(visited_children)[n_keywords:])
                for k, v in type(self).rule_info.items():
                    if k.endswith('_cmd') or k.endswith('_') or k.startswith('_'):
                        continue
                    if k not in final and k not in self._handled:
                        final[k] = BUILTIN_DEFAULTS.get(k, v['default'])
                return final

            # Filter out stray empty strings
            out = [x for x in flatten(visited_children)[n_keywords:] if x]

            # Remove underscore prefixes from rule name
            key_name = re.sub(r'^_+', r'', node.expr_name)

            if repeats or len(out) > 1:
                self._handled.add(node.expr_name)
                # If all outputs are dicts, merge them
                if len(out) > 1 and not repeats:
                    is_dicts = [x for x in out if isinstance(x, dict)]
                    if len(is_dicts) == len(out):
                        return {key_name: merge_dicts(out)}
                return {key_name: out}

            self._handled.add(node.expr_name)
            return {key_name: out[0] if out else True}

        if hasattr(node, 'match'):
            if not visited_children and not node.match.groups():
                return node.text
            return visited_children or list(node.match.groups())

        return visited_children or node.text

    def validate_rule(self, rule: str, value: Any) -> Any:
        """
        Validate the value of the given rule.

        Paraemeters
        -----------
        rule : str
            Name of the grammar rule the value belongs to
        value : Any
            Value parsed from the query

        Returns
        -------
        Any - result of the validator function

        """
        validator = type(self).validators.get(rule)
        if validator is not None:
            return validator(value)
        return value