Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/Blacksmoke16/oq

A performant, and portable jq wrapper to facilitate the consumption and output of formats other than JSON; using jq filters to transform the data.
https://github.com/Blacksmoke16/oq

cli crystal devops-tools jq json portable xml yaml

Last synced: about 1 month ago
JSON representation

A performant, and portable jq wrapper to facilitate the consumption and output of formats other than JSON; using jq filters to transform the data.

Awesome Lists containing this project

README 

        
# oq



[![Built with Crystal](https://img.shields.io/badge/built%20with-crystal-000000.svg?logo=crystal)](https://crystal-lang.org/)

[![CI](https://github.com/blacksmoke16/oq/workflows/CI/badge.svg)](https://github.com/blacksmoke16/oq/actions?query=workflow%3ACI)

[![Latest release](https://img.shields.io/github/release/blacksmoke16/oq.svg?color=teal&logo=github)](https://github.com/blacksmoke16/oq/releases)

[![oq](https://snapcraft.io/oq/badge.svg)](https://snapcraft.io/oq)

[![oq](https://img.shields.io/aur/version/oq?label=oq&logo=arch-linux)](https://aur.archlinux.org/packages/oq/)

[![oq-bin](https://img.shields.io/aur/version/oq-bin?label=oq-bin&logo=arch-linux)](https://aur.archlinux.org/packages/oq-bin/)



A performant, portable [jq](https://github.com/stedolan/jq/) wrapper that facilitates the consumption and output of formats other than JSON; using `jq` filters to transform the data.



* Compiles to a single binary for easy portability.

* Performant, similar performance with JSON data compared to `jq`.  Slightly longer execution time when going to/from a non-JSON format.

* Supports various other input/output [formats](https://blacksmoke16.github.io/oq/OQ/Format.html), such as `XML` and `YAML`.

* Can be used as a dependency within other Crystal projects.



## Installation



### Linux



A statically linked binary for Linux `x86_64` as available on the [Releases](https://github.com/Blacksmoke16/oq/releases) tab.  Additionally it can also be installed via various package managers.



#### Snapcraft



For more on installing & using `snap` with your Linux distribution, see the [official documentation](https://docs.snapcraft.io/installing-snapd).



```sh

sudo snap install oq

```



#### Arch Linux



Using [yay](https://github.com/Jguer/yay):



```sh

yay -S oq

```



A pre-compiled version is also available:



```sh

yay -S oq-bin

```



### macOS



```sh

brew install oq

```



### From Source



If building from source, `jq` will need to be installed separately. Installation instructions can be found in the [official documentation](https://stedolan.github.io/jq/).



Requires Crystal to be installed, see the [installation documentation](https://crystal-lang.org/install).



```sh

git clone https://github.com/Blacksmoke16/oq.git

cd oq/

shards build --production --release

```



The built binary will be available as `./bin/oq`.  This can be relocated elsewhere on your machine; be sure it is in your `PATH` to access it as `oq`.



### Docker



`oq` can easily be included into a Docker image by fetching the static binary from Github for the version of `oq` that you want.



```dockerfile

# Set an arg to store the oq version that should be installed.

ARG OQ_VERSION=1.3.5



# Grab the binary from the latest Github release and make it executable; placing it within /usr/local/bin.  Can also put it elsewhere if you so desire.

RUN wget https://github.com/Blacksmoke16/oq/releases/download/v${OQ_VERSION}/oq-v${OQ_VERSION}-linux-x86_64 -O /usr/local/bin/oq && chmod +x /usr/local/bin/oq



# Or using curl (needs to follow Github's redirect):

RUN curl -L -o /usr/local/bin/oq https://github.com/Blacksmoke16/oq/releases/download/v${OQ_VERSION}/oq-v${OQ_VERSION}-linux-x86_64 && chmod +x /usr/local/bin/oq



# Also be sure to install jq if it is not already!

```



### Existing Crystal Project



Add the following to your `shard.yml` and run `shards install`.



```yaml

dependencies:

  oq:

    github: blacksmoke16/oq

    version: ~> 1.3.0

```



## Usage



### CLI



Use the `oq` binary, with a few optional custom arguments, see `oq --help`.  All other arguments get passed to `jq`. See [jq manual](https://stedolan.github.io/jq/manual/) for details.



### Library



Checkout the [API Documentation](https://blacksmoke16.github.io/oq/OQ/Processor.html) for using `oq` within an existing Crystal project.



### Examples



Consume JSON and output XML



```sh

$ echo '{"name": "Jim"}' | oq -o xml .



  Jim



```



Consume YAML from a file and output XML



data.yaml



```yaml

---

name: Jim

numbers:

  - 1

  - 2

  - 3

```



```sh

$ oq -i yaml -o xml . data.yaml



  Jim

  1

  2

  3



```



Use `oq` as a library, consuming some raw `JSON` input, convert it to `YAML`, and write the transformed data to a file.



```crystal

require "oq"



# This could be any `IO`, e.g. an `HTTP` request body, etc.

input_io = IO::Memory.new %({"name":"Jim"})



# Create a processor, specifying that we want the output format to be `YAML`.

processor = OQ::Processor.new output_format: :yaml



File.open("./out.yml", "w") do |file|

  # Process the data using our custom input and output IOs.

  # The first argument represents the input arguments;

  # i.e. the filter and/or any other arguments that should be passed to `jq`.

  processor.process ["."], input: input_io, output: file

end

```



## Contributing



1. Fork it ()

2. Create your feature branch (`git checkout -b my-new-feature`)

3. Commit your changes (`git commit -am 'Add some feature'`)

4. Push to the branch (`git push origin my-new-feature`)

5. Create a new Pull Request



## Contributors



- [George Dietrich](https://github.com/Blacksmoke16) - creator, maintainer

- [Michael Springer](https://github.com/sprngr) - contributor