mirror of
https://github.com/stedolan/jq.git
synced 2024-05-11 05:55:39 +00:00
Add fixes for manual (#2391)
This commit is contained in:
Benjamin Wuethrich
committed by
GitHub
GitHub
parent
a87dca3c87
commit
e066172aa1
@ -3114,16 +3114,16 @@ sections:
|
||||
entries:
|
||||
- title: "Update-assignment: `|=`"
|
||||
body: |
|
||||
This is the "update" operator '|='. It takes a filter on the
|
||||
This is the "update" operator `|=`. It takes a filter on the
|
||||
right-hand side and works out the new value for the property
|
||||
of `.` being assigned to by running the old value through this
|
||||
expression. For instance, (.foo, .bar) |= .+1 will build an
|
||||
object with the "foo" field set to the input's "foo" plus 1,
|
||||
and the "bar" field set to the input's "bar" plus 1.
|
||||
expression. For instance, `(.foo, .bar) |= .+1` will build an
|
||||
object with the `foo` field set to the input's `foo` plus 1,
|
||||
and the `bar` field set to the input's `bar` plus 1.
|
||||
|
||||
The left-hand side can be any general path expression; see `path()`.
|
||||
|
||||
Note that the left-hand side of '|=' refers to a value in `.`.
|
||||
Note that the left-hand side of `|=` refers to a value in `.`.
|
||||
Thus `$var.foo |= . + 1` won't work as expected (`$var.foo` is
|
||||
not a valid or useful path expression in `.`); use `$var |
|
||||
.foo |= . + 1` instead.
|
||||
@ -3156,41 +3156,52 @@ sections:
|
||||
body: |
|
||||
|
||||
This is the plain assignment operator. Unlike the others, the
|
||||
input to the right-hand-side (RHS) is the same as the input to
|
||||
the left-hand-side (LHS) rather than the value at the LHS
|
||||
input to the right-hand side (RHS) is the same as the input to
|
||||
the left-hand side (LHS) rather than the value at the LHS
|
||||
path, and all values output by the RHS will be used (as shown
|
||||
below).
|
||||
|
||||
If the RHS of '=' produces multiple values, then for each such
|
||||
If the RHS of `=` produces multiple values, then for each such
|
||||
value jq will set the paths on the left-hand side to the value
|
||||
and then it will output the modified `.`. For example,
|
||||
`(.a,.b)=range(2)` outputs `{"a":0,"b":0}`, then
|
||||
`(.a,.b) = range(2)` outputs `{"a":0,"b":0}`, then
|
||||
`{"a":1,"b":1}`. The "update" assignment forms (see above) do
|
||||
not do this.
|
||||
|
||||
This example should show the difference between '=' and '|=':
|
||||
This example should show the difference between `=` and `|=`:
|
||||
|
||||
Provide input '{"a": {"b": 10}, "b": 20}' to the programs:
|
||||
Provide input `{"a": {"b": 10}, "b": 20}` to the programs
|
||||
|
||||
.a = .b
|
||||
|
||||
and
|
||||
|
||||
.a |= .b
|
||||
|
||||
The former will set the "a" field of the input to the "b"
|
||||
field of the input, and produce the output {"a": 20, "b": 20}.
|
||||
The latter will set the "a" field of the input to the "a"
|
||||
field's "b" field, producing {"a": 10, "b": 20}.
|
||||
The former will set the `a` field of the input to the `b`
|
||||
field of the input, and produce the output `{"a": 20, "b": 20}`.
|
||||
The latter will set the `a` field of the input to the `a`
|
||||
field's `b` field, producing `{"a": 10, "b": 20}`.
|
||||
|
||||
Another example of the difference between '=' and '|=':
|
||||
examples:
|
||||
- program: .a = .b
|
||||
input: '{"a": {"b": 10}, "b": 20}'
|
||||
output: '{"a":20,"b":20}'
|
||||
|
||||
null|(.a,.b)=range(3)
|
||||
- program: .a |= .b
|
||||
input: '{"a": {"b": 10}, "b": 20}'
|
||||
output: '{"a":10,"b":20}'
|
||||
|
||||
outputs '{"a":0,"b":0}', '{"a":1,"b":1}', and '{"a":2,"b":2}',
|
||||
while
|
||||
- program: (.a, .b) = range(3)
|
||||
input: 'null'
|
||||
output:
|
||||
- '{"a":0,"b":0}'
|
||||
- '{"a":1,"b":1}'
|
||||
- '{"a":2,"b":2}'
|
||||
|
||||
null|(.a,.b)|=range(3)
|
||||
|
||||
outputs just '{"a":0,"b":0}'.
|
||||
- program: (.a, .b) |= range(3)
|
||||
input: 'null'
|
||||
output: '{"a":0,"b":0}'
|
||||
|
||||
- title: Complex assignments
|
||||
body: |
|
||||
@ -3244,14 +3255,14 @@ sections:
|
||||
|
||||
Paths in the a search path are subject to various substitutions.
|
||||
|
||||
For paths starting with "~/", the user's home directory is
|
||||
substituted for "~".
|
||||
For paths starting with `~/`, the user's home directory is
|
||||
substituted for `~`.
|
||||
|
||||
For paths starting with "$ORIGIN/", the path of the jq executable
|
||||
is substituted for "$ORIGIN".
|
||||
For paths starting with `$ORIGIN/`, the path of the jq executable
|
||||
is substituted for `$ORIGIN`.
|
||||
|
||||
For paths starting with "./" or paths that are ".", the path of
|
||||
the including file is substituted for ".". For top-level programs
|
||||
For paths starting with `./` or paths that are `.`, the path of
|
||||
the including file is substituted for `.`. For top-level programs
|
||||
given on the command-line, the current directory is used.
|
||||
|
||||
Import directives can optionally specify a search path to which
|
||||
@ -3264,36 +3275,36 @@ sections:
|
||||
Null and empty string path elements terminate search path
|
||||
processing.
|
||||
|
||||
A dependency with relative path "foo/bar" would be searched for in
|
||||
"foo/bar.jq" and "foo/bar/bar.jq" in the given search path. This
|
||||
A dependency with relative path `foo/bar` would be searched for in
|
||||
`foo/bar.jq` and `foo/bar/bar.jq` in the given search path. This
|
||||
is intended to allow modules to be placed in a directory along
|
||||
with, for example, version control files, README files, and so on,
|
||||
but also to allow for single-file modules.
|
||||
|
||||
Consecutive components with the same name are not allowed to avoid
|
||||
ambiguities (e.g., "foo/foo").
|
||||
ambiguities (e.g., `foo/foo`).
|
||||
|
||||
For example, with `-L$HOME/.jq` a module `foo` can be found in
|
||||
`$HOME/.jq/foo.jq` and `$HOME/.jq/foo/foo.jq`.
|
||||
|
||||
If "$HOME/.jq" is a file, it is sourced into the main program.
|
||||
If `$HOME/.jq` is a file, it is sourced into the main program.
|
||||
|
||||
entries:
|
||||
- title: "`import RelativePathString as NAME [<metadata>];`"
|
||||
body: |
|
||||
|
||||
Imports a module found at the given path relative to a
|
||||
directory in a search path. A ".jq" suffix will be added to
|
||||
directory in a search path. A `.jq` suffix will be added to
|
||||
the relative path string. The module's symbols are prefixed
|
||||
with "NAME::".
|
||||
with `NAME::`.
|
||||
|
||||
The optional metadata must be a constant jq expression. It
|
||||
should be an object with keys like "homepage" and so on. At
|
||||
this time jq only uses the "search" key/value of the metadata.
|
||||
should be an object with keys like `homepage` and so on. At
|
||||
this time jq only uses the `search` key/value of the metadata.
|
||||
The metadata is also made available to users via the
|
||||
`modulemeta` builtin.
|
||||
|
||||
The "search" key in the metadata, if present, should have a
|
||||
The `search` key in the metadata, if present, should have a
|
||||
string or array value (array of strings); this is the search
|
||||
path to be prefixed to the top-level search path.
|
||||
|
||||
@ -3302,13 +3313,13 @@ sections:
|
||||
|
||||
Imports a module found at the given path relative to a
|
||||
directory in a search path as if it were included in place. A
|
||||
".jq" suffix will be added to the relative path string. The
|
||||
`.jq` suffix will be added to the relative path string. The
|
||||
module's symbols are imported into the caller's namespace as
|
||||
if the module's content had been included directly.
|
||||
|
||||
The optional metadata must be a constant jq expression. It
|
||||
should be an object with keys like "homepage" and so on. At
|
||||
this time jq only uses the "search" key/value of the metadata.
|
||||
should be an object with keys like `homepage` and so on. At
|
||||
this time jq only uses the `search` key/value of the metadata.
|
||||
The metadata is also made available to users via the
|
||||
`modulemeta` builtin.
|
||||
|
||||
@ -3316,17 +3327,17 @@ sections:
|
||||
body: |
|
||||
|
||||
Imports a JSON file found at the given path relative to a
|
||||
directory in a search path. A ".json" suffix will be added to
|
||||
directory in a search path. A `.json` suffix will be added to
|
||||
the relative path string. The file's data will be available
|
||||
as `$NAME::NAME`.
|
||||
|
||||
The optional metadata must be a constant jq expression. It
|
||||
should be an object with keys like "homepage" and so on. At
|
||||
this time jq only uses the "search" key/value of the metadata.
|
||||
should be an object with keys like `homepage` and so on. At
|
||||
this time jq only uses the `search` key/value of the metadata.
|
||||
The metadata is also made available to users via the
|
||||
`modulemeta` builtin.
|
||||
|
||||
The "search" key in the metadata, if present, should have a
|
||||
The `search` key in the metadata, if present, should have a
|
||||
string or array value (array of strings); this is the search
|
||||
path to be prefixed to the top-level search path.
|
||||
|
||||
@ -3338,7 +3349,7 @@ sections:
|
||||
metadata that can be read with the `modulemeta` builtin.
|
||||
|
||||
The metadata must be a constant jq expression. It should be
|
||||
an object with keys like "homepage". At this time jq doesn't
|
||||
an object with keys like `homepage`. At this time jq doesn't
|
||||
use this metadata, but it is made available to users via the
|
||||
`modulemeta` builtin.
|
||||
|
||||
@ -3347,7 +3358,7 @@ sections:
|
||||
|
||||
Takes a module name as input and outputs the module's metadata
|
||||
as an object, with the module's imports (including metadata)
|
||||
as an array value for the "deps" key.
|
||||
as an array value for the `deps` key.
|
||||
|
||||
Programs can use this to query a module's metadata, which they
|
||||
could then use to, for example, search for, download, and
|
||||
|
||||
Reference in New Issue
Block a user