twiddling 0.1

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

@@ -0,0 +1,96 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Formats the settings section of a .tw7 file.
+      # Only emits settings that differ from defaults.
+      module SettingsFormatter
+        include ConfigConstants
+
+        DEFAULTS = {
+          idle_time: 600,
+          key_repeat_delay: 100,
+          key_repeat: true,
+          haptic: true,
+          keyboard_mode: false,
+          nav_sensitivity: 4,
+          nav_invert_x: false,
+          nav_direction: 0,
+          t1_modifier: :none,
+          t2_modifier: :l_option,
+          t3_modifier: :l_control,
+          t4_modifier: :l_shift,
+          f0l_dedicated: :mouse_right,
+          f0m_dedicated: :mouse_middle,
+          f0r_dedicated: :mouse_left,
+          t0_dedicated: :mouse_left
+        }.freeze
+
+        module_function
+
+        def format(config)
+          current = extract_settings(config)
+          lines = []
+
+          current.each do |key, value|
+            next if DEFAULTS[key] == value
+            lines << "#{key}: #{format_value(value)}"
+          end
+
+          lines
+        end
+
+        def extract_settings(config)
+          extract_header_settings(config)
+            .merge(extract_thumb_settings(config))
+            .merge(extract_dedicated_settings(config))
+        end
+
+        def extract_header_settings(config)
+          extract_timing_settings(config).merge(extract_flag_settings(config))
+        end
+
+        def extract_timing_settings(config)
+          {idle_time: config.idle_time, key_repeat_delay: config.key_repeat}
+        end
+
+        def extract_flag_settings(config)
+          {
+            key_repeat: (config.flags_1 & 0x01) != 0,
+            haptic: (config.flags_1 & 0x08) != 0,
+            keyboard_mode: (config.flags_1 & 0x02) != 0,
+            nav_sensitivity: (config.flags_2 >> 3) & 0x1F,
+            nav_invert_x: (config.flags_2 & 0x04) != 0,
+            nav_direction: config.flags_2 & 0x03
+          }
+        end
+
+        def extract_thumb_settings(config)
+          {
+            t1_modifier: THUMB_MODIFIERS[config.thumb_modifiers[0]],
+            t2_modifier: THUMB_MODIFIERS[config.thumb_modifiers[1]],
+            t3_modifier: THUMB_MODIFIERS[config.thumb_modifiers[2]],
+            t4_modifier: THUMB_MODIFIERS[config.thumb_modifiers[3]]
+          }
+        end
+
+        def extract_dedicated_settings(config)
+          {
+            f0l_dedicated: DEDICATED_FUNCTIONS[config.dedicated_buttons[0]],
+            f0m_dedicated: DEDICATED_FUNCTIONS[config.dedicated_buttons[1]],
+            f0r_dedicated: DEDICATED_FUNCTIONS[config.dedicated_buttons[2]],
+            t0_dedicated: DEDICATED_FUNCTIONS[config.dedicated_buttons[3]]
+          }
+        end
+
+        def format_value(value)
+          case value
+          when true then "true"
+          when false then "false"
+          when Symbol then value.to_s
+          else value.to_s
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+module Twiddling
+  module V7
+    module Tw7
+      # Parses the settings section of a .tw7 file into Config attributes.
+      module SettingsParser
+        include ConfigConstants
+
+        THUMB_MODIFIER_NAMES = THUMB_MODIFIERS.to_h { |code, name| [name.to_s, code] }.freeze
+        DEDICATED_NAMES = DEDICATED_FUNCTIONS.to_h { |code, name| [name.to_s, code] }.freeze
+
+        module_function
+
+        # Returns a hash of Config-compatible attributes from settings lines.
+        # Missing settings use defaults from the empty.cfg baseline.
+        def parse(lines)
+          raw = parse_lines(lines)
+          build_attrs(raw)
+        end
+
+        private
+
+        def parse_lines(lines)
+          lines.each_with_object({}) do |line, hash|
+            key, value = line.split(":", 2).map(&:strip)
+            hash[key] = value
+          end
+        end
+
+        def build_attrs(raw) # rubocop:disable Metrics/AbcSize
+          {
+            idle_time: int_val(raw, "idle_time", 600),
+            key_repeat: int_val(raw, "key_repeat_delay", 100),
+            flags_1: build_flags_1(raw),
+            flags_2: build_flags_2(raw),
+            thumb_modifiers: build_thumb_modifiers(raw),
+            dedicated_buttons: build_dedicated(raw)
+          }
+        end
+
+        def build_flags_1(raw)
+          flags = 0
+          flags |= 0x01 if bool_val(raw, "key_repeat", true)
+          flags |= 0x02 if bool_val(raw, "keyboard_mode", false)
+          flags |= 0x08 if bool_val(raw, "haptic", true)
+          flags
+        end
+
+        def build_flags_2(raw)
+          sensitivity = int_val(raw, "nav_sensitivity", 4)
+          invert_x = bool_val(raw, "nav_invert_x", false) ? 1 : 0
+          direction = int_val(raw, "nav_direction", 0)
+          (sensitivity << 3) | (invert_x << 2) | direction
+        end
+
+        def build_thumb_modifiers(raw)
+          [
+            thumb_val(raw, "t1_modifier", :none),
+            thumb_val(raw, "t2_modifier", :l_option),
+            thumb_val(raw, "t3_modifier", :l_control),
+            thumb_val(raw, "t4_modifier", :l_shift)
+          ]
+        end
+
+        def build_dedicated(raw)
+          [
+            dedicated_val(raw, "f0l_dedicated", :mouse_right),
+            dedicated_val(raw, "f0m_dedicated", :mouse_middle),
+            dedicated_val(raw, "f0r_dedicated", :mouse_left),
+            dedicated_val(raw, "t0_dedicated", :mouse_left)
+          ]
+        end
+
+        def int_val(raw, key, default)
+          raw.key?(key) ? raw[key].to_i : default
+        end
+
+        def bool_val(raw, key, default)
+          raw.key?(key) ? raw[key] == "true" : default
+        end
+
+        def thumb_val(raw, key, default)
+          name = raw.key?(key) ? raw[key] : default.to_s
+          THUMB_MODIFIER_NAMES[name.to_s] || raise(ArgumentError, "Unknown thumb modifier: #{name}")
+        end
+
+        def dedicated_val(raw, key, default)
+          name = raw.key?(key) ? raw[key] : default.to_s
+          DEDICATED_NAMES[name.to_s] || raise(ArgumentError, "Unknown dedicated function: #{name}")
+        end
+
+        module_function :parse_lines, :build_attrs, :build_flags_1, :build_flags_2,
+          :build_thumb_modifiers, :build_dedicated, :int_val, :bool_val,
+          :thumb_val, :dedicated_val
+      end
+    end
+  end
+end

data/lib/twiddling/v7/validator.rb

@@ -0,0 +1,93 @@
+module Twiddling
+  module V7
+    class Validator
+      Error = Struct.new(:field, :message, keyword_init: true) do
+        def to_s = "#{field}: #{message}"
+      end
+
+      ValidationError = Class.new(Twiddling::Error)
+
+      def initialize(config)
+        @config = config
+      end
+
+      def validate
+        errors = []
+        check_format_version(errors)
+        check_chord_count(errors)
+        check_sorted_bitmasks(errors)
+        check_no_duplicate_bitmasks(errors)
+        check_string_table_offsets(errors)
+        errors
+      end
+
+      def validate!
+        errors = validate
+        return if errors.empty?
+
+        messages = errors.map(&:to_s).join("; ")
+        raise ValidationError, messages
+      end
+
+      private
+
+      def check_format_version(errors)
+        return if @config.format_version == 7
+
+        errors << Error.new(
+          field: :format_version,
+          message: "expected 7, got #{@config.format_version}"
+        )
+      end
+
+      def check_chord_count(errors)
+        return if @config.chord_count <= 0xFFFF
+
+        errors << Error.new(
+          field: :chord_count,
+          message: "exceeds u16 max (#{@config.chord_count})"
+        )
+      end
+
+      def check_sorted_bitmasks(errors)
+        bitmasks = @config.chords.map(&:bitmask)
+        return if bitmasks == bitmasks.sort
+
+        errors << Error.new(
+          field: :chords,
+          message: "chords are not sorted by bitmask"
+        )
+      end
+
+      def check_no_duplicate_bitmasks(errors)
+        seen = {}
+        @config.chords.each_with_index do |chord, idx|
+          if seen[chord.bitmask]
+            errors << Error.new(
+              field: :chords,
+              message: "duplicate bitmask 0x%08x at indices %d and %d" %
+                [chord.bitmask, seen[chord.bitmask], idx]
+            )
+          else
+            seen[chord.bitmask] = idx
+          end
+        end
+      end
+
+      def check_string_table_offsets(errors)
+        multichar_chords = @config.chords.select { |c| c.type_name == :multichar }
+        return if multichar_chords.empty?
+
+        multichar_chords.each do |chord|
+          next if chord.string_keys && !chord.string_keys.empty?
+
+          errors << Error.new(
+            field: :chords,
+            message: "multi-char chord (bitmask 0x%08x) has no string keys" %
+              chord.bitmask
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+module Twiddling
+  module V7
+    module Writer
+      # Serializes a V7::Chord back to 8 bytes of binary data.
+      #
+      # For multi-char chords, a string_table_offset must be provided
+      # to encode the correct byte offset into the modifier_type field.
+      # For other chord types, modifier_type is written as-is.
+      class Chord
+        include ChordConstants
+
+        def initialize(chord, string_table_offset: nil)
+          @chord = chord
+          @string_table_offset = string_table_offset
+        end
+
+        def to_binary
+          [@chord.bitmask, effective_modifier_type, @chord.keycode].pack("Vvv")
+        end
+
+        private
+
+        # For multi-char chords being written with a new offset,
+        # rebuild modifier_type from the type byte + offset.
+        # Otherwise, preserve the original modifier_type.
+        def effective_modifier_type
+          if @string_table_offset
+            TYPE_MULTICHAR | (@string_table_offset << 8)
+          else
+            @chord.modifier_type
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+module Twiddling
+  module V7
+    module Writer
+      # Serializes a V7::Config back to the v7 binary format.
+      #
+      # Produces three sections concatenated:
+      #   1. 128-byte header
+      #   2. 8-byte chord entries
+      #   3. String table (for multi-char chords)
+      #
+      # String table offsets in multi-char chord entries are
+      # recomputed during serialization to match the output layout.
+      class Config
+        include ConfigConstants
+
+        def initialize(config)
+          @config = config
+        end
+
+        def to_binary
+          header_binary + chords_binary + string_table_binary
+        end
+
+        private
+
+        def header_binary
+          header_fields + @config.reserved_10 + settings_binary + index_table_field
+        end
+
+        def header_fields
+          [
+            @config.version, @config.format_version,
+            @config.flags_1, @config.flags_2, @config.flags_3,
+            @config.chord_count, @config.idle_time,
+            @config.key_repeat, @config.reserved_0e
+          ].pack("VCCCCvvvv")
+        end
+
+        def settings_binary
+          Writer::Settings.new(@config.settings).to_binary
+        end
+
+        def index_table_field
+          @config.index_table.pack("C32")
+        end
+
+        def chords_binary
+          offsets = compute_string_offsets
+          @config.chords.each_with_index.map { |chord, i|
+            Writer::Chord.new(chord, string_table_offset: offsets[i]).to_binary
+          }.join
+        end
+
+        def string_table_binary
+          Writer::StringTable.new(build_string_table).to_binary
+        end
+
+        def build_string_table
+          entries = []
+          offset = 0
+          @config.chords.each do |chord|
+            next unless chord.string_keys
+            entries << StringTableEntry.new(keys: chord.string_keys, byte_offset: offset)
+            offset += (chord.string_keys.length + 1) * 4
+          end
+          V7::StringTable.new(entries)
+        end
+
+        def compute_string_offsets
+          table = build_string_table
+          @config.chords.map do |chord|
+            next unless chord.string_keys
+            table.entries.find { |e| e.keys == chord.string_keys }&.byte_offset
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Twiddling
+  module V7
+    module Writer
+      # Serializes a V7::Settings back to 32 bytes of binary data
+      # for the config header (offsets 0x40-0x5F).
+      class Settings
+        def initialize(settings)
+          @settings = settings
+        end
+
+        def to_binary
+          @settings.thumb_modifiers.pack("V4") +
+            @settings.dedicated_buttons.pack("C4") +
+            @settings.reserved
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module Twiddling
+  module V7
+    module Writer
+      # Serializes a V7::StringTable back to the binary format used
+      # at the end of a v7 config file.
+      #
+      # Each entry becomes a sequence of (modifier u16 LE, hid_code
+      # u16 LE) pairs followed by a null terminator (0x0000, 0x0000).
+      # Entries are concatenated in order - their byte offsets in the
+      # output match the offsets stored on each StringTableEntry.
+      class StringTable
+        def initialize(string_table)
+          @string_table = string_table
+        end
+
+        # Returns the binary string table as a packed byte string.
+        def to_binary
+          @string_table.entries
+            .flat_map { |entry| encode_entry(entry) }
+            .pack("v*")
+        end
+
+        private
+
+        # Encodes a single entry as a flat array of u16 values:
+        # [mod1, hid1, mod2, hid2, ..., 0, 0]
+        def encode_entry(entry)
+          encode_keys(entry.keys) + null_terminator
+        end
+
+        # Flattens key hashes into [modifier, hid_code, ...] pairs.
+        def encode_keys(keys)
+          keys.flat_map { |sk| [sk[:modifier], sk[:hid_code]] }
+        end
+
+        def null_terminator = [0, 0]
+      end
+    end
+  end
+end

data/lib/twiddling/v7.rb

@@ -0,0 +1,34 @@
+module Twiddling
+  module V7
+    module Reader
+    end
+
+    module Writer
+    end
+  end
+end
+
+require_relative "v7/string_table_entry"
+require_relative "v7/string_table"
+require_relative "v7/chord_constants"
+require_relative "v7/config_constants"
+require_relative "v7/chord"
+require_relative "v7/settings"
+require_relative "v7/validator"
+require_relative "v7/config"
+require_relative "v7/reader/string_table"
+require_relative "v7/reader/chord"
+require_relative "v7/reader/settings"
+require_relative "v7/reader/config"
+require_relative "v7/writer/string_table"
+require_relative "v7/writer/chord"
+require_relative "v7/writer/settings"
+require_relative "v7/writer/config"
+require_relative "v7/tw7/button_formatter"
+require_relative "v7/tw7/button_parser"
+require_relative "v7/tw7/effect_formatter"
+require_relative "v7/tw7/effect_parser"
+require_relative "v7/tw7/settings_formatter"
+require_relative "v7/tw7/settings_parser"
+require_relative "v7/tw7/printer"
+require_relative "v7/tw7/parser"

data/lib/twiddling/version.rb

@@ -0,0 +1,3 @@
+module Twiddling
+  VERSION = "0.1"
+end

data/lib/twiddling.rb

@@ -0,0 +1,8 @@
+require "bindata"
+
+module Twiddling
+  Error = Class.new(StandardError)
+end
+
+require_relative "twiddling/v7"
+require_relative "twiddling/cli"

data/twiddling.gemspec

@@ -0,0 +1,46 @@
+require_relative "lib/twiddling/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "twiddling"
+  spec.version = Twiddling::VERSION
+  spec.authors = ["Eric Mueller"]
+  spec.email = ["nevinera@gmail.com"]
+
+  spec.summary = "A cli tool for reading/writing/editing Twiddler v7 configuration files"
+  spec.description = <<~DESC
+    Edit twiddler4 (v7) configuration files as text, rather than using the clunky online tool.
+
+    Adding a full configuration by hand is _extremely_ tedious, and you shouldn't have to do i.
+  DESC
+  spec.homepage = "https://github.com/nevinera/twiddling"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.3.8")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.require_paths = ["lib"]
+  spec.bindir = "bin"
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`
+      .split("\x0")
+      .reject { |f| f.start_with?("spec") }
+  end
+  spec.executables = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z bin/`
+      .split("\x0")
+      .map { |path| path.sub(/^bin\//, "") }
+  end
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rspec-its", "~> 1.3"
+  spec.add_development_dependency "simplecov", "~> 0.22.0"
+  spec.add_development_dependency "pry", "~> 0.14"
+  spec.add_development_dependency "standard", ">= 1.35.1"
+  spec.add_development_dependency "rubocop", ">= 1.62"
+  spec.add_development_dependency "debug", "~> 1.7"
+  spec.add_development_dependency "mdl", "~> 0.12"
+  spec.add_development_dependency "quiet_quality", "~> 1.5"
+
+  spec.add_dependency "bindata", "~> 2.5"
+end