~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

Executable binaries are provided for select platforms (OS X) on the website at https://infinitary.org/qsh. Hence, in the most convenient way...

Download the executable binary and save it as q
Put the file into a directory that's in your system PATH
Make sure it's executable, chmod +x q if necessary
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 currently available commands of Q// are

$ q
    checksum    Checksum operations to track content changes
    directory   Recursively traverses a directory hierarchy
    filter      Filters items that match certain criteria
    head        Limits the pipeline output to the first items
    inspect     Inspect the names and data types of fields
    list        Lists the contents of one or more directories
    print       Prints fields of items using various formats
    sort        Rearranges the order of the received items
    tail        Limits the pipeline output to the last items
    q           Version, change log and copyright information

For usage information about a specific command, call it with the --help (or -h or -?) option - e.g. to get help on list type

$ q l -h

Documentation

Coming soon. Or not soon. Maybe. Dunno.

Sundry

Why is it called Q//?

Because Q rhymes with queue and I needed a single letter command that's not in use yet as a shell command. 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 spare no effort 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.

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

clone