Download Current version: v0.1.2

View on Github

I type on a Dvorak keyboard (you should too ), 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 kdbencode, 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 typeod on a different keyboard layout. The default input layout is qwerty, and the default output layout is dvorak. In detail, the input home row is a s d f g h j k l ; '. kbdencode treats input text as if the input layout were Dvorak, on which the home row is a o e u i d h t n s -. For example, the input key d maps to the output e, ; maps to s, h maps to d, and so on.

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.
-c <file>
--config=<file>
Path to custom layout configuration file. See below for formatting and content information.
Default: $HOME/.kbdencoderc
-f <layout>
--from=<layout>
The actual keyboard layout recognized by the system, where <layout> is a named layout or a layout definition string.
Default: qwerty
-t <layout>
--to=<layout>
The keyboard layout to which kbdencode should map the input. Like with the --from option, <layout> could be a named layout or a layout definition string.
Default: dvorak

Included Layouts

The following layouts can be referenced by name in the --from and --to command-line options. Click on the title to see the layout.

Defining a Custom Layout

Additional layouts can be specified by adding a named layout definition string 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:

  1. 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
  2. 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.
  3. 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.