# vim: ft=python fileencoding=utf-8 sts=4 sw=4 et: # Copyright 2014-2021 Florian Bruhin (The Compiler) # # This file is part of qutebrowser. # # qutebrowser is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # qutebrowser is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with qutebrowser. If not, see . """Base class for vim-like key sequence parser.""" import string import types import dataclasses from typing import Mapping, MutableMapping, Optional, Sequence from PyQt6.QtCore import pyqtSignal, QObject, Qt from PyQt6.QtGui import QKeySequence, QKeyEvent from qutebrowser.config import config from qutebrowser.utils import usertypes, log, utils from qutebrowser.keyinput import keyutils @dataclasses.dataclass(frozen=True) class MatchResult: """The result of matching a keybinding.""" match_type: QKeySequence.SequenceMatch command: Optional[str] sequence: keyutils.KeySequence def __post_init__(self) -> None: if self.match_type == QKeySequence.SequenceMatch.ExactMatch: assert self.command is not None else: assert self.command is None class BindingTrie: """Helper class for key parser. Represents a set of bindings. Every BindingTree will either contain children or a command (for leaf nodes). The only exception is the root BindingNode, if there are no bindings at all. From the outside, this class works similar to a mapping of keyutils.KeySequence to str. Doing trie[sequence] = 'command' adds a binding, and so does calling .update() with a mapping. Additionally, a "matches" method can be used to do partial matching. However, some mapping methods are not (yet) implemented: - __getitem__ (use matches() instead) - __len__ - __iter__ - __delitem__ Attributes: children: A mapping from KeyInfo to children BindingTries. command: Command associated with this trie node. """ __slots__ = 'children', 'command' def __init__(self) -> None: self.children: MutableMapping[keyutils.KeyInfo, BindingTrie] = {} self.command: Optional[str] = None def __setitem__(self, sequence: keyutils.KeySequence, command: str) -> None: node = self for key in sequence: if key not in node.children: node.children[key] = BindingTrie() node = node.children[key] node.command = command def __contains__(self, sequence: keyutils.KeySequence) -> bool: return self.matches(sequence).match_type == QKeySequence.SequenceMatch.ExactMatch def __repr__(self) -> str: return utils.get_repr(self, children=self.children, command=self.command) def __str__(self) -> str: return '\n'.join(self.string_lines(blank=True)) def string_lines(self, indent: int = 0, blank: bool = False) -> Sequence[str]: """Get a list of strings for a pretty-printed version of this trie.""" lines = [] if self.command is not None: lines.append('{}=> {}'.format(' ' * indent, self.command)) for key, child in sorted(self.children.items()): lines.append('{}{}:'.format(' ' * indent, key)) lines.extend(child.string_lines(indent=indent+1)) if blank: lines.append('') return lines def update(self, mapping: Mapping[keyutils.KeySequence, str]) -> None: """Add data from the given mapping to the trie.""" for key in mapping: self[key] = mapping[key] def matches(self, sequence: keyutils.KeySequence) -> MatchResult: """Try to match a given keystring with any bound keychain. Args: sequence: The key sequence to match. Return: A MatchResult object. """ node = self for key in sequence: try: node = node.children[key] except KeyError: return MatchResult(match_type=QKeySequence.SequenceMatch.NoMatch, command=None, sequence=sequence) if node.command is not None: return MatchResult(match_type=QKeySequence.SequenceMatch.ExactMatch, command=node.command, sequence=sequence) elif node.children: return MatchResult(match_type=QKeySequence.SequenceMatch.PartialMatch, command=None, sequence=sequence) else: # This can only happen when there are no bindings at all. return MatchResult(match_type=QKeySequence.SequenceMatch.NoMatch, command=None, sequence=sequence) class BaseKeyParser(QObject): """Parser for vim-like key sequences and shortcuts. Not intended to be instantiated directly. Subclasses have to override execute() to do whatever they want to. Attributes: mode_name: The name of the mode in the config. bindings: Bound key bindings _mode: The usertypes.KeyMode associated with this keyparser. _win_id: The window ID this keyparser is associated with. _sequence: The currently entered key sequence _do_log: Whether to log keypresses or not. passthrough: Whether unbound keys should be passed through with this handler. _supports_count: Whether count is supported. Signals: keystring_updated: Emitted when the keystring is updated. arg: New keystring. request_leave: Emitted to request leaving a mode. arg 0: Mode to leave. arg 1: Reason for leaving. arg 2: Ignore the request if we're not in that mode """ keystring_updated = pyqtSignal(str) request_leave = pyqtSignal(usertypes.KeyMode, str, bool) def __init__(self, *, mode: usertypes.KeyMode, win_id: int, parent: QObject = None, do_log: bool = True, passthrough: bool = False, supports_count: bool = True) -> None: super().__init__(parent) self._win_id = win_id self._sequence = keyutils.KeySequence() self._count = '' self._mode = mode self._do_log = do_log self.passthrough = passthrough self._supports_count = supports_count self.bindings = BindingTrie() self._read_config() config.instance.changed.connect(self._on_config_changed) def __repr__(self) -> str: return utils.get_repr(self, mode=self._mode, win_id=self._win_id, do_log=self._do_log, passthrough=self.passthrough, supports_count=self._supports_count) def _debug_log(self, message: str) -> None: """Log a message to the debug log if logging is active. Args: message: The message to log. """ if self._do_log: prefix = '{} for mode {}: '.format(self.__class__.__name__, self._mode.name) log.keyboard.debug(prefix + message) def _match_key(self, sequence: keyutils.KeySequence) -> MatchResult: """Try to match a given keystring with any bound keychain. Args: sequence: The command string to find. Return: A tuple (matchtype, binding). matchtype: Match.definitive, Match.partial or Match.none. binding: - None with Match.partial/Match.none. - The found binding with Match.definitive. """ assert sequence return self.bindings.matches(sequence) def _match_without_modifiers( self, sequence: keyutils.KeySequence) -> MatchResult: """Try to match a key with optional modifiers stripped.""" self._debug_log("Trying match without modifiers") sequence = sequence.strip_modifiers() return self._match_key(sequence) def _match_key_mapping( self, sequence: keyutils.KeySequence) -> MatchResult: """Try to match a key in bindings.key_mappings.""" self._debug_log("Trying match with key_mappings") mapped = sequence.with_mappings( types.MappingProxyType(config.cache['bindings.key_mappings'])) if sequence != mapped: self._debug_log("Mapped {} -> {}".format( sequence, mapped)) return self._match_key(mapped) return MatchResult(match_type=QKeySequence.SequenceMatch.NoMatch, command=None, sequence=sequence) def _match_count(self, sequence: keyutils.KeySequence, dry_run: bool) -> bool: """Try to match a key as count.""" txt = str(sequence[-1]) # To account for sequences changed above. if (txt in string.digits and self._supports_count and not (not self._count and txt == '0')): self._debug_log("Trying match as count") assert len(txt) == 1, txt if not dry_run: self._count += txt self.keystring_updated.emit(self._count + str(self._sequence)) return True return False def handle(self, e: QKeyEvent, *, dry_run: bool = False) -> QKeySequence.SequenceMatch: """Handle a new keypress. Separate the keypress into count/command, then check if it matches any possible command, and either run the command, ignore it, or display an error. Args: e: the KeyPressEvent from Qt. dry_run: Don't actually execute anything, only check whether there would be a match. Return: A QKeySequence match. """ key = Qt.Key(e.key()) txt = str(keyutils.KeyInfo.from_event(e)) self._debug_log("Got key: 0x{:x} / modifiers: {} / text: '{}' / " "dry_run {}".format(key, e.modifiers(), txt, dry_run)) if keyutils.is_modifier_key(key): self._debug_log("Ignoring, only modifier") return QKeySequence.SequenceMatch.NoMatch try: sequence = self._sequence.append_event(e) except keyutils.KeyParseError as ex: self._debug_log("{} Aborting keychain.".format(ex)) self.clear_keystring() return QKeySequence.SequenceMatch.NoMatch result = self._match_key(sequence) del sequence # Enforce code below to use the modified result.sequence if result.match_type == QKeySequence.SequenceMatch.NoMatch: result = self._match_without_modifiers(result.sequence) if result.match_type == QKeySequence.SequenceMatch.NoMatch: result = self._match_key_mapping(result.sequence) if result.match_type == QKeySequence.SequenceMatch.NoMatch: was_count = self._match_count(result.sequence, dry_run) if was_count: return QKeySequence.SequenceMatch.ExactMatch if dry_run: return result.match_type self._sequence = result.sequence if result.match_type == QKeySequence.SequenceMatch.ExactMatch: assert result.command is not None self._debug_log("Definitive match for '{}'.".format( result.sequence)) count = int(self._count) if self._count else None self.clear_keystring() self.execute(result.command, count) elif result.match_type == QKeySequence.SequenceMatch.PartialMatch: self._debug_log("No match for '{}' (added {})".format( result.sequence, txt)) self.keystring_updated.emit(self._count + str(result.sequence)) elif result.match_type == QKeySequence.SequenceMatch.NoMatch: self._debug_log("Giving up with '{}', no matches".format( result.sequence)) self.clear_keystring() else: raise utils.Unreachable("Invalid match value {!r}".format( result.match_type)) return result.match_type @config.change_filter('bindings') def _on_config_changed(self) -> None: self._read_config() def _read_config(self) -> None: """Read the configuration.""" self.bindings = BindingTrie() config_bindings = config.key_instance.get_bindings_for(self._mode.name) for key, cmd in config_bindings.items(): assert cmd self.bindings[key] = cmd def execute(self, cmdstr: str, count: int = None) -> None: """Handle a completed keychain. Args: cmdstr: The command to execute as a string. count: The count if given. """ raise NotImplementedError def clear_keystring(self) -> None: """Clear the currently entered key sequence.""" if self._sequence: self._debug_log("Clearing keystring (was: {}).".format( self._sequence)) self._sequence = keyutils.KeySequence() self._count = '' self.keystring_updated.emit('')