jqnpm / jqnpm

A package manager built for the command-line JSON processor jq.

jqnpm -- jq package manager

A package manager built for the command-line JSON processor jq as an example implementation. This is experimental software. Want to contribute?

⚠️ This project has been archived

No future updates are planned. Feel free to continue using it, but expect no support.

• Uses only namespaced packages, for example jqnpm install joelpurra/jq-stress, on github.com by default; the example package would automatically be cloned from github.com/joelpurra/jq-stress.
• Uses strict semantic versioning tags.
• Use the packages in the jqnpm wiki - it's easy to create and publish a package of your own. Share your code! 💓

Installation

On Mac with Homebrew

# NOTE: if homebrew-core's jq was installed previously.
brew unlink jq

# NOTE: due to brew formula issues, this always installs a forked jq with package-root support.
brew install joelpurra/joelpurra/jqnpm

On other systems

• Clone or download, then symlink src/jqnpm. There is no build step.
• Requirements: jq 1.5+, bash 4+, git, shUnit2.

Compatibility with jq

• jqnpm was tested with jq-1.5, which is not yet fully compatible with jqnpm.
• For example deep package resolution doesn't work with plain jq. Without this feature, every dependency has to be installed in the package root.
• See also the jqnpm's package-root fork of jq, which fixes these issues.
• The easiest way to get both is to use brew to unlink both jq and jqnpm, then install the jqnpm --devel version which installs the patched versions.

brew tap joelpurra/joelpurra
brew unlink jqnpm
brew unlink jq
brew install jqnpm --devel

Usage

jqnpm help

Example 1

These are the extended steps from the demo animation above.

# Your new project folder.
mkdir my-project
cd my-project/

# Create 'jq.json', 'jq/main.jq', the local '.jq/' folder.
jqnpm init

# Fetch package from github, installs it into '.jq/packages/'.
jqnpm install joelpurra/jq-stress

# Edit your 'jq/main.jq' file with your code.
echo 'import "joelpurra/jq-stress" as Stress; Stress::remove("e")' > jq/main.jq

# 'jqnpm execute' is a wrapper around jq, which also loads dependencies managed by jqnpm.
# **'jqnpm execute' is a workaround until plain jq is up to speed.**
echo '"Hey there!"' | jqnpm execute

Example 2

Example jq/main.jq combining two other packages; jqnpm install joelpurra/jq-zeros && jqnpm install joelpurra/jq-dry.

import "joelpurra/jq-zeros" as Zeros;
import "joelpurra/jq-dry" as DRY;

def fib($n):
    [ 0, 1 ]
    | DRY::repeat(
        $n;
        [
            .[1],
            (
                .[0]
                + .[1]
            )
        ]
    )
    | .[0];

# Get the eighth Fibonacci number, pad it to four (integer) digits.
fib(8)
| Zeros::pad(4; 0)

As this example doesn't expect to read any JSON data, execute it with --null-input/-n as you normally would with jq.

jqnpm execute --null-input

Creating a package

How to create a package of your own, using jqnpm generate. Share your code! 💓

Guidelines

• The smaller package scope the better - it improves reusability through modularity.
• One piece of functionality per package -- each package does only one thing, but does it well.
• The new github repository name should start with jq-, be all lowercase and words are separated by dashes: jq-good-tool. The jq- prefix is to make it easier for others to see which of your repositories are jq packages.
• The jq package name is written in jq.json. It is all lowercase and words are separated by dashes: good-tool. Note that there is no jq- prefix, as jq.json already knows it's package for jq.
• Author information, software license and project links are written in jq.json.

Steps

1. Create a new github repository:

• Choose a name starting with jq-, similar to jq-good-tool.
• Choose the MIT license if you don't have any other preference.

1. On your computer, run jqnpm generate <github username> <package name> "<one sentence to describe the package>":

• <github username> should be obvious.
• <package name> is the same as the git hub repository you just created, for example jq-good-tool.
• "<one sentence to describe the package>" is something snappy, like "This tool solves the worlds problems and can, contrary to a knife, only be used for good!"

1. Push the code to github:

• git commit
• git push
• git tag -a v0.1.0 -m v0.1.0 && git push origin v0.1.0 (assuming your package version is 0.1.0.)

1. Tell the world about it!

---

License

Copyright (c) 2014, 2015, Joel Purra. All rights reserved.

When using jqnpm, comply to at least one of the three available licenses: BSD, MIT, GPL. Please see the LICENSE file for details.