The manual's "Defining Functions" section shows only one-argument
functions, so it never says how to pass more than one. This adds a short
paragraph: arguments are separated by `;` in both `def f(a; b):` and
`f(.x; .y)`, and `f(.x, .y)` instead calls a one-argument `f` with the
filter `.x, .y`. It also adds an example for each. `tests/man.test` and
`jq.1.prebuilt` are regenerated.
Fixes#2163
The manual said `a op= b` is equivalent to `a |= . op b`. It is actually
equivalent to `(b as $b | a |= . op $b)`: the right-hand side gets `.`
as input, not the value being updated, and each value it outputs gives a
separate result.
This updates the description and adds two examples, `.a += .b` and `.a
+= (1,2)`. `tests/man.test` and `jq.1.prebuilt` are regenerated.
Fixes#2119, fixes#2407
The manual recommended backslash-escaped double quotes inside the jq
program for all PowerShell versions, but since PowerShell 7.3 native
command arguments are passed with standard quoting by default, so the
backslashes reach jq literally.
Describe the quoting rules separately for Unix shells and PowerShell
7.3+, for older PowerShell and Windows PowerShell, and for cmd.exe, and
update the examples to match.
Enable colored output by default only when the TERM environment variable
is set to a value other than dumb, as git and grep do, so that users no
longer need to pass -M or set NO_COLOR on terminals that cannot display
escape sequences. Colored output is now disabled not only for TERM=dumb
but also when TERM is unset or empty. The -C option still enables colors
in all these cases. On Windows, colored output is still decided by
ANSICON and the console mode, and TERM is not checked.
The date in the .TH line of jq.1.prebuilt changed whenever the manual was
regenerated in a new month, causing merge conflicts between pull requests
that touch the manual, and it did not reflect the release date anyway.
Generate the committed man page without a date.
Stamp the date into jq.1 at build time instead, taking it from the current
commit, or from SOURCE_DATE_EPOCH where that is set, so that release
tarballs and distribution builds still carry one and the behaviour added
in #3514 is kept. Write it in UTC and in ISO 8601 rather than the previous
"%B %Y", for which mandoc reports "cannot parse date, using it verbatim".
`fromdateiso8601` was `strptime("%Y-%m-%dT%H:%M:%SZ") | mktime`, which
accepts only one of the many representations ISO 8601 permits. strptime
cannot be extended to cover the rest portably, since it has no specifier
for fractional seconds and glibc discards `%G` and `%V`.
Replace it with a parser in src/iso8601.c that handles basic and extended
representations, ordinal and week dates, fractional seconds, offsets and
date-only input. It uses integer arithmetic instead of `time_t`, so the
results no longer depend on the platform.
This is stricter than before. Impossible dates like `2015-02-30`, which
`mktime` used to normalize into March, and unpadded components like
`2015-3-5T6:00:00Z` are now errors. So is any trailing input, including
whitespace. Leading whitespace is rejected too; before, glibc skipped it
and macOS did not. A leap second now maps to the second before it rather
than the next minute. The error message has changed, and the result can
now be non-integer.
This commit refactors `splits/2` implementation using `foreach` syntax
and reduces intermediate arrays. This refactoring removes an unnecessary
private (and undocumented) filter `_nwise` and closes#3148.
The introduction says all the usage examples (e.g. of truncate_stream,
etc) in the section use [0,[1]] as input, but they actually use [1,[2]].
["a",["b"]] seems better than [1,[2]] as the string values won't be
confusable with the indexes in <path>.
This comment predates the addition of $ARGS in jq 1.6, so there was no
way to access named arguments with an invalid identifier. Rather than
forbid such names, update the manual to clarify.
I also changed the behavior of limit/2 with negative count to emit an error, like nth/2 does.
Also, I redefined nth/2 using skip/2 to minimize the impact of growth of builtin filters.
* Fix typo in documentation for map_values
"map_value(f)" -> "map_values(f)"
* map_value => map_values also in the devolpment manual
---------
Co-authored-by: Emanuele Torre <torreemanuele6@gmail.com>
This commit temporarily reverts the commit that allows #\ "tcl-style"
comments everywhere and documents them, for the 1.7.1 patch release
cca1f7d18f.
\r is removed from the list of characters not allowed in a comment to
preserve that bugfix.
The description of the Alternative operator `//` was hard for me to grasp in its wording.
I suggest dividing the looong sentence into two parts. Since it is actually an alternative formulation, the sentence can be divided into the first formulation, and the alternative formulation.
* bugfix: comments were incorrectly being terminated by CR; for example
jq -n $'1 #foo\r'
fails to compile because the CR character terminates the comment, and
CR is not a valid character in jq syntax.
* improvement: comments fully support Tcl-style line continuation.
Previously this was only "supported" in `-f' scripts, whose first line
starts with "#!", and second line starts with # and ends with \, only
for the comment on the second line, only for one extra line.
* man: document comment syntax, which was previously undocumented.
* tests: add regression tests for the bugfix, and some tests for line
continuation in comments.
jq previously only allowed passing the inline script before -- (as if
they were options) even though one would expect the inline script to be
a positional argument.
Since jq previously also refused to run with a usage error if the script
was passed after -- (It was not assuming . as script as it does when
no arguments are passed), and positional arguments are allowed before --
and even before other options, it should not be a breaking change to
change that weird behaviour, and allow the script to appear after --.
It also simplifies the option parsing code a bunch.
Fixes#2918
qodelicious