upstream/tools/jq/jq.xml
1<tool id="jq" name="jq" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@" profile="@PROFILE@">
2 <description>query and transform JSON documents</description>
3 <macros>
4 <import>macros.xml</import>
5 </macros>
6 <expand macro="edam"/>
7 <expand macro="requirements"/>
8 <expand macro="version_command"/>
9 <command detect_errors="aggressive"><![CDATA[
10set -euo pipefail;
11env -i "`command -v jq`"
12#if $input_source.mode == "null"
13 --null-input
14#end if
15#if $input_options.raw_input
16 '$input_options.raw_input'
17#end if
18#if $input_options.slurp
19 '$input_options.slurp'
20#end if
21#if $output_options.raw_output or $output_options.tsv_output
22 --raw-output
23#end if
24#if $output_options.compact_output
25 '$output_options.compact_output'
26#end if
27#if $output_options.ascii_output
28 '$output_options.ascii_output'
29#end if
30#if $output_options.sort_keys
31 '$output_options.sort_keys'
32#end if
33#if $output_options.indentation.mode == "tabs"
34 --tab
35#else if $output_options.indentation.mode == "spaces"
36 --indent '$output_options.indentation.width'
37#end if
38#if $output_options.exit_status
39 '$output_options.exit_status'
40#end if
41#for $arg in $arguments.named_args
42 --arg '$arg.name' '$arg.value'
43#end for
44#for $arg in $arguments.named_json_args
45 --argjson '$arg.name' '$arg.value'
46#end for
47 --from-file '$jq_filter'
48#if $arguments.positional_arguments.mode == "strings"
49 --args
50 #for $value in $arguments.positional_arguments.string_values
51 '$value.value'
52 #end for
53#else if $arguments.positional_arguments.mode == "json"
54 --jsonargs
55 #for $value in $arguments.positional_arguments.json_values
56 '$value.value'
57 #end for
58#end if
59#if $input_source.mode == "dataset"
60 < '$input_source.input'
61#end if
62 > '$output'
63 ]]></command>
64 <configfiles>
65 <configfile name="jq_filter"><![CDATA[
66$filter
67#if $output_options.tsv_output
68| @tsv
69#end if
70]]></configfile>
71 </configfiles>
72 <inputs>
73 <conditional name="input_source">
74 <param name="mode" type="select" label="Input source">
75 <option value="dataset" selected="true">Use a dataset as jq input</option>
76 <option value="null">Start from scratch and generate a new file</option>
77 </param>
78 <when value="dataset">
79 <param name="input" type="data" format="json,txt" label="Input dataset" help="Provide JSON input, or plain text when using raw-input mode."/>
80 </when>
81 <when value="null"/>
82 </conditional>
83
84 <param name="filter" type="text" area="true" value="." label="jq filter" help="The filter expression to run. Multiline jq programs are supported.">
85 <expand macro="printable_text_sanitizer"/>
86 <validator type="regex" negate="true" message="jq module loading is disabled in Galaxy. Remove import/include directives from the filter.">(?ims)(^|;)\s*(import|include)\s+"</validator>
87 </param>
88
89 <section name="input_options" title="Input options" expanded="false">
90 <param argument="--raw-input" type="boolean" truevalue="--raw-input" falsevalue="" checked="false" label="Read input as plain text" help="Read each input line as a string instead of parsing JSON."/>
91 <param argument="--slurp" type="boolean" truevalue="--slurp" falsevalue="" checked="false" label="Slurp all inputs" help="Read all input values and pass them to the filter as a single array or string."/>
92 </section>
93
94 <section name="output_options" title="Output options" expanded="true">
95 <param argument="--raw-output" type="boolean" truevalue="--raw-output" falsevalue="" checked="false" label="Emit plain-text output" help="Write strings without JSON quotes or escaping. The output dataset datatype switches to txt."/>
96 <param argument="--compact-output" type="boolean" truevalue="--compact-output" falsevalue="" checked="false" label="Compact JSON output" help="Emit one JSON value per line without pretty-print indentation."/>
97 <param argument="--ascii-output" type="boolean" truevalue="--ascii-output" falsevalue="" checked="false" label="Escape non-ASCII characters" help="Write non-ASCII characters using JSON escape sequences."/>
98 <param argument="--sort-keys" type="boolean" truevalue="--sort-keys" falsevalue="" checked="false" label="Sort object keys" help="Sort keys alphabetically in each output object."/>
99 <conditional name="indentation">
100 <param name="mode" type="select" label="Indentation">
101 <option value="default" selected="true">Use jq default indentation</option>
102 <option value="tabs">Indent with tabs</option>
103 <option value="spaces">Indent with a custom number of spaces</option>
104 </param>
105 <when value="default"/>
106 <when value="tabs"/>
107 <when value="spaces">
108 <param argument="--indent" name="width" type="integer" value="4" min="0" max="7" label="Number of spaces" help="jq accepts indentation widths from 0 to 7."/>
109 </when>
110 </conditional>
111 <param argument="--exit-status" type="boolean" truevalue="--exit-status" falsevalue="" checked="false" label="Fail when the last result is false or null" help="Propagate jq's exit-status semantics to the Galaxy job."/>
112 <param name="tsv_output" type="boolean" truevalue="true" falsevalue="" checked="false" label="Append @tsv and mark the output as tabular" help="Adds '| @tsv' to the supplied filter and automatically enables raw output so the resulting dataset is tabular rather than quoted JSON strings."/>
113 </section>
114
115 <section name="arguments" title="Arguments" expanded="false">
116 <repeat name="named_args" title="Named string argument">
117 <param name="name" type="text" label="Argument name" help="Accessible inside jq as $name.">
118 <expand macro="identifier_sanitizer"/>
119 <validator type="regex">[A-Za-z_][A-Za-z0-9_]*</validator>
120 </param>
121 <param name="value" type="text" label="String value" help="Passed to jq with --arg. Single quotes are not supported in this field.">
122 <expand macro="printable_text_sanitizer"/>
123 <validator type="regex" message="Single quotes are not supported in jq argument values.">^[^']*$</validator>
124 </param>
125 </repeat>
126 <repeat name="named_json_args" title="Named JSON argument">
127 <param name="name" type="text" label="Argument name" help="Accessible inside jq as $name.">
128 <expand macro="identifier_sanitizer"/>
129 <validator type="regex">[A-Za-z_][A-Za-z0-9_]*</validator>
130 </param>
131 <param name="value" type="text" area="true" label="JSON value" help="Passed to jq with --argjson. Valid JSON such as {"limit": 3} or [1, 2] is expected.">
132 <expand macro="printable_text_sanitizer"/>
133 <validator type="regex" message="Single quotes are not supported in jq JSON argument values.">^[^']*$</validator>
134 </param>
135 </repeat>
136 <conditional name="positional_arguments">
137 <param name="mode" type="select" label="Positional arguments" help="jq exposes these values through $ARGS.positional.">
138 <option value="none" selected="true">Do not add positional arguments</option>
139 <option value="strings">Pass positional string arguments with --args</option>
140 <option value="json">Pass positional JSON arguments with --jsonargs</option>
141 </param>
142 <when value="none"/>
143 <when value="strings">
144 <repeat name="string_values" title="String argument">
145 <param name="value" type="text" label="String value">
146 <expand macro="printable_text_sanitizer"/>
147 <validator type="regex" message="Single quotes are not supported in jq argument values.">^[^']*$</validator>
148 </param>
149 </repeat>
150 </when>
151 <when value="json">
152 <repeat name="json_values" title="JSON argument">
153 <param name="value" type="text" area="true" label="JSON value">
154 <expand macro="printable_text_sanitizer"/>
155 <validator type="regex" message="Single quotes are not supported in jq JSON argument values.">^[^']*$</validator>
156 </param>
157 </repeat>
158 </when>
159 </conditional>
160 </section>
161 </inputs>
162 <outputs>
163 <data name="output" format="json" label="${tool.name} on ${on_string}">
164 <change_format>
165 <when input="output_options.tsv_output" value="true" format="tabular"/>
166 <when input="output_options.raw_output" value="--raw-output" format="txt"/>
167 </change_format>
168 </data>
169 </outputs>
170 <tests>
171 <test expect_num_outputs="1">
172 <conditional name="input_source">
173 <param name="mode" value="dataset"/>
174 <param name="input" value="simple.json" ftype="json"/>
175 </conditional>
176 <param name="filter" value="."/>
177 <output name="output" file="pretty.json" ftype="json">
178 <assert_contents>
179 <has_n_lines n="4"/>
180 <has_json_property_with_value property="foo" value="42"/>
181 <has_json_property_with_value property="bar" value='"less interesting data"'/>
182 </assert_contents>
183 </output>
184 </test>
185 <test expect_num_outputs="1">
186 <conditional name="input_source">
187 <param name="mode" value="dataset"/>
188 <param name="input" value="list.json" ftype="json"/>
189 </conditional>
190 <param name="filter" value=".[] | [.foo, .bar]"/>
191 <section name="output_options">
192 <param name="tsv_output" value="true"/>
193 </section>
194 <output name="output" file="table.tsv" ftype="tabular">
195 <assert_contents>
196 <has_line line="1123	a"/>
197 <has_line line="6536	b"/>
198 <has_line line="5321	c"/>
199 <has_n_lines n="3"/>
200 </assert_contents>
201 </output>
202 <assert_command>
203 <has_text text="--raw-output"/>
204 </assert_command>
205 </test>
206 <test expect_num_outputs="1">
207 <conditional name="input_source">
208 <param name="mode" value="dataset"/>
209 <param name="input" value="simple.json" ftype="json"/>
210 </conditional>
211 <param name="filter" value="env | keys"/>
212 <output name="output" file="env_keys.json" ftype="json">
213 <assert_contents>
214 <has_text text="[]"/>
215 <not_has_text text="HOME"/>
216 <has_n_lines n="1"/>
217 </assert_contents>
218 </output>
219 <assert_command>
220 <has_text text='env -i "`command -v jq`"'/>
221 </assert_command>
222 </test>
223 <test expect_num_outputs="1">
224 <conditional name="input_source">
225 <param name="mode" value="null"/>
226 </conditional>
227 <param name="filter" value="{sample: $sample}"/>
228 <section name="arguments">
229 <repeat name="named_args">
230 <param name="name" value="sample"/>
231 <param name="value" value="alpha;$(uname)|$HOME&<>"/>
232 </repeat>
233 </section>
234 <output name="output" file="dangerous_string_arg.json" ftype="json">
235 <assert_contents>
236 <has_json_property_with_value property="sample" value='"alpha;$(uname)|$HOME&<>"'/>
237 </assert_contents>
238 </output>
239 <assert_command>
240 <has_text text="--null-input"/>
241 <has_text text="--arg 'sample' 'alpha;$(uname)|$HOME&<>'"/>
242 </assert_command>
243 </test>
244 <test expect_num_outputs="1">
245 <conditional name="input_source">
246 <param name="mode" value="dataset"/>
247 <param name="input" value="simple.json" ftype="json"/>
248 </conditional>
249 <param name="filter" value=".foo"/>
250 <section name="output_options">
251 <param name="raw_output" value="true"/>
252 </section>
253 <output name="output" file="raw_foo.txt" ftype="txt">
254 <assert_contents>
255 <has_line line="42"/>
256 <has_n_lines n="1"/>
257 </assert_contents>
258 </output>
259 <assert_command>
260 <has_text text="--raw-output"/>
261 </assert_command>
262 </test>
263 <test expect_num_outputs="1">
264 <conditional name="input_source">
265 <param name="mode" value="dataset"/>
266 <param name="input" value="simple.json" ftype="json"/>
267 </conditional>
268 <param name="filter" value="."/>
269 <section name="output_options">
270 <param name="compact_output" value="true"/>
271 <param name="sort_keys" value="true"/>
272 </section>
273 <output name="output" file="compact_sorted.json" ftype="json">
274 <assert_contents>
275 <has_json_property_with_value property="bar" value='"less interesting data"'/>
276 <has_json_property_with_value property="foo" value="42"/>
277 <has_n_lines n="1"/>
278 </assert_contents>
279 </output>
280 <assert_command>
281 <has_text text="'--compact-output'"/>
282 <has_text text="'--sort-keys'"/>
283 </assert_command>
284 </test>
285 <test expect_num_outputs="1">
286 <conditional name="input_source">
287 <param name="mode" value="dataset"/>
288 <param name="input" value="simple.json" ftype="json"/>
289 </conditional>
290 <param name="filter" value="."/>
291 <section name="output_options">
292 <conditional name="indentation">
293 <param name="mode" value="spaces"/>
294 <param name="width" value="4"/>
295 </conditional>
296 </section>
297 <output name="output" file="indent4.json" ftype="json">
298 <assert_contents>
299 <has_text text=' "foo": 42,'/>
300 <has_text text=' "bar": "less interesting data"'/>
301 <has_n_lines n="4"/>
302 </assert_contents>
303 </output>
304 <assert_command>
305 <has_text text="--indent '4'"/>
306 </assert_command>
307 </test>
308 <test expect_num_outputs="1">
309 <conditional name="input_source">
310 <param name="mode" value="dataset"/>
311 <param name="input" value="unicode.json" ftype="json"/>
312 </conditional>
313 <param name="filter" value="."/>
314 <section name="output_options">
315 <param name="ascii_output" value="true"/>
316 </section>
317 <output name="output" file="ascii.json" ftype="json">
318 <assert_contents>
319 <has_json_property_with_value property="greeting" value='"Gr\u00fc\u00dfe \ud83d\udc4b"'/>
320 </assert_contents>
321 </output>
322 <assert_command>
323 <has_text text="'--ascii-output'"/>
324 </assert_command>
325 </test>
326 <test expect_num_outputs="1">
327 <conditional name="input_source">
328 <param name="mode" value="dataset"/>
329 <param name="input" value="records.jsonl" ftype="txt"/>
330 </conditional>
331 <param name="filter" value="."/>
332 <section name="input_options">
333 <param name="slurp" value="true"/>
334 </section>
335 <output name="output" file="slurped_records.json" ftype="json">
336 <assert_contents>
337 <has_json_property_with_value property="id" value="1"/>
338 <has_json_property_with_value property="id" value="2"/>
339 <has_n_lines n="8"/>
340 </assert_contents>
341 </output>
342 <assert_command>
343 <has_text text="'--slurp'"/>
344 </assert_command>
345 </test>
346 <test expect_num_outputs="1">
347 <conditional name="input_source">
348 <param name="mode" value="dataset"/>
349 <param name="input" value="lines.txt" ftype="txt"/>
350 </conditional>
351 <param name="filter" value="ascii_upcase"/>
352 <section name="input_options">
353 <param name="raw_input" value="true"/>
354 </section>
355 <output name="output" file="raw_lines.json" ftype="json">
356 <assert_contents>
357 <has_line line='"ALPHA"'/>
358 <has_line line='"BETA"'/>
359 <has_n_lines n="2"/>
360 </assert_contents>
361 </output>
362 <assert_command>
363 <has_text text="'--raw-input'"/>
364 </assert_command>
365 </test>
366 <test expect_num_outputs="1">
367 <conditional name="input_source">
368 <param name="mode" value="null"/>
369 </conditional>
370 <param name="filter" value='{"tool":"jq","status":"ok"}'/>
371 <output name="output" file="generated.json" ftype="json">
372 <assert_contents>
373 <has_json_property_with_value property="tool" value='"jq"'/>
374 <has_json_property_with_value property="status" value='"ok"'/>
375 </assert_contents>
376 </output>
377 <assert_command>
378 <has_text text="--null-input"/>
379 </assert_command>
380 </test>
381 <test expect_num_outputs="1">
382 <conditional name="input_source">
383 <param name="mode" value="null"/>
384 </conditional>
385 <param name="filter" value="{sample: $sample, limit: $config.limit}"/>
386 <section name="arguments">
387 <repeat name="named_args">
388 <param name="name" value="sample"/>
389 <param name="value" value="dataset-1"/>
390 </repeat>
391 <repeat name="named_json_args">
392 <param name="name" value="config"/>
393 <param name="value" value='{"limit": 3}'/>
394 </repeat>
395 </section>
396 <output name="output" file="named_args.json" ftype="json">
397 <assert_contents>
398 <has_json_property_with_value property="sample" value='"dataset-1"'/>
399 <has_json_property_with_value property="limit" value="3"/>
400 </assert_contents>
401 </output>
402 <assert_command>
403 <has_text text="--arg 'sample' 'dataset-1'"/>
404 <has_text text="--argjson"/>
405 <has_text text='{"limit": 3}'/>
406 </assert_command>
407 </test>
408 <test expect_num_outputs="1">
409 <conditional name="input_source">
410 <param name="mode" value="dataset"/>
411 <param name="input" value="simple.json" ftype="json"/>
412 </conditional>
413 <param name="filter" value="$ARGS.positional"/>
414 <section name="arguments">
415 <conditional name="positional_arguments">
416 <param name="mode" value="strings"/>
417 <repeat name="string_values">
418 <param name="value" value="alpha"/>
419 </repeat>
420 <repeat name="string_values">
421 <param name="value" value="beta"/>
422 </repeat>
423 </conditional>
424 </section>
425 <output name="output" file="positional_strings.json" ftype="json">
426 <assert_contents>
427 <has_text text='"alpha"'/>
428 <has_text text='"beta"'/>
429 <has_n_lines n="4"/>
430 </assert_contents>
431 </output>
432 <assert_command>
433 <has_text text="--args"/>
434 </assert_command>
435 </test>
436 <test expect_num_outputs="1">
437 <conditional name="input_source">
438 <param name="mode" value="null"/>
439 </conditional>
440 <param name="filter" value="$ARGS.positional | map(.value)"/>
441 <section name="arguments">
442 <conditional name="positional_arguments">
443 <param name="mode" value="json"/>
444 <repeat name="json_values">
445 <param name="value" value='{"value": 1}'/>
446 </repeat>
447 <repeat name="json_values">
448 <param name="value" value='{"value": 2}'/>
449 </repeat>
450 </conditional>
451 </section>
452 <output name="output" file="positional_json.json" ftype="json">
453 <assert_contents>
454 <has_line line=" 1,"/>
455 <has_line line=" 2"/>
456 <has_n_lines n="4"/>
457 </assert_contents>
458 </output>
459 <assert_command>
460 <has_text text="--jsonargs"/>
461 </assert_command>
462 </test>
463 <test expect_failure="true" expect_exit_code="1">
464 <conditional name="input_source">
465 <param name="mode" value="dataset"/>
466 <param name="input" value="simple.json" ftype="json"/>
467 </conditional>
468 <param name="filter" value=".missing"/>
469 <section name="output_options">
470 <param name="exit_status" value="true"/>
471 </section>
472 <assert_command>
473 <has_text text="--exit-status"/>
474 </assert_command>
475 </test>
476 </tests>
477 <help format="markdown">< inside Galaxy to query, reshape, and transform JSON documents.
479
480**Input modes**
481
482- Use a JSON dataset directly, or enable **Read input as plain text** to process text line by line with jq's `--raw-input`.
483- Switch **Input source** to **Start from null** when you want jq to generate JSON without reading a dataset.
484- **Slurp all inputs** applies jq's `--slurp` behavior, which is useful for newline-delimited JSON.
485- jq module loading via `import` and `include` is intentionally disabled in this Galaxy wrapper.
486
487**Output typing**
488
489- Default output is a JSON dataset.
490- **Emit plain-text output** changes the Galaxy datatype to `txt`.
491- **Append @tsv and mark the output as tabular** appends `| @tsv`, enables raw output automatically, and changes the datatype to `tabular`.
492
493**Examples**
494
495Extract a single field:
496
497```jq
498.foo
499```
500
501Create a tabular projection from an array of objects:
502
503```jq
504.[] | [.foo, .bar]
505```
506
507Generate JSON without an input dataset:
508
509```jq
510{tool: "jq", status: "ok"}
511```
512
513Use named arguments:
514
515```jq
516{sample: $sample, limit: $config.limit}
517```
518
519Use positional arguments:
520
521```jq
522$ARGS.positional
523```
524
525**References**
526
527- jq manual: <https://jqlang.org/manual/>
528- jq project: <https://github.com/jqlang/jq>
529- Auxiliary argument fields do not accept single quotes. Put such literals directly in the jq filter when nee ded.
530 ]]></help>
531 <expand macro="citations"/>
532</tool>