Swiftpack.co - MathKeyboardEngine/MathKeyboardEngine.Swift as Swift Package

MathKeyboardEngine for Swift

MathKeyboardEngine for Swift provides the logic for a highly customizable virtual math keyboard. It is intended for use together with any LaTeX typesetting library (for example KaTeX or MathJax in a WebView).

Also available:

• MathKeyboardEngine for C#.
• MathKeyboardEngine for JavaScript.
• MathKeyboardEngine for Python.
• MathKeyboardEngine for other languages.

An execution timeline

1. You load a page with your customized virtual math keyboard (based on one of the examples). The keys show typeset LaTeX - loaded form a local png file or rendered on the fly - and a cursor is displayed in a textbox-look-a-like element.
2. On your customized virtual math keyboard, you press a key. The key calls a MathKeyboardEngine function, for example insert(someMatrixNode) or moveUp(), deleteLeft(), etc.
3. Calling getEditModeLatex() outputs the total of LaTeX you typed, for example \frac{3}{4}\blacksquare (if \blacksquare is your cursor), which you then feed to KaTeX or MathJax for display.
4. Calling getViewModeLatex() outputs the LaTeX without a cursor.

Note: you can use parseLatex(latexString) for pre-filling the textbox or for allowing users to also use raw LaTeX commands.

Let me test it now!

Live (JavaScript) examples can be tested at mathkeyboardengine.github.io.

Pros and cons?

Unique about MathKeyboardEngine:

• it supports (almost?) all math mode LaTeX, including matrices. (Please share if you know anything that is not supported.)
• its syntax tree consists of very few different parts: the StandardLeafNode, StandardBranchingNode, AscendingBranchingNode and DescendingBranchingNode can be used for almost all LaTeX, including fractions, powers, combinations, subscript, etc. with ready-to-use up/down/left/right navigation.
• it can be used with any LaTeX math typesetting library you like.

A con:

• this library will never be able to handle setting the cursor with the touch of a finger on a typeset formula. (But it DOES support up/down/left/right navigation and has a selection mode via arrow keys.)

More pros:

• you have full control over what you display on the virtual keyboard keys and what a virtual key press actually does.
• customize the editor output at runtime: dot or comma as decimal separator, cross or dot for multiplication, cursor style, colors, etc.
• this library also supports handling input from a physical keyboard, where - for example - the forward slash "/" key can be programmed to result in encapsulating a previously typed number as the numerator of a fraction. (See the examples.)
• almost forgotten: it's open source, free to use, free to modify (please fork this repo)!

How to use this library

To use the MathKeyboardEngine library in a SwiftPM project, add it to the dependencies for your package and - for example - your command-line executable target:

// swift-tools-version: 5.7

import PackageDescription

let package = Package(
    name: "MyExecutable",
    dependencies: [
        .package(url: "https://github.com/MathKeyboardEngine/MathKeyboardEngine.Swift", from: "1.0.0"),
    ],
    targets: [
        .executableTarget(
            name: "MyExecutable",
            dependencies: [
                .product(name: "MathKeyboardEngine", package: "MathKeyboardEngine.Swift"),
            ]),
        // ...
    ]
)

Then add

import MathKeyboardEngine

and

let k = KeyboardMemory()
let latexConfiguration = LatexConfiguration()
// Subscribe to onclick events of virtual key presses, etc.

Note: the use of Swift.fatalError can be very helpful - especially during development and maybe even in production - for fixing wrong implementation of this libary. However, if you want MathKeyboardEngine not to use Swift.fatalError, then use the following line at startup of your app:

MathKeyboardEngineError.shouldBeFatal = false

Documentation

Visit the documentation and the (latest version of the)* Examples folder for more implementation details.

* If you use a version tag in the url like this: https://github.com/MathKeyboardEngine/MathKeyboardEngine.Swift/tree/0.1.0-alpha.2, you can see the git repository as it was for that version. That may not be needed if the changelog doesn't note any important changes.

How to use this repo

Follow these steps to set up (and verify) a development environment for this repository on Windows:

1. Install Git, Swift for Windows, Visual Studio Community Edition with the C++ Desktop Workload, VS Code and Swift for VS Code.
2. Fork (or clone), checkout and then open the root folder of this repository in VS Code.
3. In the terminal, run swift test.

Note: checking code coverage and testing for macOS and Linux is done via GitHub Actions - see .github/workflows.

License

The MathKeyboardEngine repositories use the most permissive licensing available. The "BSD Zero Clause License" (0BSD) allows for
commercial + non-commercial use, closed + open source, with + without modifications, etc. and is equivalent to licenses like:

• "MIT No Attribution License" (MIT-0).
• "The Unlicense" (Unlicense).
• "CC0" (CC0).

The "BSD Zero Clause License" (0BSD) does not have the condition

(...), provided that the above copyright notice and this permission notice appear in all copies.

which is part of the "MIT License" (MIT) and its shorter equivalent "ISC License" (ISC). Apart from that they are all equivalent.

Ask or contribute

• ask questions about anything that is not clear or when you'd like help.
• share ideas or what you've made.
• report a bug.
• request an enhancement.
• open a pull request.