Add more Job examples

Open
#425 0 comments 9 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
lua
Domain
documentation

Research direction

Start by reading the README Job example and the Job-related tests, especially the cases covering callbacks, environments, writers, and sending arguments to a running command. Verify each requested behavior from those tests before expanding the documentation. Done means a minimal example and clear examples or explanations for environment inheritance, PATH handling, piping, sequencing, cleanup, and job reuse.

Written by the indexing model from the issue text.

Description

Hello.
Thank you for the thing that is closer to a stdlib for neovim plugin development in Lua.
The thing I find more interesting in this library is the job interface. There is no easy way to run terminal commands from neovim and job is a fantastic thing to have.
However, this is also one of the methods with less docs, so it is hard to understand what it can and cannot do. For example, I was not aware that you don't need to nest callbacks to get the result of the job, like the example shows in the on_exit callback, you can just get the results directly from the job return.
All the knowledge I have about it comes from reading the tests, which are a good kind of documentation, but it is kind of hidden and not all are fully readable.

The things I would love to have docs about are:

  • Mention that not providing an environment, the job will inherit the current environment
  • Mention that if you define an environment, binary executions will fail if you don't provide a proper PATH in that environment. Also an example of how to pass the current path will be interesting
  • Document how to pipe commands. I think this is using the writer interface, but I am not sure
  • Can I conditionally execute a job based on the results I get from the previous one? How can I ensure they are run in the right order? Is just calling one after the other enough?
  • Show a very minimal example. The current example in the readme has a lot of fields, and it seems that all you need is the cmd property, which makes Job much more appealing and accessible.
  • Do commands automatically finish? Or do I have to do some cleanup?
  • Can I re-use a job? In the tests I saw there is the possibility to send arguments to a running command, but I am not sure how this works. Will it spawn a new command each time? Will it reuse the existing execution hence requiring a long-lived process?

Again, thank you very much

Dominant language
Lua
Stars
3.5k
Forks
340
PR merge metrics
No merged PRs in 30d

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from nvim-lua/plenary.nvim

All issues in nvim-lua/plenary.nvim

Similar issues

More Lua issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.