~infinitary/qsh

Welcome to Q//

Q//, also known as the Q Shell, is a set of command-line tools designed for maximum orthogonality and interoperability. It aims at bringing pipes closer to their potential while avoiding suboptimal, multi-purpose tools with lossy, text-based communication. Basically, it's like the Unix toolbox with a JSON-ified pipeline and stringent specialisation.

Installation

Q// is licensed under GNU GPL with the sources available via the website at https://infinitary.org/qsh. Executable binaries are also provided for select platforms on the Q// website. Hence, in the more convenient way...

Download the executable binary for your platform
Put the binary into a directory that's in your PATH
Type q and marvel at its clarity, elegance and power

Alternatively, you can build your own binary by downloading the Q// sources, installing Crystal from https://crystal-lang.org and calling make in the root folder of the Q// project. The current version of Q// is UNIX derivate-friendly, it may provide a suboptimal experience when used on other kinds of operating systems.

Usage

To try the replacement of the ls command, type

$ q list

Within the q shell // (two consecutive slashes) are the equivalent of the | pipe operator. To more or less replicate the ls -R command, type

$ q directory // list

The q shell wrapper will find shortened commands when unambiguous, hence instead of the above you may also type

$ q d // l

A more involved, powerful yet simple example, to list the ten largest files under the current directory type

$ q d // l // s size // t // p size path

The available commands as of Q// version 0.1.1 are

checksum
directory
head
inspect
list
print
sort
tail
q

For the available options call any command with the --help (or -h or -?) option, e.g. to get help on list type

$ q l -h

Documentation

Coming soon. Or not soon. But coming nonetheless.

Sundry

Why is it called Q//?

Because Q rhymes with queue and I needed a single letter command that's not in use yet. Also, the Q key sits comfortably under the left pinky so it's easy and quick to hit. And the // operator is to avoid colliding with the unix pipe symbol, with the same ease of typing, under the right pinky (sorry, people on non-US keyboards, your life sucks anyways).

Why the separation of directory and list?

Because of orthogonality. Get used to it, feel the power and thank me later :-)

Why the weird commands?

I undertake all efforts to keep commands on single letters for efficient use, so sometimes alternatives are needed. Also, the way things started off, commands are preferably nouns, with the odd verb as exception.

Where do I find more trivia?

Check the website at https://infinitary.org/qsh.

License

Q// is free software: you can redistribute and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Q// is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Refer to the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Q//. If not, see the GNU website at https://www.gnu.org/licenses. Further information you find on the Q// website at https://infinitary.org/qsh.

refs