Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 2 days 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.
- Host: GitHub
- URL: https://github.com/blacksmoke16/oq
- Owner: Blacksmoke16
- License: mit
- Created: 2019-06-29T02:41:53.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-04T21:44:23.000Z (5 months ago)
- Last Synced: 2024-11-21T11:37:11.738Z (about 1 month ago)
- Topics: cli, crystal, devops-tools, jq, json, portable, xml, yaml
- Language: Crystal
- Homepage: https://blacksmoke16.github.io/oq/
- Size: 173 KB
- Stars: 191
- Watchers: 5
- Forks: 15
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# oq
[](https://crystal-lang.org/)
[](https://github.com/blacksmoke16/oq/actions?query=workflow%3ACI)
[](https://github.com/blacksmoke16/oq/releases)
[](https://snapcraft.io/oq)
[](https://aur.archlinux.org/packages/oq/)
[](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