# jq [jq](https://stedolan.github.io/jq/) is an open source command-line JSON processor with over 126 contributors. ## Readme The Readme.md contains information about pipeline status, installation and configuration of jq. Also there are references to their official documentation, such as releases. A link to their StackOverflow and Liberia in case the reader has questions is found at the bottom of the page. ## Status The project has not received any updates since the end of May 2022 and the newest release is [jq 1.6](https://github.com/stedolan/jq/releases/tag/jq-1.6) which was published in November of 2018. ## Founder The original founder of jq is [Stephen Dolan](https://github.com/stedolan). Dolan has a lot of other projects and contributions. His most recent contributions (state: Apr. 2023) have been to the [OCaml](https://github.com/ocaml) language system. ## Maintainer The *AUTHORS* file mention Nicolas Williams and William Langford as maintainers. ## Hosting JQ is hosted on GitHub. Dolan has his own subdomain, which he uses for hosting the documentation: [https://stedolan.github.io/jq/](https://stedolan.github.io/jq/) ## Homepage There is no real homepage, but there is documentation of the product, that sort of acts like one: [https://stedolan.github.io/jq/](https://stedolan.github.io/jq/) ## Compatibility Jq is compatible with most operating systems. The pipeline is failing for the most recent commits, but the [latest release](https://github.com/stedolan/jq/releases/tag/jq-1.6) is built for 32- and 64-bit Linux, amd64 Mac OS and 32- and 64-bit Windows. There is no notice about ARM compatibility. But since is a "compile-ios.sh" script in the gits root directory which contains the following lines: ```bash for arch in i386 x86_64 armv7 armv7s arm64; do ... done ``` This implies, that arm compatibility is given. ## License Jq itself does not have a named license, but given the articulation it conforms to the MIT License with Stephen Dolan himself in the Copyright notice. The documentation (everything under *doc/*) is licensed under [Creative Commons CC BY 3.0](https://creativecommons.org/licenses/by/3.0/). Parts of jq are licensed differently: * dtoa.c * Copyright (c) 1991, 2000, 2001 by Lucent Technologies * Author David M. Gay * License Unknown * g_fmt.c * Copyright (c) 1991, 1996 by Lucent Technologies (David M. Gay) * Author David M. Gay * License Unknown * decNumber * Copyright (c) 1995-2005 International Business Machines Corporation and others * License Unknown ## UI Jq does not have a UI per se, since it is a commandline tool, like grep, sed or tee. ## Origin Over a decade ago, jq has been started. The origin of jq begins on **Wed Jul 18 20:57:59 2012** with the initial commit (eca89acee00faf6e9ef55d84780e6eeddf225e5c). ## Programming Languages Most of jq has been written in **C** (93.5%). It also has some **M4** (2.3%), **Yacc** (1.3%), **Shell** (1.0%) and **jq** (0.9%). There are also **Makefiles** and other smaller files, which combined make up 0.5%. ## Configuration The project is built with GNU Make: ```bash autoreconf -fi # if building from git ./configure --with-oniguruma=builtin make -j8 make check ``` ## Development Environment There are no IDEs needed to develop within the project. Vim/Neovim or nano are more than enough to write sourcecode here. ## Documentation Documentation of jq is build in Python. The templating engine [jinja2](https://jinja.palletsprojects.com/en/3.1.x/), such as markdown and yaml modules are used to build a website from the documentation source files. ## Users Jq has lots of users distributed among the world. There is no way of telling how many exactly, but the size of the project implies, that it may be at least hundreds of thousands of users. 24.7 thousand people alone have starred the project on GitHub. ## Forks Jq has been forked by 1.4 thousand people with the most starred one being [jq's maintainers version](https://github.com/jqmaintainers/jq). Even though the project is very popular and often forked, the most starred fork only has eight stars and most of them have none at all. ## Contributing To contribute to jq, you have to clone the project and hand in an issue. You can either create an issue or use an existing one. Usually, you will find a bug or a feature request already in the issues, so creating a new one is hardly wanted. Next, you create a branch for your project on which you will develop. You can create a pull request with your changes in this issue and communicate with the maintainers what you have to change in order to have your commits merged. The project has over 681 issues and 131 pull requests, so it might be a little optimistic to think that the request will eventually be merged. ## Git Workflow The project currently has 17 branches. Each branch is a short description of the bug or feature that is being implemented/fixed. Bugs usually start with *bugfix/* and releases are also kept in a seperate branch. The default branch in jq is *master*. There is no *stable* or *next* branch. ## Installation Installing and compiling jq from source can easily be done on the commandline: ```bash # Compiling git submodule update --init # if building from git to get oniguruma autoreconf -fi # if building from git ./configure --with-oniguruma=builtin make -j8 make check # Installation sudo make install ``` There are also guides for Windows and MacOS, for which a cross-compilation environment is needed. If the workspace is clean, these commands can build the binaries: ```bash # git clean ... autoreconf -i ./configure make distclean scripts/crosscompile ``` There is an [entire section](https://github.com/stedolan/jq/wiki/Cross-compilation) on the wiki where cross compilation is being explained. ## Language The notices and alerts that the programm is giving are in english. There are no other man-pages other than that. ## Example Usage: `jq [OPTIONS] [FILES]` An example of how jq can be of use is demonstrated here using a simple example. In this example, the user wants to subscribe to an mqtt broker, but the payload from the topic "telemetry/livingroom/dht11" is returned as a json string: ```bash mosquitto_sub -t telemetry/livingroom/dht11 # {"humidity":45.15715789794922,"temperature_c":20.44152069091797,"temperature_f":68.79473876953125,"timestamp":1681303320640} ``` To better read the message, the user can use jq: ```bash mosquitto_sub -t telemetry/livingroom/dht11 # { # "humidity": 45.15715789794922, # "temperature_c": 20.44152069091797, # "temperature_f": 68.79473876953125, # "timestamp": 1681303320640 # } ``` There is also the possibility, that the user wants to quickly see if a certain element is present in a json file. ```bash jq ".[]|select(.Name==\"Marge Simpson\")" simpsons.json ``` ```json { "Name": "Marge Simpson", "Alter": 34, "Kinder": [ "Bart", "Lisa", "Maggie" ], "Jobs": [ "Hausfrau", "KKW Angestellte", "Polizistin", "Telefonseelsorgerin" ], "Hobbies": [ "Malen", "Zeichnen" ] } ``` This example is from [wiki.ubuntuusers.de](https://wiki.ubuntuusers.de/jq/) and there are many more usages of jq.