ELTEST(1)

📦 version 2.9.9.2, in nixpkgs unstable

💅 ELTEST(1) — the test glow-up you didn't know you needed 🎀

okay so bestie, welcome to eltest, a little icon from the General Commands Manual section of your local man pages. she evaluates an expression and tells you the result through her exit status — no talking, just vibes and a number. periodt. ✨

🌸 SYNOPSIS 🌸

eltest expression...

that's it. that's the whole mood. 💖

🦋 DESCRIPTION 🦋

so here's the tea: eltest is basically the generic POSIX test utility[1], except she does not agree with the spec on how ambiguous arguments get parsed. more on that drama below, iykyk. 👀

she supports all the standard test operands, plus all the extensions from GNU test[2], plus a few extensions from the test builtin in bash[3]. the extensions to POSIX test are listed right down there ⬇️.

eltest accepts an arbitrary number of arguments and, if the expression is valid, always returns the result of the expression no matter how complex it is. she's built different fr fr. 💅

✨ Extensions ✨

  • expr1 -a expr2 — test whether expr1 and expr2 are true. if expr1 is false, then expr2 is not evaluated (she's efficient like that, no wasted effort 💀).
  • expr1 -o expr2 — test whether expr1 or expr2 is true. if expr1 is true, then expr2 is not evaluated.
  • -k file — test whether file has the sticky bit. sticky girl summer 🍓.
  • -O file — test whether file is owned by the effective uid of the current process.
  • -U file — as for -O. literally the same thing, she's just being generous with names 🫶.
  • -G file — test whether file's gid is the effective gid of the current process.
  • -N file — test whether file exists and has been modified since it was last read.
  • file1 -nt file2 — test whether file1 has a (strictly) newer modification date than file2.
  • file1 -ot file2 — test whether file1 has a (strictly) older modification date than file2.
  • file1 -ef file2 — test whether file1 and file2 are physically the same file (same device and inode numbers). iconic twin behavior 👯.
  • -v var — test whether the var variable is defined in the current environment.
  • string =~ pattern — tries to match string against extended regular expression pattern. true if any part of string matches pattern; in order to match whole strings, you must anchor pattern with ^ and $ markers. no cap, anchors are mandatory for full-string matches. ⚓

🧚 Argument disambiguation 🧚

unlike test[1] — which has different fixed syntax trees depending on how many arguments it receives, and has undefined behaviour when called with more than 5 arguments (yikes 😬) — eltest accepts any number of arguments and builds her syntax trees on the fly. main character energy only. 👑

but this means expressions such as -n = -n cannot be automatically disambiguated. like, eltest doesn't know there are 3 arguments, so when she reads the first -n she assumes it's an unary operator, then when she reads = she assumes it's the argument to -n, then when she reads the second -n she exits with a syntax error. she tried her best. 😭

doing otherwise would result in a combinatory explosion of possible syntax trees, making it easy for users to trigger unbounded RAM consumption, and turning a simple utility into a programming nightmare. that's the whole reason POSIX test[1] is so restricted. but we don't want the same restrictions, so instead—

eltest provides you with a mechanism to make sure operands are never mistaken for operators. slay. 💅
  • a word that looks like an operator will always be interpreted like an operator. so expressions like -n = -n will result in a syntax error, because the first -n will never be understood as data for the = operator. rules are rules bestie.
  • a word that starts with a \ (backslash) will always be interpreted like data, never like an operator, and the backslash will be removed. this means \-n = \-n is a valid expression testing the equality between the strings -n and -n. 🎀
    • be aware that execline as well as the shell use one backlash for their own unquoting mechanism, so when using backslashes in an execline or shell script, they must be doubled. you would probably need to type something like \\-n = \\-n. (yes, two backslashes. don't @ me. 🙈)
  • so if your script tests equality between $a and $b, and there's a possibility that the contents of these variables look like eltest operators, the proper syntax would be: eltest \\${a} = \\${b}. 💜

note that these details are irrelevant to a huge majority of eltest use cases, because most of the time you only need a simple test such as eltest -r ${file} to check that $file is readable, and there's no possible ambiguity. so don't panic over this. breathe. you're doing great. 🌈

⭐ Notes ⭐

eltest is a replacement for the ill-named, and now deprecated, s6-test(1) program, part of the (just as ill-named) s6-portable-utils[4] package. it is too valuable a utility to be part of a marginal package, and has nothing to do with s6[5]. she outgrew the group chat fr. 🦋

🔥 OPTIONS 🔥

none. 💀 she doesn't need them. queen behavior.

👑 EXIT STATUS 👑

  • 0 — the test is true. slay! ✨
  • 1 — the test is false. it's giving "not today". 😭
  • 100 — wrong usage. skill issue bestie. 💅
  • 101 — internal error (should never happen, warrants a bug-report). literally call the authorities if you see this. 🚨
  • 111 — system call failure.

🫶 SEE ALSO 🫶

this man page is ported from the authoritative documentation at: https://skarnet.org/software/execline/eltest.html — go give it a read, it's the source of truth 🧚

🌟 STANDARDS 🌟

eltest is not suitable as a Single Unix test[1] program, due to the way it disambiguates between arguments and operators, as described in the "Argument diambiguation" section. however — and this is the important part — if you never use arguments that start with a backslash, or that have the same name as an existing operator, then eltest exhibits the same behaviour as test. iykyk. 💖

💐 AUTHORS 💐

  • Laurent Bercot
  • Alexis <flexibeant@gmail.com> (man page port)

and that's the whole page, bestie!! 🎀🦋 this lil rewrite was brought to you by the Debian edition of the manual, dated October 12, 2024 — ELTEST(1) and proud of it. love u, go test some expressions responsibly. 💜✨👑

📦 where this page comes from