The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
JSON-Karabiner-0.018
River stage zero No dependents
1 ++
/ 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 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

  # Set up required meta data about the rules:
  set_title 'Emoji Character Viewer';              # the name for your group of manipulators
  set_rule_name 'a-s-d to show character viewer';  # the name of the rule for your manipulators

  # You must add at least one manipulator:
  new_manipulator;

  # 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 out
  write_file;

Save this code to a file on your computer and be sure to make the script executable with:

  chmod 744 my_awesome_karabiner_mod.pl

Then execute this script with:

  ./my_awesome_karabiner_mod.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 as long as you have Karbiner-Elements installed to the default directory (see the set_save_dir method if you don't). Now 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 "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 generate with your script with 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 functional (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 pattern:

  set_title 'Group heading for all rules';
  set_rule_name 'My first rule';
  new_manipulator;

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


  new_manipulator;

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

  set_rule_name 'My second rule';
  new_manipulator

  ... Add N more manipulators here ...

  # Afer all the maniuplators have been added:
  write_file;

All the manipulators will be added to the same file name.

Notice that you can group multiple manipulators under the same rule name. A new manipulator that is added will inherit the rule name of the last rule name set with the set_rule_name method.

Writing to the JSON file

As shown in the example above, a write_file is called to write out your JSON file.

METHODS

set_filename($filename)

This method override the default setting for the name of the .json file where the script will save the generated json code. By default, the .json file will share the same file prefix of your script name. So if your script is named my_script.pl, the json file will be named my_script.json.

Example usage:

  set_filename 'some_filename.json'

If you do not provide the .json file extension, it will be automatically attached for you.

set_save_dir($directory_path)

This mehtod is only needed if you have Karabiner-Elements installed in a non-standard directory and you need to override the default of ~/.config/karabiner/assets/complex_modifications.

Example usage:

  set_save_dir '/custom/path/to/complex_modifications'

set_title($rule_title)

This sets the rule title your manipulators are grouped under. It is used by Karabiner-Elements to organize your rules in the graphical user interface.

Example usage:

  set_title 'My Favorite Rules'

set_rule_name($rule_name)

Manipulators are assinged to individual rule names. These rule names, or descritpions, are grouped under the rule title. You can have many manipulators assigned to one rule name. Newly create manipulators are assigned to the last rule name set with the set_rule_method.

Example usage:

  set_rule_name 'Double tap left shift to swipe right'

new_manipulator()

Example usage:

  new_manipulator;

This method creates a new manipulator. It must be called before adding actions, conditions and parameters.

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 used 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], [$filename])

This method writes all the manipulator objects out to a .json file.

Example usage:

  write_file 'My Hotkeys', 'my_file.json';

  # or, even better:
  write_file; # title must have been already set with the "set_title"
              # method to run this method without arguments

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 argument is not required if it has already been set with the set_title method, otherwise it is required. The $filename argument is always optional and will default to the what was set with set_filename or, if that method wasn't used, than the filename will inherit the prefix from the name of the script. The .json extension is required for this method and cannot be omitted.

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

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.