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()
    ```

    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",
    )

    # Convert genquery output to json
    genquery(
        name = "deps",
        expression = "deps(//some:target)",
        scope = ["//some:target"],
    )

    jq(
        name = "deps_json",
        srcs = [":deps"],
        args = [
            "--raw-input",
            "--slurp",
        ],
        filter = "{ deps: split(\"\\n\") | map(select(. | length > 0)) }",
    )
    ```

    Args:
        name: Name of the rule
        srcs: List of input 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`
    """
    default_name = name + ".json"
    if not out and not default_name in srcs:
        out = default_name

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