<requirement name="filter-model" stories="CORE-001"> A jq program is a "filter": it takes an input, and produces an output. </requirement> <requirement name="filter-composition" stories="CORE-002"> Filters can be combined in various ways - you can pipe the output of one filter into another filter, or collect the output of a filter into an array. </requirement> <requirement name="stream-values" stories="CORE-001"> Some filters produce multiple results, for instance there's one that produces all the elements of its input array. </requirement> <requirement name="numeric-semantics" stories="VALUE-001"> Numbers in jq are internally represented by their IEEE754 double precision approximation. </requirement> <requirement name="object-access" stories="VALUE-002"> The simplest *useful* filter has the form `.foo`. When given a JSON object (aka dictionary or hash) as input, `.foo` produces the value at the key "foo" if the key is present, or null otherwise. </requirement> <requirement name="array-access-and-iteration" stories="VALUE-003"> When the index value is an integer, `.[<number>]` can index arrays. Arrays are zero-based, so `.[2]` returns the third element. </requirement> <requirement name="slices" stories="VALUE-003"> The `.[<number>:<number>]` syntax can be used to return a subarray of an array or substring of a string. </requirement> <requirement name="lexical-scanning" stories="PARSE-001"> A `#` character (not part of a string) starts a comment. </requirement> <requirement name="literals-and-interpolation" stories="PARSE-002"> Inside a string, you can put an expression inside parens after a backslash. Whatever the expression returns will be interpolated into the string. </requirement> <requirement name="core-filter-grammar" stories="PARSE-003"> The | operator combines two filters by feeding the output(s) of the one on the left into the input of the one on the right. </requirement> <requirement name="advanced-filter-grammar" stories="PARSE-004"> You can give a filter a name using "def" syntax: </requirement> <requirement name="runtime-errors-and-optional-evaluation" stories="CORE-003"> Errors can be caught by using `try EXP catch EXP`. </requirement> <requirement name="truthiness-and-comparison" stories="CORE-004"> The expression 'a == b' will produce 'true' if the results of evaluating a and b are equal (that is, if they represent equivalent JSON values) and 'false' otherwise. </requirement> <requirement name="arithmetic-and-structural-operators" stories="FLOW-001"> The operator `+` takes two filters, applies them both to the same input, and adds the results together. </requirement> <requirement name="boolean-and-default-operators" stories="FLOW-002"> jq supports the normal Boolean operators `and`, `or`, `not`. </requirement> <requirement name="conditionals-and-exception-flow" stories="FLOW-003"> `if A then B else C end` will act the same as `B` if `A` produces a value other than false or null, but act the same as `C` otherwise. </requirement> <requirement name="labels-and-breaks" stories="FLOW-004"> jq has a syntax for named lexical labels to break or go (back) to: </requirement> <requirement name="reductions-and-iteration-control" stories="FLOW-005"> The `reduce` syntax allows you to combine all of the results of an expression by accumulating them into a single answer. </requirement> <requirement name="recursive-generators" stories="FLOW-006"> The `recurse(f)` function allows you to search through a recursive structure, and extract interesting data from all levels. </requirement> <requirement name="variable-bindings" stories="FUNC-001"> jq lets you define variables using `expression as $variable`. </requirement> <requirement name="function-parameters" stories="FUNC-002"> Arguments are passed as _filters_ (functions with no arguments), _not_ as values. </requirement> <requirement name="function-definitions-and-scope" stories="FUNC-003"> It is also possible to define functions in jq, although this is a feature whose biggest use is defining jq's standard library </requirement> <requirement name="destructuring-alternatives" stories="FUNC-004"> The destructuring alternative operator provides a concise mechanism for destructuring an input that can take one of several forms. </requirement> <requirement name="path-discovery-and-projection" stories="PATH-001"> `paths` outputs the paths to all the elements in its input </requirement> <requirement name="path-access-and-mutation" stories="PATH-002"> The builtin function `getpath` outputs the values in `.` found at each path in `PATHS`. </requirement> <requirement name="assignment-operators" stories="PATH-003"> Most users will want to use modification assignment operators, such as `|=` or `+=`, rather than `=`. </requirement> <requirement name="complex-assignments" stories="PATH-004"> Any filter may be used on the left-hand side of an equals - whichever paths it selects from the input will be where the assignment is performed. </requirement> <requirement name="collection-transformations" stories="DATA-001"> For any filter `f`, `map(f)` and `map_values(f)` apply `f` to each of the values in the input array or object, that is, to the values of `.[]`. </requirement> <requirement name="sorting-grouping-and-extrema" stories="DATA-002"> The `sort` functions sorts its input, which must be an array. </requirement> <requirement name="object-entries-and-containment" stories="DATA-003"> These functions convert between an object and an array of key-value pairs. </requirement> <requirement name="index-membership-and-sql-utilities" stories="DATA-004"> The builtin function `has` returns whether the input object has the given key, or the input array has an element at the given index. </requirement> <requirement name="string-manipulation" stories="TEXT-001"> The `split` function splits an input string on the separator argument. </requirement> <requirement name="json-conversion-and-output-formats" stories="TEXT-002"> The `tojson` and `fromjson` builtins dump values as JSON texts or parse JSON texts into values, respectively. </requirement> <requirement name="regular-expression-filters" stories="TEXT-003"> jq uses the [Oniguruma regular expression library](https://github.com/kkos/oniguruma/blob/master/doc/RE), </requirement> <requirement name="date-and-time-filters" stories="TEXT-004"> jq provides some basic date handling functionality, with some high-level and low-level builtins. </requirement> <requirement name="input-stream-controls" stories="IO-001"> Two builtins functions are provided for this, `input` and `inputs`, that read from the same sources </requirement> <requirement name="diagnostics-and-stderr" stories="IO-002"> The `debug` builtin can have as a side-effect the production of one or more messages on stderr. </requirement> <requirement name="streaming-transformations" stories="IO-003"> With the `--stream` option jq can parse input texts in a streaming fashion, allowing jq programs to start processing large JSON texts immediately rather than after the parse completes. </requirement> <requirement name="process-exit-and-errors" stories="EXEC-002"> The given `exit_code` (defaulting to `5`) will be jq's exit status. </requirement> <requirement name="json-input-and-output" stories="EXEC-003"> jq's output values are always output as JSON texts on `stdout`. </requirement> <requirement name="value-types-and-primitives" stories="VALUE-004"> jq supports the same set of datatypes as JSON - numbers, strings, booleans, arrays, objects (which in JSON-speak are hashes with only string keys), and "null". </requirement> <unattached story="architecture-foundation"/> <unattached story="EXEC-001"/> <unattached story="CONF-001"/> <unattached story="CONF-002"/> <unattached story="CONF-003"/>
Run artifact