bazel-lib/lib/jq.bzl

"""Public API for jq"""

load("//lib/private:jq.bzl", _jq_lib = "jq_lib")

_jq_rule = rule(
    attrs = _jq_lib.attrs,
    implementation = _jq_lib.implementation,
    toolchains = ["@aspect_bazel_lib//lib:jq_toolchain_type"],
)

def jq(name, srcs, filter = None, filter_file = None, args = [], out = None, **kwargs):
    """Invoke jq with a filter on a set of json input files.

    For jq documentation, see https://stedolan.github.io/jq/.

    To use this rule you must register the jq toolchain in your WORKSPACE:

    ```starlark
    load("@aspect_bazel_lib//lib:repositories.bzl", "register_jq_toolchains")
    register_jq_toolchains(version = "1.6")
    ```

    Usage examples:

    ```starlark
    load("@aspect_bazel_lib//lib:jq.bzl", "jq")

    # Remove fields from package.json
    jq(
        name = "no_dev_deps",
        srcs = ["package.json"],
        filter = "del(.devDependencies)",
    )

    # Merge bar.json on top of foo.json
    jq(
        name = "merged",
        srcs = ["foo.json", "bar.json"],
        filter = ".[0] * .[1]",
        args = ["--slurp"],
        out = "foobar.json",
    )

    # Long filters can be split over several lines with comments
    jq(
        name = "complex",
        srcs = ["a.json", "b.json"],
        filter = \"\"\"
            .[0] as $a
            # Take select fields from b.json
            | (.[1] | {foo, bar, tags}) as $b
            # Merge b onto a
            | ($a * $b)
            # Combine 'tags' array from both
            | .tags = ($a.tags + $b.tags)
            # Add new field
            + {\\\"aspect_is_cool\\\": true}
        \"\"\",
        args = ["--slurp"],
    )

    # Load filter from a file
    jq(
        name = "merged",
        srcs = ["foo.json", "bar.json"],
        filter_file = "filter.txt",
        args = ["--slurp"],
        out = "foobar.json",
    )
    ```

    Args:
        name: Name of the rule
        srcs: List of input json files
        filter: Filter expression (https://stedolan.github.io/jq/manual/#Basicfilters)
        filter_file: File containing filter expression (alternative to `filter`)
        args: Additional args to pass to jq
        out: Name of the output json file; defaults to the rule name plus ".json"
        **kwargs: Other common named parameters such as `tags` or `visibility`
    """
    if not out:
        out = name + ".json"

    _jq_rule(
        name = name,
        srcs = srcs,
        filter = filter,
        filter_file = filter_file,
        args = args,
        out = out,
        **kwargs
    )