jqsh

README

#jqsh

An interactive wrapper to the jq command line utility.

##Install

Download a binary distribution for your system and extract it into your PATH (for example, in "/usr/bin"). Be aware the installation command below varies depending on your system and the current version of jqsh (it is for jqsh0.4 on OS X).

$ sudo tar -C /usr/bin -xvzf jqsh0.4.darwin-amd64.tar.gz

If Go is installed on your system, you can instead compile the latest (unstable) version of jqsh.

$ go get -u github.com/bmatsuo/jqsh

NOTE (Windows users): I have no reason to think jqsh wouldn't build or work on Windows but I don't test on Windows and thus don't provide Windows executables. Feel free to contribute patches for windows compatibility. But, until farther along in the future Windows will remain unofficially supported at best.

##Getting started

Here's an example jqsh session to get a feel for how the shell works. It's good to have some background working with jq. Although it's straight forward enough to not be necessary.

$ jqsh example.json
> .items[].name
> :pop
> .items[]
> select(.message | contains("hello"))
> :quit

Reference documentation is on godoc.org for now.

##Readline

Jqsh lacks advanced editing and history support. Rlwrap can help until support arrives.

$ rlwrap -A -N jqsh

The above command should work on Linux (untested) and OS X.

##Troubleshooting

If you run into bugs or confusing behavior first update to the latest release. If the behavior persists search for related issues.

As a last resort, open an issue. Be as descriptive as possible about your system and the situation in which you experience undesirable behavior.

##Contributing

Everyone is encouraged to make suggestions regarding how they think jqsh could be a better utility. But I'd like to keep development fairly regulated in these early stages. Jqsh is an awesome utility and things could go in a bunch of directions. I just want to make sure it is guided properly and don't want to make big decisions hastily.

If you want to work on something, comment on the issue so that people don't end up working on the same thing by accident.

##License

Copyright (c) 2014 Bryan Matsuo

Jqsh is distributed under the MIT open source license. A copy of the license agreement can be located in the LICENSE file.

Documentation

Overview

Command jqsh provides an interactive wrapper to the jq command line utility.

The filter stack

The core concept in jqsh is a stack of jq "filters". Filters create a larger filter when joined with pipes "|". And maintaining a stack of filters allows exploritory querying of JSON structures.

Filters can be pushed onto the filter stack with ":push" and popped with ":pop".

> :push .[]
> :push .type
> :pop
> :push [.type,.name]
> :pop 2

The corresponding jq filter at each step is

.[]
.[] | .type
.[]
.[] | [.type,.name]
.

Notice that in the last step the stack was emptied with ":pop 2". But jqsh leaves a "." on the stack.

Read more about jq filters at the tool's online manual.

http://stedolan.github.io/jq/manual/#Basicfilters

Shell syntax

The current shell syntax is rudimentory but it suffices. Lines prefixed with a colon ':' are commands, other lines are shorthand for specific commands. Following is a list of all shell syntax in jqsh.

:<cmd> <arg1> <arg2> ...    execute cmd with the given arguments
:<cmd> ... +<argN>          execute cmd with an argument containing spaces (argN)
.                           shorthand for ":write"
..                          shorthand for ":pop"
?<filter>                   shorthand for ":peek +<filter>"
<filter>                    shorthand for ":push +<filter>"

Note that "." is a valid jq filter but pushing it on the filter stack lacks semantic value. So "." alone on a line is used as a shorthand for ":write".

Command reference

A list of commands and other interactive help topics can be found through the "help" command.

> :help

Individual commands respond to the "-h" flag for usage documentation.