twiddling 0.1

data/lib/twiddling/cli/search.rb

@@ -0,0 +1,131 @@
+require "optparse"
+
+module Twiddling
+  module Cli
+    # twiddling search <file> [options]
+    #
+    # Searches for chords matching all supplied filters.
+    #   --chord BUTTONS   Exact button match (low bits only)
+    #   --button BUTTON   Chord includes this button (repeatable)
+    #   --result EFFECT   Chord produces this output
+    class Search
+      READABLE_EXTS = %w[.cfg .tw7].freeze
+
+      HELP_TEXT = <<~TEXT
+        Usage: twiddling search <file> [filters]
+
+        Searches for chords matching all supplied filters.
+
+        Filters:
+          --chord BUTTONS   Exact button combination match
+          --button BUTTON   Includes this button (repeatable)
+          --result EFFECT   Produces this output
+
+        Examples:
+          twiddling search my.cfg --chord "T1 1L"
+          twiddling search my.tw7 --result "@"
+          twiddling search my.cfg --button T4 --button 0M
+      TEXT
+
+      def initialize(argv:, stdout: $stdout, stderr: $stderr)
+        @argv = argv
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run
+        return @stdout.puts(HELP_TEXT) if help?
+        validate!
+        matches = apply_filters
+        if matches.empty?
+          @stderr.puts "No matching chords found."
+        else
+          print_matches(matches)
+        end
+      end
+
+      def options
+        @options ||= parse_options
+      end
+
+      private
+
+      def parse_options
+        opts = {buttons: []}
+        remaining = option_parser(opts).parse(@argv.dup)
+        opts[:path] = remaining.shift
+        opts
+      end
+
+      def option_parser(opts)
+        OptionParser.new do |parser|
+          parser.on("--chord BUTTONS", "Exact chord match") { |c| opts[:chord] = c }
+          parser.on("--button BUTTON", "Includes button (repeatable)") { |b| opts[:buttons] << b }
+          parser.on("--result EFFECT", "Produces this output") { |r| opts[:result] = r }
+        end
+      end
+
+      def path = options[:path]
+
+      def help? = @argv.include?("-h") || @argv.include?("--help")
+
+      def validate!
+        raise ExitException, HELP_TEXT if path.nil?
+        raise ExitException, "File not found: #{path}" unless File.exist?(path)
+        validate_ext!
+        raise ExitException, "No search criteria specified" unless any_filters?
+      end
+
+      def validate_ext!
+        return if READABLE_EXTS.include?(File.extname(path))
+
+        raise ExitException, "Unsupported file type: #{path} (expected .cfg or .tw7)"
+      end
+
+      def any_filters?
+        options[:chord] || options[:buttons].any? || options[:result]
+      end
+
+      def config
+        @config ||= case File.extname(path)
+        when ".cfg" then V7::Config.from_file(path)
+        when ".tw7" then V7::Tw7::Parser.new(File.read(path)).parse
+        end
+      end
+
+      def apply_filters
+        results = config.chords
+        results = filter_by_chord(results) if options[:chord]
+        results = filter_by_buttons(results) if options[:buttons].any?
+        results = filter_by_result(results) if options[:result]
+        results
+      end
+
+      def filter_by_chord(chords)
+        target = V7::Tw7::ButtonParser.parse(options[:chord])
+        chords.select { |c| (c.bitmask & 0x7FFFF) == target }
+      end
+
+      def filter_by_buttons(chords)
+        bits = options[:buttons].map { |b| V7::Tw7::ButtonParser.parse(b) }
+        chords.select { |c| bits.all? { |b| c.bitmask & b == b } }
+      end
+
+      def filter_by_result(chords)
+        target = options[:result]
+        chords.select { |c| V7::Tw7::EffectFormatter.format_effect(c) == target }
+      end
+
+      def print_matches(chords)
+        chords.each do |chord|
+          buttons = V7::Tw7::ButtonFormatter.format(
+            chord.bitmask & ~V7::ChordConstants::MOUSE_MODE_FLAG
+          )
+          effect = V7::Tw7::EffectFormatter.format_effect(chord)
+          prefix = chord.mouse_mode? ? "[MOUSEMODE] " : ""
+          @stdout.puts "#{prefix}#{buttons}: #{effect}"
+        end
+      end
+    end
+  end
+end

data/lib/twiddling/cli/twiddling.rb

@@ -0,0 +1,33 @@
+module Twiddling
+  module Cli
+    class Twiddling
+      SUBCOMMANDS = {
+        "read" => :Read,
+        "convert" => :Convert,
+        "search" => :Search,
+        "diff" => :Diff,
+        "help" => :Help
+      }.freeze
+
+      def initialize(argv:, stdout: $stdout, stderr: $stderr)
+        @argv = argv
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      def run
+        subcommand = @argv.shift || "help"
+        klass = resolve(subcommand)
+        klass.new(argv: @argv, stdout: @stdout, stderr: @stderr).run
+      end
+
+      private
+
+      def resolve(name)
+        const = SUBCOMMANDS[name]
+        raise ExitException, "Unknown subcommand: #{name}\n\n#{Help::HELP_TEXT}" unless const
+        Cli.const_get(const)
+      end
+    end
+  end
+end

data/lib/twiddling/cli.rb

@@ -0,0 +1,8 @@
+module Twiddling
+  module Cli
+    ExitException = Class.new(StandardError)
+  end
+end
+
+glob = File.expand_path("../cli/*.rb", __FILE__)
+Dir.glob(glob).sort.each { |f| require(f) }

data/lib/twiddling/v7/chord.rb

@@ -0,0 +1,48 @@
+module Twiddling
+  module V7
+    class Chord
+      include ChordConstants
+
+      attr_reader :bitmask, :modifier_type, :keycode, :string_keys
+
+      def initialize(bitmask:, modifier_type:, keycode:, string_keys: nil)
+        @bitmask = bitmask
+        @modifier_type = modifier_type
+        @keycode = keycode
+        @string_keys = string_keys
+      end
+
+      def type_byte = modifier_type & 0xFF
+
+      def type_name
+        case type_byte
+        when TYPE_DEVICE then :device
+        when TYPE_KEYBOARD then :keyboard
+        when TYPE_MULTICHAR then :multichar
+        end
+      end
+
+      def modifier_byte = (modifier_type >> 8) & 0xFF
+
+      def mouse_mode? = bitmask & MOUSE_MODE_FLAG != 0
+
+      def key_name = HID_KEYS[keycode]
+
+      def modifier_names
+        MODIFIERS.filter_map { |bit, name| name if modifier_byte & bit != 0 }
+      end
+
+      def device_function
+        DEVICE_FUNCTIONS[modifier_byte] if type_byte == TYPE_DEVICE
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          bitmask == other.bitmask &&
+          modifier_type == other.modifier_type &&
+          keycode == other.keycode &&
+          string_keys == other.string_keys
+      end
+    end
+  end
+end

data/lib/twiddling/v7/chord_constants.rb

@@ -0,0 +1,82 @@
+module Twiddling
+  module V7
+    # Constants shared between Chord, Reader::Chord, and Writer::Chord.
+    module ChordConstants
+      ENTRY_SIZE = 8
+
+      # Chord type (low byte of modifier_type)
+      TYPE_DEVICE = 0x01
+      TYPE_KEYBOARD = 0x02
+      TYPE_MULTICHAR = 0x07
+
+      # Keyboard modifier bits (high byte of modifier_type when type = 0x02)
+      MODIFIER_CTRL = 0x01
+      MODIFIER_ALT = 0x04
+      MODIFIER_CMD = 0x08
+      MODIFIER_SHIFT = 0x20
+
+      MODIFIERS = {
+        MODIFIER_CTRL => "Ctrl",
+        MODIFIER_ALT => "Alt",
+        MODIFIER_CMD => "Cmd",
+        MODIFIER_SHIFT => "Shift"
+      }.freeze
+
+      # Device function codes (high byte of modifier_type when type = 0x01)
+      DEVICE_FUNCTIONS = {
+        0x01 => :mouse_toggle,
+        0x02 => :left_click,
+        0x04 => :scroll_toggle,
+        0x05 => :speed_decrease,
+        0x06 => :speed_cycle,
+        0x0a => :middle_click,
+        0x0b => :speed_increase,
+        0x0c => :right_click,
+        0x0d => :print_stats,
+        0x0e => :config_cycle
+      }.freeze
+
+      # USB HID keycodes -> key names
+      HID_KEYS = {
+        0x04 => "a", 0x05 => "b", 0x06 => "c", 0x07 => "d",
+        0x08 => "e", 0x09 => "f", 0x0a => "g", 0x0b => "h",
+        0x0c => "i", 0x0d => "j", 0x0e => "k", 0x0f => "l",
+        0x10 => "m", 0x11 => "n", 0x12 => "o", 0x13 => "p",
+        0x14 => "q", 0x15 => "r", 0x16 => "s", 0x17 => "t",
+        0x18 => "u", 0x19 => "v", 0x1a => "w", 0x1b => "x",
+        0x1c => "y", 0x1d => "z",
+        0x1e => "1", 0x1f => "2", 0x20 => "3", 0x21 => "4",
+        0x22 => "5", 0x23 => "6", 0x24 => "7", 0x25 => "8",
+        0x26 => "9", 0x27 => "0",
+        0x28 => "enter", 0x29 => "esc", 0x2a => "backspace",
+        0x2b => "tab", 0x2c => "space",
+        0x2d => "-", 0x2e => "=", 0x2f => "[", 0x30 => "]",
+        0x31 => "\\", 0x33 => ";", 0x34 => "'", 0x35 => "`",
+        0x36 => ",", 0x37 => ".", 0x38 => "/",
+        0x39 => "caps_lock",
+        0x3a => "f1", 0x3b => "f2", 0x3c => "f3", 0x3d => "f4",
+        0x3e => "f5", 0x3f => "f6", 0x40 => "f7", 0x41 => "f8",
+        0x42 => "f9", 0x43 => "f10", 0x44 => "f11", 0x45 => "f12",
+        0x49 => "insert", 0x4a => "home", 0x4b => "page_up",
+        0x4c => "delete", 0x4d => "end", 0x4e => "page_down",
+        0x4f => "right", 0x50 => "left", 0x51 => "down", 0x52 => "up",
+        0x53 => "num_lock"
+      }.freeze
+
+      # Base key -> shifted symbol (for Shift+key display)
+      SHIFTED_KEYS = {
+        "1" => "!", "2" => "@", "3" => "#", "4" => "$",
+        "5" => "%", "6" => "^", "7" => "&", "8" => "*",
+        "9" => "(", "0" => ")",
+        "-" => "_", "=" => "+", "[" => "{", "]" => "}",
+        "\\" => "|", ";" => ":", "'" => '"', "`" => "~",
+        "," => "<", "." => ">", "/" => "?"
+      }.freeze
+
+      # Characters that need special handling in string output
+      KEY_TO_CHAR = {"space" => " ", "tab" => "\t"}.freeze
+
+      MOUSE_MODE_FLAG = 0x00080000
+    end
+  end
+end

data/lib/twiddling/v7/config.rb

@@ -0,0 +1,102 @@
+module Twiddling
+  module V7
+    class Config
+      include ConfigConstants
+
+      ATTR_NAMES = %i[
+        version format_version flags_1 flags_2 flags_3
+        idle_time key_repeat reserved_0e reserved_10
+        settings index_table chords
+      ].freeze
+
+      attr_reader(*ATTR_NAMES)
+
+      def initialize(attrs)
+        ATTR_NAMES.each { |name| instance_variable_set(:"@#{name}", attrs[name]) }
+      end
+
+      def self.from_file(path)
+        config = Reader::Config.new(File.binread(path)).parse
+        config.validate!
+        config
+      end
+
+      def self.from_binary(data)
+        config = Reader::Config.new(data).parse
+        config.validate!
+        config
+      end
+
+      def to_binary = Writer::Config.new(self).to_binary
+
+      def write(path) = File.binwrite(path, to_binary)
+
+      def chord_count = chords.length
+
+      # Returns a new Config with the chord added, sorted by bitmask,
+      # with the index table recomputed.
+      def add_chord(chord)
+        new_chords = (chords + [chord]).sort_by(&:bitmask)
+        with(chords: new_chords, index_table: self.class.compute_index_table(new_chords))
+      end
+
+      # Returns a new Config with all chords matching the given bitmask
+      # (low 16 bits) removed, with the index table recomputed.
+      def remove_chord(bitmask)
+        target = bitmask & 0xFFFF
+        new_chords = chords.reject { |c| (c.bitmask & 0xFFFF) == target }
+        with(chords: new_chords, index_table: self.class.compute_index_table(new_chords))
+      end
+
+      # Computes the 32-byte index table for a sorted list of chords.
+      # Each entry maps the low 5 bits of a bitmask prefix to the
+      # index of the first chord with that prefix. 0x80 = no match.
+      def self.compute_index_table(chords)
+        table = Array.new(32, 0x80)
+        chords.each_with_index do |chord, idx|
+          prefix = chord.bitmask & 0x1F
+          table[prefix] = idx if table[prefix] == 0x80
+        end
+        table
+      end
+
+      # Returns a new Config with the given attributes replaced.
+      def set(**overrides)
+        with(**overrides)
+      end
+
+      # Returns a new Config with the given Settings.
+      def with_settings(new_settings)
+        with(settings: new_settings)
+      end
+
+      def validator = @validator ||= Validator.new(self)
+
+      def validate = validator.validate
+
+      def validate! = validator.validate!
+
+      # Convenience delegators to settings
+      def thumb_modifiers = settings.thumb_modifiers
+
+      def dedicated_buttons = settings.dedicated_buttons
+
+      private
+
+      def attrs
+        ATTR_NAMES.to_h { |name| [name, public_send(name)] }
+      end
+
+      def with(**overrides)
+        config = self.class.new(attrs.merge(overrides))
+        config.validate!
+        config
+      end
+
+      # Builds a new Config without validation - only for testing.
+      def with_no_validate(**overrides)
+        self.class.new(attrs.merge(overrides))
+      end
+    end
+  end
+end

data/lib/twiddling/v7/config_constants.rb

@@ -0,0 +1,30 @@
+module Twiddling
+  module V7
+    # Constants shared between Config, Reader::Config, and Writer::Config.
+    module ConfigConstants
+      HEADER_SIZE = 128
+
+      # Button bitmask bit positions (bits 0-18 of chord bitmask)
+      # Note: for rows 1-4, L and R are swapped from the nchorder spec.
+      BUTTON_BITS = {
+        0 => :T1, 1 => :F1R, 2 => :F1M, 3 => :F1L,
+        4 => :T2, 5 => :F2R, 6 => :F2M, 7 => :F2L,
+        8 => :T3, 9 => :F3R, 10 => :F3M, 11 => :F3L,
+        12 => :T4, 13 => :F4R, 14 => :F4M, 15 => :F4L,
+        16 => :F0L, 17 => :F0M, 18 => :F0R
+      }.freeze
+
+      # Thumb button modifier assignment codes (offsets 0x40-0x4F)
+      THUMB_MODIFIERS = {
+        0 => :none, 1 => :l_control, 2 => :l_shift,
+        3 => :l_option, 4 => :l_command
+      }.freeze
+
+      # Dedicated button function codes (offsets 0x50-0x53)
+      DEDICATED_FUNCTIONS = {
+        0x00 => :none, 0x09 => :mouse_left,
+        0x0a => :mouse_right, 0x0b => :mouse_middle
+      }.freeze
+    end
+  end
+end

data/lib/twiddling/v7/reader/chord.rb

@@ -0,0 +1,49 @@
+module Twiddling
+  module V7
+    module Reader
+      # Parses an 8-byte chord entry from v7 binary config data.
+      #
+      # Binary layout (all little-endian):
+      #
+      #   Bytes 0-3: bitmask (u32) - button combination + flags
+      #   Bytes 4-5: modifier_type (u16) - type in low byte, modifier/function/offset in high byte
+      #   Bytes 6-7: keycode (u16) - HID keycode for keyboard chords, 0 otherwise
+      #
+      # For multi-char chords (type 0x07), the high byte of modifier_type
+      # is a byte offset into the string table. The string_table argument
+      # is used to resolve that offset into a key sequence.
+      class Chord
+        include ChordConstants
+
+        def initialize(data, string_table: nil)
+          @data = data
+          @string_table = string_table
+        end
+
+        def parse
+          bitmask, modifier_type, keycode = @data.unpack("Vvv")
+          string_keys = resolve_string_keys(modifier_type)
+
+          V7::Chord.new(
+            bitmask: bitmask,
+            modifier_type: modifier_type,
+            keycode: keycode,
+            string_keys: string_keys
+          )
+        end
+
+        private
+
+        # Looks up the string table entry for a multi-char chord.
+        # Returns nil for non-multichar chords or when no table is present.
+        def resolve_string_keys(modifier_type)
+          return nil unless @string_table
+          return nil unless (modifier_type & 0xFF) == TYPE_MULTICHAR
+
+          offset = (modifier_type >> 8) & 0xFF
+          @string_table.entry_at_offset(offset)&.keys
+        end
+      end
+    end
+  end
+end

data/lib/twiddling/v7/reader/config.rb

@@ -0,0 +1,64 @@
+module Twiddling
+  module V7
+    module Reader
+      # Parses a complete v7 binary config file into a V7::Config.
+      #
+      # Binary layout:
+      #   0x00-0x7F: 128-byte header (flags, settings, index table)
+      #   0x80+:     8-byte chord entries (chord_count of them)
+      #   after chords: string table (variable length, may be empty)
+      class Config
+        include ConfigConstants
+
+        def initialize(data)
+          @data = data
+        end
+
+        def parse
+          header = parse_header
+          string_table = parse_string_table(header[:chord_count])
+          chords = parse_chords(header[:chord_count], string_table)
+          V7::Config.new(header.merge(chords: chords))
+        end
+
+        private
+
+        def parse_header
+          parse_header_fields.merge(parse_header_regions)
+        end
+
+        def parse_header_fields
+          version, format_version, flags_1, flags_2, flags_3,
+            chord_count, idle_time, key_repeat, reserved_0e =
+            @data[0, 16].unpack("VCCCCvvvv")
+
+          {version:, format_version:, flags_1:, flags_2:, flags_3:,
+           chord_count:, idle_time:, key_repeat:, reserved_0e:}
+        end
+
+        def parse_header_regions
+          {
+            reserved_10: @data[0x10, 48],
+            settings: Reader::Settings.new(@data[0x40, 32]).parse,
+            index_table: @data[0x60, 32].unpack("C32")
+          }
+        end
+
+        def parse_string_table(chord_count)
+          offset = HEADER_SIZE + (chord_count * ChordConstants::ENTRY_SIZE)
+          table_data = @data[offset..]
+          return nil unless table_data && !table_data.empty?
+
+          Reader::StringTable.new(table_data).parse
+        end
+
+        def parse_chords(chord_count, string_table)
+          chord_count.times.map do |i|
+            offset = HEADER_SIZE + (i * ChordConstants::ENTRY_SIZE)
+            Reader::Chord.new(@data[offset, ChordConstants::ENTRY_SIZE], string_table: string_table).parse
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twiddling/v7/reader/settings.rb

@@ -0,0 +1,26 @@
+module Twiddling
+  module V7
+    module Reader
+      # Parses the 32-byte settings region (offsets 0x40-0x5F) from
+      # a v7 config header.
+      #
+      # Binary layout:
+      #   0x40-0x4F: thumb modifier assignments (4 x u32 LE)
+      #   0x50-0x53: dedicated button functions (4 x u8)
+      #   0x54-0x5F: reserved (12 bytes, always zeros)
+      class Settings
+        def initialize(data)
+          @data = data
+        end
+
+        def parse
+          V7::Settings.new(
+            thumb_modifiers: @data[0, 16].unpack("V4"),
+            dedicated_buttons: @data[16, 4].unpack("C4"),
+            reserved: @data[20, 12]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/twiddling/v7/reader/string_table.rb

@@ -0,0 +1,69 @@
+module Twiddling
+  module V7
+    module Reader
+      # Parses the string table region of a v7 binary config file.
+      #
+      # The string table is a sequence of null-terminated entries, each
+      # consisting of (modifier u16 LE, hid_code u16 LE) pairs. It
+      # appears at the end of the file, immediately after the chord
+      # entries. Multi-char chords reference entries by byte offset.
+      #
+      # Binary layout of a single entry ("te"):
+      #
+      #   02 00 17 00   modifier=0x0002 hid_code=0x0017 (t)
+      #   02 00 08 00   modifier=0x0002 hid_code=0x0008 (e)
+      #   00 00 00 00   null terminator
+      #
+      # Multiple entries are concatenated. The byte offset of each entry
+      # is stored in the chord's modifier_type high byte so the firmware
+      # can jump directly to it.
+      class StringTable
+        # Each key pair is 4 bytes: modifier u16 + hid_code u16
+        PAIR_SIZE = 4
+
+        def initialize(data)
+          @data = data.b
+        end
+
+        # Parses all entries sequentially, returning a V7::StringTable
+        # with StringTableEntry objects that track their byte offsets.
+        def parse
+          entries = []
+          offset = 0
+
+          while offset < @data.length
+            keys = read_keys(offset)
+            break if keys.nil?
+
+            entries << StringTableEntry.new(keys: keys, byte_offset: offset)
+            # Advance past this entry's key pairs + the null terminator
+            offset += (keys.length + 1) * PAIR_SIZE
+          end
+
+          V7::StringTable.new(entries)
+        end
+
+        private
+
+        # Reads a single entry's keys starting at the given byte offset.
+        # Returns nil if no valid pairs are found (end of table).
+        def read_keys(offset)
+          pairs = read_pairs(offset)
+          keys = pairs.map { |mod, hid| {modifier: mod, hid_code: hid} }
+          keys.empty? ? nil : keys
+        end
+
+        # Reads (modifier, hid_code) pairs until hitting a null terminator.
+        def read_pairs(offset)
+          each_pair(offset).take_while { |mod, hid| !null_terminator?(mod, hid) }
+        end
+
+        # Unpacks the raw bytes from the given offset as u16 LE values,
+        # yielding [modifier, hid_code] pairs.
+        def each_pair(offset) = @data[offset..].unpack("v*").each_slice(2)
+
+        def null_terminator?(mod, hid) = mod == 0 && hid == 0
+      end
+    end
+  end
+end

data/lib/twiddling/v7/settings.rb

@@ -0,0 +1,21 @@
+module Twiddling
+  module V7
+    # Device settings from the config header (offsets 0x40-0x5F).
+    #
+    # Contains thumb button modifier assignments, dedicated button
+    # functions, and a reserved region.
+    class Settings
+      include ConfigConstants
+
+      BINARY_SIZE = 32
+
+      attr_reader :thumb_modifiers, :dedicated_buttons, :reserved
+
+      def initialize(thumb_modifiers:, dedicated_buttons:, reserved:)
+        @thumb_modifiers = thumb_modifiers
+        @dedicated_buttons = dedicated_buttons
+        @reserved = reserved
+      end
+    end
+  end
+end