Skip to content

Add #[doc(alias = ...)] attributes #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 21, 2025
Merged

Add #[doc(alias = ...)] attributes #73

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 34 additions & 10 deletions convert.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,49 +46,60 @@ def parse(text):

comment = re.sub(r"[ \t][ \t]+", "\n", typical_usage.decode_contents())

display.append([name, comment, deprecated, []])
display.append([name, comment, deprecated, [], []])
return display


def emit_enum_entries(display, file):
for [key, doc_comment, deprecated, alternatives] in display:
for [key, doc_comment, deprecated, alternatives, aliases] in display:
for line in doc_comment.split('\n'):
line = line.strip()
if len(line) == 0:
continue
print(f" /// {line}", file=file)
if deprecated:
print(" #[deprecated = \"marked as legacy in the spec, use Meta instead\"]", file=file)
for alias in aliases:
print(f" #[doc(alias = \"{alias}\")]", file=file)
print(f" {key},", file=file)


def print_display_entries(display, file):
for [key, doc_comment, deprecated, alternatives] in display:
for [key, doc_comment, deprecated, alternatives, aliases] in display:
print(" {0} => f.write_str(\"{0}\"),".format(
key), file=file)


def print_from_str_entries(display, file):
for [key, doc_comment, deprecated, alternatives] in display:
for [key, doc_comment, deprecated, alternatives, aliases] in display:
print(" \"{0}\"".format(key), file=file, end='')
for alternative in alternatives:
print(" | \"{0}\"".format(alternative), file=file, end='')
print(" => Ok({0}),".format(key), file=file)


def add_comment_to(display, key, comment):
for (i, [found_key, doc_comment, deprecated, alternatives]) in enumerate(display):
for (i, [found_key, doc_comment, deprecated, alternatives, aliases]) in enumerate(display):
if found_key != key:
continue
doc_comment = doc_comment + "\n" + comment
display[i] = [found_key, doc_comment, deprecated, alternatives]
display[i] = [found_key, doc_comment, deprecated, alternatives, aliases]


def add_alias_for(display, key, alias):
for [found_key, doc_comment, deprecated, alternatives, aliases] in display:
if found_key != key:
continue
aliases.append(alias)


def add_alternative_for(display, key, alternative):
for [found_key, doc_comment, deprecated, alternatives] in display:
for [found_key, doc_comment, deprecated, alternatives, aliases] in display:
if found_key != key:
continue
alternatives.append(alternative)
# Alternatives are also listed as aliases
aliases.append(alternative)


def convert_key(text, file):
Expand Down Expand Up @@ -118,11 +129,15 @@ def convert_key(text, file):
'F{}'.format(i),
'The F{0} key, a general purpose function key, as index {0}.'.format(i),
False,
[]
[],
[],
])

add_comment_to(display, 'Meta', 'In Linux (XKB) terminology, this is often referred to as "Super".')

add_alias_for(display, 'Meta', 'Super')
add_alias_for(display, 'Enter', 'Return')

emit_enum_entries(display, file)
print("}", file=file)

Expand Down Expand Up @@ -196,7 +211,8 @@ def convert_code(text, file):
'F{}'.format(i),
'<kbd>F{}</kbd>'.format(i),
False,
[]
[],
[],
])

chromium_key_codes = [
Expand Down Expand Up @@ -228,14 +244,22 @@ def convert_code(text, file):
chromium_only,
'Non-standard code value supported by Chromium.',
False,
[]
[],
[],
])

add_comment_to(display, 'Backquote', 'This is also called a backtick or grave.')
add_comment_to(display, 'Quote', 'This is also called an apostrophe.')
add_comment_to(display, 'MetaLeft', 'In Linux (XKB) terminology, this is often referred to as the left "Super".')
add_comment_to(display, 'MetaRight', 'In Linux (XKB) terminology, this is often referred to as the right "Super".')

add_alias_for(display, 'Backquote', 'Backtick')
add_alias_for(display, 'Backquote', 'Grave')
add_alias_for(display, 'Quote', 'Apostrophe')
add_alias_for(display, 'MetaLeft', 'SuperLeft')
add_alias_for(display, 'MetaRight', 'SuperRight')
add_alias_for(display, 'Enter', 'Return')

add_alternative_for(display, 'MetaLeft', 'OSLeft')
add_alternative_for(display, 'MetaRight', 'OSRight')
add_alternative_for(display, 'AudioVolumeDown', 'VolumeDown')
Expand Down
12 changes: 12 additions & 0 deletions src/code.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ use std::error::Error;
pub enum Code {
/// <kbd>`~</kbd> on a US keyboard. This is the <kbd>半角/全角/漢字</kbd> (<span class="unicode">hankaku/zenkaku/kanji</span>) key on Japanese keyboards
/// This is also called a backtick or grave.
#[doc(alias = "Backtick")]
#[doc(alias = "Grave")]
Backquote,
/// Used for both the US <kbd>\|</kbd> (on the 101-key layout) and also for the key
/// located between the <kbd>"</kbd> and <kbd>Enter</kbd> keys on row C of the 102-,
Expand Down Expand Up @@ -131,6 +133,7 @@ pub enum Code {
Period,
/// <kbd>'"</kbd> on a US keyboard.
/// This is also called an apostrophe.
#[doc(alias = "Apostrophe")]
Quote,
/// <kbd>;:</kbd> on a US keyboard.
Semicolon,
Expand All @@ -153,12 +156,17 @@ pub enum Code {
/// <kbd>Control</kbd> or <kbd>⌃</kbd>
ControlRight,
/// <kbd>Enter</kbd> or <kbd>↵</kbd>. Labelled <kbd>Return</kbd> on Apple keyboards.
#[doc(alias = "Return")]
Enter,
/// The Windows, <kbd>⌘</kbd>, <kbd>Command</kbd> or other OS symbol key.
/// In Linux (XKB) terminology, this is often referred to as the left "Super".
#[doc(alias = "SuperLeft")]
#[doc(alias = "OSLeft")]
MetaLeft,
/// The Windows, <kbd>⌘</kbd>, <kbd>Command</kbd> or other OS symbol key.
/// In Linux (XKB) terminology, this is often referred to as the right "Super".
#[doc(alias = "SuperRight")]
#[doc(alias = "OSRight")]
MetaRight,
/// <kbd>Shift</kbd> or <kbd>⇧</kbd>
ShiftLeft,
Expand Down Expand Up @@ -313,6 +321,7 @@ pub enum Code {
LaunchApp2,
LaunchMail,
MediaPlayPause,
#[doc(alias = "LaunchMediaPlayer")]
MediaSelect,
MediaStop,
MediaTrackNext,
Expand All @@ -321,8 +330,11 @@ pub enum Code {
/// replacing the <kbd>Eject</kbd> key.
Power,
Sleep,
#[doc(alias = "VolumeDown")]
AudioVolumeDown,
#[doc(alias = "VolumeMute")]
AudioVolumeMute,
#[doc(alias = "VolumeUp")]
AudioVolumeUp,
WakeUp,
#[deprecated = "marked as legacy in the spec, use Meta instead"]
Expand Down
2 changes: 2 additions & 0 deletions src/named_key.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ pub enum NamedKey {
/// The <kbd>Meta</kbd> key, to enable meta modifier function for interpreting concurrent or subsequent keyboard input.
/// This key value is used for the <q>Windows Logo</q> key and the Apple <kbd>Command</kbd> or <kbd>⌘</kbd> key.
/// In Linux (XKB) terminology, this is often referred to as "Super".
#[doc(alias = "Super")]
Meta,
/// The <kbd>NumLock</kbd> or Number Lock key, to toggle numpad mode function for interpreting subsequent keyboard input.
NumLock,
Expand All @@ -60,6 +61,7 @@ pub enum NamedKey {
#[deprecated = "marked as legacy in the spec, use Meta instead"]
Super,
/// The <kbd>Enter</kbd> or <kbd>↵</kbd> key, to activate current selection or accept current input.<br/> This key value is also used for the <kbd>Return</kbd> (Macintosh numpad) key.<br/> This key value is also used for the Android <code class="android">KEYCODE_DPAD_CENTER</code>.
#[doc(alias = "Return")]
Enter,
/// The Horizontal Tabulation <kbd>Tab</kbd> key.
Tab,
Expand Down