mirrors/qmk_firmware
1
0
Fork 1
mirror of https://github.com/qmk/qmk_firmware synced 2024-11-16 08:56:11 +00:00
Code Issues Projects Releases Packages Wiki Activity
qmk_firmware/lib/python/qmk/keymap.py
Zach White 588bcdc8ca
Add support for tab completion (#12411) 
* Add support for tab completion

* make flake8 happy

* Add documentation
2021-04-14 19:00:22 -07:00

557 lines
18 KiB
Python
Raw Blame History

"""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
Reference in a new issue View git blame Copy permalink