Add key alias support (closes #12) #21

jackielii · 2025-11-18T20:24:15Z

Implements key aliases feature allowing users to define reusable names for modifiers, keys, and key combinations, making configs more readable and maintainable.

Features:

Three alias types: modifier, key, and keysym
Full recursive expansion at parse time (zero runtime overhead)
Circular reference detection with helpful error messages
Nested alias support (aliases can reference other aliases)
Compatible with existing syntax (modifiers combine like hyper/meh)

Syntax:
.alias $super cmd + alt # Modifier alias
.alias $grave 0x32 # Key alias
.alias $nav_left $super - h # Keysym alias

Usage:
$super - t : command # Use modifier alias
ctrl - $grave : command # Use key alias
$nav_left : command # Use keysym standalone
ctrl + $nav_left : command # Add modifiers to keysym

Implementation:

Tokenizer: Added Token_Alias for $identifier syntax
Parser: Added Alias union type with storage and resolution logic
Comprehensive error messages for type mismatches and undefined aliases
Full test coverage for all alias types and error cases
Documentation in SYNTAX.md and README.md with examples

Inspired by asmvik/skhd#288

Implements key aliases feature allowing users to define reusable names for modifiers, keys, and key combinations, making configs more readable and maintainable. Features: - Three alias types: modifier, key, and keysym - Full recursive expansion at parse time (zero runtime overhead) - Circular reference detection with helpful error messages - Nested alias support (aliases can reference other aliases) - Compatible with existing syntax (modifiers combine like hyper/meh) Syntax: .alias $super cmd + alt # Modifier alias .alias $grave 0x32 # Key alias .alias $nav_left $super - h # Keysym alias Usage: $super - t : command # Use modifier alias ctrl - $grave : command # Use key alias $nav_left : command # Use keysym standalone ctrl + $nav_left : command # Add modifiers to keysym Implementation: - Tokenizer: Added Token_Alias for $identifier syntax - Parser: Added Alias union type with storage and resolution logic - Comprehensive error messages for type mismatches and undefined aliases - Full test coverage for all alias types and error cases - Documentation in SYNTAX.md and README.md with examples Inspired by asmvik/skhd#288

jackielii · 2025-11-19T09:23:20Z

@copilot review

Copilot · 2025-11-19T09:23:29Z

@jackielii I've opened a new pull request, #22, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull Request Overview

This PR implements key aliases for skhd.zig, allowing users to define reusable names for modifiers, keys, and key combinations. The feature supports three alias types (modifier, key, keysym), recursive expansion with circular reference detection, and provides comprehensive error messages.

Key Changes:

Added Token_Alias to tokenizer for $identifier syntax recognition
Implemented Alias union type with resolution logic and type checking in parser
Added comprehensive test coverage for all alias types and error scenarios

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Tokenizer.zig	Added `Token_Alias` type and `$` character handling to recognize alias identifiers
src/Parser.zig	Implemented alias storage, resolution, type checking, and integration with hotkey parsing logic
src/tests.zig	Updated error message test to include "alias" as an expected token type
SYNTAX.md	Added comprehensive documentation section explaining alias types, syntax, usage contexts, and common errors
README.md	Added key aliases to feature list and included practical examples in window management section

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-19T09:29:33Z

README.md

+
+# Use keysym alias standalone or with additional modifiers
+$focus_west : @yabai_focus("west")
+ctrl + $focus_west : @yabai_focus("west")  # With extra modifier


These two examples (lines 400-401) demonstrate the same keybinding calling the same command, which doesn't effectively showcase the feature. Line 400 shows $focus_west (which expands to $super - h = cmd + alt - h) and line 401 shows ctrl + $focus_west (which adds ctrl to make ctrl + cmd + alt - h). However, both execute the identical command @yabai_focus("west"), making it unclear why you'd bind different key combinations to the same action. Consider either:

Using different commands (e.g., @yabai_focus("west") vs @yabai_focus_and_warp("west"))

Adding a comment explaining this is just demonstrating the syntax flexibility

Removing the duplicate binding as was done in the test on line 2594-2596

Suggested change

ctrl + $focus_west : @yabai_focus("west") # With extra modifier

ctrl + $focus_west : @yabai_focus("west") # Demonstrates that key aliases can be used with extra modifiers; both bindings perform the same action for syntax flexibility illustration

Copilot · 2025-11-19T09:29:33Z

src/Parser.zig

+    } else if (self.match(.Token_Alias)) {
+        // Nested alias
+        const token = self.previous();
+        var visited = std.ArrayList([]const u8).init(self.allocator);
+        defer visited.deinit();
+        const alias = try self.resolve_alias_internal(token.text, &visited);
+        // Return whatever type the nested alias is
+        return alias;


This code is unreachable. At line 1088, self.match(.Token_Alias) will consume any Token_Alias token, so this else if branch can never be reached. The nested alias case is already handled within the first if block (lines 1093-1110), but this unreachable code suggests there may have been an intention to handle standalone alias references differently. Consider removing this dead code or restructuring the logic if standalone alias handling was intended.

Suggested change

} else if (self.match(.Token_Alias)) {

// Nested alias

const token = self.previous();

var visited = std.ArrayList([]const u8).init(self.allocator);

defer visited.deinit();

const alias = try self.resolve_alias_internal(token.text, &visited);

// Return whatever type the nested alias is

return alias;

Copilot · 2025-11-19T09:29:34Z

src/Parser.zig

+            "Invalid alias definition. Expected one of:\n" ++
+            "  Modifier:  .alias $name cmd + alt + ctrl\n" ++
+            "  Keysym:    .alias $name cmd + shift - t\n" ++
+            "  Key combo: .alias $name shift - 1\n" ++


The distinction between "Keysym" (line 1192) and "Key combo" (line 1193) is unclear - both show the same pattern (modifier - key). Based on the code logic and the Alias union type (which has modifier, key, and keysym variants), consider either:

Renaming "Key combo" to "Key" and showing an example without modifiers like .alias $name 0x32 or .alias $name delete

Removing the redundant "Key combo" line entirely

This would make it clearer that there are three distinct types: modifiers (no dash), keys (no modifiers), and keysyms (modifiers + dash + key).

Suggested change

" Key combo: .alias $name shift - 1\n" ++

" Key: .alias $name delete\n" ++

Copilot · 2025-11-19T09:29:34Z

SYNTAX.md

+#### Circular References
+
+```bash
+.alias $a $b + shift                 # Error: $b not defined yet
+.alias $b $a + ctrl
+```


This example shows forward reference (using an undefined alias), not a circular reference. A true circular reference would be:

.alias $a $b + shift .alias $b $a + ctrl # Both depend on each other

However, this would also fail with "Undefined alias" since $b isn't defined when $a tries to use it. Consider either:

Showing a different example that better illustrates the concept (though true circularity may be hard to achieve in practice)

Renaming this section to "Forward References" or "Undefined Aliases" to match what the example actually demonstrates

Clarifying that circular reference detection exists but most circular cases manifest as undefined alias errors

jackielii

@copilot generally I think the PR should be restructured in terms of high level structure

jackielii · 2025-11-19T09:28:38Z

src/Parser.zig

-    if (found_modifier) {
+    // Handle modifier or alias at the start
+    var found_modifier = false;
+    var is_standalone_keysym = false;


@copilot is this the opposite of is_alias?

jackielii · 2025-11-19T09:29:21Z

src/Parser.zig

+        const next_is_activate = self.peek_check(.Token_Activate);
+
+        // If followed by : | [ ~ -> ; , it's a standalone keysym alias
+        if (next_is_command or next_is_forward or next_is_begin_list or next_is_unbound or next_is_arrow or next_is_activate or self.peek() == null) {


I feel like this check may not be exhaustive. Is there another way we can structure this?

jackielii · 2025-11-19T09:30:42Z

src/Parser.zig

+        // If followed by : | [ ~ -> ; , it's a standalone keysym alias
+        if (next_is_command or next_is_forward or next_is_begin_list or next_is_unbound or next_is_arrow or next_is_activate or self.peek() == null) {
+            // Standalone keysym alias: $terminal_key : command
+            var visited = std.ArrayList([]const u8).init(self.allocator);


what's the point of creating a list and deinit it within this block? if this is the only use case, why not do it within the resolve_keysym_alias_internal?

jackielii · 2025-11-19T09:32:17Z

src/Parser.zig

+            const keypress = try self.resolve_keysym_alias_internal(alias_token.text, &visited);
+            hotkey.flags = hotkey.flags.merge(keypress.flags);
+            hotkey.key = keypress.key;
+            is_standalone_keysym = true;


ok, so the logic is next_is_command or next_is_forward or next_is_begin_list or next_is_unbound or next_is_arrow or next_is_activate or self.peek() == null then is_standalone_keysym = true then we should just use is_alias = next_is_command or next_is_forward or next_is_begin_list or next_is_unbound or next_is_arrow or next_is_activate or self.peek() == null or a better logic with better forward compatibility

Copilot · 2025-11-19T09:49:56Z

@jackielii I've opened a new pull request, #23, to work on those changes. Once the pull request is ready, I'll request review from you.

claude and others added 2 commits November 18, 2025 11:07

resolve key alias

2567a8a

Copilot AI mentioned this pull request Nov 19, 2025

Code review completed - no changes needed #22

Closed

jackielii requested a review from Copilot November 19, 2025 09:23

Copilot started reviewing on behalf of jackielii November 19, 2025 09:24 View session

Copilot finished reviewing on behalf of jackielii November 19, 2025 09:28

Copilot AI reviewed Nov 19, 2025

View reviewed changes

jackielii commented Nov 19, 2025

View reviewed changes

Copilot AI mentioned this pull request Nov 19, 2025

Refactor alias handling: simplify detection logic and reduce allocations #23

Draft

	ctrl + $focus_west : @yabai_focus("west") # With extra modifier
	ctrl + $focus_west : @yabai_focus("west") # Demonstrates that key aliases can be used with extra modifiers; both bindings perform the same action for syntax flexibility illustration

	" Key combo: .alias $name shift - 1\n" ++
	" Key: .alias $name delete\n" ++

Add key alias support (closes #12) #21

Are you sure you want to change the base?

Add key alias support (closes #12) #21

Conversation

jackielii commented Nov 18, 2025

Uh oh!

jackielii commented Nov 19, 2025

Uh oh!

Copilot AI commented Nov 19, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

jackielii left a comment

Choose a reason for hiding this comment

Uh oh!

jackielii Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

jackielii Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

jackielii Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

jackielii Nov 19, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Nov 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants