Raku Land

Karabiner::CompModGenerator

zef:sdondley

Actions Status

NAME

Karabiner::CompModGenerator - Generate complex modifcations for the Karabiner-Elements app on macOS

SYNOPSIS

From the command line:

kcmg ActivateApps.cfg

DESCRIPTION

This module generates json files containing "complex modification" rules for use with the the Karabiner-Elements app on macOS. The goal of the module is to make it easier to create and regenerate complex modification files and avoid the headache of editing json files directly.

The files containing the complex modifications are generated from templates, so the rules you can create are limited by the templates provided by the module, which currently include:

More templates will be added in the future. Feel welcome to contribute your own template modules to extend Karabiner::CompModGenerator's capabilities.

Follow the USAGE instructions below for more details.

INSTALLATION

Assuming Raku and zef is already installed, install the module with:

zef install Karabiner::CompModGenerator

Once you get the module installed follow the USAGE instructions to learn how to generate new rules for use with Karabiner-Elements.

If you don't have Raku with zef installed yet, it's easiest to install them both with homebrew if you already have brew installed:

brew install rakudo-star

If you don't have brew installed, install it with:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Note, however, that the homebrew install may be months out of date.

To ensure you get the absolute latest version of Raku, see this page for other installation options. Whatever method you choose to install Raku, just be sure the zef command gets installed and is working on your machine as well.

USAGE

The four steps to generating and using the complex modification files are:

  1. creating a configuration file; see [Configuration File](#Configuration File) for details

  2. running the kcmg command, followed by the path to your configuration file, to create the json file containing the complex modification rules

  3. copy the json file into Karabiner-Elements configuration directory on your drive

  4. open Karabiner-Elements and load the new rules

The json file created in step 2 above gets saved to the same directory you ran the command from. It has the same base file name as your configuration file but with a .json file extension. Place this file into your Karbiner-Elements configuration directory. By default, this directory is at ~/.config/Karabiner/assets/complex_modifications.

Now, with the new json file in place, open Karabiner-Elements and do the following:

  1. click the "Complex Modifications" tab

  2. click the "Add rule" button

  3. click "Enable" for all the rules or individual rules you wish to use

Configuration File

A configuration file is a text file that contains the comma separated values that get inserted into a template file. Each line in the file outputs a new "description" rule that ends up in json file that's output by the kcmg command. An associated template module, as determined by the name of the configuration file, contains the logic for processing the configuration file.

You can use any text editor to create the configuration files.

Naming Your Configuration File

A configuration file can have any file extention. However, the first part of your file name (aka the base name), must exactly match the name of an installed template module. For example, if you want your configuration file to use the Karabiner::Template::ActivateApps template, name your file something like ActivateApps.cfg or ActivateApps.txt.

Writing Your Configuration File

Here is a sample configuration file for use with the ActivateApps template:

# Filename: ActivateApps.cfg
# lines beginning with the '#' character get ignored
# The '*' indicates an optional field
# 1st app name, 2nd app name*, key, modifier*

Adobe Photoshop 2021, Preview, p, command
zoom.us, z, option

The first four lines beginning with the '#' sign are are comments and are ignored. The blank line is also skipped.

The next two lines tell the template module what data to insert into a pre-defined json template file to create the following three shortcuts:

Notice the second app name is optional. If only one app name is provided, only one shortcut (a double tap) will be generated. If two app names are provided, the first app is assigned to the double tap shortcut and the second app is assigned to the triple tap shortcut.

The "modifier" argument is also optional. If not provided, it defaults to the "command" key when using the ActivateApps template. You may use "option," "control," "shift," or "command" for the modifier key.

PRO TIP: The app name in the configuration file must exactly match the name of the offical app name as installed on your Mac. The official name often differ substantially than the app's common name. For example, the app name for "Zoom" is "zoom.us". To ensure you app name correct, use the Mac::Application::List module installed with this module to list out the apps installed on your machine. Alternatively, use the Karabiner-EventViewer application. The module will warn you if it does not recognize the name of an app in yur configuration file.

AUTHOR

Steve Dondley s@dondley.com

COPYRIGHT AND LICENSE

Copyright 2022 Steve Dondley

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.