"""Class definitions for DEC Private Modes and their Response values."""

# std imports
from typing import Any, Union


class DecModeResponse:
    """
    Container for DEC Private Mode query response.

    Use helper properties :attr:`~DecModeResponse.supported`,
    :attr:`~DecModeResponse.enabled`, :attr:`~DecModeResponse.permanent`,
    and :attr:`~DecModeResponse.failed` to interpret responses rather than
    checking numeric values directly.
    """
    # Response value constants. Values -1 and -2 are internal abstractions
    # for timeout or query failure, functionally equivalent to NOT_RECOGNIZED.
    NOT_QUERIED = -2
    NO_RESPONSE = -1
    NOT_RECOGNIZED = 0
    SET = 1
    RESET = 2
    PERMANENTLY_SET = 3
    PERMANENTLY_RESET = 4

    def __init__(self, mode: Union[int, "DecPrivateMode"], value: int):
        """
        Initialize response for a DEC private mode query.

        :param mode: DEC private mode number
        :type mode: int
        :param value: Response value from terminal
        :type value: int
        :raises TypeError: If mode is not an integer
        """
        if isinstance(mode, DecPrivateMode):
            self._mode_value = mode.value
        elif isinstance(mode, int):
            self._mode_value = mode
        else:
            raise TypeError(f"Invalid mode got {mode!r}, DecPrivateMode or int expected")
        self._value = value

    @property
    def mode(self) -> "DecPrivateMode":
        """
        The :class:`DecPrivateMode` instance for this response.

        :rtype: DecPrivateMode
        """
        return DecPrivateMode(self._mode_value)

    @property
    def description(self) -> str:
        """
        Description of what this mode controls.

        :rtype: str
        """
        if isinstance(self.mode, DecPrivateMode):
            return self.mode.long_description
        return "Unknown mode"

    @property
    def value(self) -> int:
        """
        Numeric response value for compatibility.

        Prefer using helper properties like :attr:`~DecModeResponse.enabled`
        instead of checking this value directly.

        :rtype: int
        """
        return self._value

    @property
    def supported(self) -> bool:
        """
        Check if the mode is supported by the terminal.

        :rtype: bool
        :returns: True if terminal recognizes and supports this mode
        """
        return self.value > 0

    @property
    def enabled(self) -> bool:
        """
        Check if the mode is currently enabled.

        :rtype: bool
        :returns: True if mode is set (temporarily or permanently)
        """
        return self.value in {1, 3}

    @property
    def disabled(self) -> bool:
        """
        Check if the mode is currently disabled.

        :rtype: bool
        :returns: True if mode is reset (temporarily or permanently)
        """
        return self.value in {2, 4}

    @property
    def changeable(self) -> bool:
        """
        Check if the mode setting can be changed.

        :rtype: bool
        :returns: True if mode can be toggled by applications
        """
        return self.value in {1, 2}

    @property
    def permanent(self) -> bool:
        """
        Check if the mode setting is permanent.

        :rtype: bool
        :returns: True if mode cannot be changed by applications
        """
        return self.value in {3, 4}

    @property
    def failed(self) -> bool:
        """
        Check if the query failed.

        :rtype: bool
        :returns: True if response indicates timeout or query failure
        """
        return self.value < 0

    def __str__(self) -> str:
        """
        Return the constant name for the response value.

        :rtype: str
        """
        return {
            self.NOT_QUERIED: "NOT_QUERIED",
            self.NO_RESPONSE: "NO_RESPONSE",
            self.NOT_RECOGNIZED: "NOT_RECOGNIZED",
            self.SET: "SET",
            self.RESET: "RESET",
            self.PERMANENTLY_SET: "PERMANENTLY_SET",
            self.PERMANENTLY_RESET: "PERMANENTLY_RESET"
        }.get(self.value, "UNKNOWN")

    def __repr__(self) -> str:
        """
        Return full representation with mode and response details.

        :rtype: str
        """
        response_name = str(self)
        response_value = f"({self.value})"
        return f"{self.mode.name}({self._mode_value}) is {response_name}{response_value}"


class DecPrivateMode:
    """
    DEC Private Mode with mnemonic name and description.

    Each instance provides:

    - :attr:`~DecPrivateMode.value`: Numeric private mode identifier
    - :attr:`~DecPrivateMode.name`: Mnemonic name or "UNKNOWN" for unrecognized modes
    - :attr:`~DecPrivateMode.long_description`: Full description of mode functionality
    """
    # These are *not* DecPrivateModes, in that they are not negotiable using the
    # DEC Private Mode sequences, but are carried in the same way, and attached
    # to this class for type safety, as they carry meaning that they have a
    # "special encoding" that is evaluated on-demand on evaluation of
    # term.inkey().name as 'KEY_SHIFT_F1' or testing inkey().is_alt_shift('a').
    # these key "events" have special late-binding evaluations depending on the
    # 'mode' they were sent as.
    SpecialInternalLegacyCSIModifier = -3
    SpecialInternalModifyOtherKeys = -2
    SpecialInternalKitty = -1

    # VT/DEC standard modes (using canonical mnemonics where available) the
    # "official" constants as published should always be used, even if cryptic,
    # at least they are sure to match exactly to existing documentation
    DECCKM = 1
    DECANM = 2
    DECCOLM = 3  # https://vt100.net/docs/vt510-rm/DECCOLM.html
    DECSCLM = 4  # https://vt100.net/docs/vt510-rm/DECSCLM.html
    DECSCNM = 5  # https://vt100.net/docs/vt510-rm/DECSCNM.html
    DECOM = 6    # https://vt100.net/docs/vt510-rm/DECOM.html
    DECAWM = 7   # https://vt100.net/docs/vt510-rm/DECAWM.html
    DECARM = 8   # https://vt100.net/docs/vt510-rm/DECARM.html
    DECINLM = 9
    DECEDM = 10
    DECLTM = 11
    DECKANAM = 12
    DECSCFDM = 13
    DECTEM = 14
    DECEKEM = 16
    DECPFF = 18
    DECPEX = 19
    OV1 = 20
    BA1 = 21
    BA2 = 22
    PK1 = 23
    AH1 = 24
    DECTCEM = 25
    DECPSP = 27
    DECPSM = 29
    SHOW_SCROLLBAR_RXVT = 30
    DECRLM = 34
    DECHEBM = 35
    DECHEM = 36
    DECTEK = 38
    DECCRNLM = 40
    DECUPM = 41
    DECNRCM = 42
    DECGEPM = 43
    DECGPCM = 44
    DECGPCS = 45
    DECGPBM = 46
    DECGRPM = 47
    DECTHAIM = 49
    DECTHAICM = 50
    DECBWRM = 51
    DECOPM = 52
    DEC131TM = 53
    DECBPM = 55
    DECNAKB = 57
    DECIPEM = 58
    DECKKDM = 59
    DECHCCM = 60
    DECVCCM = 61
    DECPCCM = 64
    DECBCMM = 65
    DECNKM = 66
    DECBKM = 67
    DECKBUM = 68
    DECVSSM = 69
    DECFPM = 70
    DECXRLM = 73
    DECSDM = 80
    DECKPM = 81
    WY_52_LINE = 83
    WYENAT_OFF = 84
    REPLACEMENT_CHAR_COLOR = 85
    DECTHAISCM = 90
    DECNCSM = 95
    DECRLCM = 96
    DECCRTSM = 97
    DECARSM = 98
    DECMCM = 99
    DECAAM = 100
    DECCANSM = 101
    DECNULM = 102
    DECHDPXM = 103
    DECESKM = 104
    DECOSCNM = 106
    DECNUMLK = 108
    DECCAPSLK = 109
    DECKLHIM = 110
    DECFWM = 111
    DECRPL = 112
    DECHWUM = 113
    DECATCUM = 114
    DECATCBM = 115
    DECBBSM = 116
    DECECM = 117

    # Mouse reporting modes and xterm/rxvt extensions
    MOUSE_REPORT_CLICK = 1000
    MOUSE_HILITE_TRACKING = 1001
    MOUSE_REPORT_DRAG = 1002
    MOUSE_ALL_MOTION = 1003
    FOCUS_IN_OUT_EVENTS = 1004
    MOUSE_EXTENDED_UTF8 = 1005
    MOUSE_EXTENDED_SGR = 1006
    ALT_SCROLL_XTERM = 1007
    SCROLL_ON_TTY_OUTPUT_RXVT = 1010
    SCROLL_ON_KEYPRESS_RXVT = 1011
    FAST_SCROLL = 1014
    MOUSE_URXVT = 1015
    MOUSE_SGR_PIXELS = 1016
    BOLD_ITALIC_HIGH_INTENSITY = 1021

    # Keyboard and meta key handling modes
    META_SETS_EIGHTH_BIT = 1034
    MODIFIERS_ALT_NUMLOCK = 1035
    META_SENDS_ESC = 1036
    KP_DELETE_SENDS_DEL = 1037
    ALT_SENDS_ESC = 1039

    # Selection, clipboard, and window manager hint modes
    KEEP_SELECTION_NO_HILITE = 1040
    USE_CLIPBOARD_SELECTION = 1041
    URGENCY_ON_CTRL_G = 1042
    RAISE_ON_CTRL_G = 1043
    REUSE_CLIPBOARD_DATA = 1044
    EXTENDED_REVERSE_WRAPAROUND = 1045
    ALT_SCREEN_BUFFER_SWITCH = 1046

    # Alternate screen buffer and cursor save/restore combinations
    ALT_SCREEN_BUFFER_XTERM = 1047
    SAVE_CURSOR_DECSC = 1048
    ALT_SCREEN_AND_SAVE_CLEAR = 1049

    # Terminal info and function key emulation modes
    TERMINFO_FUNC_KEY_MODE = 1050
    SUN_FUNC_KEY_MODE = 1051
    HP_FUNC_KEY_MODE = 1052
    SCO_FUNC_KEY_MODE = 1053

    # Legacy keyboard emulation modes
    LEGACY_KBD_X11R6 = 1060
    VT220_KBD_EMULATION = 1061

    SIXEL_PRIVATE_PALETTE = 1070

    # VTE BiDi extensions
    BIDI_ARROW_KEY_SWAPPING = 1243

    # iTerm2 extensions
    ITERM2_REPORT_KEY_UP = 1337

    # XTerm readline and mouse enhancements
    READLINE_MOUSE_BUTTON_1 = 2001
    READLINE_MOUSE_BUTTON_2 = 2002
    READLINE_MOUSE_BUTTON_3 = 2003
    BRACKETED_PASTE = 2004
    READLINE_CHARACTER_QUOTING = 2005
    READLINE_NEWLINE_PASTING = 2006

    # Modern terminal extensions
    SYNCHRONIZED_OUTPUT = 2026
    GRAPHEME_CLUSTERING = 2027
    TEXT_REFLOW = 2028
    PASSIVE_MOUSE_TRACKING = 2029
    REPORT_GRID_CELL_SELECTION = 2030
    COLOR_PALETTE_UPDATES = 2031
    IN_BAND_WINDOW_RESIZE = 2048

    # VTE bidirectional text extensions
    MIRROR_BOX_DRAWING = 2500
    BIDI_AUTODETECTION = 2501

    # mintty extensions
    AMBIGUOUS_WIDTH_REPORTING = 7700
    SCROLL_MARKERS = 7711
    REWRAP_ON_RESIZE_MINTTY = 7723
    APPLICATION_ESCAPE_KEY = 7727
    ESC_KEY_SENDS_BACKSLASH = 7728
    GRAPHICS_POSITION = 7730
    ALT_MODIFIED_MOUSEWHEEL = 7765
    SHOW_HIDE_SCROLLBAR = 7766
    FONT_CHANGE_REPORTING = 7767
    GRAPHICS_POSITION_2 = 7780
    SHORTCUT_KEY_MODE = 7783
    MOUSEWHEEL_REPORTING = 7786
    APPLICATION_MOUSEWHEEL = 7787
    BIDI_CURRENT_LINE = 7796

    # Terminal-specific extensions
    TTCTH = 8200
    SIXEL_SCROLLING_LEAVES_CURSOR = 8452
    CHARACTER_MAPPING_SERVICE = 8800
    AMBIGUOUS_WIDTH_DOUBLE_WIDTH = 8840
    WIN32_INPUT_MODE = 9001
    KITTY_HANDLE_CTRL_C_Z = 19997
    MINTTY_BIDI = 77096
    INPUT_METHOD_EDITOR = 737769

    # Comprehensive descriptions for each mode -- it would have been nice if all
    # 3 mode items (value, key, description) could be defined side-by-side but
    # we wish to have a int-derived and like-type and not do any metaclassing,
    # or otherwise "unpicklable" or difficult to reason about for compatibility
    _LONG_DESCRIPTIONS = {
        SpecialInternalLegacyCSIModifier: "Non-DEC Mode used internally by Keystroke",
        SpecialInternalModifyOtherKeys: "Non-DEC Mode used internally by Keystroke",
        SpecialInternalKitty: "Non_DEC Mode used internally by Keystroke",

        # DEC standard modes (1-117). The "classical" names are used instead of
        # more friendly mnemonics, that's because most of these are legacy and
        # unused and it makes it easier to find out about them.
        DECCKM: "Cursor Keys Mode",
        DECANM: "ANSI/VT52 Mode",
        DECCOLM: "Column Mode",
        DECSCLM: "Scrolling Mode",
        DECSCNM: "Screen Mode (light or dark screen)",
        DECOM: "Origin Mode",
        DECAWM: "Auto Wrap Mode",
        DECARM: "Auto Repeat Mode",
        DECINLM: "Interlace Mode / Mouse X10 tracking",
        DECEDM: "Editing Mode / Show toolbar (rxvt)",
        DECLTM: "Line Transmit Mode",
        DECKANAM: "Katakana Shift Mode / Blinking cursor (xterm)",
        DECSCFDM: ("Space Compression/Field Delimiter Mode / "
                   "Start blinking cursor (xterm)"),
        DECTEM: "Transmit Execution Mode / Enable XOR of blinking cursor control (xterm)",
        DECEKEM: "Edit Key Execution Mode",
        DECPFF: "Print Form Feed",
        DECPEX: "Printer Extent",
        OV1: "Overstrike",
        BA1: "Local BASIC",
        BA2: "Host BASIC",
        PK1: "Programmable Keypad",
        AH1: "Auto Hardcopy",
        DECTCEM: "Text Cursor Enable Mode",
        DECPSP: "Proportional Spacing",
        DECPSM: "Pitch Select Mode",
        SHOW_SCROLLBAR_RXVT: "Show scrollbar (rxvt)",
        DECRLM: "Cursor Right to Left Mode",
        DECHEBM: "Hebrew (Keyboard) Mode / Enable font-shifting functions (rxvt)",
        DECHEM: "Hebrew Encoding Mode",
        DECTEK: "Tektronix 4010/4014 Mode",
        DECCRNLM: "Carriage Return/New Line Mode / Allow 80⇒132 mode (xterm)",
        DECUPM: "Unidirectional Print Mode / more(1) fix (xterm)",
        DECNRCM: "National Replacement Character Set Mode",
        DECGEPM: "Graphics Expanded Print Mode",
        DECGPCM: "Graphics Print Color Mode / Turn on margin bell (xterm)",
        DECGPCS: "Graphics Print Color Syntax / Reverse-wraparound mode (xterm)",
        DECGPBM: "Graphics Print Background Mode / Start logging (xterm)",
        DECGRPM: "Graphics Rotated Print Mode / Use Alternate Screen Buffer (xterm)",
        DECTHAIM: "Thai Input Mode",
        DECTHAICM: "Thai Cursor Mode",
        DECBWRM: "Black/White Reversal Mode",
        DECOPM: "Origin Placement Mode",
        DEC131TM: "VT131 Transmit Mode",
        DECBPM: "Bold Page Mode",
        DECNAKB: "Greek/N-A Keyboard Mapping Mode",
        DECIPEM: "Enter IBM Proprinter Emulation Mode",
        DECKKDM: "Kanji/Katakana Display Mode",
        DECHCCM: "Horizontal Cursor Coupling",
        DECVCCM: "Vertical Cursor Coupling Mode",
        DECPCCM: "Page Cursor Coupling Mode",
        DECBCMM: "Business Color Matching Mode",
        DECNKM: "Numeric Keypad Mode",
        DECBKM: "Backarrow Key Mode",
        DECKBUM: "Keyboard Usage Mode",
        DECVSSM: "Vertical Split Screen Mode / DECLRMM - Left Right Margin Mode",
        DECFPM: "Force Plot Mode",
        DECXRLM: "Transmission Rate Limiting",
        DECSDM: "Sixel Display Mode",
        DECKPM: "Key Position Mode",
        WY_52_LINE: "52 line mode (WY-370)",
        WYENAT_OFF: "Erasable/nonerasable WYENAT Off attribute select (WY-370)",
        REPLACEMENT_CHAR_COLOR: "Replacement character color (WY-370)",
        DECTHAISCM: "Thai Space Compensating Mode",
        DECNCSM: "No Clearing Screen on Column Change Mode",
        DECRLCM: "Right to Left Copy Mode",
        DECCRTSM: "CRT Save Mode",
        DECARSM: "Auto Resize Mode",
        DECMCM: "Modem Control Mode",
        DECAAM: "Auto Answerback Mode",
        DECCANSM: "Conceal Answerback Message Mode",
        DECNULM: "Ignore Null Mode",
        DECHDPXM: "Half Duplex Mode",
        DECESKM: "Secondary Keyboard Language Mode",
        DECOSCNM: "Overscan Mode",
        DECNUMLK: "NumLock Mode",
        DECCAPSLK: "Caps Lock Mode",
        DECKLHIM: "Keyboard LEDs Host Indicator Mode",
        DECFWM: "Framed Windows Mode",
        DECRPL: "Review Previous Lines Mode",
        DECHWUM: "Host Wake-Up Mode",
        DECATCUM: "Alternate Text Color Underline Mode",
        DECATCBM: "Alternate Text Color Blink Mode",
        DECBBSM: "Bold and Blink Style Mode",
        DECECM: "Erase Color Mode",

        # Mouse and xterm extensions (1000+)
        MOUSE_REPORT_CLICK: "Send Mouse X & Y on button press",
        MOUSE_HILITE_TRACKING: "Use Hilite Mouse Tracking",
        MOUSE_REPORT_DRAG: "Use Cell Motion Mouse Tracking",
        MOUSE_ALL_MOTION: "Use All Motion Mouse Tracking",
        FOCUS_IN_OUT_EVENTS: "Send FocusIn/FocusOut events",
        MOUSE_EXTENDED_UTF8: "Enable UTF-8 Mouse Mode",
        MOUSE_EXTENDED_SGR: "Enable SGR Mouse Mode",
        ALT_SCROLL_XTERM: "Enable Alternate Scroll Mode",
        SCROLL_ON_TTY_OUTPUT_RXVT: "Scroll to bottom on tty output",
        SCROLL_ON_KEYPRESS_RXVT: "Scroll to bottom on key press",
        FAST_SCROLL: "Enable fastScroll resource",
        MOUSE_URXVT: "Enable urxvt Mouse Mode",
        MOUSE_SGR_PIXELS: "Enable SGR Mouse PixelMode",
        BOLD_ITALIC_HIGH_INTENSITY: "Bold/italic implies high intensity",

        # Keyboard and meta key handling modes
        META_SETS_EIGHTH_BIT: 'Interpret "meta" key',
        MODIFIERS_ALT_NUMLOCK: "Enable special modifiers for Alt and NumLock keys",
        META_SENDS_ESC: "Send ESC when Meta modifies a key",
        KP_DELETE_SENDS_DEL: "Send DEL from the editing-keypad Delete key",
        ALT_SENDS_ESC: "Send ESC when Alt modifies a key",

        # Selection, clipboard, and window manager hint modes
        KEEP_SELECTION_NO_HILITE: "Keep selection even if not highlighted",
        USE_CLIPBOARD_SELECTION: "Use the CLIPBOARD selection",
        URGENCY_ON_CTRL_G: "Enable Urgency window manager hint when Control-G is received",
        RAISE_ON_CTRL_G: "Enable raising of the window when Control-G is received",
        REUSE_CLIPBOARD_DATA: "Reuse the most recent data copied to CLIPBOARD",
        EXTENDED_REVERSE_WRAPAROUND: "Extended Reverse-wraparound mode (XTREVWRAP2)",
        ALT_SCREEN_BUFFER_SWITCH: "Enable switching to/from Alternate Screen Buffer",

        # Alternate screen buffer and cursor save/restore combinations
        ALT_SCREEN_BUFFER_XTERM: "Use Alternate Screen Buffer",
        SAVE_CURSOR_DECSC: "Save cursor as in DECSC",
        ALT_SCREEN_AND_SAVE_CLEAR: "Save cursor as in DECSC and use alternate screen buffer",

        # Terminal info and function key emulation modes
        TERMINFO_FUNC_KEY_MODE: "Set terminfo/termcap function-key mode",
        SUN_FUNC_KEY_MODE: "Set Sun function-key mode",
        HP_FUNC_KEY_MODE: "Set HP function-key mode",
        SCO_FUNC_KEY_MODE: "Set SCO function-key mode",

        # Legacy keyboard emulation modes
        LEGACY_KBD_X11R6: "Set legacy keyboard emulation, i.e, X11R6",
        VT220_KBD_EMULATION: "Set VT220 keyboard emulation",

        SIXEL_PRIVATE_PALETTE: "Use private color registers for each graphic",

        # VTE BiDi extensions
        BIDI_ARROW_KEY_SWAPPING: "Arrow keys swapping (BiDi)",

        # iTerm2 extensions
        ITERM2_REPORT_KEY_UP: "Report Key Up",

        # XTerm readline and mouse enhancements
        READLINE_MOUSE_BUTTON_1: "Enable readline mouse button-1",
        READLINE_MOUSE_BUTTON_2: "Enable readline mouse button-2",
        READLINE_MOUSE_BUTTON_3: "Enable readline mouse button-3",
        BRACKETED_PASTE: "Set bracketed paste mode",
        READLINE_CHARACTER_QUOTING: "Enable readline character-quoting",
        READLINE_NEWLINE_PASTING: "Enable readline newline pasting",

        # Modern terminal extensions
        SYNCHRONIZED_OUTPUT: "Synchronized Output",
        GRAPHEME_CLUSTERING: "Grapheme Clustering",
        TEXT_REFLOW: "Text reflow",
        PASSIVE_MOUSE_TRACKING: "Passive Mouse Tracking",
        REPORT_GRID_CELL_SELECTION: "Report grid cell selection",
        COLOR_PALETTE_UPDATES: "Color palette updates",
        IN_BAND_WINDOW_RESIZE: "In-Band Window Resize Notifications",

        # VTE bidirectional text extensions
        MIRROR_BOX_DRAWING: "Mirror box drawing characters",
        BIDI_AUTODETECTION: "BiDi autodetection",

        # mintty extensions
        AMBIGUOUS_WIDTH_REPORTING: "Ambiguous width reporting",
        SCROLL_MARKERS: "Scroll markers (prompt start)",
        REWRAP_ON_RESIZE_MINTTY: "Rewrap on resize",
        APPLICATION_ESCAPE_KEY: "Application escape key mode",
        ESC_KEY_SENDS_BACKSLASH: "Send ^\\ instead of the standard ^[ for the ESC key",
        GRAPHICS_POSITION: "Graphics position",
        ALT_MODIFIED_MOUSEWHEEL: "Alt-modified mousewheel mode",
        SHOW_HIDE_SCROLLBAR: "Show/hide scrollbar",
        FONT_CHANGE_REPORTING: "Font change reporting",
        GRAPHICS_POSITION_2: "Graphics position",
        SHORTCUT_KEY_MODE: "Shortcut key mode",
        MOUSEWHEEL_REPORTING: "Mousewheel reporting",
        APPLICATION_MOUSEWHEEL: "Application mousewheel mode",
        BIDI_CURRENT_LINE: "BiDi on current line",

        # Terminal-specific extensions
        TTCTH: "Terminal-to-Computer Talk-back Handler",
        SIXEL_SCROLLING_LEAVES_CURSOR: "Sixel scrolling leaves cursor to right of graphic",
        CHARACTER_MAPPING_SERVICE: "enable/disable character mapping service",
        AMBIGUOUS_WIDTH_DOUBLE_WIDTH: "Treat ambiguous width characters as double-width",
        WIN32_INPUT_MODE: "win32-input-mode",
        KITTY_HANDLE_CTRL_C_Z: "Handle Ctrl-C/Ctrl-Z mode",
        MINTTY_BIDI: "BiDi",
        INPUT_METHOD_EDITOR: "Input Method Editor (IME) mode",
    }

    # Reverse lookup mapping from numeric value to mnemonic name
    _VALUE_TO_NAME = {v: k for k, v in locals().items()
                      if k.isupper() and isinstance(v, int)
                      and not k.startswith('_')}

    def __init__(self, value: int):
        """
        Initialize DEC Private Mode with numeric identifier.

        :param value: Numeric DEC private mode identifier
        :type value: int
        """
        self.value = int(value)
        self.name = self._VALUE_TO_NAME.get(value, "UNKNOWN")

    def __repr__(self) -> str:
        """
        Return representation in format, ``'NAME(value)'``.

        :rtype: str
        """
        return f"{self.name}({self.value})"

    def __int__(self) -> int:
        """
        Return the integer value of this mode.

        :rtype: int
        """
        return self.value

    def __index__(self) -> int:
        """
        Return integer value for use in contexts requiring an integer index.

        :rtype: int
        """
        return self.value

    def __eq__(self, other: Any) -> bool:
        """
        Compare with another :class:`DecPrivateMode` or int.

        :param other: Object to compare with
        :type other: DecPrivateMode or int
        :rtype: bool
        """
        if isinstance(other, DecPrivateMode):
            return self.value == other.value
        if isinstance(other, int):
            return self.value == other
        return False

    def __hash__(self) -> int:
        """
        Return hash based on numeric value.

        :rtype: int
        """
        return hash(self.value)

    @property
    def long_description(self) -> str:
        """
        Full description of this DEC private mode's functionality.

        :rtype: str
        :returns: Detailed description or "Unknown mode" for unrecognized modes
        """
        return self._LONG_DESCRIPTIONS.get(self.value, "Unknown mode")