add readme

This commit is contained in:
James Andariese 2024-04-11 21:27:43 -05:00
parent 8d94ebeece
commit f4a773e425

33
README.md Normal file
View File

@ -0,0 +1,33 @@
# `shq`
`sh` quoting for your `sh` scripts. Or for your rust stuff. Whichever.
## Usage
`shq` is mostly interesting for use when escaping unknown strings so here's
an example of that:
```bash
trap "$(shq echo "your first arg was $1 and your random token was $RANDOM")" 2
```
This will echo your first arg safely as well as a random number
whenever you press Ctrl-C. Significantly, these will be the values at
the time the trap was created.
## How it works
In `sh`, a single quote (`'`) opens a string which may contain any character
other than another single quote. A single quote may be included in a double
quoted string. And finally, two strings may be concatenated by simply
shoving them together. Thus, we get `echo 'this string'"'"'s very cool'`
which produces `this string's very cool`. An alternate version which uses
`echo 'this string'\''s very cool'` is possible. I don't like `\`.
## Comparison to other tools
`coreutils`'s as well as possibly other implementations of the `printf` shell
scripting tool have a %q format specifier which does largely the same
thing as this tool. Some of these use backslashes which may be more or less
compatible with your particular use case than the reliance on single quote
strings.