What is the actual purpose of GNU grep's -X option and why is it undocumented?

Question

By reading this question, I have discovered that GNU grep has a -X option which expects an argument. Strangely, it is mentioned neither in the man page nor in the info page.

Looking at the source code, there is that comment right in the middle of the --help output:

/* -X is deliberately undocumented.  */

Looking further, it appears that the -X matcher option sets the engine used for the regexp, matcher being one of grep, egrep, fgrep, awk, gawk, posixawk and perl (as of version 2.25).

Some of those values are strictly identical to existing options (namely grep -G, grep -E, grep -F and grep -P). On the other hand, the three awk variants have no corresponding options.

Does someone know what is the actual purpose of this option, especially with one of the awk regexp engines? Can someone tell me why it is purposely not documented?

Answer 1

Its purpose is to provide access to the various matchers implemented in GNU grep in one form or another, in particular AWK matchers which aren’t available otherwise, probably for testing purposes (see bug 16481 which discusses adding the gawk and posixawk matchers).

However it is currently buggy, which is the reason why it’s documented as being undocumented:

On Thu, Jan 27, 2005 at 04:06:04PM -0500, Charles Levert wrote:
> The '-X' option, and in particular its use with the "awk" matcher
> ("-X awk") is undocumented.

please leave it undocumented.

It doesn't provide any new functionality besides -X awk.

And the implementation of awk regexps is not perfect, I think.

The new GNU regex conatins some means to set AWK style syntax, yes. Yet gawk doesn't use it directly: it parses the regex first.

In particular, awk regexps allow escape sequences \NNN, where NNN is an octal value. So /\040/ mathes space. grep -X awk doesn't seem to support this.

I'm afraid that regex.c doesn't support these escape sequences.

We would have to make sure that the regexes are fully compatible with awk regexes before we decided to document (and thus support) this feature.

I think it's not worth the trouble.

Stepan

A follow-up asked for the comment to be added, and provided a bit more background on the -X option:

My own inclination is to suggest just removing -X entirely. I suspect it was added by the original author mainly for testing purposes. If it's going to stay in, at least add a comment like this.

/* -X is undocumented on purpose. */

to avoid future discussion of a resolved issue.

Arnold

which Stepan did shortly thereafter.