From 1b8911ad3684f4f9fcdce4f3bd368880813ca0c1 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Fri, 26 Jan 2024 12:25:26 -0800 Subject: [PATCH] add slurp docs --- README.md | 52 +++++++++++++++++++++++++++++++++ man/jc.1 | 60 +++++++++++++++++++++++++++++++++++++- templates/manpage_template | 58 ++++++++++++++++++++++++++++++++++++ templates/readme_template | 52 +++++++++++++++++++++++++++++++++ 4 files changed, 221 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7cad0239..2c013860 100644 --- a/README.md +++ b/README.md @@ -386,6 +386,58 @@ Here is a breakdown of line slice options: | `:-STOP` | lines from the beginning through `STOP` lines from the end | | `:` | all lines | +### Slurp +Some parsers support multi-item input and can output an array of results in a +single pass. Slurping works for string parsers that accept a single line of +input. (e.g. `url` and `ip-address`) To see a list of parsers that support +the `--slurp` option, use `jc -hhh`. + +For example, you can send a file with multiple IP addresses (one per line) to +`jc` with the `--slurp` option and an array of results will output: + +```bash +$ cat ip-addresses.txt | jc --slurp --ip-address +[] +``` + +The magic syntax for `/proc` files automatically supports slurping of multiple +files (no need to use the `--slurp` option). For example, you can convert many +PID files at once: + +```bash +$ jc /proc/*/status +[] +``` + +When the `/proc` magic syntax is used and multiple files are selected, an +additional `_file` field is inserted in the output so it is easier to tell what +file each output object refers to. + +Finally, the `--meta-out` option can be used in conjunction with slurped output. +In this case, the slurped output is wrapped in an object with the following +structure: + +```json +{ + "result": [], + "_jc_meta": { + "parser": "url", + "timestamp": 1706235558.654576, + "slice_start": null, + "slice_end": null, + "input_list": [ + "http://www.google.com", + "https://www.apple.com", + "https://www.microsoft.com" + ] + } +} +``` + +With `--meta-out`, `input_list` contains a list of inputs (actual input strings +or `/proc` filenames) so you can identify which output object relates to each +input string or `/proc` filename. + ### Exit Codes Any fatal errors within `jc` will generate an exit code of `100`, otherwise the exit code will be `0`. diff --git a/man/jc.1 b/man/jc.1 index c6ad66ca..bc90d0f0 100644 --- a/man/jc.1 +++ b/man/jc.1 @@ -1,4 +1,4 @@ -.TH jc 1 2024-01-08 1.24.1 "JSON Convert" +.TH jc 1 2024-01-26 1.24.1 "JSON Convert" .SH NAME \fBjc\fP \- JSON Convert JSONifies the output of many CLI tools, file-types, and strings @@ -1244,6 +1244,64 @@ lines from the beginning through \fBSTOP\fP lines from the end \fB:\fP all lines +.SH SlURP +Some parsers support multi-item input and can output an array of results in a +single pass. Slurping works for string parsers that accept a single line of +input. (e.g. \fBurl\fP and \fBip-address\fP) To see a list of parsers that support +the \fB--slurp\fP option, use \fBjc -hhh\fP. + +For example, you can send a file with multiple IP addresses (one per line) to +\fBjc\fP with the \fB--slurp\fP option and an array of results will output: + +.RS +.nf +$ cat ip-addresses.txt | jc --slurp --ip-address +[] +.fi +.RE + +The magic syntax for \fB/proc\fP files automatically supports slurping of multiple +files (no need to use the \fB--slurp\fP option). For example, you can convert many +PID files at once: + +.RS +.nf +$ jc /proc/*/status +[] +.fi +.RE + +When the \fB/proc\fP magic syntax is used and multiple files are selected, an +additional \fB_file\fP field is inserted in the output so it is easier to tell what +file each output object refers to. + +Finally, the \fB--meta-out\fP option can be used in conjunction with slurped output. +In this case, the slurped output is wrapped in an object with the following +structure: + +.RS +.nf +{ + "result": [], + "_jc_meta": { + "parser": "url", + "timestamp": 1706235558.654576, + "slice_start": null, + "slice_end": null, + "input_list": [ + "http://www.google.com", + "https://www.apple.com", + "https://www.microsoft.com" + ] + } +} +.fi +.RE + +With \fB--meta-out\fP, \fBinput_list\fP contains a list of inputs (actual input strings +or \fB/proc\fP filenames) so you can identify which output object relates to each +input string or \fB/proc\fP filename. + .SH EXIT CODES Any fatal errors within \fBjc\fP will generate an exit code of \fB100\fP, otherwise the exit code will be \fB0\fP. diff --git a/templates/manpage_template b/templates/manpage_template index 9cb837ae..edd48880 100644 --- a/templates/manpage_template +++ b/templates/manpage_template @@ -194,6 +194,64 @@ lines from the beginning through \fBSTOP\fP lines from the end \fB:\fP all lines +.SH SlURP +Some parsers support multi-item input and can output an array of results in a +single pass. Slurping works for string parsers that accept a single line of +input. (e.g. \fBurl\fP and \fBip-address\fP) To see a list of parsers that support +the \fB--slurp\fP option, use \fBjc -hhh\fP. + +For example, you can send a file with multiple IP addresses (one per line) to +\fBjc\fP with the \fB--slurp\fP option and an array of results will output: + +.RS +.nf +$ cat ip-addresses.txt | jc --slurp --ip-address +[] +.fi +.RE + +The magic syntax for \fB/proc\fP files automatically supports slurping of multiple +files (no need to use the \fB--slurp\fP option). For example, you can convert many +PID files at once: + +.RS +.nf +$ jc /proc/*/status +[] +.fi +.RE + +When the \fB/proc\fP magic syntax is used and multiple files are selected, an +additional \fB_file\fP field is inserted in the output so it is easier to tell what +file each output object refers to. + +Finally, the \fB--meta-out\fP option can be used in conjunction with slurped output. +In this case, the slurped output is wrapped in an object with the following +structure: + +.RS +.nf +{ + "result": [], + "_jc_meta": { + "parser": "url", + "timestamp": 1706235558.654576, + "slice_start": null, + "slice_end": null, + "input_list": [ + "http://www.google.com", + "https://www.apple.com", + "https://www.microsoft.com" + ] + } +} +.fi +.RE + +With \fB--meta-out\fP, \fBinput_list\fP contains a list of inputs (actual input strings +or \fB/proc\fP filenames) so you can identify which output object relates to each +input string or \fB/proc\fP filename. + .SH EXIT CODES Any fatal errors within \fBjc\fP will generate an exit code of \fB100\fP, otherwise the exit code will be \fB0\fP. diff --git a/templates/readme_template b/templates/readme_template index 5dbef813..0757380b 100644 --- a/templates/readme_template +++ b/templates/readme_template @@ -227,6 +227,58 @@ Here is a breakdown of line slice options: | `:-STOP` | lines from the beginning through `STOP` lines from the end | | `:` | all lines | +### Slurp +Some parsers support multi-item input and can output an array of results in a +single pass. Slurping works for string parsers that accept a single line of +input. (e.g. `url` and `ip-address`) To see a list of parsers that support +the `--slurp` option, use `jc -hhh`. + +For example, you can send a file with multiple IP addresses (one per line) to +`jc` with the `--slurp` option and an array of results will output: + +```bash +$ cat ip-addresses.txt | jc --slurp --ip-address +[] +``` + +The magic syntax for `/proc` files automatically supports slurping of multiple +files (no need to use the `--slurp` option). For example, you can convert many +PID files at once: + +```bash +$ jc /proc/*/status +[] +``` + +When the `/proc` magic syntax is used and multiple files are selected, an +additional `_file` field is inserted in the output so it is easier to tell what +file each output object refers to. + +Finally, the `--meta-out` option can be used in conjunction with slurped output. +In this case, the slurped output is wrapped in an object with the following +structure: + +```json +{ + "result": [], + "_jc_meta": { + "parser": "url", + "timestamp": 1706235558.654576, + "slice_start": null, + "slice_end": null, + "input_list": [ + "http://www.google.com", + "https://www.apple.com", + "https://www.microsoft.com" + ] + } +} +``` + +With `--meta-out`, `input_list` contains a list of inputs (actual input strings +or `/proc` filenames) so you can identify which output object relates to each +input string or `/proc` filename. + ### Exit Codes Any fatal errors within `jc` will generate an exit code of `100`, otherwise the exit code will be `0`.