fabridamicelli / cronex.nvim

If you find this work useful, don't forget to give it a GitHub ⭐ to help others find and trust it! cronex.nvim Human-readable cron expressions in Neovim What is Cronex Cronex is a Neovim plugin to asynchronously render in-line, human-readable explanations of cron expressions: Here's a short introduction video. This plugin is **not** a cron expression parser/checker by itself. Cronex is rather the "client" that allows the Neovim user to integrate and customize "servers" (cron expression "explainers") in a flexible fashion, with fully asynchronous non-blocking API. There are several implementations of those out there (see below). You can use any of those with Cronex. Getting Started Dependencies Since version 0.2.0, depends on . If you're using pin (see below under ). You will need a cron expression explainer installed. The default is cronstrue, which is the one used by the vscode package . Install the library and make sure that the command is available in the environment where your buffer is being shown. Mason users can alternatively install from the mason registry with or by adding it to the list: That will use the library under the hood to generate the explanations. Installation Using lazy.nvim If you are using , tag to earlier versions like so: Using vim-plug Usage Calling setup makes the explainer available and set explanations when leaving insert mode. Entering insert mode clears the explanations. Cronex can be also disabled/enabled on any file (see Commands). Commands The setup will make the following commands available: |Command | Description | |-----------------------|----------------------------------------------------------------| | | Turn off the explanations permanently | | | Turn on the explanations again (regardless of filetype) | Customization Cronex setup structure The plugin consists of three building blocks: | Module | Description | |------------| --------------------------------------------------------------------------| | | Logic to extract cron expressions from current buffer | | | Program that will parse and explain the cron expressions | | | Postprocess the output string produced by the explainer for final display | Default configuration: To embed the above configuration code snippet in a file (for example in ), wrap it in : Look here for more config examples, including support for . Extractor Logic of the default extractor can be found here in . Default extractor searches for at most 1 expression per line of length 7, 6 or 5 (in that order). But Cronex allows the user to hook in and swap this by any arbitrary logic. The extractor has 2 parts: and , both are functions. You can swap any or both of the two with custom functions, provided you respect the following interfaces: : Function with signature . Returns the cron expression if found (else ) : Function with signature The input processes each buffer line (may be identity, i.e. just return line as is). Output of pairs ( , ), empty if no cron expressions found. Here's a toy example on how to customize the functions, that will set "line says --> hello world" on every line of the buffer: Under the hood, will be passed to like so: This allows you to plug a custom function to extract cron from line and still use the default function You may even just set to and use the function to send the whole buffer to another program from which you capture the output. All that matters is that returns the table with pairs ( , ). For example: Explainer As already mentioned above, Cronex integrates the functionality of external cron expression explainers into Neovim. There are several implementations of those out there. More generally, it's up to the user which explainer program to use in the background. Cronex will call such program via the command ( ), collect the output and pass it along to Neovim. This is the default: For example, you can have installed in a conda virtualenv. If the virtualenv is active, everything should work out of the box. But you may not want to install in every virtualenv, so you can have only one central environment with installed and point to that binary explicitly in the config: In fact can call anything that knows how to deal with the cron expression. For example, calling a go program: Here are a few of those third-party libraries as well as the Cronex command to use them: *** *** This is the default explainer by Cronex and the very same library used by the vscode package . You need first install the library and make sure that the command is available in the environment where your buffer is being shown. For example, you can use it inside of a Python virtual environment (in this case managed by conda to install ): After that will only be installed inside (thus only available there). Calling the explainer running in docker container You could even call the program running in a docker container using a dockerfile like this: building the image: and configuring the plugin like so: *** *** This explainer is written in Go and much considerably faster than the default. But it is not as widely used and the project does not seem to be that well maintained. Recommendation: Compile the binary Here's a (non-exhaustive) overview cron explainers out there: | Language | Link | |------------| --------------------------------------------------------| | JavaScript | https://github.com/bradymholt/cronstrue | | Go | https://github.com/lnquy/cron | | Python | https://github.com/Salamek/cron-descriptor | | .NET | https://github.com/bradymholt/cron-expression-descriptor| | Java | https://github.com/grahamar/cron-parser | | Rust | https://github.com/zslayton/cron | format We might want to modify the output from the third-party explainer libraries. For example, some explainers show the input as well in the output like so: In that case, you could use the function ) to transform the output to just show "Every minute". But the user can do any other transformation by defining a lua function…