Why does the -ls- command also accept Unix-style command flags as options?

[Archibald Dunlop]

Everyone is likely familiar with Stata's ls command, which lists the files in the current directory, just like the Unix command ls. In the help file for Stata's ls there is only one option with ls, wide. However, I've found that Stata's ls also accepts the very same Unix-style command flags that one can use with ls in their terminal:

. ls -t    // sort by modification time
. ls -S    // sort by file size
. ls -1    // force output to one entry per line
. ls -a    // do not ignore entries starting with . (invisibles)

However they do not work in conjunction with filename search patterns:

. ls -t *.ado
invalid '*'
r(198);

. ls *.dta -S
invalid '-'
r(198);

. ls -t raw_data/
invalid 'raw_data'
r(198);

. ls raw_data/

total 0
-rw-r--r--  1 adunlop  staff  107928278317 Apr 26 22:17 datadump.csv

and I've never seen another Stata function style its options this way. What is behind this? Wouldn't this implementation require a very different type of syntax parsing than for comma-style options? I do notice that it is a Stata built-in, so perhaps it isn't coded in ado or even mata. But it also doesn't seem to be a direct pass-thru to my shell's ls because it can't handle (for instance) zsh glob qualifiers. For example, if I use the zsh glob qualifier to show the last 5 files based on modification date:

. ls *(D.om[1,5])
invalid '('
r(198);

but if I use my operating system's ls through shell with the same syntax:

. shell ls *.ado(D.om[1,5])

some_prog.ado
some_other_prog.ado
another_prog.ado
one_more_program.ado
an_additional_program.ado

it works as expected just like in my terminal. Does anyone have an explanation or similar experience? My question is perhaps not one of critical importance; it just comes from a very curious party.

[Archibald Dunlop]

Upon further investigation I've noticed that the help file for both dir and ls exists at "`:sysdir BASE'd/dir.sthlp" and includes a line within the starbangs on my copy of StataSE 17(.0.116):

{* *! version 1.1.8  03sep2020}

More importantly; when the usage of an invalid options occurs this error message is produced:

. ls -2

ls: illegal option -- 2
usage: ls [-@ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1%] [file ...]

Perhaps that precise sequence of available options somehow points to a specific implementation of ls.