sharkov63 / sakls Goto Github PK

Before releasing SAKLS, we should write tutorials on how to contribute and extend SAKLS. One of these tutorials should be "How to write a Layout Plugin", which will use sakls.xkb-switch as an example. The tutorial is best written in markdown with source lying directly in SAKLS repository.

We should create a convenience class, which given an implementation of C SAKLS Layout API (sakls_LayoutAPI), creates a C++ class sakls::LayoutAPI which makes access to Layout API more convenient.

Schema concept

Schema (or syntax-to-layout schema) is a convenient, manually written set of rules that tells sakls which keyboard layout should be set at any given moment based on the syntax information of the vim buffer.

Syntax Stack

Say we have a vim buffer, the syntax tree of it's contents and a position $p$ in this buffer. Then the syntax stack for position $p$ is the path from the lowest node in the syntax tree that contains $p$ to the root of the syntax tree (that is, the top of the stack is the lowest node, and the bottom is the root). The elements of the syntax stack are called syntax node IDs (or just node IDs) and they represent the types of the syntax nodes, not the nodes themselves (different nodes with the same type will have the same node ID). Usually they are integers, but can be strings and whatnot.

A schema determines the keyboard layout only by looking at the syntax stack of the current cursor position in the buffer. Simplifying, it looks at the node ID at top of the syntax stack and determines the layout from it.

Algorithm

A schema divides all possible node IDs into the following three disjoint sets.

• Memorized node ID: when such node ID is at the top of the stack, the keyboard layout is determined by looking up into a table (with key being this node ID). When the syntax stack changes, the keyboard layout for this node ID is saved into that table; so it's possible to switch the layout manually and sakls will switch to that layout next time we appear in the same syntax node ID. It's possible to set a default layout for a memorized node ID (when the table is initialized). All node IDs are memorized by default and their default layout is determined by the default_layout field of Layout API.
• Forced node ID: when such node ID is at the top of the stack, the keyboard layout is forced to a certain layout. We can change the layout while being in this node ID, but next time we enter it, the layout will change back. (It is important to implement sakls engine so that when we change text/position and remain in the same forced node ID, the layout is not changed even if it is not equal to the forced layout.)
• Ignored node ID: when such node ID is at the top of the stack, it is skipped and sakls considers the next node ID in the stack (the process repeats until it finds a memorized or a forced node ID).

This is an epic which sums up to prepare all docs before SAKLS release.

Instead of using

#ifdef __cplusplus
extern "C" {
#endif
//...
#ifdef __cplusplus
}
#endif

We should define convenience macros SAKLS_EXTERN_C_BEGIN and SAKLS_EXTERN_C_END.

Layout API is an interface which provides means of getting and setting the current keyboard layout. Simply, it consists of two methods: get_layout(): layout and set_layout(layout). The interface should be agnostic of the actual implementation that does the layout switching.

The implementations of layout API can be:

• Mock implementation which switching a variable - it would be useful for testing.
• Implementation switching iminsert between 0 and 1 - it would be useful when there are no means of switching the actual system keyboard layout.
• Implementation which calls an external library to actually switch the system keyboard layout. The backend library is OS-dependent. There are the following ones:
  • xkb-switch for Linux;
  • im-select for MacOS and Windows.

The Layout API makes it so that implementation of this API would be very easy to write.

After task #7 we have a stub implementation of sakls::Engine class. In this task we should implement this class, providing the full support of memorized, forced and ignored syntax node types.

Currently we only aim to implement updateNewSyntaxStack function which changes the whole syntax stack at once. In the future we can add support for push and pop syntax stack functions.

In order to use sakls headers in other projects (for exmaple, using LayoutAPI.h header in Layout API implementations in separate repositories, we should create a CMake INTERFACE library. This will not make itself as a library, but using target_link_libraries with it will add the necessary include paths, without the need to do it manually.

We should design a basic C API of creating/deleting a SAKLS Engine as well as provide a function to fully update the syntax stack in the engine.

This is an epic to ensure doxygen support.

Goals:

• Doxygen docs should be generated by CMake-defined build target, ideally in one command like ninja sakls-doxygen or something.
• When we have CI and a website, it should automatically deliver doxygen docs to the website.

In this task we should make the necessary decisions regarding error handling:

1. In C++ implementation of SAKLS, should we use error codes or exceptions?
2. How to understand error codes from an Layout API implementation? Should the error codes be agnostic of the Layout API implementation, or should they be unified?
3. If we are to choose error codes in C++ and want to utilize Expected<T>-like mechanisms, should we use std::expected from C++23, or should we use some other error-code library (like llvm-expected header-only library)?

Before the release we should prepare the following:

• README.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• Issue and PR templates