twiddling 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 100f1bce7fb108f29712c2a203f41abf3073ff2c45d73bbee561d2127c9dc646
+  data.tar.gz: 8fc0d6aa7adca0c9e66c998044643b6ba91c81fceaffe6053afca1fa9bec4313
+SHA512:
+  metadata.gz: d6bc2545b64960e2604856d51ba4223230826309f466ffd4626a87f8ee3f3138bfbabcef5292747d11d7b07f0ad470565030c94feeec2969b6c8344935867837
+  data.tar.gz: 38c8a2390ff5ef6eb9c15071e10a8138f9f250ae160d6023c0fbead51e7c2f21320ae046265cb4fab6c6c091f245509eba7b4adf99be8c2e30d192d0d6764b91

data/.gitignore

@@ -0,0 +1,7 @@
+.ruby-version
+.ruby-gemset
+Gemfile.lock
+*.gem
+coverage/
+tmp/*
+.DS_Store

data/.mdl_rules.rb

@@ -0,0 +1,2 @@
+all
+rule "MD013", ignore_code_blocks: true

data/.mdlrc

@@ -0,0 +1,2 @@
+style File.expand_path("../.mdl_rules.rb", __FILE__)
+git_recurse true

data/.quiet_quality.yml

@@ -0,0 +1,9 @@
+---
+default_tools: ["standardrb", "rubocop", "markdown_lint"]
+executor: concurrent
+comparison_branch: main
+changed_files: false
+filter_messages: false
+logging: light
+colorize: true
+message_format: "%lcyan10tool| [%myellow40rule] %bred60loc  %e-90body"

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+---
+AllCops:
+  SuggestExtensions: false
+  DisabledByDefault: true
+
+Metrics/AbcSize:
+  Max: 15
+Metrics/CyclomaticComplexity:
+  Max: 8
+Metrics/PerceivedComplexity:
+  Max: 7
+
+Metrics/ClassLength:
+  CountComments: false
+  Max: 150
+Metrics/MethodLength:
+  CountComments: false
+  Max: 15
+Metrics/ParameterLists:
+  Max: 5
+  CountKeywordArgs: true

data/.standard.yml

@@ -0,0 +1,3 @@
+---
+format: progress
+ruby_version: 3.3

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Mueller
+
+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 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.

data/README.md

@@ -0,0 +1,116 @@
+# Twiddling
+
+CLI tools for managing Twiddler 4 (v7) configuration files as
+human-readable text instead of using the online tuner.
+
+## Installation
+
+```sh
+bundle install
+```
+
+Requires Ruby >= 3.3.8.
+
+## The .tw7 format
+
+Twiddling uses a text format (`.tw7`) for editing configs. It has an
+optional settings section and a chords section separated by `=====`.
+See [formats/tw7.md](formats/tw7.md) for a fuller specification.
+
+```text
+idle_time: 480
+haptic: false
+=====
+1R: backspace
+1M: space
+1L: tab
+
+T2::
+  2R: ctrl+d
+  2M: ctrl+c
+
+[MOUSEMODE]::
+  1R: left_click
+  1M: middle_click
+```
+
+## Commands
+
+### twiddling read
+
+Print a `.cfg` or `.tw7` file as text:
+
+```sh
+bin/twiddling read my_config.cfg
+bin/twiddling read layout.tw7
+```
+
+### twiddling convert
+
+Convert between `.cfg` and `.tw7` formats:
+
+```sh
+bin/twiddling convert my_config.cfg layout.tw7
+bin/twiddling convert layout.tw7 my_config.cfg
+```
+
+### twiddling search
+
+Search for chords by button combination or output:
+
+```sh
+bin/twiddling search my.cfg --chord "T4 1M"
+bin/twiddling search my.tw7 --result "@"
+bin/twiddling search my.cfg --button T4 --button 0M
+```
+
+All filters are combined as AND conditions.
+
+### twiddling diff
+
+Compare two configs, showing changed settings and chords:
+
+```sh
+bin/twiddling diff old.cfg new.cfg
+bin/twiddling diff base.tw7 mine.tw7 --no-color
+```
+
+Output is colorized by default (red=removed, yellow=changed,
+green=added).
+
+### Standalone conversion scripts
+
+These are really necessary (and I recommend `twiddling convert`
+most of the time). But simple coversion tools can be more convenient
+sometimes.
+
+```sh
+bin/cfg2tw7 input.cfg output.tw7
+bin/cfg2tw7 input.cfg              # prints to stdout
+bin/tw72cfg input.tw7 output.cfg
+```
+
+## Binary format
+
+Config files use a binary format documented in
+[formats/v7-cfg.md](formats/v7-cfg.md). Files should be named `1.cfg`,
+`2.cfg`, or `3.cfg` when placed on the device.
+
+Note that I have not fully explored the possible chords/settings; I assume
+there are some things that are no converted correctly or currently
+representable in the tw7 format. Feel free to submit PRs, or include a tuner-
+generated .cfg file with minimal chords in your Issue and explain what those
+chords actually do (I personally only use keys, modified keys, and short
+multi-character strings).
+
+## Config Collection
+
+There are a few full configurations in `configs/v7/`. Feel free to submit
+additional configs, either as PRs or issues; if you use it as your primary
+configuration (or if it's a community standard), I'm happy to include it!
+
+## Credits
+
+The v7 binary format was originally reverse-engineered by the
+[nchorder](https://github.com/GlassOnTin/nchorder) project, though
+we've departed from their interpretation pretty substantially.

data/bin/cfg2tw7

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/twiddling"
+
+input, output = ARGV
+abort "Usage: cfg2tw7 <input.cfg> [output.tw7]" unless input
+
+config = Twiddling::V7::Config.from_file(input)
+if output
+  File.open(output, "w") { |f| Twiddling::V7::Tw7::Printer.new(config, io: f).print }
+else
+  Twiddling::V7::Tw7::Printer.new(config).print
+end

data/bin/tw72cfg

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/twiddling"
+
+input, output = ARGV
+abort "Usage: tw72cfg <input.tw7> <output.cfg>" unless input && output
+
+config = Twiddling::V7::Tw7::Parser.new(File.read(input)).parse
+config.write(output)

data/bin/twiddling

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require_relative "../lib/twiddling"
+
+begin
+  Twiddling::Cli::Twiddling.new(argv: ARGV).run
+rescue Twiddling::Cli::ExitException => e
+  abort e.message
+end

data/configs/v7/default.tw7

@@ -0,0 +1,168 @@
+1R: a
+1M: e
+1L: space
+2R: b
+1R 2R: .
+1M 2R: r
+1L 2R: i
+2M: f
+1R 2M: '
+1M 2M: u
+1L 2M: l
+2L: delete
+1R 2L: /
+1M 2L: x
+1L 2L: o
+3R: c
+1R 3R: ,
+1M 3R: s
+1L 3R: j
+2R 3R: "the "
+1R 2R 3R: esc
+2M 3R: up
+2L 3R: 4
+3M: g
+1R 3M: '
+1M 3M: v
+1L 3M: m
+2R 3M: "of "
+2M 3M: left
+1M 2M 3M: /
+3L: backspace
+1R 3L: !
+1M 3L: y
+1L 3L: p
+2R 3L: 0
+2M 3L: down
+2L 3L: 9
+1L 2L 3L: \
+4R: d
+1R 4R: ;
+1M 4R: t
+1L 4R: k
+2R 4R: "to "
+2M 4R: "ed "
+3R 4R: page_up
+1R 3R 4R: "ant "
+2R 3R 4R: home
+1R 2R 3R 4R: caps_lock
+3M 4R: =
+3L 4R: @
+4M: h
+1R 4M: "and "
+1M 4M: w
+1L 4M: n
+2R 4M: "in"
+2M 4M: right
+1M 2M 4M: tab
+2L 4M: "ion "
+3R 4M: 5
+3M 4M: "ing "
+1M 3M 4M: "ent "
+1M 2M 3M 4M: num_lock
+3L 4M: 8
+4L: enter
+1R 4L: -
+1M 4L: z
+1L 4L: q
+2R 4L: -
+2M 4L: 3
+2L 4L: 7
+3R 4L: :
+3M 4L: =
+3L 4L: page_down
+2L 3L 4L: end
+
+T1::
+  1R: 1
+  1M: 5
+  1L: 9
+  2R: 2
+  2M: 6
+  1R 2M: [
+  1L 2M: ^
+  2L: 0
+  3R: 3
+  1R 3R: >
+  1L 2L 3R: |
+  3M: 7
+  1L 2L 3M: ~
+  1R 3L: `
+  4R: 4
+  1L 2L 4R: }
+  4M: 8
+  1R 4M: ]
+  4L: enter
+  1R 4L: {
+  1M 4L: <
+
+T3::
+  1R: ctrl+a
+  1M: ctrl+e
+  2R: ctrl+b
+  1M 2R: ctrl+r
+  1L 2R: ctrl+i
+  2M: ctrl+f
+  1M 2M: ctrl+u
+  1L 2M: ctrl+l
+  1M 2L: ctrl+x
+  1L 2L: ctrl+o
+  3R: ctrl+c
+  1M 3R: ctrl+s
+  1L 3R: ctrl+j
+  3M: ctrl+g
+  1M 3M: ctrl+v
+  1L 3M: ctrl+m
+  1L 2L 3M: insert
+  1M 3L: ctrl+y
+  1L 3L: ctrl+p
+  4R: ctrl+d
+  1M 4R: ctrl+t
+  1L 4R: ctrl+k
+  4M: ctrl+h
+  1M 4M: ctrl+w
+  1L 4M: ctrl+n
+  1M 4L: ctrl+z
+  1L 4L: ctrl+q
+
+T4::
+  1M 2M 4M: tab
+  4L: enter
+
+T12::
+  1R: f1
+  1M: f5
+  1L: f9
+  2R: f2
+  1L 2R: alt+f1
+  2M: f6
+  1L 2M: alt+f4
+  2L: f10
+  1L 2L: alt+f7
+  3R: f3
+  1L 3R: alt+f2
+  2L 3R: alt+f10
+  3M: f7
+  1L 3M: alt+f5
+  2L 3M: alt+f12
+  3L: f11
+  1L 3L: alt+f8
+  4R: f4
+  1L 4R: alt+f3
+  2L 4R: alt+f11
+  4M: f8
+  1L 4M: alt+f6
+  4L: f12
+  1L 4L: alt+f9
+  1L 2L 4L: 0x0047
+
+T14 4R: speed_cycle
+
+[MOUSEMODE]::
+  1R: left_click
+  1M: middle_click
+  1L: right_click
+  T23: mouse_toggle
+  4R: speed_decrease
+  4M: scroll_toggle
+  4L: speed_increase

data/configs/v7/ericspace2.tw7

@@ -0,0 +1,203 @@
+key_repeat: false
+haptic: false
+nav_direction: 1
+t1_modifier: l_command
+t2_modifier: none
+t3_modifier: l_shift
+t4_modifier: none
+f0l_dedicated: none
+f0m_dedicated: none
+f0r_dedicated: none
+t0_dedicated: none
+=====
+
+# The primary bindings here are based on the tabspace layout - see
+# https://rhodesmill.org/brandon/projects/tabspace-guide.pdf for
+# details. I have departed in several places, but the general idea
+# is to dedicate the 1-row to chord bases (index finger is most
+# capable of isolated control).
+
+1R: backspace
+1M: space
+1L: tab
+
+# -------- letters ------------------------------
+2R: i
+2M: e
+2L: o
+3R: n
+3M: t
+3L: r
+4R: a
+4M: h
+4L: s
+
+1M::
+  # -- Secondary letters (chorded on space/1M)
+  2R: c
+  2M: d
+  2L: u
+  3R: f
+  3M: l
+  3L: w
+  4R: g
+  4M: m
+  4L: y
+
+  # -- Tertiary letters (adjacent pairs chorded on space/1M)
+  2R 3R: b
+  2M 3M: p
+  3M 4M: k
+  2L 3L: v
+  3L 4L: x
+  3R 4R: j
+
+  # -- Rare letters (adjacent triples chorded on space/1M)
+  2R 3R 4R: z
+  2M 3M 4M: q
+  # Note that 1M 2L3L4L is in the next section (as ESC)
+
+# -------- whole hand chords --------------------
+1R 2R 3R 4R: enter
+1M 2L 3L 4L: esc
+
+# -------- numerics -----------------------------
+1R::
+  # numbers
+  2R: 1
+  3R: 2
+  4R: 3
+  2M: 4
+  3M: 5
+  4M: 6
+  2L: 7
+  3L: 8
+  4L: 9
+  2R 3R: 0  # (three adjacent)
+
+  3R 4R: .
+  3M 4M: ,
+  2L 3L: ^
+
+  3L 4L: ~
+  2L 3L 4L: %
+
+# -------- calculation glyphs ------------------------------
+1R2R:: 
+  # (3R is above - that's zero)
+  3M: +
+  3L: -
+  4R: =
+  4M: *
+  4L: /
+
+# I am less happy with the punctuation/symbol bindings.
+# There are _so many_ of them, and I don't have a good mental model for
+# how to organize them so that I can find what I need on the fly yet.
+# I write mostly ruby, so the easily reachable symbols are biased in
+# that direction.
+
+# -------- paired glyphs (mostly) ---------------------
+1R2M:: 
+  3R: [
+  4R: ]
+  3M: (
+  4M: )
+  3L: {
+  4L: }
+  3R 4R: <
+  3L 4L: >
+
+  3M 4M: $
+
+1L:: # -------- common punctuation ------------------------------
+  2L: .
+  3L: ,
+  4L: '
+
+  2M: enter
+  3M: !
+  4M: *
+
+  2R: -
+  3R: /
+  4R: \
+
+  # adjacent pairs
+  3R 4R: &
+  3M 4M: `
+  3L 4L: shift+' # (double-quote)
+
+1L2L::
+  3R: @
+  3M: ?     # way more common than I expected, this needs promoting to a 2-finger chord
+  3L: ;
+  4R: %
+  4M: $
+  4L: "#"
+  3L 4L: "_"
+
+1L2M::      # don't chord too much from here; 'enter' is a dangerous base in a terminal
+  3M: ":"
+  3M 4M: =
+
+1L2R::      # awkward reach
+  3R: ~
+  3R 4R: |
+
+# Thumb chords - these are entirely tentative, and I'm playing with other approaches.
+# Chords including them buttons are _awkward_, and usually require a hgrip shift,
+# so they aren't terribly useful.
+
+# Probably the answer is 'sticky' thumb buttons, but I need to see how often I get
+# confused about what buttons are _stuck_.
+
+T2::
+  2R: ctrl+d
+  2M: ctrl+c
+  2L: cmd+n
+
+  1R 2R: cmd+c
+  1R 2M: cmd+v
+  1R 2L: cmd+x
+
+  3R: cmd+l
+  3M: cmd+k
+  3L: cmd+f
+
+  4R: cmd+w
+  4M: cmd+t
+  4L: cmd+q
+
+T4::
+  1R: ctrl+y
+  1M: up
+  1L: page_up
+  2R: alt+f
+  2M: right
+  2L: end
+  3R: alt+b
+  2R 3R: ctrl+cmd+up
+  3M: left
+  3L: home
+  2L 3L: ctrl+cmd+enter
+  4R: ctrl+e
+  1R 4R: ctrl+cmd+left
+  4M: down
+  4L: page_down
+  1L 4L: ctrl+cmd+right
+  1L 2L 3L 4L: ctrl+cmd+enter
+  0L: ctrl+tab
+  0M: cmd+`
+  0R: cmd+tab
+
+T14 4R: speed_cycle
+
+[MOUSEMODE]::
+  1R: left_click
+  1M: middle_click
+  1L: right_click
+  T23: mouse_toggle
+  4R: speed_decrease
+  4M: scroll_toggle
+  4L: speed_increase

data/fixtures/v7/README.md

@@ -0,0 +1,31 @@
+# Fixtures
+
+- empty.cfg - config downloaded with only system chords and default settings
+- large.cfg - a full config with many chords.
+
+## Settings
+
+Each of these is a variation of empty.cfg with one setting changed.
+
+- no-right-mouse-button.cfg - 'dedicated button function' removed from
+  0L (previously was 'Mouse Button Right')
+- no-t0-dedicated.cfg - t0 no longer dedicated to mouse button left.
+- idle-time-8m.cfg - 'idle time until sleep' lowered from 10m to 8m
+- nav-invert-x-axis.cfg - 'Nav Invert X-Axis' enabled
+- nav-sensitivity-lowered.cfg - 'nav sensitivity' reduced all the way
+- button-mode-keyboard.cfg - button-mode set to "keyboard"
+- haptic-feedback-off.cfg - haptic feedback disabled
+- nav-up-east.cfg - nav-up set to east instead of north
+- key-repeat-disabled.cfg - key-repeat disabled
+- key-repeat-1020.cfg - key-repeat threshold changed from 1000 to 1020 ms
+
+## Buttons
+
+Each of these is empty.cfg with one extra chord added.
+
+- single-unmodified-key.cfg - F1R = "c"
+- shifted-key.cfg - F1R = "@"
+- modifier-key.cfg - F1R = "ctrl+c"
+- multi-char.cfg - F1R = "test" (a string)
+- cycle-config-chord.cfg - F1R = "Cycle config"
+- mini-buttons.cfg - 0L = "l", 0M = "m", and 0R = "r"

data/fixtures/v7/button-mode-keyboard.tw7

@@ -0,0 +1,16 @@
+keyboard_mode: true
+=====
+0L: l
+0M: m
+0R: r
+
+T14 4R: speed_cycle
+
+[MOUSEMODE]::
+  1R: left_click
+  1M: middle_click
+  1L: right_click
+  T23: mouse_toggle
+  4R: speed_decrease
+  4M: scroll_toggle
+  4L: speed_increase

data/fixtures/v7/cycle-config-chord.tw7

@@ -0,0 +1,12 @@
+1R: config_cycle
+
+T14 4R: speed_cycle
+
+[MOUSEMODE]::
+  1R: left_click
+  1M: middle_click
+  1L: right_click
+  T23: mouse_toggle
+  4R: speed_decrease
+  4M: scroll_toggle
+  4L: speed_increase

data/fixtures/v7/empty.tw7

@@ -0,0 +1,10 @@
+T14 4R: speed_cycle
+
+[MOUSEMODE]::
+  1R: left_click
+  1M: middle_click
+  1L: right_click
+  T23: mouse_toggle
+  4R: speed_decrease
+  4M: scroll_toggle
+  4L: speed_increase