JSON::Karabiner - easy JSON code generation for Karabiner-Elements
Below is an example of an executable perl script for generating a json file for use by Karbiner-Elements. You can copy and paste this code to your local machine and execute it. Feel free to modify it to your liking. Note that you must first install the JSON::Karabiner package (see the "INSTALLATION" section below).
JSON::Karabiner
Hopefully it is simple enough to understand even if you have no experience with programming in Perl. Read through the code below and see if you can determine what it will do. Don't hesitate to file an issue if you need asssistance.
#!/usr/bin/env perl # shebang line so this program is opened with perl interpreter use JSON::Karabiner; # The JSON::Karabiner Perl package must be installed on your machine use strict; # always set these in perl for your use warnings; # own sanity # Create an object by passing it a title and the name of the file you will write to: my $kb_obj = JSON::Karabiner->new('Typing assists', 'my_awesome_karbiner_mod.json'); # Now add a rule and give it a description: my $rule = $kb_obj->add_rule('a-s-d to show character viewer'); # Add a manipulator to the rule: my $manip_1 = $rule->add_manipulator; # Add a "from" and "to" action to the manipulator my $from = $manip_1->add_action('from'); my $to = $manip_1->add_action('to'); # Tell the "from" action what to do $from->add_simultaneous('a', 's', 'd'); $from->add_optional_modifiers('any'); # Tell the "to" action what to do $to->add_key_code('spacebar'); $to->add_modifiers('control', 'command'); # Done! Now it's time to write the file: $kb_obj->write_file;
Save this above code to a file on your computer and be sure to make the script executable with:
chmod 744 your_file_name.pl
Then execute this script with:
./your_file_name.pl
from the same directory where this script is saved.
After this script is run, a json file called my_awesome_karbiner_mod.json should now be sitting in the assets/complex_modifications directory. Open the Karabiner-Elements app on your Mac to install the new rules.
Ready to give is try? Follow the "INSTALLATION" instructions to get started.
Karabiner stores rules for its modifications in a file using a data format known as JSON which is painstaking to edit and create. JSON::Karbiner eases the pain by letting Perl write the JSON for you. If you aren't familar with Perl, or programming at all, don't worry. There are examples provided that you can follow so no programming knowledge should be necessary. The 10 or 20 minutes you spend learning how to install and use this module will pay off in spades.
A Karbiner JSON complex modification file stores the rules for modifying the keyboard in a data structure called the "manipulators." Therefore, most of Perl code you write adds data to the manipulator data structure. JSON::Karabiner can then write the JSON to a file and then you can load the rules you've written using the Kabrabiner-Elements program.
Below are descriptions of the methods you use to generate the json file. There are three important methods to know:
add_action
for adding the from/to actions to the Karbiner manipulator data structure
add_condition
for adding condtions to the manipulator structure
add_parameters
for adding parameters to the manipulator data structure
It will be very helpful if you have a basic familiarity with the Karbiner manipulator definition. See the Karabiner complex_modification manipulator documentation for more information.
The documentation below is not exhaustive. You'll also need to consult the documentation at:
These pages document the methods for actions and conditions.
But the best way to learn, of course, is to experiment and see what happens.
Below are the methods for the Karabiner, Rule, and Manipulator classes. The classes are used to create objects that you then run methods on.
First, you create your Karabiner object, then add a rule object to it, and then you add one or more manipulators to the rule. Then you add your actions, conditions and paramaters to manipulators.
Together, these methods create one large data structure that gets written to the json file. A good way to get a feel for how this works is to write just a little bit of Perl code, write it to a file, and then look at the file. Then add a little bit more Perl code, run the script again, and see what happens. You can also use the undocumented _dump_json method on the Karbiner object to spit out it's current state: $kb_obj-<E<t>_dump_json.
_dump_json
$kb_obj-<E<t>_dump_json
my $kb_obj = JSON::Karbiner->new('title', 'file.json');
The new method creates the Karbiner object that holds the entire data structure. This should be the first command you issue in your scipt.
The $title and $file arguments are required. An optional third argument, set inside curly braces, can be passed to change the default Karbiner directory which is set to:
~/.config/karabiner/assets/complex_modifications/
You must pass this third argument inside the curly brackes as shown in this example:
my $kb_obj = JSON::Karbiner->new('title', 'file.json', { mod_file_dir => '/path/to/dir' } ));
If you are using a non-standard location for your Karbiner install, you must change this directory to where Karbiner stores its modifications on your local machine by setting mod_file_dir option to the correct path on your drive.
mod_file_dir
This will generally be the last command in your script:
$kb_obj->write_file();
Once the file is written, you should be able to add the rules from your script using the Karbiner-Elements program. If it does not appear there, first check to make sure the file is saving to the right directory. If it still doesn't work, please open an issue on GitHub and post your perl script as it may be a bug.
Every Karabiner json file has a rules data structure which contains all the modifications. Add it to your object like so:
my $rule = $kb_obj->add_rule('My Cool Rule Title');
Set the title of the rule by passing it a string set in quotes.
A manipulator must be added to the Rule object to do anything useful:
my $manip = $rule->add_manipulator
Once done, you can add actions, conditions, and parameters to your manipulator. See below for more information.
There are seven different types of actions you can add:
my $from = $manip->add_action('from'); my $to = $manip->add_action('to'); my $to_alone = $manip->add_action('to_if_alone'); my $to_down = $manip->add_action('to_if_held_down'); my $to_up = $manip->add_action('to_after_key_up'); my $to_invoked = $manip->add_action('to_delayed_if_invoked'); my $to_canceled = $manip->add_action('to_delayed_if_canceled');
The major ones are the first four listed above. You must create a from action to your manipulator. This the actions that contains the keystrokes you want to change. The other to actions describe what the from keystroke actions will be changed into. See the Karbiner documentation for more information on these actions.
from
to
Once these actions are created, you may apply methods to them to add additional data. Consult the documentation for the different actions for a listing and description of those methods:
Conditions make the modification conditional upon some other bit of data. You can add the following types of conditions:
$manip->add_condition('device_if'); $mainp->add_condition('device_unless') $manip->add_condition('event_changed_if') $manip->add_condition('frontmost_application_if') $manip->add_condition('frontmost_application_unless') $manip->add_condition('input_source_if') $manip->add_condition('input_source_unless') $manip->add_condition('keyboard_type_if') $manip->add_condition('variable_if') $manip->add_condition('variable_unless')
Consult the Karabiner documenation for more information on conditions. Once the conditions are created, you can add data to them using methods. See the documenation for each of the type of conditions and the types of methods they use:
JSON::Karabiner::Manipulator::Conditions
Parameters are used by Karabiner to change various timing aspects of the actions. Four different parameters may be set:
$manip->add_parameter('to_if_alone_timeout_milliseconds', 500); $manip->add_parameter('to_if_held_down_threshold_milliseconds, 500); $manip->add_parameter('to_delayed_action_delay_milliseconds, 250); $manip->add_parameter('simultaneous_threshold_milliseconds, 50);
See the Karabiner documentation for more details.
Adds a description to the manipulator data structure:
$manip->add_description('This turns a period into a hyper key.');
This software is written in Perl and bundled as a package called JSON::Karabiner. If you are not familiar with installing Perl packages, don't worry. Just follow this simple two-step process:
cpanm
Run the following command from a terminal window:
C<which cpanm>
If the terminal reponds with the path to cpanm, proceed to Step 2.
If the cpanm command is not installed, copy and paste one of the following three commands into your terminal window to install it:
# Option 1: Install to system Perl curl -L https://cpanmin.us | perl - --sudo App::cpanminus # Option 2: Install to local Perl (you must have a local version of Perl already installed) curl -L https://cpanmin.us | perl - App::cpanminus # Option 3: Install as standalone executable cd ~/bin && curl -L https://cpanmin.us/ -o cpanm && chmod +x cpanm
If you are unsure what the best option is for installing cpanm, consult its documentation for more help..
Now issue the following comamdn to install the software:
cpanm JSON::Karabiner
After issuing the cpanm command above, you should see a success message. If so, you can start using cpanm JSON::Karabiner and start using it in local Perl scripts you write. If you get errors about lack of permissions, try running:
sudo cpanm JSON::Karabiner
If you still get weird errors, it may be a bug. Please report your issue to the issue queue.
This module can also be installed using the older cpan command that is already on your Mac. See how to install CPAN modules for more information.
cpan
version 0.009
This module is currently in the early alpha stages and is actively supported and maintained. Suggestion for improvement are welcome. It is known to generate valid JSON that allow Karabiner to import rules from the file generated for simple cases.
Many improvements are in the works.
You can find documentation for this module with the perldoc command.
perldoc JSON::Karabiner
The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.
MetaCPAN
A modern, open-source CPAN search engine, useful to view POD in HTML format.
https://metacpan.org/release/JSON-Karabiner
The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)
https://github.com/sdondley/JSON-Karabiner
git clone git://github.com/sdondley/JSON-Karabiner.git
Though this software is still in an alpha state, it should be able to generate code for any property with the exception of the to_after_key_up key/value use for the simultaneous options behavior due to uncertainty in how this should be implemented. If you need this feature, generate your json code using this script as you normally would and then manually edit it to insert the necessary json code.
to_after_key_up
Steve Dondley <s@dondley.com>
This software is copyright (c) 2020 by Steve Dondley.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
1 POD Error
The following errors were encountered while parsing the POD:
Unknown E content in E<t>
To install JSON::Karabiner, copy and paste the appropriate command in to your terminal.
CPAN shell
perl -MCPAN -e shell install JSON::Karabiner
For more information on module installation, please visit the detailed CPAN module installation guide.