docs(assert): correct the assert_true guidance — arguments need an eval prefix

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

[Chemaclass]

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a single command word. It never splits on whitespace, so test -d /tmp is looked up as a command literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not assumed:

assert_true "my_function"# bare name
assert_true "eval test -d /tmp"# arguments need eval
assert_true "eval [ -d /tmp ]"# brackets work too, with eval

The eval prefix is already a supported branch in run_command_or_eval — it was simply never documented, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.