mirror of
https://github.com/qmk/qmk_firmware.git
synced 2024-12-21 17:13:22 +00:00
558 lines
18 KiB
Python
558 lines
18 KiB
Python
"""Functions that help you work with QMK keymaps.
|
|
"""
|
|
import json
|
|
import subprocess
|
|
import sys
|
|
from pathlib import Path
|
|
|
|
import argcomplete
|
|
from milc import cli
|
|
from pygments.lexers.c_cpp import CLexer
|
|
from pygments.token import Token
|
|
from pygments import lex
|
|
|
|
import qmk.path
|
|
import qmk.commands
|
|
from qmk.keyboard import find_keyboard_from_dir, rules_mk
|
|
|
|
# The `keymap.c` template to use when a keyboard doesn't have its own
|
|
DEFAULT_KEYMAP_C = """#include QMK_KEYBOARD_H
|
|
|
|
/* THIS FILE WAS GENERATED!
|
|
*
|
|
* This file was generated by qmk json2c. You may or may not want to
|
|
* edit it directly.
|
|
*/
|
|
|
|
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
|
|
__KEYMAP_GOES_HERE__
|
|
};
|
|
"""
|
|
|
|
|
|
def template_json(keyboard):
|
|
"""Returns a `keymap.json` template for a keyboard.
|
|
|
|
If a template exists in `keyboards/<keyboard>/templates/keymap.json` that text will be used instead of an empty dictionary.
|
|
|
|
Args:
|
|
keyboard
|
|
The keyboard to return a template for.
|
|
"""
|
|
template_file = Path('keyboards/%s/templates/keymap.json' % keyboard)
|
|
template = {'keyboard': keyboard}
|
|
if template_file.exists():
|
|
template.update(json.load(template_file.open(encoding='utf-8')))
|
|
|
|
return template
|
|
|
|
|
|
def template_c(keyboard):
|
|
"""Returns a `keymap.c` template for a keyboard.
|
|
|
|
If a template exists in `keyboards/<keyboard>/templates/keymap.c` that text will be used instead of an empty dictionary.
|
|
|
|
Args:
|
|
keyboard
|
|
The keyboard to return a template for.
|
|
"""
|
|
template_file = Path('keyboards/%s/templates/keymap.c' % keyboard)
|
|
if template_file.exists():
|
|
template = template_file.read_text(encoding='utf-8')
|
|
else:
|
|
template = DEFAULT_KEYMAP_C
|
|
|
|
return template
|
|
|
|
|
|
def _strip_any(keycode):
|
|
"""Remove ANY() from a keycode.
|
|
"""
|
|
if keycode.startswith('ANY(') and keycode.endswith(')'):
|
|
keycode = keycode[4:-1]
|
|
|
|
return keycode
|
|
|
|
|
|
def find_keymap_from_dir():
|
|
"""Returns `(keymap_name, source)` for the directory we're currently in.
|
|
|
|
"""
|
|
relative_cwd = qmk.path.under_qmk_firmware()
|
|
|
|
if relative_cwd and len(relative_cwd.parts) > 1:
|
|
# If we're in `qmk_firmware/keyboards` and `keymaps` is in our path, try to find the keyboard name.
|
|
if relative_cwd.parts[0] == 'keyboards' and 'keymaps' in relative_cwd.parts:
|
|
current_path = Path('/'.join(relative_cwd.parts[1:])) # Strip 'keyboards' from the front
|
|
|
|
if 'keymaps' in current_path.parts and current_path.name != 'keymaps':
|
|
while current_path.parent.name != 'keymaps':
|
|
current_path = current_path.parent
|
|
|
|
return current_path.name, 'keymap_directory'
|
|
|
|
# If we're in `qmk_firmware/layouts` guess the name from the community keymap they're in
|
|
elif relative_cwd.parts[0] == 'layouts' and is_keymap_dir(relative_cwd):
|
|
return relative_cwd.name, 'layouts_directory'
|
|
|
|
# If we're in `qmk_firmware/users` guess the name from the userspace they're in
|
|
elif relative_cwd.parts[0] == 'users':
|
|
# Guess the keymap name based on which userspace they're in
|
|
return relative_cwd.parts[1], 'users_directory'
|
|
|
|
return None, None
|
|
|
|
|
|
def keymap_completer(prefix, action, parser, parsed_args):
|
|
"""Returns a list of keymaps for tab completion.
|
|
"""
|
|
try:
|
|
if parsed_args.keyboard:
|
|
return list_keymaps(parsed_args.keyboard)
|
|
|
|
keyboard = find_keyboard_from_dir()
|
|
|
|
if keyboard:
|
|
return list_keymaps(keyboard)
|
|
|
|
except Exception as e:
|
|
argcomplete.warn(f'Error: {e.__class__.__name__}: {str(e)}')
|
|
return []
|
|
|
|
return []
|
|
|
|
|
|
def is_keymap_dir(keymap, c=True, json=True, additional_files=None):
|
|
"""Return True if Path object `keymap` has a keymap file inside.
|
|
|
|
Args:
|
|
keymap
|
|
A Path() object for the keymap directory you want to check.
|
|
|
|
c
|
|
When true include `keymap.c` keymaps.
|
|
|
|
json
|
|
When true include `keymap.json` keymaps.
|
|
|
|
additional_files
|
|
A sequence of additional filenames to check against to determine if a directory is a keymap. All files must exist for a match to happen. For example, if you want to match a C keymap with both a `config.h` and `rules.mk` file: `is_keymap_dir(keymap_dir, json=False, additional_files=['config.h', 'rules.mk'])`
|
|
"""
|
|
files = []
|
|
|
|
if c:
|
|
files.append('keymap.c')
|
|
|
|
if json:
|
|
files.append('keymap.json')
|
|
|
|
for file in files:
|
|
if (keymap / file).is_file():
|
|
if additional_files:
|
|
for file in additional_files:
|
|
if not (keymap / file).is_file():
|
|
return False
|
|
|
|
return True
|
|
|
|
|
|
def generate_json(keymap, keyboard, layout, layers):
|
|
"""Returns a `keymap.json` for the specified keyboard, layout, and layers.
|
|
|
|
Args:
|
|
keymap
|
|
A name for this keymap.
|
|
|
|
keyboard
|
|
The name of the keyboard.
|
|
|
|
layout
|
|
The LAYOUT macro this keymap uses.
|
|
|
|
layers
|
|
An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
|
|
"""
|
|
new_keymap = template_json(keyboard)
|
|
new_keymap['keymap'] = keymap
|
|
new_keymap['layout'] = layout
|
|
new_keymap['layers'] = layers
|
|
|
|
return new_keymap
|
|
|
|
|
|
def generate_c(keyboard, layout, layers):
|
|
"""Returns a `keymap.c` or `keymap.json` for the specified keyboard, layout, and layers.
|
|
|
|
Args:
|
|
keyboard
|
|
The name of the keyboard
|
|
|
|
layout
|
|
The LAYOUT macro this keymap uses.
|
|
|
|
layers
|
|
An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
|
|
"""
|
|
new_keymap = template_c(keyboard)
|
|
layer_txt = []
|
|
for layer_num, layer in enumerate(layers):
|
|
if layer_num != 0:
|
|
layer_txt[-1] = layer_txt[-1] + ','
|
|
layer = map(_strip_any, layer)
|
|
layer_keys = ', '.join(layer)
|
|
layer_txt.append('\t[%s] = %s(%s)' % (layer_num, layout, layer_keys))
|
|
|
|
keymap = '\n'.join(layer_txt)
|
|
new_keymap = new_keymap.replace('__KEYMAP_GOES_HERE__', keymap)
|
|
|
|
return new_keymap
|
|
|
|
|
|
def write_file(keymap_filename, keymap_content):
|
|
keymap_filename.parent.mkdir(parents=True, exist_ok=True)
|
|
keymap_filename.write_text(keymap_content)
|
|
|
|
cli.log.info('Wrote keymap to {fg_cyan}%s', keymap_filename)
|
|
|
|
return keymap_filename
|
|
|
|
|
|
def write_json(keyboard, keymap, layout, layers):
|
|
"""Generate the `keymap.json` and write it to disk.
|
|
|
|
Returns the filename written to.
|
|
|
|
Args:
|
|
keyboard
|
|
The name of the keyboard
|
|
|
|
keymap
|
|
The name of the keymap
|
|
|
|
layout
|
|
The LAYOUT macro this keymap uses.
|
|
|
|
layers
|
|
An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
|
|
"""
|
|
keymap_json = generate_json(keyboard, keymap, layout, layers)
|
|
keymap_content = json.dumps(keymap_json)
|
|
keymap_file = qmk.path.keymap(keyboard) / keymap / 'keymap.json'
|
|
|
|
return write_file(keymap_file, keymap_content)
|
|
|
|
|
|
def write(keyboard, keymap, layout, layers):
|
|
"""Generate the `keymap.c` and write it to disk.
|
|
|
|
Returns the filename written to.
|
|
|
|
Args:
|
|
keyboard
|
|
The name of the keyboard
|
|
|
|
keymap
|
|
The name of the keymap
|
|
|
|
layout
|
|
The LAYOUT macro this keymap uses.
|
|
|
|
layers
|
|
An array of arrays describing the keymap. Each item in the inner array should be a string that is a valid QMK keycode.
|
|
"""
|
|
keymap_content = generate_c(keyboard, layout, layers)
|
|
keymap_file = qmk.path.keymap(keyboard) / keymap / 'keymap.c'
|
|
|
|
return write_file(keymap_file, keymap_content)
|
|
|
|
|
|
def locate_keymap(keyboard, keymap):
|
|
"""Returns the path to a keymap for a specific keyboard.
|
|
"""
|
|
if not qmk.path.is_keyboard(keyboard):
|
|
raise KeyError('Invalid keyboard: ' + repr(keyboard))
|
|
|
|
# Check the keyboard folder first, last match wins
|
|
checked_dirs = ''
|
|
keymap_path = ''
|
|
|
|
for dir in keyboard.split('/'):
|
|
if checked_dirs:
|
|
checked_dirs = '/'.join((checked_dirs, dir))
|
|
else:
|
|
checked_dirs = dir
|
|
|
|
keymap_dir = Path('keyboards') / checked_dirs / 'keymaps'
|
|
|
|
if (keymap_dir / keymap / 'keymap.c').exists():
|
|
keymap_path = keymap_dir / keymap / 'keymap.c'
|
|
if (keymap_dir / keymap / 'keymap.json').exists():
|
|
keymap_path = keymap_dir / keymap / 'keymap.json'
|
|
|
|
if keymap_path:
|
|
return keymap_path
|
|
|
|
# Check community layouts as a fallback
|
|
rules = rules_mk(keyboard)
|
|
|
|
if "LAYOUTS" in rules:
|
|
for layout in rules["LAYOUTS"].split():
|
|
community_layout = Path('layouts/community') / layout / keymap
|
|
if community_layout.exists():
|
|
if (community_layout / 'keymap.json').exists():
|
|
return community_layout / 'keymap.json'
|
|
if (community_layout / 'keymap.c').exists():
|
|
return community_layout / 'keymap.c'
|
|
|
|
|
|
def list_keymaps(keyboard, c=True, json=True, additional_files=None, fullpath=False):
|
|
"""List the available keymaps for a keyboard.
|
|
|
|
Args:
|
|
keyboard
|
|
The keyboards full name with vendor and revision if necessary, example: clueboard/66/rev3
|
|
|
|
c
|
|
When true include `keymap.c` keymaps.
|
|
|
|
json
|
|
When true include `keymap.json` keymaps.
|
|
|
|
additional_files
|
|
A sequence of additional filenames to check against to determine if a directory is a keymap. All files must exist for a match to happen. For example, if you want to match a C keymap with both a `config.h` and `rules.mk` file: `is_keymap_dir(keymap_dir, json=False, additional_files=['config.h', 'rules.mk'])`
|
|
|
|
fullpath
|
|
When set to True the full path of the keymap relative to the `qmk_firmware` root will be provided.
|
|
|
|
Returns:
|
|
a sorted list of valid keymap names.
|
|
"""
|
|
# parse all the rules.mk files for the keyboard
|
|
rules = rules_mk(keyboard)
|
|
names = set()
|
|
|
|
if rules:
|
|
keyboards_dir = Path('keyboards')
|
|
kb_path = keyboards_dir / keyboard
|
|
|
|
# walk up the directory tree until keyboards_dir
|
|
# and collect all directories' name with keymap.c file in it
|
|
while kb_path != keyboards_dir:
|
|
keymaps_dir = kb_path / "keymaps"
|
|
|
|
if keymaps_dir.is_dir():
|
|
for keymap in keymaps_dir.iterdir():
|
|
if is_keymap_dir(keymap, c, json, additional_files):
|
|
keymap = keymap if fullpath else keymap.name
|
|
names.add(keymap)
|
|
|
|
kb_path = kb_path.parent
|
|
|
|
# if community layouts are supported, get them
|
|
if "LAYOUTS" in rules:
|
|
for layout in rules["LAYOUTS"].split():
|
|
cl_path = Path('layouts/community') / layout
|
|
if cl_path.is_dir():
|
|
for keymap in cl_path.iterdir():
|
|
if is_keymap_dir(keymap, c, json, additional_files):
|
|
keymap = keymap if fullpath else keymap.name
|
|
names.add(keymap)
|
|
|
|
return sorted(names)
|
|
|
|
|
|
def _c_preprocess(path, stdin=None):
|
|
""" Run a file through the C pre-processor
|
|
|
|
Args:
|
|
path: path of the keymap.c file (set None to use stdin)
|
|
stdin: stdin pipe (e.g. sys.stdin)
|
|
|
|
Returns:
|
|
the stdout of the pre-processor
|
|
"""
|
|
pre_processed_keymap = qmk.commands.run(['cpp', path] if path else ['cpp'], stdin=stdin, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=True)
|
|
return pre_processed_keymap.stdout
|
|
|
|
|
|
def _get_layers(keymap): # noqa C901 : until someone has a good idea how to simplify/split up this code
|
|
""" Find the layers in a keymap.c file.
|
|
|
|
Args:
|
|
keymap: the content of the keymap.c file
|
|
|
|
Returns:
|
|
a dictionary containing the parsed keymap
|
|
"""
|
|
layers = list()
|
|
opening_braces = '({['
|
|
closing_braces = ')}]'
|
|
keymap_certainty = brace_depth = 0
|
|
is_keymap = is_layer = is_adv_kc = False
|
|
layer = dict(name=False, layout=False, keycodes=list())
|
|
for line in lex(keymap, CLexer()):
|
|
if line[0] is Token.Name:
|
|
if is_keymap:
|
|
# If we are inside the keymap array
|
|
# we know the keymap's name and the layout macro will come,
|
|
# followed by the keycodes
|
|
if not layer['name']:
|
|
if line[1].startswith('LAYOUT') or line[1].startswith('KEYMAP'):
|
|
# This can happen if the keymap array only has one layer,
|
|
# for macropads and such
|
|
layer['name'] = '0'
|
|
layer['layout'] = line[1]
|
|
else:
|
|
layer['name'] = line[1]
|
|
elif not layer['layout']:
|
|
layer['layout'] = line[1]
|
|
elif is_layer:
|
|
# If we are inside a layout macro,
|
|
# collect all keycodes
|
|
if line[1] == '_______':
|
|
kc = 'KC_TRNS'
|
|
elif line[1] == 'XXXXXXX':
|
|
kc = 'KC_NO'
|
|
else:
|
|
kc = line[1]
|
|
if is_adv_kc:
|
|
# If we are inside an advanced keycode
|
|
# collect everything and hope the user
|
|
# knew what he/she was doing
|
|
layer['keycodes'][-1] += kc
|
|
else:
|
|
layer['keycodes'].append(kc)
|
|
|
|
# The keymaps array's signature:
|
|
# const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]
|
|
#
|
|
# Only if we've found all 6 keywords in this specific order
|
|
# can we know for sure that we are inside the keymaps array
|
|
elif line[1] == 'PROGMEM' and keymap_certainty == 2:
|
|
keymap_certainty = 3
|
|
elif line[1] == 'keymaps' and keymap_certainty == 3:
|
|
keymap_certainty = 4
|
|
elif line[1] == 'MATRIX_ROWS' and keymap_certainty == 4:
|
|
keymap_certainty = 5
|
|
elif line[1] == 'MATRIX_COLS' and keymap_certainty == 5:
|
|
keymap_certainty = 6
|
|
elif line[0] is Token.Keyword:
|
|
if line[1] == 'const' and keymap_certainty == 0:
|
|
keymap_certainty = 1
|
|
elif line[0] is Token.Keyword.Type:
|
|
if line[1] == 'uint16_t' and keymap_certainty == 1:
|
|
keymap_certainty = 2
|
|
elif line[0] is Token.Punctuation:
|
|
if line[1] in opening_braces:
|
|
brace_depth += 1
|
|
if is_keymap:
|
|
if is_layer:
|
|
# We found the beginning of a non-basic keycode
|
|
is_adv_kc = True
|
|
layer['keycodes'][-1] += line[1]
|
|
elif line[1] == '(' and brace_depth == 2:
|
|
# We found the beginning of a layer
|
|
is_layer = True
|
|
elif line[1] == '{' and keymap_certainty == 6:
|
|
# We found the beginning of the keymaps array
|
|
is_keymap = True
|
|
elif line[1] in closing_braces:
|
|
brace_depth -= 1
|
|
if is_keymap:
|
|
if is_adv_kc:
|
|
layer['keycodes'][-1] += line[1]
|
|
if brace_depth == 2:
|
|
# We found the end of a non-basic keycode
|
|
is_adv_kc = False
|
|
elif line[1] == ')' and brace_depth == 1:
|
|
# We found the end of a layer
|
|
is_layer = False
|
|
layers.append(layer)
|
|
layer = dict(name=False, layout=False, keycodes=list())
|
|
elif line[1] == '}' and brace_depth == 0:
|
|
# We found the end of the keymaps array
|
|
is_keymap = False
|
|
keymap_certainty = 0
|
|
elif is_adv_kc:
|
|
# Advanced keycodes can contain other punctuation
|
|
# e.g.: MT(MOD_LCTL | MOD_LSFT, KC_ESC)
|
|
layer['keycodes'][-1] += line[1]
|
|
|
|
elif line[0] is Token.Literal.Number.Integer and is_keymap and not is_adv_kc:
|
|
# If the pre-processor finds the 'meaning' of the layer names,
|
|
# they will be numbers
|
|
if not layer['name']:
|
|
layer['name'] = line[1]
|
|
|
|
else:
|
|
# We only care about
|
|
# operators and such if we
|
|
# are inside an advanced keycode
|
|
# e.g.: MT(MOD_LCTL | MOD_LSFT, KC_ESC)
|
|
if is_adv_kc:
|
|
layer['keycodes'][-1] += line[1]
|
|
|
|
return layers
|
|
|
|
|
|
def parse_keymap_c(keymap_file, use_cpp=True):
|
|
""" Parse a keymap.c file.
|
|
|
|
Currently only cares about the keymaps array.
|
|
|
|
Args:
|
|
keymap_file: path of the keymap.c file (or '-' to use stdin)
|
|
|
|
use_cpp: if True, pre-process the file with the C pre-processor
|
|
|
|
Returns:
|
|
a dictionary containing the parsed keymap
|
|
"""
|
|
if keymap_file == '-':
|
|
if use_cpp:
|
|
keymap_file = _c_preprocess(None, sys.stdin)
|
|
else:
|
|
keymap_file = sys.stdin.read()
|
|
else:
|
|
if use_cpp:
|
|
keymap_file = _c_preprocess(keymap_file)
|
|
else:
|
|
keymap_file = keymap_file.read_text(encoding='utf-8')
|
|
|
|
keymap = dict()
|
|
keymap['layers'] = _get_layers(keymap_file)
|
|
return keymap
|
|
|
|
|
|
def c2json(keyboard, keymap, keymap_file, use_cpp=True):
|
|
""" Convert keymap.c to keymap.json
|
|
|
|
Args:
|
|
keyboard: The name of the keyboard
|
|
|
|
keymap: The name of the keymap
|
|
|
|
layout: The LAYOUT macro this keymap uses.
|
|
|
|
keymap_file: path of the keymap.c file
|
|
|
|
use_cpp: if True, pre-process the file with the C pre-processor
|
|
|
|
Returns:
|
|
a dictionary in keymap.json format
|
|
"""
|
|
keymap_json = parse_keymap_c(keymap_file, use_cpp)
|
|
|
|
dirty_layers = keymap_json.pop('layers', None)
|
|
keymap_json['layers'] = list()
|
|
for layer in dirty_layers:
|
|
layer.pop('name')
|
|
layout = layer.pop('layout')
|
|
if not keymap_json.get('layout', False):
|
|
keymap_json['layout'] = layout
|
|
keymap_json['layers'].append(layer.pop('keycodes'))
|
|
|
|
keymap_json['keyboard'] = keyboard
|
|
keymap_json['keymap'] = keymap
|
|
return keymap_json
|