mirror of
https://github.com/TECHNOFAB11/pay-respects.git
synced 2025-12-12 14:30:10 +01:00
43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
|
# Modules
|
||
|
|
|
||
|
|
`pay-respects` followed a very stupid approach ---or better said, *Keep It Simple, Stupid*--- when it comes to implementing the module / plugin system:
|
||
|
|
|
||
|
|
- Modules interacts with core program by passing **messages through processes**. In other words, we are sending necessary information to the module, so it can return the required suggestion.
|
||
|
|
- This approach is the most extendable way, as it has the least amount of limitations compared to:
|
||
|
|
- Dynamic libraries (Safe): Requires the module to be compiled in the same compiler version as the core, which also limits the language available
|
||
|
|
- FFI (Unsafe): Requires overloading of dynamic libraries, limits to C types, and not extendable as it's overloading a library instead of appending
|
||
|
|
- Embedding a runtime: Unnecessary binary sizes if never used
|
||
|
|
- `pay-respects` takes the message passing approach as its core is blazing fast without observable delay so having a small overhead is acceptable. This allows:
|
||
|
|
- **Modules in any language**: Regardless of compiled binary or interpreted scripts, just make them executable and that's a module!
|
||
|
|
- **Extendable**: As many modules as you want
|
||
|
|
- **Performance or ease? Both!**: Write in a compiled language if it's something computational heavy, or just use a shell script as module right away
|
||
|
|
|
||
|
|
## Creating a Module
|
||
|
|
|
||
|
|
There are 2 types of modules:
|
||
|
|
|
||
|
|
- **Standard module**: Will always run to retrieve suggestions
|
||
|
|
- Naming convention: `pay-respects-module-<your module name>`
|
||
|
|
- **Fallback module**: Will only be run if no previous suggestion were found
|
||
|
|
- **CAUTION**: Will immediately return if a suggestion is obtained, and there is no guaranteed the modules are executed in a specific order.
|
||
|
|
- Naming convention: `pay-respects-fallback-<your module name>`
|
||
|
|
|
||
|
|
When running your module, you will get the following environment variables:
|
||
|
|
|
||
|
|
- `_PR_SHELL`: User shell
|
||
|
|
- `_PR_COMMAND`: The command, without arguments
|
||
|
|
- `_PR_LAST_COMMAND`: Full command with arguments
|
||
|
|
- `_PR_ERROR_MSG`: Error message from the command
|
||
|
|
- `_PR_EXECUTABLES`: A comma (`,`) separated list of executables in `PATH`
|
||
|
|
|
||
|
|
Your module should return:
|
||
|
|
|
||
|
|
- **To `stdout`**: Only suggestions.
|
||
|
|
- At the end of each suggestion, append `<_PR_BR>` so pay-respects knows you are either done or adding another suggestion
|
||
|
|
- **To `stderr`**: Any relevant information that should display to the user (e.g, warning for AI generated content)
|
||
|
|
|
||
|
|
## Adding a Module
|
||
|
|
|
||
|
|
Expose your module as executable (`chmod u+x`) in `PATH`, and done!
|
||
|
|
|