Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

Documentation for @jq.bzl@v0.6.0 — View source
Load in your BUILD file with: 
load("@jq.bzl", "jq")

​
Examples

Create a new file bazel-out/.../no_srcs.json containing some JSON data: 
jq(
    name = "no_srcs",
    srcs = [],
    filter = ".greeting = "Hello, " + $name",
    args = ["--arg" "name" "World"],
)
Remove a field from package.json:
The output path bazel-out/.../package.json matches the path of the source file, which means you must refer to the label :no_dev_deps to reference the output, since Bazel doesn’t provide a label for an output file that collides with an input file. 
jq(
    name = "no_dev_deps",
    srcs = ["package.json"],
    out = "package.json",
    filter = "del(.devDependencies)",
)
Merge data from bar.json on top of foo.json, producing foobar.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 filter.jq, making it easier to edit complex filters: 
jq(
    name = "merged",
    srcs = ["foo.json", "bar.json"],
    filter_file = "filter.jq",
    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)) }",
)
When Bazel is run with --stamp, replace some properties with version control info: 
jq(
    name = "stamped",
    srcs = ["package.json"],
    filter = "|".join([
        # Don't directly reference $STAMP as it's only set when stamping
        # This 'as' syntax results in $stamp being null in unstamped builds.
        "$ARGS.named.STAMP as $stamp",
        # Provide a default using the "alternative operator" in case $stamp is null.
        ".version = ($stamp[0].BUILD_EMBED_LABEL // "<unstamped>")",
    ]),
)
jq is exposed as a “Make variable”, so you could use it directly from a genrule by referencing the toolchain. 
genrule(
    name = "case_genrule",
    srcs = ["a.json"],
    outs = ["genrule_output.json"],
    cmd = "$(JQ_BIN) '.' $(location a.json) > $@",
    toolchains = ["@jq_toolchains//:resolved_toolchain"],
)

​
Rule: jq_rule

Most users should use the jq macro instead.

​
Attributes

​
name
name
required
A unique name for this target.
​
srcs
list of labels
required
​
data
list of labels
default:"[]"
​
filter
string
default:"\"\""
​
filter_file
label
default:"None"
​
args
list of strings
default:"[]"
​
expand_args
boolean
default:"False"
​
out
label
default:"None"
​
stamp
integer
default:"-1"
Whether to encode build information into the output. Possible values:
  • stamp = 1: Always stamp the build information into the output, even in —nostamp builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result.
  • stamp = 0: Never stamp, instead replace build information by constant values. This gives good build result caching.
  • stamp = -1: Embedding of build information is controlled by the —[no]stamp flag. Stamped targets are not rebuilt unless their dependencies change.

​
Function: jq_lib.implementation

​
Parameters

​
ctx
name
required

​
Function: jq_lib.jq_action

Run jq as a Bazel action.

​
Parameters

​
ctx
name
required
The Bazel action context object
​
sources
name
required
The list of source files jq should process
​
filter
name
required
The filter expression string OR a file containing the filter for —from-file
​
out
name
required
The output file
​
args
name
default:"[]"
Additional arguments to jq
​
data
name
default:"[]"
Files jq may need to read at runtime which are referenced in flags like —from-file
Returns: The output file

​
Function: jq

Invoke jq with a filter on a set of json input files.

​
Parameters

​
name
name
required
Name of the rule
​
srcs
name
required
List of input files. May be empty.
​
filter
name
default:"None"
Filter expression (https://jqlang.org/manual/#basic-filters). Subject to stamp variable replacements, see Stamping. When stamping is enabled, a variable named “STAMP” will be available in the filter.Be careful to write the filter so that it handles unstamped builds, as in the example above.
​
filter_file
name
default:"None"
File containing filter expression (alternative to filter)
​
args
name
default:"[]"
Additional args to pass to jq
​
out
name
default:"None"
Name of the output json file; defaults to the rule name plus “.json”
​
data
name
default:"[]"
List of additional files. May be empty.
​
expand_args
name
default:"False"
Run bazel’s location and make variable expansion on the args.
​
kwargs
string_list
Other common named parameters such as tags or visibility

​
Function: jq_test

Assert that the given json files have the same semantic content. Uses jq to filter each file. The default value of "." as the filter means to compare the whole file. See the jq macro for more about the filter expressions as well as setup notes for the jq toolchain. Note that this macro is equivalent to calling bazel_lib’s diff_test with the jq outputs.

​
Parameters

​
name
name
required
name of resulting diff_test target
​
file1
name
required
a json file
​
file2
name
required
another json file
​
filter1
name
default:"."
a jq filter to apply to file1
​
filter2
name
default:"."
a jq filter to apply to file2
​
kwargs
string_list
additional named arguments for the resulting diff_test