Enhance pueue edit UX

[pacien]

Hello, and thank you for this very useful program!

I often forget to pass some options when adding new tasks,
and find myself needing to edit those, often in batch.

The current edit sub-command opens an editor for each value to edit,
which is quite cumbersome when just wanting to replace a value,
especially for multiple tasks at once.

Therefore, I think it would be nice for the edit sub-command to:

• accept mulitple task IDs at once, and
• accept replacement values directly from the CLI,
  to be applied to all the specified tasks at once.

Current help text of the edit sub-command:

❯ pueue edit --help
Edit the command, path, label, or priority of a stashed or queued task.
By default only the command is edited.
Multiple properties can be added in one go.

Usage: pueue edit [OPTIONS] <TASK_ID>

Arguments:
  <TASK_ID>  The task's id

Options:
  -c, --command   Edit the task's command
  -p, --path      Edit the task's path
  -l, --label     Edit the task's label
  -o, --priority  Edit the task's priority
  -h, --help      Print help

Target help text with the suggested additions:

❯ pueue edit --help
Edit the command, path, label, or priority of a stashed or queued task(s).
Values specified in options are used as replacements.
When no option is specified, EDITOR is opened.

Usage: pueue edit [OPTIONS] [TASK_IDS]...

Arguments:
  [TASK_IDS]...  The task(s) id

Options:
  -c, --command <COMMAND>    Edit the task(s)' command
  -p, --path <PATH>          Edit the task(s)' path
  -l, --label <LABEL>        Edit the task(s)' label
  -o, --priority <PRIORITY>  Edit the task(s)' priority
  -h, --help                 Print help

When no replacement option is supplied on the CLI,
the default EDITOR can be used to edit the properties.

But instead of opening the EDITOR for each value for each task individually,
this could be done in a combined way in a single YAML or TOML file.

For example, running pueue edit 0 1 would open an EDITOR with:

[0]
command = "echo this is my first command"
path = "/home/user"
label =
priority = 0

[1]
command = "echo this is my second command"
path = "/home/user/whatever"
label =
priority = 5

Since the current edit sub-command is quite interactive,
these modificatinos shouldn't break existing automated user scripts.

[Nukesor]

Thanks for the detailed feature request :)

I already thought about this some time ago, over here.

I would like to take some time to re-evaluate on which approach is the most user-friendly, but this'll have to wait for a bit :)

[Nukesor]

So, I thought about this for quite some time and this problem is pretty tricky.

As users can theoretically start any valid shell syntax in any shell they like (as the shell is configurable), we have practically no guarantees on how the input will look like.

To keep this convenient, we must allow multi-line editing. Strings with "\n" inside of it aren't an option.
No structured data format i know of can properly handle this. All of them have some kind of reserved characters or other constraints that make them unfeasible.

So, after some discussions with friends and other people, we came up with the idea to instead of creating a temporary file, to rather create a temporary directory with a file for each property to add.

All modern editors have directory/file tree support, so users can simply select the files they're interested in and edit without any file format constraints.

I really like this solution as it is very simple and outsources the UI issue to the user's editor, which is a highly specialized tool for editing multiple files.

[Nukesor]

This could then be expanded for multiple tasks, where we create subdirectories for each task to edit with the ID being the name of the subdirectory.

[fzyzcjy]

Hi thanks for the new feature!

Here is my naive thoughts: Maybe we can let user edit a YAML file. For example,

- command: "echo this is my first command"
  path: "/home/user"
  label: 
  priority: 0
- command: "echo this is my second command"
  path: "/home/user"
  label: 
  priority: 0

Or in TOML:

[[commands]]
command = "echo this is my first command"
path = "/home/user"
label = ""
priority = 0

[[commands]]
command = "echo this is my second command"
path = "/home/user"
label = ""
priority = 0

Pros:

• Everything in one file, thus easy to quickly modify. For example, I use vim, and can very quickly move these tasks around (as they are just several lines of "code"). On the other hand, if it is a folder (or multi folders), then it is not very easy.

Extension:

• It would be great to support more "declarative" ways. For example, if I add several new lines, then that will be treated as adding a task. If I delete some lines, then that is parsed as removing a task.

If we want to allow multiline edit without "\n" in it: YAML has nice multiline string support https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines. TOML also have https://toml.io/en/.

[Nukesor]

Using yaml or toml was one of the very first ideas. I actually like yamls | block quite a bit but there's this annoying thing that there's currently no well-maintained serde yaml library out there that supports that formatting option (at least none I know of). So that option dropped out due to a rather trivial technical reason.

Regardless of that, there're multiple pros and cons for both sides.

File based structure

Pros

• Allows any input (hard to break, very robust)
• Very clear separation
• Intuitive
• Works for hundreds of tasks without issues

Cons

• Your Editor should have a file tree for this to be useful.
• Is probably a bit slower for few tasks

Structured Data

Pros

• Single file, simple to navigate
• Nicer for editing few tasks

Cons

• Users must know about the file format, not everybody is familiar with toml/yaml.
• We allow full shell syntax with configurable shells as command input. Users must have detailed knowledge about reserved characters of the used format if they write complex scripts, otherwise they might break their commands.

---

A friend of mine proposed to make this configurable and allow both solutions. I tend to go towards that approach as I see that the structured data solution is nicer for some users and is easier to use when your editor doesn't have a file tree.

[fzyzcjy]

Thanks for the reply! I personally love the structured data approach, so my thought below are opinionated :)

So that option dropped out due to a rather trivial technical reason.

Thus curious whether TOML has one for that

not everybody is familiar with toml/yaml

I guess it is intuitive enough that it is not hard for users to realize the format.

Users must have detailed knowledge about reserved characters of the used format if they write complex scripts, otherwise they might break their commands.

https://toml.io/en/ seems to support "literal string" like below. Thus, seems there are zero reserved characters (except for three consequtive quotes ''')

re = '''I [dw]on't need \d{2} apples'''
lines = '''
The first newline is
trimmed in raw strings.
All other whitespace
is preserved.
'''

A friend of mine proposed to make this configurable and allow both solutions. I tend to go towards that approach as I see that the structured data solution is nicer for some users and is easier to use when your editor doesn't have a file tree.

Looking forward to it!

[Nukesor]

I'm going to build this, but I just want to drive home my point of view.

I guess it is intuitive enough that it is not hard for users to realize the format.

Pueue is being used by quite a few people in the science sector, specifically machine learning. Those aren't necessarily ver tech savy.

https://toml.io/en/ seems to support "literal string" like below. Thus, seems there are zero reserved characters (except for three consequtive quotes ''')

For this, users need to know about ''', they need to be fairly familiar with toml/yaml and know that they can simply use that to have a long string in which they don't have to worry about character escaping or multi line shennanigans.
It may seem very intuitive and easy for you, but it won't be intuitive for everyone, especially for people that haven't worked with toml before (i.e. People that don't use Python or Rust).

As I said, I plan to support both approaches, I just want to make clear that it isn't that easy.

[fzyzcjy]

I see, good point!

Btw, people in machine learning are often using python nowadays (I am also doing machine learning). But yes, often they do not work with TOML (maybe pyproject.toml is often the only toml they will see?).

know that they can simply use that to have a long string in which they don't have to worry about character escaping or multi line shennanigans

For this, not sure whether we can generate toml with comments like:

# you can have multiline and no worries about escaping inside triple quotes
command: '''
the current command
'''

[Nukesor]

I'm open to contributions on this one :)

If anyone wants to work on this, feel free to go ahead. I currently have quite a bit on my plate and don't know when I'll get to it :)