twiddling 0.1

data/lib/twiddling/v7/string_table.rb

@@ -0,0 +1,21 @@
+module Twiddling
+  module V7
+    class StringTable
+      attr_reader :entries
+
+      def initialize(entries = [])
+        @entries = entries
+      end
+
+      def entry_at_offset(byte_offset)
+        offset_lookup[byte_offset]
+      end
+
+      private
+
+      def offset_lookup
+        @offset_lookup ||= entries.to_h { |e| [e.byte_offset, e] }
+      end
+    end
+  end
+end

data/lib/twiddling/v7/string_table_entry.rb

@@ -0,0 +1,14 @@
+module Twiddling
+  module V7
+    class StringTableEntry
+      attr_reader :keys, :byte_offset
+
+      def initialize(keys:, byte_offset:)
+        @keys = keys
+        @byte_offset = byte_offset
+      end
+
+      def byte_size = (keys.length + 1) * 4
+    end
+  end
+end

data/lib/twiddling/v7/tw7/button_formatter.rb

@@ -0,0 +1,63 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Formats a chord bitmask as T4 notation button strings.
+      #
+      # Produces compact notation: thumb buttons combined (T14),
+      # finger buttons grouped by row (F1LR, F2M).
+      module ButtonFormatter
+        include ConfigConstants
+
+        module_function
+
+        # Returns the full button string for a bitmask (e.g. "T14 F1L F2M").
+        def format(bitmask)
+          thumbs, fingers = partition_buttons(bitmask)
+          parts = []
+          parts << format_thumbs(thumbs) unless thumbs.empty?
+          fingers.sort.each { |row, cols| parts << "#{row}#{cols.join}" }
+          parts.join(" ")
+        end
+
+        # Returns just the thumb portion of a bitmask (e.g. "T14").
+        # Returns nil if no thumb buttons.
+        def thumb_key(bitmask)
+          thumbs, _ = partition_buttons(bitmask)
+          return nil if thumbs.empty?
+          format_thumbs(thumbs)
+        end
+
+        # Returns the finger portion of a bitmask (e.g. "F1L F2M"),
+        # excluding thumb buttons.
+        def finger_part(bitmask)
+          _, fingers = partition_buttons(bitmask)
+          fingers.sort.map { |row, cols| "#{row}#{cols.join}" }.join(" ")
+        end
+
+        def partition_buttons(bitmask)
+          thumbs = []
+          fingers = {}
+
+          BUTTON_BITS.each do |bit, name|
+            next unless bitmask[bit] == 1
+            classify_button(name, thumbs, fingers)
+          end
+
+          [thumbs, fingers]
+        end
+
+        def classify_button(name, thumbs, fingers)
+          if name.start_with?("T")
+            thumbs << name[1..].to_i
+          else
+            (fingers[name[1].to_i] ||= []) << name[2..].to_sym
+          end
+        end
+
+        def format_thumbs(thumbs)
+          "T#{thumbs.sort.join}"
+        end
+      end
+    end
+  end
+end

data/lib/twiddling/v7/tw7/button_parser.rb

@@ -0,0 +1,78 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Parses T4 button notation into a bitmask.
+      #
+      # Accepts various forms:
+      #   "T14 F1L F2M"   - full notation
+      #   "T14 1L 2M"     - F prefix optional for fingers
+      #   "T14 1L2M"      - spaces optional between finger tokens
+      #   "t14 f1l f2m"   - case-insensitive
+      #   "1LR"           - multiple columns in one token
+      #
+      # A space or F is required between thumb buttons and finger
+      # buttons (T141R is ambiguous, use T14 1R).
+      module ButtonParser
+        include ConfigConstants
+
+        BUTTON_NAME_TO_BIT = BUTTON_BITS.to_h { |bit, name|
+          [name.to_s, bit]
+        }.freeze
+
+        module_function
+
+        def parse(text)
+          thumb_part, finger_part = split_thumb_finger(text.strip.upcase)
+          mask = 0
+          mask |= parse_thumbs(thumb_part) if thumb_part
+          mask |= parse_fingers(finger_part) if finger_part
+          raise ArgumentError, "Invalid button spec: #{text}" if mask == 0
+          mask
+        end
+
+        private
+
+        # Split on the boundary between thumb (T...) and finger parts.
+        # Returns [thumb_string_or_nil, finger_string_or_nil].
+        def split_thumb_finger(text)
+          if text.start_with?("T")
+            match = text.match(/\A(T\d+)\s*(.*)?\z/)
+            raise ArgumentError, "Invalid button spec: #{text}" unless match
+            thumb = match[1]
+            rest = match[2]&.strip
+            [thumb, rest&.empty? ? nil : rest]
+          else
+            [nil, text]
+          end
+        end
+
+        # "T14" -> T1 + T4
+        def parse_thumbs(text)
+          text[1..].chars.reduce(0) do |mask, digit|
+            bit = BUTTON_NAME_TO_BIT["T#{digit}"]
+            raise ArgumentError, "Unknown thumb button: T#{digit}" unless bit
+            mask | (1 << bit)
+          end
+        end
+
+        # "F1L2M" or "1L2M" or "F1LR" -> walk chars
+        def parse_fingers(text)
+          tokens = text.delete(" \t").gsub(/F(?=\d)/, "").scan(/\d[LMR]+/)
+          tokens.reduce(0) { |mask, token| mask | resolve_finger_token(token) }
+        end
+
+        def resolve_finger_token(token)
+          row = token[0]
+          token[1..].chars.reduce(0) do |mask, col|
+            bit = BUTTON_NAME_TO_BIT["F#{row}#{col}"]
+            raise ArgumentError, "Unknown button: F#{row}#{col}" unless bit
+            mask | (1 << bit)
+          end
+        end
+
+        module_function :split_thumb_finger, :parse_thumbs, :parse_fingers,
+          :resolve_finger_token
+      end
+    end
+  end
+end

data/lib/twiddling/v7/tw7/effect_formatter.rb

@@ -0,0 +1,78 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Formats a chord's effect (output) as tw7 text.
+      module EffectFormatter
+        include ChordConstants
+
+        module_function
+
+        def format_effect(chord)
+          case chord.type_name
+          when :keyboard then format_keyboard(chord)
+          when :device then format_device(chord)
+          when :multichar then format_multichar(chord)
+          else "0x%04x" % chord.modifier_type
+          end
+        end
+
+        def format_keyboard(chord)
+          mods = chord.modifier_names.map(&:downcase)
+          key = chord.key_name || ("0x%04x" % chord.keycode)
+
+          result = if mods == ["shift"] && SHIFTED_KEYS[key]
+            SHIFTED_KEYS[key]
+          elsif mods.empty?
+            key
+          else
+            (mods + [key]).join("+")
+          end
+
+          format_ambiguous(result, chord)
+        end
+
+        # Characters that can't appear as bare effects.
+        # # starts a comment, " starts a string literal.
+        QUOTE_CHARS = Set.new(["#"]).freeze
+        UNQUOTABLE_CHARS = Set.new(['"']).freeze
+
+        def format_ambiguous(result, chord)
+          if UNQUOTABLE_CHARS.include?(result)
+            # Can't quote " inside double quotes - use explicit modifier form
+            mods = chord.modifier_names.map(&:downcase)
+            key = chord.key_name
+            (mods + [key]).join("+")
+          elsif QUOTE_CHARS.include?(result)
+            %("#{result}")
+          else
+            result
+          end
+        end
+
+        def format_device(chord)
+          chord.device_function&.to_s || ("device_0x%02x" % chord.modifier_byte)
+        end
+
+        def format_multichar(chord)
+          return "multichar_0x%04x" % chord.modifier_type unless chord.string_keys
+
+          chars = chord.string_keys.map { |sk| string_key_to_char(sk) }.join
+          %("#{chars}")
+        end
+
+        def string_key_to_char(sk)
+          key = HID_KEYS[sk[:hid_code]]
+          return "?" unless key
+          return KEY_TO_CHAR[key] if KEY_TO_CHAR.key?(key)
+
+          shifted = ((sk[:modifier] >> 8) & MODIFIER_SHIFT) != 0
+          if shifted && key.length == 1
+            SHIFTED_KEYS[key] || key.upcase
+          else
+            key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twiddling/v7/tw7/effect_parser.rb

@@ -0,0 +1,121 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Parses a chord effect string into modifier_type, keycode,
+      # and optional string_keys.
+      #
+      # Accepts:
+      #   "c"           - plain key
+      #   "@"           - shifted symbol
+      #   "ctrl+c"      - modifier+key
+      #   "cmd+shift+a" - multiple modifiers
+      #   '"the "'      - multi-char string (double-quoted)
+      #   "speed_cycle" - device function name
+      module EffectParser
+        include ChordConstants
+
+        # Reverse lookups
+        KEY_TO_HID = HID_KEYS.to_h { |hid, name| [name, hid] }.freeze
+        SHIFTED_TO_BASE = SHIFTED_KEYS.to_h { |base, shifted| [shifted, base] }.freeze
+        FUNCTION_TO_CODE = DEVICE_FUNCTIONS.to_h { |code, name| [name.to_s, code] }.freeze
+        MODIFIER_NAME_TO_BIT = MODIFIERS.to_h { |bit, name| [name.downcase, bit] }.freeze
+        CHAR_TO_KEY = KEY_TO_CHAR.to_h { |name, char| [char, name] }.freeze
+
+        module_function
+
+        # Returns {modifier_type:, keycode:, string_keys:}
+        def parse(text)
+          text = text.strip
+          return parse_quoted(text) if text.start_with?('"') && text.end_with?('"')
+
+          classify_and_parse(text)
+        end
+
+        def parse_quoted(text)
+          inner = text[1..-2]
+          (inner.length == 1) ? parse_quoted_char(inner) : parse_string(inner)
+        end
+
+        def classify_and_parse(text)
+          if FUNCTION_TO_CODE.key?(text) then parse_device_function(text)
+          elsif SHIFTED_TO_BASE.key?(text) then parse_key(text)
+          elsif text.include?("+") then parse_modified_key(text)
+          elsif text.match?(/\A0x[0-9a-f]+\z/i) then parse_hex_key(text)
+          else
+            parse_key(text)
+          end
+        end
+
+        private
+
+        def parse_key(text)
+          if (base = SHIFTED_TO_BASE[text])
+            hid = KEY_TO_HID[base] || raise(ArgumentError, "Unknown key: #{text}")
+            {modifier_type: TYPE_KEYBOARD | (MODIFIER_SHIFT << 8), keycode: hid}
+          else
+            hid = KEY_TO_HID[text] || raise(ArgumentError, "Unknown key: #{text}")
+            {modifier_type: TYPE_KEYBOARD, keycode: hid}
+          end
+        end
+
+        def parse_modified_key(text)
+          parts = text.split("+")
+          key_name = parts.pop
+          mod_byte = parts.reduce(0) { |m, name|
+            bit = MODIFIER_NAME_TO_BIT[name.downcase]
+            raise ArgumentError, "Unknown modifier: #{name}" unless bit
+            m | bit
+          }
+          hid = KEY_TO_HID[key_name] || raise(ArgumentError, "Unknown key: #{key_name}")
+          {modifier_type: TYPE_KEYBOARD | (mod_byte << 8), keycode: hid}
+        end
+
+        # A single-char quoted string like "#" is a keyboard chord,
+        # not a multi-char string.
+        def parse_quoted_char(char)
+          sk = char_to_key(char)
+          {modifier_type: sk[:modifier], keycode: sk[:hid_code]}
+        end
+
+        def parse_hex_key(text)
+          {modifier_type: TYPE_KEYBOARD, keycode: Integer(text, 16)}
+        end
+
+        def parse_device_function(text)
+          code = FUNCTION_TO_CODE[text]
+          {modifier_type: TYPE_DEVICE | (code << 8), keycode: 0}
+        end
+
+        def parse_string(text)
+          keys = text.chars.map { |ch| char_to_key(ch) }
+          {modifier_type: TYPE_MULTICHAR, keycode: 0, string_keys: keys}
+        end
+
+        def char_to_key(char)
+          hid, shifted = resolve_char(char)
+          modifier = shifted ? (TYPE_KEYBOARD | (MODIFIER_SHIFT << 8)) : TYPE_KEYBOARD
+          {modifier: modifier, hid_code: hid}
+        end
+
+        def resolve_char(char)
+          hid, shifted = lookup_char(char)
+          raise ArgumentError, "Unknown character: #{char}" unless hid
+          [hid, shifted]
+        end
+
+        def lookup_char(char)
+          if (base = SHIFTED_TO_BASE[char]) then [KEY_TO_HID[base], true]
+          elsif char.match?(/[A-Z]/) then [KEY_TO_HID[char.downcase], true]
+          else
+            [KEY_TO_HID[CHAR_TO_KEY[char] || char], false]
+          end
+        end
+
+        module_function :parse_quoted, :classify_and_parse, :parse_key,
+          :parse_quoted_char, :parse_hex_key, :parse_modified_key,
+          :parse_device_function, :parse_string, :char_to_key,
+          :resolve_char, :lookup_char
+      end
+    end
+  end
+end

data/lib/twiddling/v7/tw7/parser.rb

@@ -0,0 +1,133 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Parses a .tw7 text file into a V7::Config.
+      class Parser
+        DIVIDER = /\A={5,}\z/
+        MOUSEMODE_SCOPE = "[MOUSEMODE]"
+
+        def initialize(text, base: nil)
+          @text = text
+          @base = base || default_base
+        end
+
+        def parse
+          settings_lines, chord_lines = split_sections
+          attrs = build_attrs(settings_lines)
+          chords = parse_chords(chord_lines)
+          sorted = chords.sort_by(&:bitmask)
+          attrs[:chords] = sorted
+          attrs[:index_table] = Config.compute_index_table(sorted)
+          Config.new(attrs)
+        end
+
+        private
+
+        def default_base
+          Config.from_file(
+            File.expand_path("../data/default_base.cfg", __dir__)
+          )
+        end
+
+        def split_sections
+          lines = strip_comments(@text.lines.map(&:rstrip))
+          divider_idx = lines.index { |l| l.match?(DIVIDER) }
+          if divider_idx
+            [lines[0...divider_idx], lines[(divider_idx + 1)..]]
+          else
+            [[], lines]
+          end
+        end
+
+        def strip_comments(lines)
+          lines.map { |line| strip_line_comment(line) }
+        end
+
+        # Remove # comments. A # starts a comment unless it's
+        # inside double quotes.
+        def strip_line_comment(line)
+          in_quotes = false
+          line.each_char.with_index do |ch, i|
+            if ch == '"'
+              in_quotes = !in_quotes
+            elsif ch == "#" && !in_quotes
+              return line[0, i].rstrip
+            end
+          end
+          line
+        end
+
+        def build_attrs(settings_lines)
+          non_blank = settings_lines.reject(&:empty?)
+          parsed = SettingsParser.parse(non_blank)
+          settings = Settings.new(
+            thumb_modifiers: parsed.delete(:thumb_modifiers),
+            dedicated_buttons: parsed.delete(:dedicated_buttons),
+            reserved: @base.settings.reserved
+          )
+          base_attrs.merge(parsed).merge(settings: settings)
+        end
+
+        def base_attrs
+          Config::ATTR_NAMES.to_h { |name| [name, @base.public_send(name)] }
+        end
+
+        def parse_chords(lines)
+          chords = []
+          scope_bitmask = 0
+          mousemode = false
+
+          lines.each_with_index do |line, idx|
+            next if line.strip.empty?
+            parse_chord_line(line, idx, chords, scope_bitmask, mousemode)
+              .then { |new_scope, new_mouse| scope_bitmask, mousemode = new_scope, new_mouse }
+          end
+
+          chords
+        end
+
+        def parse_chord_line(line, idx, chords, scope_bitmask, mousemode)
+          indented = line.start_with?("  ", "\t")
+          content = line.strip
+
+          if content.end_with?("::")
+            open_scope(content, mousemode)
+          elsif indented
+            chords << build_chord(content, scope_bitmask, mousemode, idx)
+            [scope_bitmask, mousemode]
+          else
+            chords << build_chord(content, 0, false, idx)
+            [0, false]
+          end
+        end
+
+        def open_scope(content, _mousemode)
+          scope_text = content.chomp("::")
+          if scope_text == MOUSEMODE_SCOPE
+            [0, true]
+          else
+            [ButtonParser.parse(scope_text), false]
+          end
+        end
+
+        def build_chord(content, scope_bitmask, mousemode, line_idx)
+          buttons_text, effect_text = content.split(":", 2)
+          raise ArgumentError, "Line #{line_idx + 1}: missing effect" unless effect_text
+
+          bitmask = ButtonParser.parse(buttons_text) | scope_bitmask
+          bitmask |= ChordConstants::MOUSE_MODE_FLAG if mousemode
+          effect = EffectParser.parse(effect_text)
+
+          Chord.new(
+            bitmask: bitmask,
+            modifier_type: effect[:modifier_type],
+            keycode: effect[:keycode],
+            string_keys: effect[:string_keys]
+          )
+        rescue ArgumentError => e
+          raise ArgumentError, "Line #{line_idx + 1}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/twiddling/v7/tw7/printer.rb

@@ -0,0 +1,105 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Prints a V7::Config as .tw7 text format.
+      class Printer
+        MOUSEMODE_KEY = "[MOUSEMODE]"
+
+        def initialize(config, io: $stdout)
+          @config = config
+          @io = io
+        end
+
+        def print
+          settings_lines = SettingsFormatter.format(@config)
+          print_settings(settings_lines) if settings_lines.any?
+          print_chords
+        end
+
+        private
+
+        def print_settings(lines)
+          lines.each { |line| @io.puts line }
+          @io.puts "====="
+        end
+
+        def print_chords
+          groups = group_chords
+          groups.each_with_index do |(group_key, chords), idx|
+            @io.puts if idx > 0
+            print_group(group_key, chords)
+          end
+        end
+
+        def group_chords
+          grouped = {}
+          @config.chords.each do |chord|
+            key = group_key(chord)
+            (grouped[key] ||= []) << chord
+          end
+          sort_groups(grouped)
+        end
+
+        def group_key(chord)
+          if chord.mouse_mode?
+            MOUSEMODE_KEY
+          else
+            ButtonFormatter.thumb_key(chord.bitmask) || ""
+          end
+        end
+
+        # Sort: no-thumb first, then by thumb combo length, then
+        # alphabetically. MOUSEMODE sorts last.
+        def sort_groups(grouped)
+          grouped.sort_by { |key, _| sort_key(key) }
+        end
+
+        def sort_key(key)
+          case key
+          when "" then [0, 0, key]
+          when MOUSEMODE_KEY then [3, 0, key]
+          else [1, key.length, key]
+          end
+        end
+
+        def print_group(group_key, chords)
+          if group_key.empty?
+            chords.each { |chord| print_standalone(chord) }
+          elsif chords.length == 1
+            print_standalone(chords[0])
+          else
+            @io.puts "#{group_key}::"
+            chords.each { |chord| print_indented(chord, group_key) }
+          end
+        end
+
+        def print_standalone(chord)
+          buttons = format_all_buttons(chord)
+          @io.puts "#{buttons}: #{EffectFormatter.format_effect(chord)}"
+        end
+
+        def print_indented(chord, group_key)
+          buttons = format_nested_buttons(chord, group_key)
+          @io.puts "  #{buttons}: #{EffectFormatter.format_effect(chord)}"
+        end
+
+        # Full button string for standalone chords, stripping mouse flag.
+        def format_all_buttons(chord)
+          ButtonFormatter.format(chord.bitmask & ~ChordConstants::MOUSE_MODE_FLAG)
+        end
+
+        # For indented chords, strip the group's contribution.
+        # Thumb groups: show only fingers.
+        # MOUSEMODE: show all buttons except the mouse flag.
+        def format_nested_buttons(chord, group_key)
+          clean = chord.bitmask & ~ChordConstants::MOUSE_MODE_FLAG
+          if group_key == MOUSEMODE_KEY
+            ButtonFormatter.format(clean)
+          else
+            ButtonFormatter.finger_part(clean)
+          end
+        end
+      end
+    end
+  end
+end