twiddling 0.1

data/fixtures/v7/haptic-feedback-off.tw7

@@ -0,0 +1,16 @@
+haptic: false
+=====
+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/idle-time-8m.tw7

@@ -0,0 +1,12 @@
+idle_time: 480
+=====
+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/key-repeat-1020.tw7

@@ -0,0 +1,12 @@
+key_repeat_delay: 102
+=====
+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/key-repeat-disabled.tw7

@@ -0,0 +1,12 @@
+key_repeat: false
+=====
+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/large.tw7

@@ -0,0 +1,142 @@
+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
+=====
+1R: backspace
+1M: space
+1L: tab
+2R: i
+1R 2R: 1
+1M 2R: c
+1L 2R: -
+2M: e
+1R 2M: 4
+1M 2M: d
+1L 2M: enter
+2L: o
+1R 2L: 7
+1M 2L: u
+1L 2L: .
+3R: n
+1R 3R: 2
+1M 3R: f
+1L 3R: /
+1R 2R 3R: 0
+1M 2R 3R: b
+1L 2R 3R: ~
+1R 2M 3R: [
+1L 2L 3R: @
+3M: t
+1R 3M: 5
+1M 3M: l
+1L 3M: !
+1R 2R 3M: +
+1R 2M 3M: (
+1M 2M 3M: p
+1L 2M 3M: :
+1L 2L 3M: ?
+3L: r
+1R 3L: 8
+1M 3L: w
+1L 3L: ,
+1R 2R 3L: -
+1R 2M 3L: {
+1R 2L 3L: ^
+1M 2L 3L: v
+1L 2L 3L: ;
+4R: a
+1R 4R: 3
+1M 4R: g
+1L 4R: \
+1R 2R 4R: =
+1R 2M 4R: ]
+1L 2L 4R: %
+1R 3R 4R: .
+1M 3R 4R: j
+1L 3R 4R: &
+1R 2R 3R 4R: enter
+1M 2R 3R 4R: z
+1L 2R 3R 4R: |
+1R 2M 3R 4R: <
+4M: h
+1R 4M: 6
+1M 4M: m
+1L 4M: *
+1R 2R 4M: *
+1R 2M 4M: )
+1L 2L 4M: $
+1R 3M 4M: ,
+1M 3M 4M: k
+1L 3M 4M: `
+1R 2M 3M 4M: $
+1M 2M 3M 4M: q
+1L 2M 3M 4M: =
+4L: s
+1R 4L: 9
+1M 4L: y
+1L 4L: '
+1R 2R 4L: /
+1R 2M 4L: }
+1L 2L 4L: "#"
+1R 3L 4L: ~
+1M 3L 4L: x
+1L 3L 4L: shift+'
+1R 2M 3L 4L: >
+1R 2L 3L 4L: %
+1M 2L 3L 4L: esc
+1L 2L 3L 4L: _
+
+T2::
+  2R: ctrl+d
+  1R 2R: cmd+c
+  2M: ctrl+c
+  1R 2M: cmd+v
+  2L: cmd+n
+  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/mini-buttons.tw7

@@ -0,0 +1,14 @@
+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/modifier-key.tw7

@@ -0,0 +1,12 @@
+1R: ctrl+c
+
+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/multi-char.tw7

@@ -0,0 +1,12 @@
+1R: "test"
+
+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/nav-invert-x-axis.tw7

@@ -0,0 +1,16 @@
+nav_invert_x: 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/nav-sensitivity-lowered.tw7

@@ -0,0 +1,12 @@
+nav_sensitivity: 0
+=====
+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/nav-up-east.tw7

@@ -0,0 +1,12 @@
+nav_direction: 1
+=====
+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/no-right-mouse-button.tw7

@@ -0,0 +1,12 @@
+f0l_dedicated: none
+=====
+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/no-t0-dedicated.tw7

@@ -0,0 +1,12 @@
+t0_dedicated: none
+=====
+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/shifted-key.tw7

@@ -0,0 +1,12 @@
+1R: @
+
+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/single-unmodified-key.tw7

@@ -0,0 +1,12 @@
+1R: c
+
+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/formats/tw7.md

@@ -0,0 +1,222 @@
+# Twiddler Configuration Text Format (.tw7)
+
+A human-readable text format for Twiddler 4 configurations. Can be
+converted to and from the binary `.cfg` format.
+
+## File structure
+
+A `.tw7` file has two sections separated by a divider line (five or more
+`=` characters). The first section contains settings, the second
+contains chords. If no divider is present, the entire file is chords.
+
+```text
+idle_time: 480
+key_repeat: false
+=====
+T4 F1M: f
+F1L: backspace
+```
+
+## Comments
+
+Lines starting with `#`, or inline `#` after content, are comments.
+Comments are not recognized inside double-quoted strings.
+
+```text
+# This is a comment
+F1L: backspace  # so is this
+F1R: "hello #world"  # the # inside quotes is literal
+```
+
+## Settings section
+
+Key-value pairs separated by a colon. Settings not specified use the
+defaults from an empty tuner config.
+
+### Available settings
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| idle_time | integer | 600 | Seconds until sleep |
+| key_repeat | boolean | true | Key repeat enabled |
+| key_repeat_delay | integer | 100 | Repeat threshold (10ms units) |
+| haptic | boolean | true | Haptic feedback enabled |
+| keyboard_mode | boolean | false | Button mode: keyboard |
+| nav_sensitivity | integer | 4 | Navigation sensitivity (0-31) |
+| nav_invert_x | boolean | false | Invert X axis |
+| nav_direction | integer | 0 | Nav-up direction (0=N, 1=E, ...) |
+
+### Thumb modifier assignments
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| t1_modifier | string | none | T1 modifier (see below) |
+| t2_modifier | string | l_option | T2 modifier |
+| t3_modifier | string | l_control | T3 modifier |
+| t4_modifier | string | l_shift | T4 modifier |
+
+Modifier values: none, l_control, l_shift, l_option, l_command.
+
+### Dedicated button functions
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| f0l_dedicated | string | mouse_right | F0L dedicated function |
+| f0m_dedicated | string | mouse_middle | F0M dedicated function |
+| f0r_dedicated | string | mouse_left | F0R dedicated function |
+| t0_dedicated | string | mouse_left | T0 dedicated function |
+
+Dedicated function values: none, mouse_left, mouse_right, mouse_middle.
+
+## Chords section
+
+Each chord maps a button combination to an effect (key, modifier+key,
+device function, or string).
+
+### Basic chords
+
+A chord is a button combination followed by a colon and an effect:
+
+```text
+F1R: c
+F1M: space
+T14 F4L: tab
+```
+
+### Button notation
+
+Buttons use T4 chord notation. The `T` or `F` prefix is optional for
+finger buttons - `4L` is equivalent to `F4L`. Button names are
+case-insensitive.
+
+| Type | Syntax | Examples |
+|------|--------|---------|
+| Thumb | T followed by digits | T1, T14, T234 |
+| Finger | F followed by row and columns | F1R, F2LR, F0M |
+| Finger (short) | Row and columns only | 1R, 2LR, 0M |
+
+Multiple buttons in a chord are space-separated:
+
+```text
+T4 F1M: up
+F1L F2L: 1
+```
+
+Buttons within the same row can be combined:
+
+```text
+F1LR: =     # F1L and F1R together
+```
+
+### Effects
+
+| Type | Syntax | Examples |
+|------|--------|---------|
+| Key | key name | c, space, enter, f1 |
+| Shifted | shifted symbol | @, !, # |
+| Modified | modifier+key | ctrl+c, cmd+shift+a |
+| String | double-quoted | "the ", "hello" |
+| Device function | function name | speed_cycle, left_click |
+
+#### Key names
+
+Letters (a-z), digits (0-9), and symbols (-, =, [, ], \, ;, ', `,
+comma, ., /). Special keys: enter, esc, backspace, tab, space, delete,
+insert, home, end, page_up, page_down, up, down, left, right,
+caps_lock, num_lock, f1-f12.
+
+Shifted symbols can be used directly: @, !, #, $, %, ^, &, *, (, ),
+\_, +, {, }, |, :, ", ~, <, >, ?.
+
+#### Modifiers
+
+ctrl, alt, cmd, shift - combined with `+`:
+
+```text
+F1R: ctrl+c
+F2L: cmd+shift+a
+```
+
+#### Device functions
+
+| Name            | Description          |
+|-----------------|----------------------|
+| mouse_toggle    | Toggle mouse mode    |
+| left_click      | Left mouse click     |
+| middle_click    | Middle mouse click   |
+| right_click     | Right mouse click    |
+| scroll_toggle   | Toggle scroll mode   |
+| speed_cycle     | Cycle mouse speed    |
+| speed_increase  | Increase mouse speed |
+| speed_decrease  | Decrease mouse speed |
+| print_stats     | Print device stats   |
+| config_cycle    | Cycle configuration  |
+
+#### Strings
+
+Double-quoted strings produce multi-character output. Characters inside
+are typed as a sequence of keypresses:
+
+```text
+F3L: "the "
+F3M: "ing "
+```
+
+Uppercase letters in strings are automatically shifted. The `#`
+character inside quotes is literal, not a comment.
+
+### Grouping
+
+A button combination followed by `::` (double colon) starts a group.
+Indented chords below it are unioned with the group's buttons:
+
+```text
+T1::
+  F1M: space
+  F2M: "hello"
+```
+
+This is equivalent to:
+
+```text
+T1 F1M: space
+T1 F2M: "hello"
+```
+
+Groups do not nest. A group ends when a non-indented line is
+encountered.
+
+### Grouping on output
+
+When converting a binary config to `.tw7`, chords are grouped by thumb
+button combination: first chords with no thumb buttons, then T1, T2,
+T3, T4, T12, T13, etc.
+
+## Example
+
+```text
+idle_time: 480
+haptic: false
+t1_modifier: l_command
+=====
+# Single-finger keys
+F1L: backspace
+F1M: space
+F1R: tab
+
+# Two-finger combinations
+F1L F2L: 1
+F1M F2L: c
+
+# Thumb-modified groups
+T1::
+  F1M: enter
+  F2M: "the "
+
+T4::
+  F1M: up
+  F1R: page_up
+
+# Device functions
+T14 F4L: speed_cycle
+```