wc/README.md

# wc: count words in <50 lines of C

## Desiderata

- Simple: Just count words as delimited by spaces, tabs, newlines.
- Allow: reading files, piping to the utility, and reading from stdin.
- Separate utilities for counting different things, like lines and characters, into their own tools.
- Avoid off-by-one errors.
- Linux only.
- Small.

## Comparison with other historical versions wc.

The version in wc/wc.c in this repository sits at 43 lines. It decides to read from stdin if the number of arguments fed to it is otherwise zero, and uses the linux `read` function to read character by character. It doesn't have flags, instead, there are further utilities in the src/extra/ folder for counting characters and lines, sitting at 33 and 35 lines of code, respectively. This version also has little error checking.

[Here](https://github.com/dspinellis/unix-history-repo/blob/Research-V7-Snapshot-Development/usr/src/cmd/wc.c) is a version of wc from UNIX V7, at 86 lines. It allows for counting characters, words and lines. I couldn't find a version in UNIX V6, so I'm guessing this is one of the earliest versions of this program. It decides to read from stdin if the number of arguments fed to it is zero, and reads character by character using the standard C `getc` function.

The busybox version ([git.busybox.net](https://git.busybox.net/busybox/tree/coreutils/wc.c)) of wc sits at 257 lines (162 with comments stripped), while striving to be [POSIX-compliant](https://pubs.opengroup.org/onlinepubs/9699919799/), meaning it has a fair number of flags and a bit of complexity. It reads character by character by using the standard `getc` function, and decides to read from stdin or not using its own `fopen_or_warn_stdin` function. It uses two GOTOs to get around, and has some incomplete Unicode support.

The [plan9](https://9p.io/sources/plan9/sys/src/cmd/wc.c) version implements some sort of table method in 331 lines. It uses plan9 rather than Unix libraries and methods, and seems to read from stdin if the number of args is 0.

The plan9port version of wc ([github](https://github.com/9fans/plan9port/blob/master/src/cmd/wc.c)) also implements some sort of table method, in 352 lines. It reads from stdin if the number of args is 0, and uses the Linux `read` function to read character by character.

The [FreeBSD version](https://cgit.freebsd.org/src/tree/usr.bin/wc/wc.c) sits at 367 lines. It has enough new things that I can't parse all that it's doing: in lines 137-143, what is capabilities mode? what is casper?, but otherwise it decides whether to read from stdin by the number of arguments, in line 157. It uses a combination of fstat and read, depending on the type of file.

Finally, the GNU utils version ([github](https://github.com/coreutils/coreutils/tree/master/src/wc.c), [savannah](http://git.savannah.gnu.org/gitweb/?p=coreutils.git;a=blob;f=src/wc.c;hb=HEAD)) is a bit over 1K lines of C. It does many things and checks many possible failure modes. I think it detects whether it should be reading from stdin using some very wrapped fstat, and it reads character by character using its own custom function.

So this utility started out reasonably small, then started getting more and more complex. [The POSIX committee](https://pubs.opengroup.org/onlinepubs/9699919799/) ended up codifying that implementation, and now we are stuck with it because even implementations like busybox which strive to be quite small try to keep to POSIX.

## Usage examples

```
echo "En un lugar de la Mancha" | ww
cat README.md | ww
ww README.md 
ww # write something, then exit with Ctrl+D
```

## Relationship with cat-v

Does one really need to spend 1k lines of C code to count characters, words and lines? There are many versions of this rant one could give, but the best and probably best known is [this one](to do: locate) by cat-v, named for the explosion of options. 

[ add sad busybox comment on its cat implementation ] 

## Steps:

- [x] Look into how C utilities both read from stdin and from files.
- [x] Program first version of the utility
- [x] Compare with other implementations, see how they do it, after I've created my own version
  - [x] Compare with gnu utils.
    
  - [x] Compare with busybox implementation
  - Compare with other projects: <https://github.com/leecannon/zig-coreutils>, <https://github.com/keiranrowan/tiny-core/tree/master>.
- [x] Install to ww, but check that ww is empty (installing to wc2 or smth would mean that you don't save that many keypresses vs wc -w)
- [x] Look specifically at how other versions do stuff.
  - [x] Distinguish between reading from stdin and reading from a file
    - If it doesn't have arguments, read from stdin. 
  - [x] Open files, read characters.
- [x] Write version that counts lines (lc)
  - [ ] Take into account what happens if file doesn't end in newline.
  - [ ] Count EOF as word & line separator
  - [ ] Document it
- [ ] Document reading from user-inputed stdin (end with Ctrl+D)
- [ ] Possible follow-up: Write simple versions for other coreutils. <https://git.busybox.net/busybox/tree/coreutils/>? Would be a really nice project. 
  - Get it working on a DuskOS/CollapseOS machine? Or, find a minimalistic kernel that could use them?
- [ ] add chc, or charcounter (cc is "c compiler")
- [ ] Pitch to lwn.net?

Discarded:

- ~~[ ] Could use zig? => Not for now~~
- ~~Maybe make some pull requests, if I'm doing something better? => doesn't seem like it~~
- ~~[ ] Write man files?~~