/ 
JSON-Karabiner-0.016
River stage zero No dependents
/ JSON::Karabiner

NAME

JSON::Karabiner - easy JSON code generation for Karabiner-Elements

SYNOPSIS

Below is an executable perl script that generates a json file that can be read by by Karabiner-Elements. You can copy and paste this code to your local machine,modify it if you wish, and execute it. Note that you must first install the JSON::Karabiner package (see the "INSTALLATION" section below).

This script is easy to understand even if you have no experience with Perl, or any programming langauge, for that matter. But 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::Manipulator;  # The JSON::Karabiner Perl package must be installed on your machine

# Create a new manipulator object with a description and the file you want to save it to
new_manipulator('a-s-d to show character viewer', 'my_awesome_karabiner_mod.json');

# Add a from action to the manipulator:
add_action 'from';

# Add behaviors to the action:
add_simultaneous 'a', 's', 'd';
add_optional_modifiers 'any';

# Add a "to" action to the manipulator:
add_action 'to';

# Tell the "to" action what to do
add_key_code('spacebar');
add_modifiers('control', 'command');

# Done! Now it's time to write the file and give the rule a title:
write_file('Emoji Character Viewer');

Save this 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_karabiner_mod.json should now be sitting in the assets/complex_modifications directory. Open the Karabiner-Elements app on your Mac to install the new rule.

Ready to give is try? Follow the "INSTALLATION" instructions to get started.

DESCRIPTION

Karabiner stores rules for its modifications in a file using a data format known as JSON which is painstaking to edit and create. JSON::Karabiner 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 is necessary. The 10 or 20 minutes you spend learning how to install and use this module will pay off in spades.

A Karabiner JSON complex modification file stores the rules for modifying the keyboard in a data structure called the "manipulators." Therefore, most of methods you write will add 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 used on manipulators.

add_action method

for adding the from/to actions to the manipulator

add_condition method

for adding manipulator conditions

add_parameter method

for adding maniplator parameters

add_description method

for adding a description to the manipulator

After you run a add_action or add_condition method, you will need to run additional methods that will be applied to the last action or condition you added.

It will be very helpful if you have a basic familiarity with the Karabiner manipulator definition to gain an understanding of which methods to run. See the Karabiner complex_modification manipulator documentation for more information.

DSL Interface

As of version 0.011, JSON::Karabiner moved to a DSL (domain specific language) interface to make writing scripts even easier. Please see the "SYNOPSIS" for an example of how to use the DSL. Note that the older object-oriented interface, though currently deprecated and undocumented, is still fully funcitonal (or should be, in theory).

How to Use the DSL Interface

There are two parts to a DSL inteface: the method and the list of arguments you are passing to the method. You can think of the method as the action you want to take and the arguments as the data "nouns" you want to store or process.

Methods that add data to the manipulator begin with add_ followed by a string of characters that corresponds to properties outlined in the Karabiner documentation. For example, to add a key_code property, you write:

add_key_code 't';

Here, the action is add_key_code and the data is the character "t". Note that the method call must end in a semicolon. Each argument you pass must be surrounded by apostrophes. Or, if you want to avoid the pain of having to type apostrophers, you can use Perl's qw function:

add_modifiers qw(control shift command);

It bears repeating that methods that apply to actions (or condtions) are automatically assigned to the most recent action (or condition) that was created. In other words, if your have:

add_action 'to';
add_action 'from';
add_key_code 'x';

The key code will be added to the from action. If you wish apply it to the to action, simply move the add_key_code line immediately after the to action. This same rule applies for condtions as well as actions. Any method that adds data to a condtion will get added to the last condition created.

List of Methods for Actions

The following methods apply to actions (e.g. from, to, to_if_alone etc.)

From methods

The following methods are for the from action:

add_any
add_consumer_key_code
add_key_code
add_mandatory_modifiers
add_optional_modifiers
add_pointing_button
add_simultaneous
add_simultaneous_options

To methods

The following methods are for the to action (includes to_if_alone, to_if_held_down to_after_key_up, to_delayed_if_invoked, to_delayed_if_canceled):

add_consumer_key_code
add_key_code
add_modifiers
add_mouse_key
add_pointing_button
add_select_input_source
add_set_variable
add_shell_command

List of Methods for Conditions

The following methods will add data to the most recently created condition in the script.

add_bundle_identifiers
add_description
add_file_path
add_identifier
add_input_source
add_keyboard_types
add_value
add_variable

For further details on each these methods, including the arguments they take, please see the appropriate perl doc page:

from action
to action
conditions

Multiple manipulators

The DSL interface makes it easy to include multiple manipulator in a single rule. Follow this patter:

new_manipulator('Turn x key into y key', 'name_of_file.json');

... Run methods for above manipulator here ...

write_file('Name of Rule');

new_manipulator('Turn a key into by key', 'name_of_file.json');

... Run methods for the second manipulator here ...

write_file('');

... Add N more manipulators here ...

Just be sure the manipulators all have the same file name so they will be included in the same file.

Notice that only the first write_file method requires the name of the rule to be passed. Subsequent calls to write_file will inherit the title from the first manipulator written.

Writing to the JSON file

As shown in the example above, a write_file call must be made for each manipulator in your script to have it included in the JSON file. The title is required to be supplied to the first manipulator. Subsequent write_file calls will use the first title.

METHODS

new_manipulator($maniuplator_description, $file_name, [ { mod_file_dir => '/path_/to/dir' } ])

Example usage:

new_manipulator 'Double tap shift for ⌘-f', 'double-taps.json', { mod_file_dir => '/some/dir' };

This method creates a new manipulator. It must be called before adding actions, condtisions and parameters. The method takes two required arguments: a description of the manipulator and the name of the file you with to save it to. A third argument for passing options to the maniplator, is optional.

Manipulator description

The description will be displayed in the Karabiner-Elements application. The description is used to let you know which rule is getting enabled/disabled. You should be descriptive here.

File name

This is the name of the file your manipulator will be saved in. If this file name is the same for other manipulators, those manipulators will be stored together in the same file. This file should end with the ".json" file extension.

Options

Only one option is available, mod_file_dir. This is needed only if you want to save your json file to a place other than the default, ~/.config/karabiner/assets/complex_modifications.

Note that options are passed as an anonymous has reference. What this means to you is that you have to place this option inside curly braces per the example above.

add_action($type)

There are seven different types of actions you can add:

add_action('from');
add_action('to');
add_action('to_if_alone');
add_action('to_if_held_down');
add_action('to_after_key_up');
add_action('to_delayed_if_invoked');
add_action('to_delayed_if_canceled');

The most frequently uses actions are the first four listed above. You must create a from action to your manipulator. The from action contains the keystrokes you want to modify. The other to actions describe what the from keystroke actions will be changed into. See the Karabiner documentation for more information on these actions.

Once these actions are created, you may run methods to that add additional data to them to modify their behavior. Consult the documentation for the different actions for a listing and description of those methods:

JSON::Karabiner::Manipulator::Actions::From
JSON::Karabiner::Manipulator::Actions::To

add_condition($type)

Conditions make the modification conditional upon some other bit of data. You can add the following types of conditions:

add_condition('device_if');
add_condition('device_unless')
add_condition('event_changed_if')
add_condition('frontmost_application_if')
add_condition('frontmost_application_unless')
add_condition('input_source_if')
add_condition('input_source_unless')
add_condition('keyboard_type_if')
add_condition('variable_if')
add_condition('variable_unless')

Once the conditions are created, you can add data with additional methods. See the additional documenation for these methods and the arguments they accept:

JSON::Karabiner::Manipulator::Conditions

Consult the Karabiner documentation to understand how they modifty the behavior of the actions.

add_parameter($name, $value)

Parameters are used by Karabiner to change various timing aspects of the actions. Four different parameters may be set:

add_parameter('to_if_alone_timeout_milliseconds', 500);
add_parameter('to_if_held_down_threshold_milliseconds, 500);
add_parameter('to_delayed_action_delay_milliseconds, 250);
add_parameter('simultaneous_threshold_milliseconds, 50);

See the Karabiner documentation for more details.

add_description($description)

Adds a description to the manipulator data structure:

add_description('This turns a period into a hyper key.');

This description is not visible inside Karabiner-Elements apps.

write_file($title)

Example usage:

write_file('My Hotkeys');

This method outputs the most recently created manipulator object to the file set by the manipulator. If other manipulators exist in your script and share the same file name, they will be merged together into the same file.

This method will overwrite pre-existing files with the same name without warning, so be sure the file name is unique if you don't want this to happen.

The title is a require field, but only for the first manipulator saved. If the title is left blank for later manipulators, they will share the same title as the first. This allows you to group manipulators under the same title in the Karabiner-Elements interface.

INSTALLATION

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:

Step 1: Ensure the cpanm command is installed:

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..

Step 2: Install the JSON::Karabiner package

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.

Other install methods

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.

VERSION

version 0.016

Development Status

This module is currently in alpha release 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 at least simple cases and probably more advanced cases as well.

Many improvements are in the works. Please watch us on GitHub.

SUPPORT

Perldoc

You can find documentation for this module with the perldoc command.

perldoc JSON::Karabiner

Websites

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.

Source Code

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

BUGS AND LIMITATIONS

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.

SEE ALSO

Karabiner Elements Home Page
Karabiner Elements Reference Manual

AUTHOR

Steve Dondley <s@dondley.com>

COPYRIGHT AND LICENSE

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:

Around line 407:

Non-ASCII character seen before =encoding in '⌘-f','. Assuming UTF-8