(74904dc) Let a ticket field be cleared back to unset, and bump to 0.18.0

`set --clear <field>` is the one way to take a value away, repeatable, with
the field as a `ValueEnum` value: an unknown one is a usage error listing the
six that are not, and the shells complete them for free. Not a per-field
`--clear-due`, which is a flag per field to keep in step with the one it
undoes, and not an empty value, which is already a paragraph break for a
section and would make an accidentally empty variable a silent delete.

What goes back is what `add` writes for a field it was never given, through
the new `NOT_SET` and `NONE` constants and each section's placeholder, so a
cleared ticket and one filed without the field read the same. Sections are in
scope and go back through `clear_section_body` rather than
`set_section_body`: the latter runs its items through `Section::render`, which
would have written `- [ ] _No acceptance criteria provided._`.

Owner is `chown --clear <ticket>`, so the field keeps its one writer. The flag
carries the ticket because the ticket is chown's second positional and a bare
flag would land it in the user's slot for the handler to read back out, which
is hand-parsing what clap can state. It writes `_Not set_` rather than the git
user: `add` falls back to the git user because it is filing something new, and
an owner taken away says nobody owns this.

The empty-value error split in two rather than being reworded. `non_empty`
says only that the value cannot be empty, for the arguments with no empty
form; `clearable` names `--clear`, for the arguments whose field has one. One
message for both would have lied about `ls --tag`.

Replacing and clearing one field in a single call is refused rather than
resolved by whichever was applied last, and cleared fields are reported as
`Cleared due on '...'` beside `Updated priority on '...'`, since one list
would say `Updated` of a field that was emptied.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ansho Rei
2026-08-23 00:04:28 +02:00
co-authored by Claude Opus 5
parent 175c1d016d
commit cc5f9b8a46
15 changed files with 810 additions and 92 deletions
+105 -18
View File
@@ -4,7 +4,7 @@ use std::sync::LazyLock;
use chrono::NaiveDate;
use crate::util::{PRIORITY_RANGE, RelationKind, Status, priority_legend};
use crate::util::{Clearable, PRIORITY_RANGE, RelationKind, Status, priority_legend};
/// clap wants a `&str` with a long enough lifetime, and the legend is built from
/// the same ramp the listing uses rather than spelled out a second time.
@@ -43,13 +43,31 @@ pub struct Cli {
/// Reject an empty value at parse time, so it lands as a usage error rather than a
/// runtime one.
///
/// An empty value looks like a way to clear a field, and clearing is not supported
/// yet. Refusing it keeps the gap visible and stops an accidentally empty variable
/// from silently blanking a field. Only the scalars use this: for the multi-line
/// sections an empty value is a paragraph break.
/// Two messages rather than one, because the arguments that use this fall into two
/// kinds. A search term or a title has no empty form at all, and that is all this says.
/// A field that *can* be emptied says so and names `--clear`, which is [`clearable`]
/// below: an accidentally empty variable must not blank a field silently, and somebody
/// typing an empty value on purpose is reaching for exactly the flag that does it.
///
/// Only the scalars use either one. For the multi-line sections an empty value is a
/// paragraph break.
fn non_empty(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty, and clearing a field is not supported yet".to_string());
return Err("value cannot be empty".to_string());
}
Ok(raw.to_string())
}
/// Reject an empty value on an argument whose field can be cleared, and say how.
///
/// The message names no command, because the arguments that use this belong to three:
/// `set --tags`, `set --due`, `add --due` and the `chown` user. `set` and `chown` both
/// take a `--clear`; `add` does not, and there a field is left unset by omitting the
/// flag, which is what the caller was reaching for anyway.
fn clearable(raw: &str) -> Result<String, String> {
if raw.trim().is_empty() {
return Err("value cannot be empty, use --clear to return a field to unset".to_string());
}
Ok(raw.to_string())
@@ -73,7 +91,7 @@ fn non_empty(raw: &str) -> Result<String, String> {
fn iso_date(raw: &str) -> Result<String, String> {
// An empty value keeps the message that explains why it is refused, since somebody
// typing it is reaching for a way to clear the field rather than mistyping a date.
non_empty(raw)?;
clearable(raw)?;
let bytes = raw.as_bytes();
let shaped = raw.len() == 10 && bytes[4] == b'-' && bytes[7] == b'-';
@@ -143,7 +161,7 @@ pub enum Command {
/// Record a relation from one ticket to another
Relate(RelateArgs),
/// Change the owner of a ticket
/// Change the owner of a ticket, or return it to unset
///
/// User first, ticket second, after Unix `chown`. That reverses the ticket-first
/// order `mv`, `comment` and `show` use, deliberately: the name borrows the Unix
@@ -154,14 +172,7 @@ pub enum Command {
/// username usually will not, so the call fails on its own. It is silently wrong
/// only when both arguments resolve, which needs a ticket whose title matches the
/// username.
Chown {
/// New owner. Free text, like `add --owner`, checked against nothing
#[arg(value_parser = non_empty)]
user: String,
/// Ticket UUID or title
ticket: String,
},
Chown(ChownArgs),
/// Open the board view
Tui {
@@ -361,7 +372,7 @@ pub struct AddArgs {
clap::ArgGroup::new("set_fields")
.required(true)
.multiple(true)
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority"])
.args(["title", "description", "acceptance", "plan", "tags", "due", "priority", "clear"])
))]
pub struct SetArgs {
/// Ticket UUID or title
@@ -384,7 +395,7 @@ pub struct SetArgs {
pub plan: Vec<String>,
/// Replace the tags
#[arg(short = 'g', long, value_parser = non_empty)]
#[arg(short = 'g', long, value_parser = clearable)]
pub tags: Vec<String>,
/// Replace the due date (YYYY-MM-DD)
@@ -398,6 +409,82 @@ pub struct SetArgs {
/// Replace the priority, 1 (most urgent) to 5 (least)
#[arg(long, value_parser = priority_level)]
pub priority: Option<u8>,
/// Return a field to unset. Repeat the flag for more than one
///
/// The counterpart to the flag it names, and the only way to take a value away: an
/// empty value is a paragraph break for a section and a usage error for a scalar, so
/// neither can spell this. What goes back is what `add` writes for a field it was
/// never given.
///
/// No `title`, which addresses the ticket and names its file, and no `owner`, which
/// is `chown --clear`'s. The reasoning for each is on `util::Clearable`.
#[arg(long, value_name = "FIELD")]
pub clear: Vec<Clearable>,
}
impl SetArgs {
/// A field this call both replaces and clears, if there is one.
///
/// clap cannot express the conflict, because `--clear` carries the field as a value
/// rather than in the flag's own name. So it is checked once here and refused, rather
/// than resolved by whichever of the two happens to be applied last, which is a
/// silent answer to a contradictory call.
pub fn contested(&self) -> Option<Clearable> {
self.clear.iter().copied().find(|field| match field {
Clearable::Due => self.due.is_some(),
Clearable::Tags => !self.tags.is_empty(),
Clearable::Priority => self.priority.is_some(),
Clearable::Description => !self.description.is_empty(),
Clearable::Acceptance => !self.acceptance.is_empty(),
Clearable::Plan => !self.plan.is_empty(),
})
}
}
/// `chown` is the only writer of Owner, so clearing the field has to live here too, and
/// that is what shapes the arguments.
///
/// **`--clear` carries the ticket rather than being a bare flag.** The ticket is the
/// *second* positional, so `chown --clear 1b78a24` with a plain flag would land the
/// ticket in the user's slot, and reading it back out of there is hand-parsing what clap
/// can state outright. The typed call is the same either way; only who checks it differs.
///
/// The two forms are mutually exclusive, and each argument says so, so a call carrying
/// both is a usage error from clap rather than a decision made here.
#[derive(clap::Args)]
pub struct ChownArgs {
/// New owner. Free text, like `add --owner`, checked against nothing
#[arg(value_parser = clearable, required_unless_present = "clear", conflicts_with = "clear")]
pub user: Option<String>,
/// Ticket UUID or title
#[arg(required_unless_present = "clear", conflicts_with = "clear")]
pub ticket: Option<String>,
/// Return the owner to unset on this ticket, which is named here since there is no
/// user to name
#[arg(long, value_name = "TICKET", value_parser = non_empty)]
pub clear: Option<String>,
}
impl ChownArgs {
/// The ticket the call names, and the owner to write on it, `None` being unset.
///
/// `None` for the pair is unreachable while the constraints above hold, and is an
/// error at the call site rather than a panic, so loosening one of them costs a
/// message instead of a crash.
pub fn target(&self) -> Option<(&str, Option<&str>)> {
match (
self.clear.as_deref(),
self.user.as_deref(),
self.ticket.as_deref(),
) {
(Some(ticket), None, None) => Some((ticket, None)),
(None, Some(user), Some(ticket)) => Some((ticket, Some(user))),
_ => None,
}
}
}
/// `append` only offers the sections that hold multiple lines, since appending to a