Crate libdof

Libdof

The .dof file format is a json compatible format with specified fields describing any keyboard layout, including some defaults.

It has a set amount of (sometimes optional*) fields:

• name: name of the layout

• authors[]*: authors of the layout

• year*: year the layout was created.

• description*: string containing a description of the layout.

• link*: url to a page with more information about the layout.

• layers{}: specifies all layers on the layout. They’re of the form of name: <layer> where each layer is an array of rows specified by a string consisting of keys delimited by any amount of whitespace. They work like the following:

  • If the string length is 1, output:

    • An empty key when it’s equal to ~
    • A transparent key when it’s equal to *, which refers to the value on the main layer. This is equivalent to ~ when on the main layer.
    • Enter when it’s equal to \n,
    • Tab when it’s equal to \t,
    • A character key otherwise.

  • If the string length is more than 1, output:

    • ~ and * characters if it contains \\~ and \\* respectively,
    • A special key like shift or space when provided with specific identifiers which can be found at the bottom of the document,
    • A layer key if it leads with an @, for example @altgr
    • A word key with its first character removed if it leads with #, \\# or\\@, for example \\@altgr would output @altgr rather than become an altgr layer key,
    • A word key, which outputs multiple characters at the same time, otherwise.

  • If the string is any of these modifier values:

    • esc => Esc,
    • repeat, rpt => Repeat,
    • space, spc => Space,
    • tab, tb => Tab,
    • enter, return, ret, ent, rt => Enter,
    • shift, shft, sft, st => Shift,
    • caps, cps, cp => Caps,
    • ctrl, ctl, ct => Ctrl,
    • alt, lalt, ralt, lt => Alt,
    • meta, mta, met, mt, super, sup, sp => Meta,
    • fn => Fn,
    • backspace, bksp, bcsp, bsp => Backspace,
    • del => Del

  All layer names are allowed though two are reserved:

  • main (mandatory)
  • shift

  While main is mandatory to be filled, shift can be elided and will follow qwerty’s capitalization scheme when unspecified. Any shape is allowed, but if you use a standard 3x10 shape you may be able to forego specifying a custom finger map and keyboard as well.

• board: specifies the keyboard type the layout is made for. Three formats are accepted here:

  • ansi, iso, ortho, colstag specify preset boards, which by default place the provided as if they are a standard 3x10 matrix.

  • A relative board, which specifies a keyboard that has horizontal rows, but isn’t ortholinear; ansi and iso boards fall into this category. The way they’re specified is with an array of strings that contain something like "k 2k 3", where k is a key of 1x1, <number>k is a key with a width of number, and simply a number specifies empty space, used for split ortho boards for example.

  • A full specification. They’re specified as an array of arrays, containing each key as a string. Each string contains 2 to four numbers specified by whitespace: "1 2.5" specifies (x, y) = (1, 2.5), where further numbers specify the width and height respectively.

• anchor[]*: Specifies where on the physical board the actual layers ‘anchor’ on. For example, if you wanted to place a 3x10 matrix on an ansi or iso board, the anchor is one from the top, and one from the left so [1, 1]. There are default anchors for the preset boards, but you are required to provide an anchor for custom boards.

• fingering: specifies which finger presses which key. For known boards (iso, ansi etc) you can specify a known name:

  • board: "ansi" where the main layer shape starts at qwerty q, allowed fingerings are traditional, standard, angle
  • board: "iso" where the main layer shape starts at qwerty q and the bottom row includes the iso key, allowed fingerings are traditional, standard, angle
  • board: "ortho", board: "colstag", allowed fingerings are traditional, standard

  If you use a custom keyboard, you can specify fingering the same way you would a layer, but with fingers. Layer and fingering shapes should match though, as it will error otherwise.

  • LP or 0: left pinky
  • LR or 1: left ring
  • LM or 2: left middle
  • LI or 3: left index
  • LT or 4: left thumb
  • RT or 5: right thumb
  • RI or 6: right index
  • RM or 7: right middle
  • RR or 8: right ring
  • RP or 9: right pinky

• combos{}: Allows you to specify combos on a layer by layer basis. This works the same as with layers, except you now specify an array of combos. Say you specified "k k-2": "rpt" for the main layer, this means that if you pressed the first (starting top-left) and second k together, they output the repeat key. Index 0 and 1 are equivalent here, and do not have to be specified.

For all of these, it might be worth it to check out the example dofs.

Modules

• combos
  A way to define combos for a keyboard layout.
• dofinitions
  Contains most types to represent elements of a keyboard layout with
• interaction
  Contains some structs and functions that are used when interacting with the layout, like swapping two keys.
• keyboard
  Contains the Keyboard struct and helpers which can be used to describe physical keyboards.
• prelude
  Just exports everything the library offers

Macros

• keyboard_conv
  NOTE: Depends on serde_with.

Structs

• Anchor
  An anchor represents where the top left key on a Dof is compared to where it would be on a physical keyboard. For example, if you were to provide a 3x10 raster of letters but would like this applied to an ANSI keyboard, the Anchor would be (1, 1), as the top left corner of the Dof (being where qwerty q is) would need to be shifted one left and one up to be in the top left corner of the physical keyboard. Therefore, the default value of an anchor is dependent on the physical keyboard it is applied to.
• DescriptiveKey
  A Key with metadata attached. These are produced by calling Dof::keys().
• Dof
  A struct to represent the dof keyboard layout spec. This struct is useful for interacting with dofs and parsing to/from .dof using serde_json. For converting other formats into dofs, consider taking a look at DofIntermediate.
• DofError
  The main error struct of the library. Internally it uses a Box containing DofErrorInner to save space.
• DofIntermediate
  Main struct to use for parsing, and a more or less literal interpretation of what a .dof file can contain. As its fields are public, this can also be useful for implementing TryFrom<Type> for Dof because at the end of that function you can call intermediate.try_into() to handle all validation for you.
• Fingering
  Struct that represents the fingering of each layout. It is an abstraction over Vec<Vec<Finger>>.
• Language
  Used to represent the language(s) a layout is optimized for, containing the name of a language as well as a weight, the latter being useful for layouts that are made for a combination of languages with some amount of % split.
• Layer
  An abstraction of Vec<Vec<Key>> to represent a layer on a layout.

Enums

• ParsedFingering
  Abstraction over the way an actual .dof file is allowed to represent the fingering of a layout, being either explicit through providing a list of fingerings for each key, or implicit, by providing a name.

Traits

• Keyboard
  Overarching trait for any type that contains a Vec<Vec<K>> represinting one aspect of a keyboard(layout). In libdof these are Layer and Fingering, but this could also be implemented for a heatmap type or a physical keyboard for example.