#!/usr/bin/python3
#
# Copyright 2016 Red Hat, Inc.
#
# 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 (including the next
# paragraph) shall be included in all copies or substantial portions of the
# Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.

import evdev
import subprocess
import sys
import argparse
import textwrap
from typing import Any, Callable, Dict, List, Optional, Tuple, Union

# This must be on a single line, as we replace it using merge_ratbagd.py while building.
# fmt: off
import os
import sys
import hashlib

from enum import IntEnum
from evdev import ecodes
from gettext import gettext as _
from gi.repository import Gio, GLib, GObject
from typing import List, Optional, Tuple, Union


# Deferred translations, see https://docs.python.org/3/library/gettext.html#deferred-translations
def N_(x):
    return x


def evcode_to_str(evcode: int) -> str:
    # Values in ecodes.keys are stored as either a str or list[str].
    value = ecodes.keys[evcode]
    if isinstance(value, list):
        return value[0]
    return value


class RatbagErrorCode(IntEnum):
    SUCCESS = 0

    """An error occurred on the device. Either the device is not a libratbag
    device or communication with the device failed."""
    DEVICE = -1000

    """Insufficient capabilities. This error occurs when a requested change is
    beyond the device's capabilities."""
    CAPABILITY = -1001

    """Invalid value or value range. The provided value or value range is
    outside of the legal or supported range."""
    VALUE = -1002

    """A low-level system error has occurred, e.g. a failure to access files
    that should be there. This error is usually unrecoverable and libratbag will
    print a log message with details about the error."""
    SYSTEM = -1003

    """Implementation bug, either in libratbag or in the caller. This error is
    usually unrecoverable and libratbag will print a log message with details
    about the error."""
    IMPLEMENTATION = -1004


class RatbagDeviceType(IntEnum):
    """DeviceType property specified in the .device files"""

    """There was no DeviceType specified for this device"""
    UNSPECIFIED = 0

    """Device is specified as anything other than a mouse or a keyboard"""
    OTHER = 1

    """Device is specified as a mouse"""
    MOUSE = 2

    """Device is specified as a keyboard"""
    KEYBOARD = 3


class RatbagdIncompatibleError(Exception):
    """ratbagd is incompatible with this client"""

    def __init__(self, ratbagd_version, required_version):
        super().__init__()
        self.ratbagd_version = ratbagd_version
        self.required_version = required_version
        self.message = f"ratbagd API version is {ratbagd_version} but we require {required_version}"

    def __str__(self):
        return self.message


class RatbagdUnavailableError(Exception):
    """Signals DBus is unavailable or the ratbagd daemon is not available."""


class RatbagdDBusTimeoutError(Exception):
    """Signals that a timeout occurred during a DBus method call."""


class RatbagError(Exception):
    """A common base exception to catch any ratbag exception."""


class RatbagDeviceError(RatbagError):
    """An exception corresponding to RatbagErrorCode.DEVICE."""


class RatbagCapabilityError(RatbagError):
    """An exception corresponding to RatbagErrorCode.CAPABILITY."""


class RatbagValueError(RatbagError):
    """An exception corresponding to RatbagErrorCode.VALUE."""


class RatbagSystemError(RatbagError):
    """An exception corresponding to RatbagErrorCode.SYSTEM."""


class RatbagImplementationError(RatbagError):
    """An exception corresponding to RatbagErrorCode.IMPLEMENTATION."""


"""A table mapping RatbagErrorCode values to RatbagError* exceptions."""
EXCEPTION_TABLE = {
    RatbagErrorCode.DEVICE: RatbagDeviceError,
    RatbagErrorCode.CAPABILITY: RatbagCapabilityError,
    RatbagErrorCode.VALUE: RatbagValueError,
    RatbagErrorCode.SYSTEM: RatbagSystemError,
    RatbagErrorCode.IMPLEMENTATION: RatbagImplementationError,
}


class _RatbagdDBus(GObject.GObject):
    _dbus = None

    def __init__(self, interface, object_path):
        super().__init__()

        if _RatbagdDBus._dbus is None:
            try:
                _RatbagdDBus._dbus = Gio.bus_get_sync(Gio.BusType.SYSTEM, None)
            except GLib.Error as e:
                raise RatbagdUnavailableError(e.message) from e

        ratbag1 = "org.freedesktop.ratbag1"
        if os.environ.get("RATBAG_TEST"):
            ratbag1 = "org.freedesktop.ratbag_devel1"

        if object_path is None:
            object_path = "/" + ratbag1.replace(".", "/")

        self._object_path = object_path
        self._interface = f"{ratbag1}.{interface}"

        try:
            self._proxy = Gio.DBusProxy.new_sync(
                _RatbagdDBus._dbus,
                Gio.DBusProxyFlags.NONE,
                None,
                ratbag1,
                object_path,
                self._interface,
                None,
            )
        except GLib.Error as e:
            raise RatbagdUnavailableError(e.message) from e

        if self._proxy.get_name_owner() is None:
            raise RatbagdUnavailableError(f"No one currently owns {ratbag1}")

        self._proxy.connect("g-properties-changed", self._on_properties_changed)
        self._proxy.connect("g-signal", self._on_signal_received)

    def _on_properties_changed(self, proxy, changed_props, invalidated_props):
        # Implement this in derived classes to respond to property changes.
        pass

    def _on_signal_received(self, proxy, sender_name, signal_name, parameters):
        # Implement this in derived classes to respond to signals.
        pass

    def _find_object_with_path(self, iterable, object_path):
        # Find the index of an object in an iterable that whose object path
        # matches the given object path.
        for index, obj in enumerate(iterable):
            if obj._object_path == object_path:
                return index
        return -1

    def _get_dbus_property(self, property):
        # Retrieves a cached property from the bus, or None.
        p = self._proxy.get_cached_property(property)
        if p is not None:
            return p.unpack()
        return p

    def _get_dbus_property_nonnull(self, property: str):
        p = self._get_dbus_property(property)
        if p is None:
            raise ValueError(f"D-Bus API returned `None` for property {property}")
        return p

    def _set_dbus_property(self, property, type, value, readwrite=True):
        # Sets a cached property on the bus.

        # Take our real value and wrap it into a variant. To call
        # org.freedesktop.DBus.Properties.Set we need to wrap that again
        # into a (ssv), where v is our value's variant.
        # args to .Set are "interface name", "function name",  value-variant
        val = GLib.Variant(f"{type}", value)
        if readwrite:
            pval = GLib.Variant("(ssv)", (self._interface, property, val))
            self._proxy.call_sync(
                "org.freedesktop.DBus.Properties.Set",
                pval,
                Gio.DBusCallFlags.NO_AUTO_START,
                2000,
                None,
            )

        # This is our local copy, so we don't have to wait for the async
        # update
        self._proxy.set_cached_property(property, val)

    def _dbus_call(self, method, type, *value):
        # Calls a method synchronously on the bus, using the given method name,
        # type signature and values.
        #
        # If the result is valid, it is returned. Invalid results raise the
        # appropriate RatbagError* or RatbagdDBus* exception, or GLib.Error if
        # it is an unexpected exception that probably shouldn't be passed up to
        # the UI.
        val = GLib.Variant(f"({type})", value)
        try:
            res = self._proxy.call_sync(
                method, val, Gio.DBusCallFlags.NO_AUTO_START, 2000, None
            )
            if res in EXCEPTION_TABLE:
                raise EXCEPTION_TABLE[res]
            return res.unpack()[0]  # Result is always a tuple
        except GLib.Error as e:
            if e.code == Gio.IOErrorEnum.TIMED_OUT:
                raise RatbagdDBusTimeoutError(e.message) from e

            # Unrecognized error code.
            print(e.message, file=sys.stderr)
            raise

    def __eq__(self, other):
        return other and self._object_path == other._object_path


class Ratbagd(_RatbagdDBus):
    """The ratbagd top-level object. Provides a list of devices available
    through ratbagd; actual interaction with the devices is via the
    RatbagdDevice, RatbagdProfile, RatbagdResolution and RatbagdButton objects.

    Throws RatbagdUnavailableError when the DBus service is not available.
    """

    __gsignals__ = {
        "device-added": (GObject.SignalFlags.RUN_FIRST, None, (GObject.TYPE_PYOBJECT,)),
        "device-removed": (
            GObject.SignalFlags.RUN_FIRST,
            None,
            (GObject.TYPE_PYOBJECT,),
        ),
        "daemon-disappeared": (GObject.SignalFlags.RUN_FIRST, None, ()),
    }

    def __init__(self, api_version):
        super().__init__("Manager", None)
        result = self._get_dbus_property("Devices")
        if result is None and not self._proxy.get_cached_property_names():
            raise RatbagdUnavailableError(
                "Make sure it is running and your user is in the required groups."
            )
        if self.api_version != api_version:
            raise RatbagdIncompatibleError(self.api_version or -1, api_version)
        self._devices = [RatbagdDevice(objpath) for objpath in result or []]
        self._proxy.connect("notify::g-name-owner", self._on_name_owner_changed)

    def _on_name_owner_changed(self, *kwargs):
        self.emit("daemon-disappeared")

    def _on_properties_changed(self, proxy, changed_props, invalidated_props):
        try:
            new_device_object_paths = changed_props["Devices"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            object_paths = [d._object_path for d in self._devices]
            for object_path in new_device_object_paths:
                if object_path not in object_paths:
                    device = RatbagdDevice(object_path)
                    self._devices.append(device)
                    self.emit("device-added", device)
            for device in self.devices:
                if device._object_path not in new_device_object_paths:
                    self._devices.remove(device)
                    self.emit("device-removed", device)
            self.notify("devices")

    @GObject.Property
    def api_version(self):
        return self._get_dbus_property("APIVersion")

    @GObject.Property
    def devices(self):
        """A list of RatbagdDevice objects supported by ratbagd."""
        return self._devices

    def __getitem__(self, id):
        """Returns the requested device, or None."""
        for d in self.devices:
            if d.id == id:
                return d
        return None

    def __enter__(self):
        return self

    def __exit__(self, exc_type, exc_val, exc_tb):
        pass


class RatbagdDevice(_RatbagdDBus):
    """Represents a ratbagd device."""

    __gsignals__ = {
        "active-profile-changed": (
            GObject.SignalFlags.RUN_FIRST,
            None,
            (GObject.TYPE_PYOBJECT,),
        ),
        "resync": (GObject.SignalFlags.RUN_FIRST, None, ()),
    }

    def __init__(self, object_path):
        super().__init__("Device", object_path)

        # FIXME: if we start adding and removing objects from this list,
        # things will break!
        result = self._get_dbus_property("Profiles") or []
        self._profiles = [RatbagdProfile(objpath) for objpath in result]
        for profile in self._profiles:
            profile.connect("notify::is-active", self._on_active_profile_changed)

        # Use a SHA1 of our object path as our device's ID
        self._id = hashlib.sha1(object_path.encode("utf-8")).hexdigest()

    def _on_signal_received(self, proxy, sender_name, signal_name, parameters):
        if signal_name == "Resync":
            self.emit("resync")

    def _on_active_profile_changed(self, profile, pspec):
        if profile.is_active:
            self.emit("active-profile-changed", self._profiles[profile.index])

    @GObject.Property
    def id(self):
        return self._id

    @id.setter
    def id(self, id):
        self._id = id

    @GObject.Property
    def model(self):
        """The unique identifier for this device model."""
        return self._get_dbus_property("Model")

    @GObject.Property
    def name(self):
        """The device name, usually provided by the kernel."""
        return self._get_dbus_property("Name")

    @GObject.Property
    def device_type(self):
        """The device type, see RatbagDeviceType"""
        return RatbagDeviceType(self._get_dbus_property("DeviceType"))

    @GObject.Property
    def firmware_version(self):
        """The firmware version of the device."""
        return self._get_dbus_property("FirmwareVersion")

    @GObject.Property
    def profiles(self):
        """A list of RatbagdProfile objects provided by this device."""
        return self._profiles

    @GObject.Property
    def active_profile(self):
        """The currently active profile. This is a non-DBus property computed
        over the cached list of profiles. In the unlikely case that your device
        driver is misconfigured and there is no active profile, this returns
        `None`."""
        for profile in self._profiles:
            if profile.is_active:
                return profile
        print(
            "No active profile. Please report this bug to the libratbag developers",
            file=sys.stderr,
        )
        return None

    def commit(self):
        """Commits all changes made to the device.

        This is implemented asynchronously inside ratbagd. Hence, we just call
        this method and always succeed.  Any failure is handled inside ratbagd
        by emitting the Resync signal, which automatically resynchronizes the
        device. No further interaction is required by the client.
        """
        self._dbus_call("Commit", "")


class RatbagdProfile(_RatbagdDBus):
    """Represents a ratbagd profile."""

    CAP_WRITABLE_NAME = 100
    CAP_SET_DEFAULT = 101
    CAP_DISABLE = 102
    CAP_WRITE_ONLY = 103

    def __init__(self, object_path):
        super().__init__("Profile", object_path)
        self._active = self._get_dbus_property("IsActive")
        self._angle_snapping = self._get_dbus_property("AngleSnapping")
        self._debounce = self._get_dbus_property("Debounce")
        self._dirty = self._get_dbus_property("IsDirty")
        self._disabled = self._get_dbus_property("Disabled")
        self._report_rate = self._get_dbus_property("ReportRate")

        # FIXME: if we start adding and removing objects from any of these
        # lists, things will break!
        result = self._get_dbus_property("Resolutions") or []
        self._resolutions = [RatbagdResolution(objpath) for objpath in result]
        self._subscribe_dirty(self._resolutions)

        result = self._get_dbus_property("Buttons") or []
        self._buttons = [RatbagdButton(objpath) for objpath in result]
        self._subscribe_dirty(self._buttons)

        result = self._get_dbus_property("Leds") or []
        self._leds = [RatbagdLed(objpath) for objpath in result]
        self._subscribe_dirty(self._leds)

    def _subscribe_dirty(self, objects: List[GObject.GObject]):
        for obj in objects:
            obj.connect("notify", self._on_obj_notify)

    def _on_obj_notify(self, obj: GObject.GObject, pspec: Optional[GObject.ParamSpec]):
        if not self._dirty:
            self._dirty = True
            self.notify("dirty")

    def _on_properties_changed(self, proxy, changed_props, invalidated_props):
        try:
            angle_snapping = changed_props["AngleSnapping"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if angle_snapping != self._angle_snapping:
                self._angle_snapping = angle_snapping
                self.notify("angle-snapping")

        try:
            debounce = changed_props["Debounce"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if debounce != self._debounce:
                self._debounce = debounce
                self.notify("debounce")

        try:
            disabled = changed_props["Disabled"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if disabled != self._disabled:
                self._disabled = disabled
                self.notify("disabled")

        try:
            active = changed_props["IsActive"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if active != self._active:
                self._active = active
                self.notify("is-active")

        try:
            dirty = changed_props["IsDirty"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if dirty != self._dirty:
                self._dirty = dirty
                self.notify("dirty")

        try:
            report_rate = changed_props["ReportRate"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if report_rate != self._report_rate:
                self._report_rate = report_rate
                self.notify("report-rate")

    @GObject.Property
    def capabilities(self):
        """The capabilities of this profile as an array. Capabilities not
        present on the profile are not in the list. Thus use e.g.

        if RatbagdProfile.CAP_WRITABLE_NAME in profile.capabilities:
            do something
        """
        return self._get_dbus_property("Capabilities") or []

    @GObject.Property
    def name(self):
        """The name of the profile"""
        return self._get_dbus_property("Name")

    @name.setter
    def name(self, name):
        """Set the name of this profile.

        @param name The new name, as str"""
        self._set_dbus_property("Name", "s", name)

    @GObject.Property
    def index(self):
        """The index of this profile."""
        return self._get_dbus_property("Index")

    @GObject.Property
    def dirty(self):
        """Whether this profile is dirty."""
        return self._dirty

    @GObject.Property
    def disabled(self):
        """tells if the profile is disabled."""
        return self._disabled

    @disabled.setter
    def disabled(self, disabled):
        """Enable/Disable this profile.

        @param disabled The new state, as boolean"""
        self._set_dbus_property("Disabled", "b", disabled)

    @GObject.Property
    def report_rate(self) -> int:
        """The report rate in Hz."""
        return self._report_rate

    @report_rate.setter
    def report_rate(self, rate):
        """Set the report rate in Hz.

        @param rate The new report rate, as int
        """
        self._set_dbus_property("ReportRate", "u", rate)

    @GObject.Property
    def report_rates(self):
        """The list of supported report rates"""
        return self._get_dbus_property("ReportRates") or []

    @GObject.Property
    def angle_snapping(self):
        """The angle snapping option."""
        return self._angle_snapping

    @angle_snapping.setter
    def angle_snapping(self, value):
        """Set the angle snapping option.

        @param value The angle snapping option as int
        """
        self._set_dbus_property("AngleSnapping", "i", value)

    @GObject.Property
    def debounce(self):
        """The button debounce time in ms."""
        return self._debounce

    @debounce.setter
    def debounce(self, value):
        """Set the button debounce time in ms.

        @param value The button debounce time, as int
        """
        self._set_dbus_property("Debounce", "i", value)

    @GObject.Property
    def debounces(self):
        """The list of supported debounce times"""
        return self._get_dbus_property("Debounces") or []

    @GObject.Property
    def resolutions(self):
        """A list of RatbagdResolution objects with this profile's resolutions.
        Note that the list of resolutions differs between profiles but the number
        of resolutions is identical across profiles."""
        return self._resolutions

    @GObject.Property
    def active_resolution(self):
        """The currently active resolution of this profile. This is a non-DBus
        property computed over the cached list of resolutions. In the unlikely
        case that your device driver is misconfigured and there is no active
        resolution, this returns `None`."""
        for resolution in self._resolutions:
            if resolution.is_active:
                return resolution
        print(
            "No active resolution. Please report this bug to the libratbag developers",
            file=sys.stderr,
        )
        return None

    @GObject.Property
    def buttons(self):
        """A list of RatbagdButton objects with this profile's button mappings.
        Note that the list of buttons differs between profiles but the number
        of buttons is identical across profiles."""
        return self._buttons

    @GObject.Property
    def leds(self):
        """A list of RatbagdLed objects with this profile's leds. Note that the
        list of leds differs between profiles but the number of leds is
        identical across profiles."""
        return self._leds

    @GObject.Property
    def is_active(self):
        """Returns True if the profile is currently active, false otherwise."""
        return self._active

    def set_active(self):
        """Set this profile to be the active profile."""
        ret = self._dbus_call("SetActive", "")
        self._set_dbus_property("IsActive", "b", True, readwrite=False)
        return ret


class RatbagdResolution(_RatbagdDBus):
    """Represents a ratbagd resolution."""

    CAP_SEPARATE_XY_RESOLUTION = 1
    CAP_DISABLE = 2

    def __init__(self, object_path):
        super().__init__("Resolution", object_path)
        self._active = self._get_dbus_property("IsActive")
        self._default = self._get_dbus_property("IsDefault")
        self._disabled = self._get_dbus_property("IsDisabled")
        self._resolution = self._convert_resolution_from_dbus(
            self._get_dbus_property_nonnull("Resolution")
        )

    def _on_properties_changed(self, proxy, changed_props, invalidated_props):
        try:
            resolution = self._convert_resolution_from_dbus(changed_props["Resolution"])
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if resolution != self._resolution:
                self._resolution = resolution
                self.notify("resolution")

        try:
            active = changed_props["IsActive"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if active != self._active:
                self._active = active
                self.notify("is-active")

        try:
            default = changed_props["IsDefault"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if default != self._default:
                self._default = default
                self.notify("is-default")

        try:
            disabled = changed_props["IsDisabled"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if disabled != self._disabled:
                self._disabled = disabled
                self.notify("is-disabled")

    @GObject.Property
    def capabilities(self):
        """The capabilities of this resolution as an array. Capabilities not
        present on the resolution are not in the list. Thus use e.g.

        if resolution.CAP_DISABLE in resolution.capabilities:
            do something
        """
        return self._get_dbus_property("Capabilities") or []

    @GObject.Property
    def index(self):
        """The index of this resolution."""
        return self._get_dbus_property("Index")

    @staticmethod
    def _convert_resolution_from_dbus(
        res: Union[int, Tuple[int, int]],
    ) -> Union[Tuple[int], Tuple[int, int]]:
        """
        Convert resolution from what D-Bus API returns - either an int or a tuple of two ints, to a tuple of either one or two ints.
        """
        if isinstance(res, int):
            return (res,)
        return res

    @GObject.Property
    def resolution(self):
        """The resolution in DPI, either as single value tuple ``(res, )``
        or as tuple ``(xres, yres)``.
        """
        return self._resolution

    @resolution.setter
    def resolution(self, resolution):
        """Set the x- and y-resolution using the given (xres, yres) tuple.

        @param res The new resolution, as (int, int)
        """
        res = self.resolution
        if len(res) != len(resolution) or len(res) > 2:
            raise ValueError("invalid resolution precision")
        if len(res) == 1:
            variant = GLib.Variant("u", resolution[0])
        else:
            variant = GLib.Variant("(uu)", resolution)
        self._set_dbus_property("Resolution", "v", variant)

    @GObject.Property
    def resolutions(self):
        """The list of supported DPI values"""
        return self._get_dbus_property("Resolutions") or []

    @GObject.Property
    def is_active(self):
        """True if this is the currently active resolution, False
        otherwise"""
        return self._active

    @GObject.Property
    def is_default(self):
        """True if this is the currently default resolution, False
        otherwise"""
        return self._default

    @GObject.Property
    def is_disabled(self):
        """True if this is currently disabled, False otherwise"""
        return self._disabled

    def set_active(self):
        """Set this resolution to be the active one."""
        ret = self._dbus_call("SetActive", "")
        self._set_dbus_property("IsActive", "b", True, readwrite=False)
        return ret

    def set_default(self):
        """Set this resolution to be the default."""
        ret = self._dbus_call("SetDefault", "")
        self._set_dbus_property("IsDefault", "b", True, readwrite=False)
        return ret

    def set_disabled(self, disable):
        """Set this resolution to be disabled."""
        return self._set_dbus_property("IsDisabled", "b", disable)


class RatbagdButton(_RatbagdDBus):
    """Represents a ratbagd button."""

    class ActionType(IntEnum):
        NONE = 0
        BUTTON = 1
        SPECIAL = 2
        KEY = 3
        MACRO = 4

    class ActionSpecial(IntEnum):
        INVALID = -1
        UNKNOWN = 1 << 30
        DOUBLECLICK = (1 << 30) + 1
        WHEEL_LEFT = (1 << 30) + 2
        WHEEL_RIGHT = (1 << 30) + 3
        WHEEL_UP = (1 << 30) + 4
        WHEEL_DOWN = (1 << 30) + 5
        RATCHET_MODE_SWITCH = (1 << 30) + 6
        RESOLUTION_CYCLE_UP = (1 << 30) + 7
        RESOLUTION_CYCLE_DOWN = (1 << 30) + 8
        RESOLUTION_UP = (1 << 30) + 9
        RESOLUTION_DOWN = (1 << 30) + 10
        RESOLUTION_ALTERNATE = (1 << 30) + 11
        RESOLUTION_DEFAULT = (1 << 30) + 12
        PROFILE_CYCLE_UP = (1 << 30) + 13
        PROFILE_CYCLE_DOWN = (1 << 30) + 14
        PROFILE_UP = (1 << 30) + 15
        PROFILE_DOWN = (1 << 30) + 16
        SECOND_MODE = (1 << 30) + 17
        BATTERY_LEVEL = (1 << 30) + 18

    class Macro(IntEnum):
        NONE = 0
        KEY_PRESS = 1
        KEY_RELEASE = 2
        WAIT = 3

    """A table mapping a button's index to its usual function as defined by X
    and the common desktop environments."""
    BUTTON_DESCRIPTION = {
        0: N_("Left mouse button click"),
        1: N_("Right mouse button click"),
        2: N_("Middle mouse button click"),
        3: N_("Backward"),
        4: N_("Forward"),
    }

    """A table mapping a special function to its human-readable description."""
    SPECIAL_DESCRIPTION = {
        ActionSpecial.INVALID: N_("Invalid"),
        ActionSpecial.UNKNOWN: N_("Unknown"),
        ActionSpecial.DOUBLECLICK: N_("Doubleclick"),
        ActionSpecial.WHEEL_LEFT: N_("Wheel Left"),
        ActionSpecial.WHEEL_RIGHT: N_("Wheel Right"),
        ActionSpecial.WHEEL_UP: N_("Wheel Up"),
        ActionSpecial.WHEEL_DOWN: N_("Wheel Down"),
        ActionSpecial.RATCHET_MODE_SWITCH: N_("Ratchet Mode"),
        ActionSpecial.RESOLUTION_CYCLE_UP: N_("Cycle Resolution Up"),
        ActionSpecial.RESOLUTION_CYCLE_DOWN: N_("Cycle Resolution Down"),
        ActionSpecial.RESOLUTION_UP: N_("Resolution Up"),
        ActionSpecial.RESOLUTION_DOWN: N_("Resolution Down"),
        ActionSpecial.RESOLUTION_ALTERNATE: N_("Resolution Switch"),
        ActionSpecial.RESOLUTION_DEFAULT: N_("Default Resolution"),
        ActionSpecial.PROFILE_CYCLE_UP: N_("Cycle Profile Up"),
        ActionSpecial.PROFILE_CYCLE_DOWN: N_("Cycle Profile Down"),
        ActionSpecial.PROFILE_UP: N_("Profile Up"),
        ActionSpecial.PROFILE_DOWN: N_("Profile Down"),
        ActionSpecial.SECOND_MODE: N_("Second Mode"),
        ActionSpecial.BATTERY_LEVEL: N_("Battery Level"),
    }

    def __init__(self, object_path):
        super().__init__("Button", object_path)

    def _on_properties_changed(self, proxy, changed_props, invalidated_props):
        if "Mapping" in changed_props.keys():
            self.notify("action-type")

    def _mapping(self):
        return self._get_dbus_property("Mapping")

    @GObject.Property
    def index(self):
        """The index of this button."""
        return self._get_dbus_property("Index")

    @GObject.Property
    def mapping(self):
        """An integer of the current button mapping, if mapping to a button
        or None otherwise."""
        type, button = self._mapping()
        if type != RatbagdButton.ActionType.BUTTON:
            return None
        return button

    @mapping.setter
    def mapping(self, button):
        """Set the button mapping to the given button.

        @param button The button to map to, as int
        """
        button = GLib.Variant("u", button)
        self._set_dbus_property(
            "Mapping", "(uv)", (RatbagdButton.ActionType.BUTTON, button)
        )

    @GObject.Property
    def macro(self):
        """A RatbagdMacro object representing the currently set macro or
        None otherwise."""
        type, macro = self._mapping()
        if type != RatbagdButton.ActionType.MACRO:
            return None
        return RatbagdMacro.from_ratbag(macro)

    @macro.setter
    def macro(self, macro):
        """Set the macro to the macro represented by the given RatbagdMacro
        object.

        @param macro A RatbagdMacro object representing the macro to apply to
                     the button, as RatbagdMacro.
        """
        macro = GLib.Variant("a(uu)", macro.keys)
        self._set_dbus_property(
            "Mapping", "(uv)", (RatbagdButton.ActionType.MACRO, macro)
        )

    @GObject.Property
    def special(self):
        """An enum describing the current special mapping, if mapped to
        special or None otherwise."""
        type, special = self._mapping()
        if type != RatbagdButton.ActionType.SPECIAL:
            return None
        return special

    @special.setter
    def special(self, special):
        """Set the button mapping to the given special entry.

        @param special The special entry, as one of RatbagdButton.ActionSpecial
        """
        special = GLib.Variant("u", special)
        self._set_dbus_property(
            "Mapping", "(uv)", (RatbagdButton.ActionType.SPECIAL, special)
        )

    @GObject.Property
    def key(self):
        type, key = self._mapping()
        if type != RatbagdButton.ActionType.KEY:
            return None
        return key

    @key.setter
    def key(self, key):
        key = GLib.Variant("u", key)
        self._set_dbus_property("Mapping", "(uv)", (RatbagdButton.ActionType.KEY, key))

    @GObject.Property
    def action_type(self):
        """An enum describing the action type of the button. One of
        ActionType.NONE, ActionType.BUTTON, ActionType.SPECIAL,
        ActionType.MACRO. This decides which
        *Mapping property has a value.
        """
        type, mapping = self._mapping()
        return type

    @GObject.Property
    def action_types(self):
        """An array of possible values for ActionType."""
        return self._get_dbus_property("ActionTypes")

    @GObject.Property
    def disabled(self):
        type, unused = self._mapping()
        return type == RatbagdButton.ActionType.NONE

    def disable(self):
        """Disables this button."""
        zero = GLib.Variant("u", 0)
        self._set_dbus_property(
            "Mapping", "(uv)", (RatbagdButton.ActionType.NONE, zero)
        )


class RatbagdMacro(GObject.Object):
    """Represents a button macro. Note that it uses keycodes as defined by
    linux/input-event-codes.h and not those used by X.Org or any other higher
    layer such as Gdk."""

    # Both a key press and release.
    _MACRO_KEY = 1000

    _MACRO_DESCRIPTION = {
        RatbagdButton.Macro.KEY_PRESS: lambda key: f"↓{evcode_to_str(key)}",
        RatbagdButton.Macro.KEY_RELEASE: lambda key: f"↑{evcode_to_str(key)}",
        RatbagdButton.Macro.WAIT: lambda val: f"{val}ms",
        _MACRO_KEY: lambda key: f"↕{evcode_to_str(key)}",
    }

    __gsignals__ = {
        "macro-set": (GObject.SignalFlags.RUN_FIRST, None, ()),
    }

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self._macro = []

    def __str__(self):
        if not self._macro:
            # Translators: this is used when there is no macro to preview.
            return _("None")

        keys = []
        idx = 0
        while idx < len(self._macro):
            t, v = self._macro[idx]
            try:
                if t == RatbagdButton.Macro.KEY_PRESS:
                    # Check for a paired press/release event
                    t2, v2 = self._macro[idx + 1]
                    if t2 == RatbagdButton.Macro.KEY_RELEASE and v == v2:
                        t = self._MACRO_KEY
                        idx += 1
            except IndexError:
                pass
            keys.append(self._MACRO_DESCRIPTION[t](v))
            idx += 1
        return " ".join(keys)

    @GObject.Property
    def keys(self):
        """A list of (RatbagdButton.Macro.*, value) tuples representing the
        current macro."""
        return self._macro

    @staticmethod
    def from_ratbag(macro):
        """Instantiates a new RatbagdMacro instance from the given macro in
        libratbag format.

        @param macro The macro in libratbag format, as
                     [(RatbagdButton.Macro.*, value)].
        """
        ratbagd_macro = RatbagdMacro()

        # Do not emit notify::keys for every key that we add.
        with ratbagd_macro.freeze_notify():
            for type, value in macro:
                ratbagd_macro.append(type, value)
        return ratbagd_macro

    def accept(self):
        """Applies the currently cached macro."""
        self.emit("macro-set")

    def append(self, type, value):
        """Appends the given event to the current macro.

        @param type The type of event, as one of RatbagdButton.Macro.*.
        @param value If the type denotes a key event, the X.Org or Gdk keycode
                     of the event, as int. Otherwise, the value of the timeout
                     in milliseconds, as int.
        """
        # Only append if the entry isn't identical to the last one, as we cannot
        # e.g. have two identical key presses in a row.
        if len(self._macro) == 0 or (type, value) != self._macro[-1]:
            self._macro.append((type, value))
            self.notify("keys")


class RatbagdLed(_RatbagdDBus):
    """Represents a ratbagd led."""

    class Mode(IntEnum):
        OFF = 0
        ON = 1
        CYCLE = 2
        BREATHING = 3

    class ColorDepth(IntEnum):
        MONOCHROME = 0
        RGB_888 = 1
        RGB_111 = 2

    LED_DESCRIPTION = {
        # Translators: the LED is off.
        Mode.OFF: N_("Off"),
        # Translators: the LED has a single, solid color.
        Mode.ON: N_("Solid"),
        # Translators: the LED is cycling between red, green and blue.
        Mode.CYCLE: N_("Cycle"),
        # Translators: the LED's is pulsating a single color on different
        # brightnesses.
        Mode.BREATHING: N_("Breathing"),
    }

    def __init__(self, object_path):
        super().__init__("Led", object_path)

        self._brightness = self._get_dbus_property("Brightness")
        self._color = self._get_dbus_property("Color")
        self._effect_duration = self._get_dbus_property("EffectDuration")
        self._mode: RatbagdLed.Mode = self._get_dbus_property_nonnull("Mode")

    @GObject.Property
    def index(self):
        """The index of this led."""
        return self._get_dbus_property("Index")

    @GObject.Property
    def mode(self):
        """This led's mode, one of Mode.OFF, Mode.ON, Mode.CYCLE and
        Mode.BREATHING."""
        return self._mode

    @mode.setter
    def mode(self, mode):
        """Set the led's mode to the given mode.

        @param mode The new mode, as one of Mode.OFF, Mode.ON, Mode.CYCLE and
                    Mode.BREATHING.
        """
        self._set_dbus_property("Mode", "u", mode)

    @GObject.Property
    def modes(self):
        """The supported modes as a list"""
        return self._get_dbus_property("Modes")

    @GObject.Property
    def color(self):
        """An integer triple of the current LED color."""
        return self._color

    @color.setter
    def color(self, color):
        """Set the led color to the given color.

        @param color An RGB color, as an integer triplet with values 0-255.
        """
        self._set_dbus_property("Color", "(uuu)", color)

    @GObject.Property
    def colordepth(self):
        """An enum describing this led's colordepth, one of
        RatbagdLed.ColorDepth.MONOCHROME, RatbagdLed.ColorDepth.RGB"""
        return self._get_dbus_property("ColorDepth")

    @GObject.Property
    def effect_duration(self):
        """The LED's effect duration in ms, values range from 0 to 10000."""
        return self._effect_duration

    @effect_duration.setter
    def effect_duration(self, effect_duration):
        """Set the effect duration in ms. Allowed values range from 0 to 10000.

        @param effect_duration The new effect duration, as int
        """
        self._set_dbus_property("EffectDuration", "u", effect_duration)

    @GObject.Property
    def brightness(self):
        """The LED's brightness, values range from 0 to 255."""
        return self._brightness

    @brightness.setter
    def brightness(self, brightness):
        """Set the brightness. Allowed values range from 0 to 255.

        @param brightness The new brightness, as int
        """
        self._set_dbus_property("Brightness", "u", brightness)

    def _on_properties_changed(self, proxy, changed_props, invalidated_props):
        try:
            brightness = changed_props["Brightness"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if brightness != self._brightness:
                self._brightness = brightness
                self.notify("brightness")

        try:
            color = changed_props["Color"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if color != self._color:
                self._color = color
                self.notify("color")

        try:
            effect_duration = changed_props["EffectDuration"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if effect_duration != self._effect_duration:
                self._effect_duration = effect_duration
                self.notify("effect-duration")

        try:
            mode = changed_props["Mode"]
        except KeyError:
            # Different property changed, skip.
            pass
        else:
            if mode != self._mode:
                self._mode = mode
                self.notify("mode")
# fmt: on


RATBAGD_API_VERSION = int("2")


def humanize(string: str) -> str:
    return string.lower().replace("_", "-")


button_special_names = [
    humanize(e.name) for e in RatbagdButton.ActionSpecial if e.name != "INVALID"
]
led_mode_names = [humanize(e.name) for e in RatbagdLed.Mode]

button_specials_strmap = {
    **{e: e.name.lower().replace("_", "-") for e in RatbagdButton.ActionSpecial},
    **{e.name.lower().replace("_", "-"): e for e in RatbagdButton.ActionSpecial},
}


def convert_str_to_evcode(s: str) -> int:
    if not s.startswith("KEY_") and not s.startswith("BTN_"):
        msg = f"Don't know how to convert {s}"
        raise ValueError(msg)

    try:
        return evdev.ecodes.ecodes[s]
    except KeyError as e:
        msg = f"No such button or key `{s}`"
        raise ValueError(msg) from e


def list_devices(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    if not ratbagd.devices:
        print("No devices available.")

    for device in ratbagd.devices:
        print("{:20s} {:32s}".format(device.id + ":", device.name))


def find_device(ratbagd: Ratbagd, args: argparse.Namespace) -> RatbagdDevice:
    device = ratbagd[args.device]
    if device is None:
        for device in ratbagd.devices:
            if args.device in device.name:
                return device
        print(f"Unable to find device {args.device}")
        sys.exit(1)
    return device


def find_profile(
    ratbagd: Ratbagd, args: argparse.Namespace
) -> Tuple[RatbagdProfile, RatbagdDevice]:
    device = find_device(ratbagd, args)
    try:
        profile = device.profiles[args.profile_n]
    except IndexError:
        print(f"Invalid profile index {args.profile_n}")
        sys.exit(1)
    except AttributeError:
        profile = device.active_profile
        if ratbagd is None:
            print("The device has no active profile")
            sys.exit(1)
    return profile, device


def find_resolution(
    ratbagd: Ratbagd, args: argparse.Namespace
) -> Tuple[RatbagdResolution, RatbagdProfile, RatbagdDevice]:
    profile, device = find_profile(ratbagd, args)
    try:
        resolution = profile.resolutions[args.resolution_n]
    except IndexError:
        print(f"Invalid resolution index {args.resolution_n}")
        sys.exit(1)
    except AttributeError:
        resolution = profile.active_resolution
        if resolution is None:
            print("The device has no active resolution")
            sys.exit(1)
    return resolution, profile, device


def find_button(
    ratbagd: Ratbagd, args: argparse.Namespace
) -> Tuple[RatbagdButton, RatbagdProfile, RatbagdDevice]:
    profile, device = find_profile(ratbagd, args)
    try:
        button = profile.buttons[args.button_n]
    except IndexError:
        print(f"Invalid button index {args.button_n}")
        sys.exit(1)
    return button, profile, device


def find_led(
    ratbagd: Ratbagd, args: argparse.Namespace
) -> Tuple[RatbagdLed, RatbagdProfile, RatbagdDevice]:
    profile, device = find_profile(ratbagd, args)
    try:
        led = profile.leds[args.led_n]
    except IndexError:
        print(f"Invalid LED index {args.led_n}")
        sys.exit(1)
    return led, profile, device


def print_led(
    _device: RatbagdDevice, _profile: RatbagdProfile, led: RatbagdLed, level: int
) -> None:
    leds = {
        RatbagdLed.Mode.BREATHING: "breathing",
        RatbagdLed.Mode.CYCLE: "cycle",
        RatbagdLed.Mode.OFF: "off",
        RatbagdLed.Mode.ON: "on",
    }
    depths = {
        RatbagdLed.ColorDepth.MONOCHROME: "monochrome",
        RatbagdLed.ColorDepth.RGB_888: "rgb",
        RatbagdLed.ColorDepth.RGB_111: "rgb111",
    }
    if led.mode == RatbagdLed.Mode.OFF:
        print(
            " " * level
            + f"LED: {led.index}, depth: {depths[led.colordepth]}, mode: {leds[led.mode]}"
        )
    elif led.mode == RatbagdLed.Mode.ON:
        print(
            " " * level
            + f"LED: {led.index}, depth: {depths[led.colordepth]}, mode: {leds[led.mode]}, color: {led.color[0]:02x}{led.color[1]:02x}{led.color[2]:02x}"
        )
    elif led.mode == RatbagdLed.Mode.CYCLE:
        print(
            " " * level
            + f"LED: {led.index}, depth: {depths[led.colordepth]}, mode: {leds[led.mode]}, duration: {led.effect_duration}, brightness: {led.brightness}"
        )
    elif led.mode == RatbagdLed.Mode.BREATHING:
        print(
            " " * level
            + f"LED: {led.index}, depth: {depths[led.colordepth]}, mode: {leds[led.mode]}, color: {led.color[0]:02x}{led.color[1]:02x}{led.color[2]:02x}, duration: {led.effect_duration},"
            f" brightness: {led.brightness}"
        )


def print_led_caps(
    _device: RatbagdDevice, _profile: RatbagdProfile, led: RatbagdLed, level: int
) -> None:
    leds = {
        RatbagdLed.Mode.BREATHING: "breathing",
        RatbagdLed.Mode.CYCLE: "cycle",
        RatbagdLed.Mode.OFF: "off",
        RatbagdLed.Mode.ON: "on",
    }
    supported = sorted([v for k, v in leds.items() if k in led.modes])
    print(" " * level + "Modes: {}".format(", ".join(supported)))


def print_button(
    _device: RatbagdDevice, _profile: RatbagdProfile, button: RatbagdButton, level: int
) -> None:
    header = " " * level + f"Button: {button.index} is mapped to "

    if button.action_type == RatbagdButton.ActionType.BUTTON:
        print(f"{header}'button {button.mapping}'")
    elif button.action_type == RatbagdButton.ActionType.SPECIAL:
        print(f"{header}'{button_specials_strmap[button.special]}'")
    elif button.action_type == RatbagdButton.ActionType.KEY:
        key_name = evcode_to_str(button.key)
        print(f"{header}key '{key_name}'")
    elif button.action_type == RatbagdButton.ActionType.MACRO:
        print(f"{header}macro '{str(button.macro)}'")
    elif button.action_type == RatbagdButton.ActionType.NONE:
        print(f"{header}none")
    else:
        print(f"{header}UNKNOWN")


def print_resolution(
    _device: RatbagdDevice,
    _profile: RatbagdProfile,
    resolution: RatbagdResolution,
    level: int,
) -> None:
    if resolution.resolution == (0, 0):
        print(" " * level + f"{resolution.index}: <disabled>")
        return
    if len(resolution.resolution) == 2:
        dpi = f"{resolution.resolution[0]}x{resolution.resolution[1]}"
    else:
        dpi = f"{resolution.resolution[0]}"

    print(
        " " * level
        + "{}: {}dpi{}{}{}".format(
            resolution.index,
            dpi,
            " (active)" if resolution.is_active else "",
            " (default)" if resolution.is_default else "",
            " (disabled)" if resolution.is_disabled else "",
        )
    )


def print_profile(device: RatbagdDevice, profile: RatbagdProfile, level: int) -> None:
    print(
        " " * (level - 2)
        + "Profile {}:{}{}{}".format(
            profile.index,
            " (disabled)" if profile.disabled else "",
            " (active)" if profile.is_active else "",
            " (dirty)" if profile.dirty else "",
        )
    )

    if not profile.disabled:
        print(" " * level + "Name: {}".format(profile.name or "n/a"))
        if profile.report_rate:
            print(" " * level + f"Report Rate: {profile.report_rate}Hz")
        if profile.resolutions:
            print(" " * level + "Resolutions:")
            for resolution in profile.resolutions:
                print_resolution(device, profile, resolution, level + 2)
        if profile.angle_snapping != -1:
            print(" " * level + f"Angle Snapping: {bool(profile.angle_snapping)}")
        if profile.debounce != -1:
            print(" " * level + f"Debounce time: {profile.debounce}ms")
        if profile.buttons:
            for button in profile.buttons:
                print_button(device, profile, button, level)
        if profile.leds:
            for led in profile.leds:
                print_led(device, profile, led, level)


def print_device(device: RatbagdDevice, level: int) -> None:
    profile = device.profiles[0]  # there should be always one

    print(" " * level + f"{device.id} - {device.name}")
    print(" " * level + f"             Model: {device.model}")
    print(" " * level + f"       Device Type: {device.device_type.name.capitalize()}")
    if device.firmware_version:
        print(" " * level + f"  Firmware version: {device.firmware_version}")
    print(" " * level + f" Number of Buttons: {len(profile.buttons)}")
    print(" " * level + f"    Number of Leds: {len(profile.leds)}")
    print(" " * level + f"Number of Profiles: {len(device.profiles)}")
    for profile in device.profiles:
        print_profile(device, profile, level + 2)


def show_device(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    device = find_device(ratbagd, args)
    print_device(device, 0)


def show_profile(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    print(f"Profile {args.profile} on {device.id} ({device.name})")
    print_profile(device, profile, 0)


def show_resolution(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, p, d = find_resolution(ratbagd, args)
    print(
        f"Resolution {args.resolution} on Profile {args.profile} on {d.id} ({d.name})"
    )
    print_resolution(d, p, resolution, 0)
    caps = {
        RatbagdResolution.CAP_INDIVIDUAL_REPORT_RATE: "individual-report-rate",
        RatbagdResolution.CAP_SEPARATE_XY_RESOLUTION: "separate-xy-resolution",
    }
    capabilities = [caps[c] for c in resolution.capabilities]
    print("  Capabilities: {}".format(", ".join(capabilities)))


def show_button(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    button, profile, device = find_button(ratbagd, args)
    print(
        f"Button {args.button} on Profile {args.profile} on {device.id} ({device.name})"
    )
    print_button(device, profile, button, 0)


def func_led_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    led, profile, device = find_led(ratbagd, args)
    print_led(device, profile, led, 0)


def func_led_caps(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    led, profile, device = find_led(ratbagd, args)
    print_led_caps(device, profile, led, 0)


def func_led_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    led, _profile, device = find_led(ratbagd, args)
    try:
        mode = args.mode
    except AttributeError:
        pass
    else:
        leds = {
            "breathing": RatbagdLed.Mode.BREATHING,
            "cycle": RatbagdLed.Mode.CYCLE,
            "off": RatbagdLed.Mode.OFF,
            "on": RatbagdLed.Mode.ON,
        }
        led.mode = leds[mode]
    try:
        color = args.color
    except AttributeError:
        pass
    else:
        led.color = color
    try:
        duration = args.duration
    except AttributeError:
        pass
    else:
        led.effect_duration = duration
    try:
        brightness = args.brightness
    except AttributeError:
        pass
    else:
        led.brightness = brightness
    commit(device, args)


def func_led_get_all(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    for led in profile.leds:
        print_led(device, profile, led, 0)


def func_button_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    button, profile, _device = find_button(ratbagd, args)
    print_button(button, profile, button, 0)


def func_button_action_set_none(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    button, _profile, device = find_button(ratbagd, args)
    if button.ActionType.NONE not in button.action_types:
        raise RatbagCapabilityError("disabling buttons is not supported on this device")

    button.disable()
    commit(device, args)


def func_button_action_set_button(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    button, _profile, device = find_button(ratbagd, args)
    button.mapping = args.target_button
    commit(device, args)


def func_button_action_set_special(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    button, _profile, device = find_button(ratbagd, args)
    try:
        special = args.target_special
    except AttributeError:
        pass
    else:
        button.special = button_specials_strmap[special]
    commit(device, args)


def func_button_action_set_key(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    button, _profile, device = find_button(ratbagd, args)
    if button.ActionType.KEY not in button.action_types:
        raise RatbagCapabilityError("assigning a key is not supported on this device")

    try:
        key = args.target_key
    except AttributeError:
        pass
    else:
        button.key = convert_str_to_evcode(key)
    commit(device, args)


def func_button_action_set_macro(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    button, _profile, device = find_button(ratbagd, args)
    if button.ActionType.MACRO not in button.action_types:
        raise RatbagCapabilityError("assigning a macro is not supported on this device")

    macro_keys = args.target_macro
    macro = RatbagdMacro()
    for s in macro_keys:
        is_press = True
        is_release = True
        is_timeout = False

        s = s.upper()
        if s[0] == "T":
            is_timeout = True
            is_press = False
            is_release = False
        elif s[0] == "+":
            is_release = False
            s = s[1:]
        elif s[0] == "-":
            is_press = False
            s = s[1:]

        if is_timeout:
            t = int(s[1:])
            macro.append(RatbagdButton.Macro.WAIT, t)
        else:
            code = convert_str_to_evcode(s)
            if is_press:
                macro.append(RatbagdButton.Macro.KEY_PRESS, code)
            if is_release:
                macro.append(RatbagdButton.Macro.KEY_RELEASE, code)

    button.macro = macro
    commit(device, args)


def func_button_count(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    print(len(profile.buttons))


def func_dpi_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    ratbagd, _profile, _device = find_resolution(ratbagd, args)
    if len(ratbagd.resolution) == 2:
        print(f"{ratbagd.resolution[0]}x{ratbagd.resolution[1]}dpi")
    else:
        print(f"{ratbagd.resolution[0]}dpi")


def func_dpi_get_all(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, _profile, _device = find_resolution(ratbagd, args)
    dpis = resolution.resolutions
    print(" ".join([str(x) for x in dpis]))


def func_dpi_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, _profile, device = find_resolution(ratbagd, args)
    dpi = args.dpi_n
    if len(resolution.resolution) > len(dpi):
        dpi = (dpi[0], dpi[0])
    resolution.resolution = dpi
    commit(device, args)


def func_report_rate_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    print(profile.report_rate)


def func_report_rate_get_all(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    rates = profile.report_rates
    print(" ".join([str(x) for x in rates]))


def func_report_rate_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    profile.report_rate = args.rate_n
    commit(device, args)


def func_angle_snapping_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    if profile.angle_snapping == -1:
        return
    print(bool(profile.angle_snapping))


def func_angle_snapping_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    profile.angle_snapping = 1 if args.angle_snapping_n else 0
    commit(device, args)


def func_debounce_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    if profile.debounce == -1:
        return
    print(profile.debounce)


def func_debounce_get_all(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    values = profile.debounces
    print(" ".join([str(x) for x in values]))


def func_debounce_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    profile.debounce = args.debounce_n
    commit(device, args)


def func_resolution_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, profile, device = find_resolution(ratbagd, args)
    print_resolution(device, profile, resolution, 0)


def func_resolution_active_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    print(profile.active_resolution.index)


def func_resolution_active_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, _profile, device = find_resolution(ratbagd, args)
    resolution.set_active()
    commit(device, args)


def func_resolution_default_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    resolution = None
    for resolution in profile.resolutions:
        if resolution.is_default:
            break

    if resolution is None:
        print("The device has no default resolution")
        sys.exit(1)

    print(resolution.index)


def func_default_resolution_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    # FIXME: capabilities check?
    resolution, _profile, device = find_resolution(ratbagd, args)
    resolution.set_default()
    commit(device, args)


def func_resolution_disabled_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, _profile, _device = find_resolution(ratbagd, args)
    print(resolution.is_disabled)


def func_resolution_enabled_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, _profile, _device = find_resolution(ratbagd, args)
    print(not resolution.is_disabled)


def func_resolution_disabled_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, _profile, device = find_resolution(ratbagd, args)
    resolution.set_disabled(True)
    commit(device, args)


def func_resolution_enabled_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    resolution, _profile, device = find_resolution(ratbagd, args)
    resolution.set_disabled(False)
    commit(device, args)


def func_profile_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    print_profile(device, profile, 0)


def func_profile_name_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, _device = find_profile(ratbagd, args)
    # See https://github.com/libratbag/libratbag/issues/617
    # ratbag converts to ascii, so this has no real effect there, but
    # ratbag-command may still have a non-ascii string.
    string = bytes(profile.name, "utf-8", "ignore")
    print(string.decode("utf-8"))


def func_profile_name_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    if not profile.name:
        raise RatbagCapabilityError(
            "assigning a profile name is not supported on this profile"
        )
    profile.name = args.name
    commit(device, args)


def func_profile_active_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    device = find_device(ratbagd, args)
    profile = device.active_profile
    if profile is None:
        print("The device has no active profile")
        sys.exit(1)
    print(profile.index)


def func_profile_active_set(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    profile.set_active()
    commit(device, args)


def func_profile_enable(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    profile.disabled = False
    commit(device, args)


def func_profile_disable(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    profile, device = find_profile(ratbagd, args)
    profile.disabled = True
    commit(device, args)


def func_device_name_get(ratbagd: Ratbagd, args: argparse.Namespace) -> None:
    device = find_device(ratbagd, args)
    print(device.name)


################################################################################
# these are definitions to be reused in the dict that defines our language

# key elements
"""the type of the element (see 'types' below)"""
of_type = "type"
"""the name of the element, it'll be the one matching the args on the CLI"""
name = "name"
"""the group to logically associate commands while printing the help"""
group = "group"
"""list of positional arguments for the given command"""
pos_args = "pos_args"
"""a tag that we can refer latrer in an element of type 'link'"""
tag = "tag"
"""the element pointed to in an element of type 'link'"""
dest = "dest"
"""the function to associate to the switch or command"""
func = "func"
"""this is a particular command that is an integer, but not an terminating argument.
example:
 profile active get
 profile **2** button 3 get
 - "profile" needs to be a switch
 - "2" needs to be translated as a N_access, given it is a requirement to be able to call 'button'
 """
N_access = "N_access"

# argparse.add_argument parameters (forwarded as such)
"""'type' of the argument"""
arg_type = "arg_type"
"""'metavar' of the argument"""
metavar = "metavar"
"""'help' of the argument"""
help_str = "help"
"""'nargs' of the argument"""
nargs = "nargs"
"""'choices' of the argument"""
choices = "choices"

# types
"""an option to interpret as a command (example 'list', 'info')"""
command = "command"
"""an argument that is required for the given command arguments are leaf nodes
and can not have children
"""
argument = "argument"
"""provides a list of choice of commands for instance, a switch of [A, B] means
we can have A or B only when parsing the command line
"""
switch = "switch"
"""same as list, except we can loop inside the list for instance, a set of
[A, B] means we can have A and B (and A, ...) one after the other, no matter
the order
"""
set = "set"
"""a reference to any other element in the tree marked with a tag"""
link = "link"

################################################################################


def commit(device: RatbagdDevice, args: argparse.Namespace) -> None:
    if args.nocommit:
        return
    device.commit()


def color(string: str) -> Tuple[int, int, int]:
    try:
        int_value = int(string, 16)
    except ValueError as e:
        msg = f"{string!r} is not a color in hex format"
        raise ValueError(msg) from e
    r = (int_value >> 16) & 0xFF
    g = (int_value >> 8) & 0xFF
    b = (int_value >> 0) & 0xFF
    return (r, g, b)


def u8(string: str) -> int:
    int_value = int(string)
    msg = f"{string!r} is not a single byte"
    if int_value < 0 or int_value > 255:
        raise ValueError(msg)
    return int_value


def dpi(string: str) -> Union[Tuple[int, int], Tuple[int,]]:
    try:
        int_value = int(string)
    except ValueError:
        pass
    else:
        return (int_value,)
    if string.endswith("dpi"):
        string = string[:-3]
    x, y = string.split("x")
    try:
        int_x = int(x)
        int_y = int(y)
    except ValueError as e:
        raise ValueError(f"{string!r} is not a valid dpi") from e
    return (int_x, int_y)


RatbagParserSchemaElement = Dict[str, Any]

# TODO: make it easier to introspect this.
# note: 'hidrawX' is assumed before each command
parser_def: List[RatbagParserSchemaElement] = [
    {
        of_type: command,
        name: "info",
        help_str: "Show device information",
        func: show_device,
        group: "Device",
    },
    {
        of_type: command,
        name: "name",
        help_str: "Returns the device name",
        func: func_device_name_get,
    },
    {
        of_type: switch,
        name: "profile",
        help_str: "Access profile information",
        tag: "profile",
        group: "Profile",
        switch: [
            {
                of_type: switch,
                name: "active",
                help_str: "access active profile information",
                switch: [
                    {
                        of_type: command,
                        name: "get",
                        help_str: "Show current active profile",
                        func: func_profile_active_get,
                    },
                    {
                        of_type: command,
                        name: "set",
                        help_str: "Set current active profile",
                        pos_args: [
                            {
                                of_type: argument,
                                name: "profile_n",
                                metavar: "N",
                                help_str: "The profile to set as current",
                                arg_type: int,
                            },
                        ],
                        func: func_profile_active_set,
                    },
                ],
            },
        ],
        N_access: {
            of_type: N_access,
            name: "profile_n",
            metavar: "N",
            help_str: "The profile to act on",
            switch: [
                {
                    of_type: command,
                    name: "get",
                    help_str: "Show selected profile information",
                    func: func_profile_get,
                },
                {
                    of_type: switch,
                    name: "name",
                    help_str: "access profile name information",
                    switch: [
                        {
                            of_type: command,
                            name: "get",
                            help_str: "Show the name of the profile",
                            func: func_profile_name_get,
                        },
                        {
                            of_type: command,
                            name: "set",
                            help_str: "Set the name of the profile",
                            pos_args: [
                                {
                                    of_type: argument,
                                    name: "name",
                                    metavar: "blah",
                                    help_str: "The name to set",
                                },
                            ],
                            func: func_profile_name_set,
                        },
                    ],
                },
                {
                    of_type: command,
                    name: "enable",
                    help_str: "Enable a profile",
                    func: func_profile_enable,
                },
                {
                    of_type: command,
                    name: "disable",
                    help_str: "Disable a profile",
                    func: func_profile_disable,
                },
                {
                    of_type: link,
                    dest: "resolution",
                },
                {
                    of_type: link,
                    dest: "dpi",
                },
                {
                    of_type: link,
                    dest: "rate",
                },
                {
                    of_type: link,
                    dest: "angle_snapping",
                },
                {
                    of_type: link,
                    dest: "debounce",
                },
                {
                    of_type: link,
                    dest: "button",
                },
                {
                    of_type: link,
                    dest: "led",
                },
            ],
        },
    },
    {
        of_type: switch,
        name: "resolution",
        help_str: """Access resolution information

Resolution commands work on the given profile, or on the
active profile if none is given.""",
        tag: "resolution",
        group: "Resolution",
        switch: [
            {
                of_type: switch,
                name: "active",
                help_str: "access active resolution information",
                switch: [
                    {
                        of_type: command,
                        name: "get",
                        help_str: "Show current active resolution",
                        func: func_resolution_active_get,
                    },
                    {
                        of_type: command,
                        name: "set",
                        help_str: "Set current active resolution",
                        pos_args: [
                            {
                                of_type: argument,
                                name: "resolution_n",
                                metavar: "N",
                                help_str: "The resolution to set as current",
                                arg_type: int,
                            },
                        ],
                        func: func_resolution_active_set,
                    },
                ],
            },
            {
                of_type: switch,
                name: "default",
                help_str: "access default resolution information",
                switch: [
                    {
                        of_type: command,
                        name: "get",
                        help_str: "Show current default resolution",
                        func: func_resolution_default_get,
                    },
                    {
                        of_type: command,
                        name: "set",
                        help_str: "Set current default resolution",
                        pos_args: [
                            {
                                of_type: argument,
                                name: "resolution_n",
                                metavar: "N",
                                help_str: "The resolution to set as default",
                                arg_type: int,
                            },
                        ],
                        func: func_default_resolution_set,
                    },
                ],
            },
        ],
        N_access: {
            of_type: N_access,
            name: "resolution_n",
            metavar: "N",
            help_str: "The resolution to act on",
            switch: [
                {
                    of_type: command,
                    name: "get",
                    help_str: "Show selected resolution",
                    func: func_resolution_get,
                },
                {
                    of_type: switch,
                    name: "disabled",
                    help_str: "access disabled resolution information",
                    switch: [
                        {
                            of_type: command,
                            name: "get",
                            help_str: "Show if resolution is disabled",
                            func: func_resolution_disabled_get,
                        },
                        {
                            of_type: command,
                            name: "set",
                            help_str: "Set resolution as disabled",
                            func: func_resolution_disabled_set,
                        },
                    ],
                },
                {
                    of_type: switch,
                    name: "enabled",
                    help_str: "access enabled resolution information",
                    switch: [
                        {
                            of_type: command,
                            name: "get",
                            help_str: "Show if resolution is enabled",
                            func: func_resolution_enabled_get,
                        },
                        {
                            of_type: command,
                            name: "set",
                            help_str: "Set resolution as enabled",
                            func: func_resolution_enabled_set,
                        },
                    ],
                },
                {
                    of_type: link,
                    dest: "dpi",
                },
            ],
        },
    },
    {
        of_type: switch,
        name: "dpi",
        help_str: """Access DPI information

DPI commands work on the given profile and resolution, or on the
active resolution of the active profile if none are given.""",
        tag: "dpi",
        group: "DPI",
        switch: [
            {
                of_type: command,
                name: "get",
                help_str: "Show current DPI value",
                func: func_dpi_get,
            },
            {
                of_type: command,
                name: "get-all",
                help_str: "Show all available DPIs",
                func: func_dpi_get_all,
            },
            {
                of_type: command,
                name: "set",
                help_str: "Set the DPI value to N",
                pos_args: [
                    {
                        of_type: argument,
                        name: "dpi_n",
                        metavar: "N",
                        help_str: "The resolution to set as current",
                        arg_type: dpi,
                    },
                ],
                func: func_dpi_set,
            },
        ],
    },
    {
        of_type: switch,
        name: "rate",
        help_str: """Access report rate information

Rate commands work on the given profile, or on the active profile if none is given.""",
        tag: "rate",
        group: "Rate",
        switch: [
            {
                of_type: command,
                name: "get",
                help_str: "Show current report rate",
                func: func_report_rate_get,
            },
            {
                of_type: command,
                name: "get-all",
                help_str: "Show all available report rates",
                func: func_report_rate_get_all,
            },
            {
                of_type: command,
                name: "set",
                help_str: "Set the report rate to N",
                pos_args: [
                    {
                        of_type: argument,
                        name: "rate_n",
                        metavar: "N",
                        help_str: "The report rate to set as current",
                        arg_type: int,
                    },
                ],
                func: func_report_rate_set,
            },
        ],
    },
    {
        of_type: switch,
        name: "angle_snapping",
        help_str: """Angle snapping information

Angle snapping commands work on the given profile, or on the active profile if none is given.""",
        tag: "angle_snapping",
        group: "AngleSnapping",
        switch: [
            {
                of_type: command,
                name: "get",
                help_str: "Show current angle snapping",
                func: func_angle_snapping_get,
            },
            {
                of_type: command,
                name: "set",
                help_str: "Set the current angle snapping to N",
                pos_args: [
                    {
                        of_type: argument,
                        name: "angle_snapping_n",
                        metavar: "N",
                        help_str: "The angle snapping to set as current",
                        arg_type: int,
                    },
                ],
                func: func_angle_snapping_set,
            },
        ],
    },
    {
        of_type: switch,
        name: "debounce",
        help_str: """Access debounce time information

Debounce commands work on the given profile, or on the active profile if none is given.""",
        tag: "debounce",
        group: "Debounce",
        switch: [
            {
                of_type: command,
                name: "get",
                help_str: "Show current debounce time",
                func: func_debounce_get,
            },
            {
                of_type: command,
                name: "get-all",
                help_str: "Show all available debounce times",
                func: func_debounce_get_all,
            },
            {
                of_type: command,
                name: "set",
                help_str: "Set the current debounce time to N",
                pos_args: [
                    {
                        of_type: argument,
                        name: "debounce_n",
                        metavar: "N",
                        help_str: "The debounce time to set as current",
                        arg_type: int,
                    },
                ],
                func: func_debounce_set,
            },
        ],
    },
    {
        of_type: switch,
        name: "button",
        help_str: """Access Button information

Button commands work on the given profile, or on the
active profile if none is given.""",
        tag: "button",
        group: "Button",
        switch: [
            {
                of_type: command,
                name: "count",
                help_str: "Print the number of buttons",
                func: func_button_count,
            },
        ],
        N_access: {
            of_type: N_access,
            name: "button_n",
            metavar: "N",
            help_str: "The button to act on",
            switch: [
                {
                    of_type: command,
                    name: "get",
                    help_str: "Show selected button",
                    func: func_button_get,
                },
                {
                    of_type: switch,
                    name: "action",
                    help_str: "Act on the selected button",
                    switch: [
                        {
                            of_type: command,
                            name: "get",
                            help_str: "Print the button action",
                            func: func_button_get,
                        },
                        {
                            of_type: switch,
                            name: "set",
                            help_str: "Set an action on the selected button",
                            switch: [
                                {
                                    of_type: command,
                                    name: "button",
                                    help_str: "Set the button action to button B",
                                    pos_args: [
                                        {
                                            of_type: argument,
                                            name: "target_button",
                                            metavar: "B",
                                            help_str: "The new button value to assign",
                                            arg_type: int,
                                        },
                                    ],
                                    func: func_button_action_set_button,
                                },
                                {
                                    of_type: command,
                                    name: "special",
                                    help_str: (
                                        "Set the button action to special action S"
                                    ),
                                    pos_args: [
                                        {
                                            of_type: argument,
                                            name: "target_special",
                                            metavar: "S",
                                            help_str: "The new special value to assign",
                                            choices: button_special_names,
                                        },
                                    ],
                                    func: func_button_action_set_special,
                                },
                                {
                                    of_type: command,
                                    name: "key",
                                    help_str: "Set the button action to key",
                                    pos_args: [
                                        {
                                            of_type: argument,
                                            name: "target_key",
                                            metavar: "S",
                                            help_str: "The new key value to assign",
                                        },
                                    ],
                                    func: func_button_action_set_key,
                                },
                                {
                                    of_type: command,
                                    name: "macro",
                                    help_str: """Set the button action to the given macro

  Macro syntax:
        A macro is a series of key events or waiting periods.
        Keys must be specified in linux/input-event-codes.h key names.
        KEY_A                   Press and release 'a'
        +KEY_A                  Press 'a'
        -KEY_A                  Release 'a'
        t300                    Wait 300ms""",
                                    pos_args: [
                                        {
                                            of_type: argument,
                                            name: "target_macro",
                                            metavar: "...",
                                            help_str: "The new macro to assign",
                                            nargs: argparse.REMAINDER,
                                        },
                                    ],
                                    func: func_button_action_set_macro,
                                },
                                {
                                    of_type: command,
                                    name: "disabled",
                                    help_str: "Disable this button",
                                    pos_args: [],
                                    func: func_button_action_set_none,
                                },
                            ],
                        },
                    ],
                },
            ],
        },
    },
    {
        of_type: switch,
        name: "led",
        help_str: """Access LED information

LED commands work on the given profile, or on the
active profile if none is given.""",
        tag: "led",
        group: "LED",
        switch: [
            {
                of_type: command,
                name: "get",
                help_str: "Show current LED value",
                func: func_led_get_all,
            },
        ],
        N_access: {
            of_type: N_access,
            name: "led_n",
            metavar: "N",
            help_str: "The LED to act on",
            switch: [
                {
                    of_type: command,
                    name: "get",
                    help_str: "Show current LED value",
                    func: func_led_get,
                },
                {
                    of_type: command,
                    name: "capabilities",
                    help_str: "Show LED capabilities",
                    func: func_led_caps,
                },
                {
                    of_type: set,
                    name: "set",
                    help_str: "Act on the selected LED",
                    switch: [
                        {
                            of_type: command,
                            name: "mode",
                            help_str: "The mode to set as current",
                            pos_args: [
                                {
                                    of_type: argument,
                                    name: "mode",
                                    metavar: "mode",
                                    help_str: "The mode to set as current",
                                    choices: led_mode_names,
                                },
                            ],
                        },
                        {
                            of_type: command,
                            name: "color",
                            help_str: "The color to set as current",
                            pos_args: [
                                {
                                    of_type: argument,
                                    name: "color",
                                    metavar: "RRGGBB",
                                    help_str: (
                                        "The color in hex format to set as current"
                                    ),
                                    arg_type: color,
                                },
                            ],
                        },
                        {
                            of_type: command,
                            name: "duration",
                            help_str: "The duration to set as current",
                            pos_args: [
                                {
                                    of_type: argument,
                                    name: "duration",
                                    metavar: "R",
                                    help_str: "The duration in ms to set as current",
                                    arg_type: int,
                                },
                            ],
                        },
                        {
                            of_type: command,
                            name: "brightness",
                            help_str: "The brightness to set as current",
                            pos_args: [
                                {
                                    of_type: argument,
                                    name: "brightness",
                                    metavar: "B",
                                    help_str: "The brightness to set as current",
                                    arg_type: u8,
                                },
                            ],
                        },
                    ],
                    func: func_led_set,
                },
            ],
        },
    },
]


class ParseError(Exception):
    pass


RatbagParserFunction = Callable[[Ratbagd, argparse.Namespace], None]


class RatbagParser:
    tagged: Dict[str, "RatbagParser"] = {}

    def __init__(
        self,
        type: str,
        name: str,
        group: Optional[str] = None,
        tag: Optional[str] = None,
        func: Optional[RatbagParserFunction] = None,
        help: Optional[str] = None,
    ) -> None:
        self.type = type
        self.name = name
        self.tag = tag
        self.group = group
        if tag is not None:
            RatbagParser.tagged[tag] = self
        self.func = func
        self.help = help

    def repr_args(self) -> str:
        return f"name='{self.name}', tag='{self.tag}', func='{self.func}', help='{self.help}'"

    def __repr__(self) -> str:
        return f"{type(self)}({self.repr_args()})"

    def store_function(self, parser: argparse.ArgumentParser) -> None:
        if self.func is not None:
            parser.set_defaults(func=self.func)

    def _add_to_subparsers(self, parent: Any) -> None:
        raise ParseError(f"please implement _add_to_subparsers on {type(self)}")

    def add_to_subparsers(self, parent: Any) -> None:
        self._add_to_subparsers(parent)

    def _sub_parse(
        self, input_string: List[str], ns: argparse.Namespace
    ) -> argparse.ArgumentParser:
        raise ParseError(f"please implement _sub_parse on {type(self)}")

    def sub_parse(
        self, input_string: List[str], ns: argparse.Namespace
    ) -> argparse.ArgumentParser:
        r = self._sub_parse(input_string, ns)
        return r  # noqa: RET504

    def print_help(self, group: Optional[str], prefix: str = "") -> None:
        if self.group is not None:
            print(f"\n{self.group} Commands:")
        self._print_help(prefix)

    def _print_help(self, prefix: str) -> None:
        raise ParseError(f"please implement _print_help on {type(self)}")


class RatbagParserSwitch(RatbagParser):
    def __init__(
        self,
        type: str,
        name: str,
        group: Optional[str] = None,
        switch: Optional[List[RatbagParserSchemaElement]] = None,
        N_access: Optional[RatbagParserSchemaElement] = None,
        tag: Optional[str] = None,
        func: Optional[RatbagParserFunction] = None,
        help: Optional[str] = None,
    ) -> None:
        super().__init__(type, name, group, tag, func, help)
        self.switch: List[RatbagParser] = (
            [classes[obj[of_type]](**obj) for obj in switch]
            if switch is not None
            else []
        )
        self.N_access = (
            RatbagParserNAccess(**N_access) if N_access is not None else None
        )

    def repr_args(self) -> str:
        return f"""switch='{[repr(o) for o in self.switch]}', N_access='{self.N_access}', {RatbagParser.repr_args(self)}"""

    def _add_to_subparsers(self, parent: Any) -> None:
        parser = parent.add_parser(self.name, help=self.help)
        parser.set_defaults(subparse=self.sub_parse)

    def _sub_parse(
        self, input_string: List[str], ns: argparse.Namespace
    ) -> argparse.ArgumentParser:
        if input_string and self.N_access is not None:
            # retrieve first numbered element if any
            try:
                int(input_string[0])
            except ValueError:
                # there are arguments, but they look like commands
                pass
            else:
                # we have a single int as first argument, switch to the
                # N_access subtree of the command
                return self.N_access.parse_parent(self, input_string, ns)

        parser = argparse.ArgumentParser(
            prog=f"{sys.argv[0]} <device> {self.name}",
            description=self.help,
            add_help=False,
        )

        # create a new subparser to handle all commands
        subs = parser.add_subparsers(title="COMMANDS", help=None)
        for e in self.switch:
            e.add_to_subparsers(subs)

        return parser

    def _print_help(self, prefix: str) -> None:
        if self.help and self.group is not None:
            print(textwrap.indent(self.help, "  "), "\n")
        for e in self.switch:
            e.print_help(None, f"{prefix}{self.name} ")
        if self.N_access is not None:
            self.N_access.print_help(None, self.name + " ")

    def __repr__(self) -> str:
        return f"switch({self.repr_args()})"


class RatbagParserNAccess(RatbagParserSwitch):
    def __init__(
        self,
        type: str,
        name: str,
        group: Optional[str] = None,
        switch: Optional[List[RatbagParserSchemaElement]] = None,
        metavar: Optional[str] = None,
        tag: Optional[str] = None,
        func: Optional[RatbagParserFunction] = None,
        help: Optional[str] = None,
    ) -> None:
        super().__init__(type, name, group, switch, None, tag, func, help)
        self.metavar = metavar

    def parse_parent(
        self, parent: Any, input_string: List[str], ns: argparse.Namespace
    ) -> argparse.ArgumentParser:
        parser = argparse.ArgumentParser(
            prog=f"{sys.argv[0]} <device> {parent.name}", add_help=False
        )
        parser.add_argument(self.name, help=self.help, type=int)
        # create a new subparser to handle all commands
        subs = parser.add_subparsers(title="COMMANDS", help=None)
        for e in self.switch:
            e.add_to_subparsers(subs)
        return parser

    def repr_args(self) -> str:
        return f"""switch='{[repr(o) for o in self.switch]}', metavar = '{self.metavar}', {RatbagParser.repr_args(self)}"""

    def __repr__(self) -> str:
        return f"N_Access({self.repr_args()})"

    def _print_help(self, prefix: str) -> None:
        for e in self.switch:
            e.print_help(None, f"{prefix}N ")


class RatbagParserSet(RatbagParserSwitch):
    def __init__(
        self,
        type: str,
        name: str,
        group: Optional[str] = None,
        switch: Optional[List[RatbagParserSchemaElement]] = None,
        N_access: Optional[RatbagParserSchemaElement] = None,
        tag: Optional[str] = None,
        func: Optional[RatbagParserFunction] = None,
        help: Optional[str] = None,
    ) -> None:
        super().__init__(type, name, group, switch, N_access, tag, func, help)

    def _add_to_subparsers(self, parent: Any) -> None:
        parser = parent.add_parser(self.name, help=self.help)
        parser.set_defaults(subparse=self.sub_parse)

    def _sub_parse(
        self, input_string: List[str], ns: argparse.Namespace
    ) -> argparse.ArgumentParser:
        parser = argparse.ArgumentParser(
            prog=f"{sys.argv[0]} <device> {self.name}", add_help=False
        )
        # create a new subparser to handle all commands
        subs = parser.add_subparsers(title="COMMANDS", help=None)
        for e in self.switch:
            e.add_to_subparsers(subs)
        if len(input_string) == 2:
            self.store_function(parser)
        else:
            parser.set_defaults(subparse=self.sub_parse)
        return parser

    def __repr__(self) -> str:
        return f"set({self.repr_args()})"

    def _print_help(self, prefix: str) -> None:
        command = prefix + "{COMMAND} ..."
        print("  {:<36}{}".format(command, self.help if self.help else ""))
        for e in self.switch:
            e.print_help(None, " " * len(prefix))


class RatbagParserCommand(RatbagParser):
    def __init__(
        self,
        type: str,
        name: str,
        group: Optional[str] = None,
        pos_args: Optional[List[RatbagParserSchemaElement]] = None,
        tag: Optional[str] = None,
        func: Optional[RatbagParserFunction] = None,
        help: Optional[str] = None,
    ) -> None:
        super().__init__(type, name, group, tag, func, help)
        self.pos_args: List[RatbagParserArgument] = (
            [classes[obj[of_type]](**obj) for obj in pos_args]
            if pos_args is not None
            else []
        )

    def _add_to_subparsers(self, parent: Any) -> None:
        parser = parent.add_parser(self.name, help=self.help)
        for a in self.pos_args:
            a.add_to_subparsers(parser)
        self.store_function(parser)

    def __repr__(self) -> str:
        return f"command({self.repr_args()})"

    def _print_help(self, prefix: str) -> None:
        command = prefix + self.name
        for a in self.pos_args:
            if a.choices is None or len(a.choices) > 5:
                command += f" {a.metavar}"
            else:
                command += " [{}]".format("|".join(a.choices))
        print("  {:<36}{}".format(command, self.help if self.help else ""))


class RatbagParserArgument(RatbagParser):
    def __init__(
        self,
        type: str,
        name: str,
        group: Optional[str] = None,
        arg_type: Optional[object] = None,
        metavar: Optional[str] = None,
        nargs: Optional[int] = None,
        choices: Optional[List] = None,
        tag: Optional[str] = None,
        func: Optional[RatbagParserFunction] = None,
        help: Optional[str] = None,
    ) -> None:
        super().__init__(type, name, group, tag, func, help)
        self.arg_type = arg_type
        self.metavar = metavar
        self.nargs = nargs
        self.choices = choices

    def _add_to_subparsers(self, parent: Any) -> None:
        parent.add_argument(
            self.name,
            metavar=self.metavar,
            help=self.help,
            type=self.arg_type,
            nargs=self.nargs,
            choices=self.choices,
        )


class RatbagParserLink(RatbagParser):
    def __init__(
        self,
        type: str,
        dest: str,
        group: Optional[str] = None,
        tag: Optional[str] = None,
        func: Optional[RatbagParserFunction] = None,
        help: Optional[str] = None,
    ) -> None:
        super().__init__(type, dest, group, tag, func, help)
        self.dest = dest

    def get_dest(self) -> RatbagParser:
        try:
            dest = RatbagParser.tagged[self.dest]
        except KeyError as e:
            raise ParseError(f"link '{self.dest}' points to nothing") from e
        return dest

    def _add_to_subparsers(self, parent: Any) -> None:
        dest = self.get_dest()
        dest.add_to_subparsers(parent)

    def _print_help(self, prefix: str) -> None:
        dest = self.get_dest()
        print(
            "  {:<36}Use {}for '{} Commands'".format(
                prefix + self.dest + " ...", prefix, dest.group
            )
        )


classes = {
    switch: RatbagParserSwitch,
    set: RatbagParserSet,
    command: RatbagParserCommand,
    argument: RatbagParserArgument,
    link: RatbagParserLink,
    N_access: RatbagParserNAccess,
}


class RatbagParserRoot:
    def __init__(self, commands: List[RatbagParserSchemaElement]) -> None:
        self.children: List[RatbagParser] = [
            classes[def_parser[of_type]](**def_parser) for def_parser in commands
        ]
        self.want_keepalive = False

    def parse(self, input_string: List[str]) -> argparse.Namespace:
        self.parser = argparse.ArgumentParser(
            description="Inspect and modify a configurable device", add_help=False
        )
        self.parser.add_argument(
            "-V", "--version", action="version", version="0.18"
        )
        self.parser.add_argument("--verbose", "-v", action="count", default=0)
        self.parser.add_argument("--help", "-h", action="store_true", default=False)
        self.parser.add_argument("--nocommit", action="store_true", default=False)
        if self.want_keepalive:
            self.parser.add_argument("--keepalive", action="store_true", default=False)

        # retrieve the global options now and remove them from the processing
        ns, rest = self.parser.parse_known_args(input_string)

        if ns.help:
            return ns

        # retrieve the device and remove it from the command processing
        self.parser.add_argument("device_or_list", action="store")
        ns, rest = self.parser.parse_known_args(rest, namespace=ns)

        if ns.device_or_list == "list":
            if rest:
                self.parser.error("extra arguments: '{}'".format(" ".join(rest)))
            ns.func = list_devices
            return ns

        ns.device = ns.device_or_list

        # we need a new parser or 'device_or_list' will eat all of our commands
        command_parser = argparse.ArgumentParser(
            description="command parser",
            prog=f"{sys.argv[0]} <device>",
            add_help=False,
        )

        subs = command_parser.add_subparsers(title="COMMANDS")

        subparser = command_parser

        for child in self.children:
            child.add_to_subparsers(subs)

        ns.subparse = None

        while rest and subparser:
            old_rest = rest
            ns, rest = subparser.parse_known_args(rest, namespace=ns)
            if hasattr(ns, func):
                break
            if old_rest == rest:
                break
            if ns.subparse:
                subparser = ns.subparse(rest, ns)

        if rest:
            self.parser.error("extra arguments: '{}'".format(" ".join(rest)))

        return ns

    def print_help(self) -> None:
        print(f"usage: {self.parser.prog} [OPTIONS] list")
        print(f"       {self.parser.prog} [OPTIONS] <device> {{COMMAND}} ...\n")
        print(self.parser.description)
        print(
            """
Common options:
    --version -V                show program's version number and exit
    --verbose, -v               increase verbosity level
    --nocommit                  Do not immediately write the settings to the mouse
    --help, -h                  show this help and exit"""
        )
        if self.want_keepalive:
            print(
                "    --keepalive                 do not terminate ratbagd after the"
                " processing"
            )
        print(
            """
General Commands:
  list                                List supported devices (does not take a device argument)"""
        )
        for c in self.children:
            c.print_help(None)
        print(
            """
Examples:
  {0} profile active get
  {0} profile 0 resolution active set 4
  {0} profile 0 resolution 1 dpi get
  {0} resolution 4 rate get
  {0} dpi set 800
  {0} profile 0 led 0 set mode on
  {0} profile 0 led 0 set color ff00ff
  {0} profile 0 led 0 set duration 50

Exit codes:
  0     Success
  1     Unsupported feature, index out of available range or invalid device
  2     Commandline arguments are invalid
  3     A command failed on the device
""".format(  # noqa: UP032
                self.parser.prog
            )
        )


def get_parser() -> RatbagParserRoot:
    return RatbagParserRoot(parser_def)


def on_device_added(_ratbagd: Ratbagd, device: RatbagdDevice) -> None:
    device_names = [
        "mara",
        "capybara",
        "porcupine",
        "paca",
        "vole",
        "woodrat",
        "gerbil",
        "shrew",
        "hutia",
        "beaver",
        "squirrel",
        "chinchilla",
        "rabbit",
        "viscacha",
        "hare",
        "degu",
        "gundi",
        "acouchy",
        "nutria",
        "paca",
        "hamster",
        "zokor",
        "chipmunk",
        "gopher",
        "marmot",
        "groundhog",
        "suslik",
        "agouti",
        "blesmol",
    ]

    device_attr = [
        "sobbing",
        "whooping",
        "barking",
        "yapping",
        "howling",
        "squawking",
        "cheering",
        "warbling",
        "thundering",
        "booming",
        "blustering",
        "humming",
        "crying",
        "bawling",
        "roaring",
        "raging",
        "chanting",
        "crooning",
        "murmuring",
        "bellowing",
        "wailing",
        "weeping",
        "screaming",
        "yelling",
        "yodeling",
        "singing",
        "honking",
        "hooting",
        "whispering",
        "hollering",
    ]

    # Let's convert the sha into something not boring. This takes the first
    # 4 characters, creates two different indices from it to generate a
    # name. The rest is hope hope that never get a collision here but it's
    # unlikely enough.
    name = device_names[int(device.id[0:2], 16) % len(device_names)]
    attr = device_attr[int(device.id[2:4], 16) % len(device_attr)]
    device.id = "-".join([attr, name])


def open_ratbagd(
    ratbagd_process: Optional[subprocess.Popen] = None, verbose: int = 0
) -> Optional[Ratbagd]:
    try:
        ratbagd = Ratbagd(RATBAGD_API_VERSION)
        ratbagd.verbose = verbose
        try:
            ratbagd.connect("device-added", on_device_added)
            for device in ratbagd.devices:
                on_device_added(ratbagd, device)
        except AttributeError:
            pass  # the ratbag-command case

    except RatbagdUnavailableError as e:
        print(f"Unable to connect to ratbagd: {e}")
        return None

    if ratbagd_process is not None:
        # if some old version of ratbagd is still running, ratbagd_process may
        # have never started but our DBus bindings may succeed. Check for the
        # return code here, this also gives ratbagd enough time to start and
        # die. If we check immediately we may not have terminated yet.
        ratbagd_process.poll()
        assert ratbagd_process.returncode is None

    return ratbagd


def main(argv: List[str]) -> int:
    if not argv:
        argv = ["list"]

    parser = get_parser()
    cmd = parser.parse(argv)
    if cmd.help:
        parser.print_help()
        return 0

    _r = open_ratbagd(verbose=cmd.verbose)
    if _r is not None:
        with _r as r:
            try:
                f = cmd.func
            except AttributeError:
                parser.print_help()
                return 2
            else:
                try:
                    f(r, cmd)
                except RatbagCapabilityError as e:
                    print(f"Error: {e}", file=sys.stderr)
                    return 1
                except ValueError as e:
                    print(f"Error: {e}", file=sys.stderr)
                    return 2
    return 0


if __name__ == "__main__":
    ret = main(sys.argv[1:])
    sys.exit(ret)