kbdencode

Keyboard layout encoder: type input using your favorite keyboard layout, see the output as if you were typing in another layout.

This page is here only for archival purposes. The authoritative documentation is available in the README on the GitHub repository.

Download Current version: v0.1.2

View on GitHub

I type on a Dvorak keyboard, and I often fumble trying to use QWERTY when typing something short on someone else's computer. I could add Dvorak to the keyboard layout preferences, but kbdencode presents an alternate solution: typing on a QWERTY keyboard as if it were a Dvorak keyboard, and then converting the gibberish into what I had originally intended to type.

Installation

At present, there are no official binary builds of kbdencode, so all installations have to be compiled from source.

To compile kbdencode, please ensure you have the Boost program_options library available on your system. This can be done by installing Boost or by downloading the necessary static libraries and header files for your system and providing paths as variables to the configure script or in a config.site file.

Once all dependencies are satisfied, the kbdencode executable can be installed like any Autotools-built software:

./configure
make
make install

Note: super user permissions might be required to perform the make install action. If this step fails on your machine, try again, but with sudo make install.

You can change the target installation directory by supplying the --prefix option to the configuration script:

./configure --prefix=$HOME/.local

And finally—though this tip does not apply to this project since there are very few source files to compile—the performance of any make task can be boosted by supplying the -jN option, where N is the number of concurrent threads to use. For example, most if not all quad-core Intel Core i7 processors can handle up to 8 simultaneously executing threads.

make -j8

Usage

As mentioned above, kbdencode’s purpose is to translate text typed on an input layout and convert it to the output as if it were typed on a different keyboard layout. The default transform is from qwerty to dvorak.

kbdencode is designed to be a command-line utility, so it accepts input through stdin or from one or more files specified as arguments:

echo "Jdppsw ,soph!" | kbdencode
# => Hello, world!
echo "Kjg; kdbk ,a; odah yosm a ygpde" > file.txt
kbdencode file.txt
# => This text was read from a file.

The entire command-line syntax is kbdencode [options] [files...], where the options are described below.

Command-Line Options

--help: Displays a help message containing these options and licensing information.

Included Layouts

The following layouts can be referenced by name in the --from and --to command-line options.

Defining a Custom Layout

Additional layouts can be specified by adding a named layout definition to the source code before compiling or by providing a layout definition string to the --from or --to command-line options.

A layout definition string is a sequence of characters formed by pressing all of the keyboard keys in a certain order. Perhaps the best way to demonstrate is with an example. The layout definition string for the qwerty layout is:

`1234567890-=qwertyuiop[]\asdfghjkl;'zxcvbnm,./~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:"ZXCVBNM<>?

It should be easy to see the key sequence:

Starting at the key in the top-left corner of the keyboard (below the function key row), type all of the keys on the top row from left to right
Repeat the previous instruction for the remaining three rows on the keyboard. The last key pressed should be the key at the bottom-right corner of the keyboard.
Repeat the order again, but this time holding the Shift key.

Configuration File Format

Since version 0.1.2, kbdencode can load custom layouts from a configuration file. The default configuration file location is $HOME/.kbdencoderc, and custom locations can be specified with the --config command-line option. The format is straightforward:

layout-name
layout-definition-string
layout-name
layout-definition-string
layout-name
layout-definition-string
...

This is probably best explained with an example. Here is a configuration file specifying the default built-in qwerty and dvorak layouts:

qwerty
`1234567890-=qwertyuiop[]\asdfghjkl;'zxcvbnm,./~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:"ZXCVBNM<>?
dvorak
`1234567890[]',.pyfgcrl/=\aoeuidhtns-;qjkxbmwvz~!@#$%^&*(){}"<>PYFGCRL?+|AOEUIDHTNS_:QJKXBMWVZ

Layouts in the configuration file may be referred to by name via the --from and --to command-line options.

Built-in Layouts

A layout definition string may be added as a named layout by placing it in the map initializer in src/kbdencode.cc. Be sure to escape characters as needed (i.e. the " and \ characters)

std::map<string, string> keymaps = {
    { "qwerty", "`1234567890-=qwertyuiop[]\\asdfghjkl;'zxcvbnm,./~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:\"ZXCVBNM<>?" },
    { "dvorak", "`1234567890[]',.pyfgcrl/=\\aoeuidhtns-;qjkxbmwvz~!@#$%^&*(){}\"<>PYFGCRL?+|AOEUIDHTNS_:QJKXBMWVZ" },
    { "my-layout", "/* put your layout definition string here */" },
};

The layout definition string should be the same length as the others (93 characters long, 95 including the escape backslashes). Rebuild and install the executable to start using your custom layout.

Explicit Layouts

The alternative way to specify custom layouts is by providing the layout definition string as values for the --from and --to options. Once again, be careful to escape special characters! For example, the qwerty layout could be specified as follows:

kbdencode --from='`1234567890-=qwertyuiop[]\\asdfghjkl;\'zxcvbnm,./~!@#$%^&*()_+QWERTYUIOP{}|ASDFGHJKL:"ZXCVBNM<>?'

License

kbdencode is licensed under GPLv2. If this presents a problem for you in any way, please let me know and I will consider relicensing the software for you.