From b4fffbb6476daf78fbdf19dbf31bbeeab950d2dc Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Wed, 19 Jan 2022 17:30:14 -0800 Subject: [PATCH] formatting --- docs/parsers/crontab.md | 3 +- docs/parsers/crontab_u.md | 22 ++++--- docs/parsers/csv.md | 9 ++- docs/parsers/csv_s.md | 35 +++++++---- docs/parsers/date.md | 18 ++++-- docs/parsers/dig.md | 16 +++-- docs/parsers/dir.md | 6 +- docs/parsers/dpkg_l.md | 7 ++- docs/parsers/du.md | 20 +++--- docs/parsers/env.md | 5 +- docs/parsers/file.md | 4 +- docs/parsers/history.md | 8 ++- docs/parsers/ini.md | 15 ++--- docs/parsers/iostat_s.md | 25 +++++--- docs/parsers/iw_scan.md | 5 +- docs/parsers/jar_manifest.md | 25 ++++---- docs/parsers/jobs.md | 3 +- docs/parsers/kv.md | 11 +++- docs/parsers/last.md | 10 +-- docs/parsers/ls.md | 19 ++++-- docs/parsers/ls_s.md | 51 ++++++++++------ docs/parsers/lsblk.md | 10 ++- docs/parsers/lsusb.md | 5 +- docs/parsers/netstat.md | 3 +- docs/parsers/ping.md | 32 ++++++---- docs/parsers/ping_s.md | 85 +++++++++++++++----------- docs/parsers/ps.md | 8 +-- docs/parsers/rpm_qi.md | 37 +++++++----- docs/parsers/sfdisk.md | 8 ++- docs/parsers/ss.md | 6 +- docs/parsers/stat.md | 6 +- docs/parsers/stat_s.md | 27 ++++++--- docs/parsers/sysctl.md | 7 ++- docs/parsers/systemctl.md | 4 +- docs/parsers/systemctl_ls.md | 3 +- docs/parsers/systemctl_luf.md | 3 +- docs/parsers/systeminfo.md | 19 ++++-- docs/parsers/time.md | 33 ++++++---- docs/parsers/timedatectl.md | 5 +- docs/parsers/traceroute.md | 5 +- docs/parsers/ufw.md | 7 ++- docs/parsers/ufw_appinfo.md | 28 ++++++--- docs/parsers/upower.md | 16 +++-- docs/parsers/vmstat.md | 13 ++-- docs/parsers/vmstat_s.md | 111 ++++++++++++++++++++-------------- docs/parsers/who.md | 7 ++- 46 files changed, 501 insertions(+), 304 deletions(-) diff --git a/docs/parsers/crontab.md b/docs/parsers/crontab.md index 09031ec0..028bde7c 100644 --- a/docs/parsers/crontab.md +++ b/docs/parsers/crontab.md @@ -1,7 +1,8 @@ [Home](https://kellyjonbrazil.github.io/jc/) # jc.parsers.crontab -jc - JSON CLI output utility `crontab -l` command output and crontab file parser +jc - JSON CLI output utility `crontab -l` command output and crontab +file parser Supports `crontab -l` command output and crontab files. diff --git a/docs/parsers/crontab_u.md b/docs/parsers/crontab_u.md index 58d14e0d..f5f84c95 100644 --- a/docs/parsers/crontab_u.md +++ b/docs/parsers/crontab_u.md @@ -1,9 +1,11 @@ [Home](https://kellyjonbrazil.github.io/jc/) # jc.parsers.crontab_u -jc - JSON CLI output utility `crontab -l` command output and crontab file parser +jc - JSON CLI output utility `crontab -l` command output and crontab +file parser -This version of the `crontab -l` parser supports output that contains user information for processes. +This version of the `crontab -l` parser supports output that contains user +information for processes. Usage (cli): @@ -60,7 +62,7 @@ Examples: "variables": [ { "name": "PATH", - "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin" + "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sb..." }, { "name": "SHELL", @@ -85,7 +87,7 @@ Examples: "*" ], "user": "root", - "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )" + "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..." }, { "minute": [ @@ -104,7 +106,7 @@ Examples: "7" ], "user": "root", - "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )" + "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..." }, { "minute": [ @@ -123,7 +125,7 @@ Examples: "*" ], "user": "root", - "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )" + "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..." } ] } @@ -133,7 +135,7 @@ Examples: "variables": [ { "name": "PATH", - "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin" + "value": "/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/..." }, { "name": "SHELL", @@ -148,7 +150,7 @@ Examples: "month": "*", "day_of_week": "*", "user": "root", - "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )" + "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..." }, { "minute": "47", @@ -157,7 +159,7 @@ Examples: "month": "*", "day_of_week": "7", "user": "root", - "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )" + "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..." }, { "minute": "52", @@ -166,7 +168,7 @@ Examples: "month": "*", "day_of_week": "*", "user": "root", - "command": "test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )" + "command": "test -x /usr/sbin/anacron || ( cd / && run-parts ..." } ] } diff --git a/docs/parsers/csv.md b/docs/parsers/csv.md index dcc1f81b..515e9614 100644 --- a/docs/parsers/csv.md +++ b/docs/parsers/csv.md @@ -3,7 +3,9 @@ # jc.parsers.csv jc - JSON CLI output utility `csv` file parser -The `csv` parser will attempt to automatically detect the delimiter character. If the delimiter cannot be detected it will default to comma. The first row of the file must be a header row. +The `csv` parser will attempt to automatically detect the delimiter +character. If the delimiter cannot be detected it will default to comma. The +first row of the file must be a header row. Usage (cli): @@ -21,7 +23,8 @@ Usage (module): Schema: - csv file converted to a Dictionary: https://docs.python.org/3/library/csv.html + csv file converted to a Dictionary: + https://docs.python.org/3/library/csv.html [ { @@ -33,7 +36,7 @@ Schema: Examples: $ cat homes.csv - "Sell", "List", "Living", "Rooms", "Beds", "Baths", "Age", "Acres", "Taxes" + "Sell", "List", "Living", "Rooms", "Beds", "Baths", "Age", "Acres"... 142, 160, 28, 10, 5, 3, 60, 0.28, 3167 175, 180, 18, 8, 4, 1, 12, 0.43, 4033 129, 132, 13, 6, 3, 1, 41, 0.33, 1471 diff --git a/docs/parsers/csv_s.md b/docs/parsers/csv_s.md index 3f01a0f3..7bae1f38 100644 --- a/docs/parsers/csv_s.md +++ b/docs/parsers/csv_s.md @@ -5,9 +5,12 @@ jc - JSON CLI output utility `csv` file streaming parser > This streaming parser outputs JSON Lines -The `csv` streaming parser will attempt to automatically detect the delimiter character. If the delimiter cannot be detected it will default to comma. The first row of the file must be a header row. +The `csv` streaming parser will attempt to automatically detect the +delimiter character. If the delimiter cannot be detected it will default +to comma. The first row of the file must be a header row. -Note: The first 100 rows are read into memory to enable delimiter detection, then the rest of the rows are loaded lazily. +Note: The first 100 rows are read into memory to enable delimiter detection, +then the rest of the rows are loaded lazily. Usage (cli): @@ -16,27 +19,33 @@ Usage (cli): Usage (module): import jc - result = jc.parse('csv_s', csv_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parse('csv_s', csv_output.splitlines()) for item in result: # do something or import jc.parsers.csv_s - result = jc.parsers.csv_s.parse(csv_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parsers.csv_s.parse(csv_output.splitlines()) for item in result: # do something Schema: - csv file converted to a Dictionary: https://docs.python.org/3/library/csv.html + csv file converted to a Dictionary: + https://docs.python.org/3/library/csv.html { "column_name1": string, "column_name2": string, - "_jc_meta": # This object only exists if using -qq or ignore_exceptions=True + + # below object only exists if using -qq or ignore_exceptions=True + + "_jc_meta": { - "success": boolean, # true if successfully parsed, false if error + "success": boolean, # false if error parsing "error": string, # exists if "success" is false "line": string # exists if "success" is false } @@ -45,16 +54,16 @@ Schema: Examples: $ cat homes.csv - "Sell", "List", "Living", "Rooms", "Beds", "Baths", "Age", "Acres", "Taxes" + "Sell", "List", "Living", "Rooms", "Beds", "Baths", "Age", "Acres"... 142, 160, 28, 10, 5, 3, 60, 0.28, 3167 175, 180, 18, 8, 4, 1, 12, 0.43, 4033 129, 132, 13, 6, 3, 1, 41, 0.33, 1471 ... $ cat homes.csv | jc --csv-s - {"Sell":"142","List":"160","Living":"28","Rooms":"10","Beds":"5","Baths":"3","Age":"60","Acres":"0.28","Taxes":"3167"} - {"Sell":"175","List":"180","Living":"18","Rooms":"8","Beds":"4","Baths":"1","Age":"12","Acres":"0.43","Taxes":"4033"} - {"Sell":"129","List":"132","Living":"13","Rooms":"6","Beds":"3","Baths":"1","Age":"41","Acres":"0.33","Taxes":"1471"} + {"Sell":"142","List":"160","Living":"28","Rooms":"10","Beds":"5"...} + {"Sell":"175","List":"180","Living":"18","Rooms":"8","Beds":"4"...} + {"Sell":"129","List":"132","Living":"13","Rooms":"6","Beds":"3"...} ... @@ -73,7 +82,9 @@ Main text parsing generator function. Returns an iterator object. Parameters: - data: (iterable) line-based text data to parse (e.g. sys.stdin or str.splitlines()) + data: (iterable) line-based text data to parse + (e.g. sys.stdin or str.splitlines()) + raw: (boolean) output preprocessed JSON if True quiet: (boolean) suppress warning messages if True ignore_exceptions: (boolean) ignore parsing exceptions if True diff --git a/docs/parsers/date.md b/docs/parsers/date.md index 2c3c1c26..6a314879 100644 --- a/docs/parsers/date.md +++ b/docs/parsers/date.md @@ -3,9 +3,11 @@ # jc.parsers.date jc - JSON CLI output utility `date` command output parser -The `epoch` calculated timestamp field is naive. (i.e. based on the local time of the system the parser is run on) +The `epoch` calculated timestamp field is naive. (i.e. based on the local +time of the system the parser is run on) -The `epoch_utc` calculated timestamp field is timezone-aware and is only available if the timezone field is UTC. +The `epoch_utc` calculated timestamp field is timezone-aware and is only +available if the timezone field is UTC. Usage (cli): @@ -40,15 +42,19 @@ Schema: "second": integer, "period": string, "timezone": string, - "utc_offset": string, # null if timezone field is not UTC + "utc_offset": string, # null if timezone field is not UTC "day_of_year": integer, "week_of_year": integer, "iso": string, - "epoch": integer, # naive timestamp - "epoch_utc": integer, # timezone-aware timestamp. Only available if timezone field is UTC - "timezone_aware": boolean # if true, all fields are correctly based on UTC + "epoch": integer, # [0] + "epoch_utc": integer, # [1] + "timezone_aware": boolean # [2] } + [0] naive timestamp + [1] timezone-aware timestamp. Only available if timezone field is UTC + [2] if true, all fields are correctly based on UTC + Examples: $ date | jc --date -p diff --git a/docs/parsers/dig.md b/docs/parsers/dig.md index 7b852be0..d655d140 100644 --- a/docs/parsers/dig.md +++ b/docs/parsers/dig.md @@ -4,12 +4,15 @@ jc - JSON CLI output utility `dig` command output parser Options supported: -- `+noall +answer` options are supported in cases where only the answer information is desired. +- `+noall +answer` options are supported in cases where only the answer + information is desired. - `+axfr` option is supported on its own -The `when_epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `when_epoch` calculated timestamp field is naive. (i.e. based on the +local time of the system the parser is run on) -The `when_epoch_utc` calculated timestamp field is timezone-aware and is only available if the timezone field is UTC. +The `when_epoch_utc` calculated timestamp field is timezone-aware and is +only available if the timezone field is UTC. Usage (cli): @@ -98,13 +101,16 @@ Schema: "query_time": integer, # in msec "server": string, "when": string, - "when_epoch": integer, # naive timestamp if when field is parsable, else null - "when_epoch_utc": integer, # timezone aware timestamp availabe for UTC, else null + "when_epoch": integer, # [0] + "when_epoch_utc": integer, # [1] "rcvd": integer "size": string } ] + [0] naive timestamp if when field is parsable, else null + [1] timezone aware timestamp availabe for UTC, else null + Examples: $ dig example.com | jc --dig -p diff --git a/docs/parsers/dir.md b/docs/parsers/dir.md index ed6a1e15..c5ea41bb 100644 --- a/docs/parsers/dir.md +++ b/docs/parsers/dir.md @@ -9,9 +9,11 @@ Options supported: - `/C, /-C` - `/S` -The "Magic" syntax is not supported since the `dir` command is a shell builtin. +The "Magic" syntax is not supported since the `dir` command is a shell +builtin. -The `epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `epoch` calculated timestamp field is naive. (i.e. based on the local +time of the system the parser is run on) Usage (cli): diff --git a/docs/parsers/dpkg_l.md b/docs/parsers/dpkg_l.md index 99479e62..cc19b7c2 100644 --- a/docs/parsers/dpkg_l.md +++ b/docs/parsers/dpkg_l.md @@ -3,7 +3,8 @@ # jc.parsers.dpkg_l jc - JSON CLI output utility `dpkg -l` command output parser -Set the `COLUMNS` environment variable to a large value to avoid field truncation. For example: +Set the `COLUMNS` environment variable to a large value to avoid field +truncation. For example: $ COLUMNS=500 dpkg -l | jc --dpkg-l @@ -77,7 +78,7 @@ Examples: "name": "acpid", "version": "1:2.0.28-1ubuntu1", "architecture": "amd64", - "description": "Advanced Configuration and Power Interface event daemon", + "description": "Advanced Configuration and Power Interface...", "desired": "remove", "status": "half installed" }, @@ -121,7 +122,7 @@ Examples: "name": "acpid", "version": "1:2.0.28-1ubuntu1", "architecture": "amd64", - "description": "Advanced Configuration and Power Interface event daemon" + "description": "Advanced Configuration and Power Interface..." }, { "codes": "pn", diff --git a/docs/parsers/du.md b/docs/parsers/du.md index 96233fbd..db82f909 100644 --- a/docs/parsers/du.md +++ b/docs/parsers/du.md @@ -40,23 +40,23 @@ Examples: }, { "size": 56, - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/_CodeSignature" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": 0, - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local/standalone" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": 0, - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": 0, - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": 1008, - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/dfu" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, ... ] @@ -69,23 +69,23 @@ Examples: }, { "size": "56", - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/_CodeSignature" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": "0", - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local/standalone" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": "0", - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr/local" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": "0", - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/usr" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, { "size": "1008", - "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/Contents/Resources/Firmware/dfu" + "name": "/usr/standalone/firmware/iBridge1_1Customer.bundle/..." }, ... ] diff --git a/docs/parsers/env.md b/docs/parsers/env.md index 826c72c0..0d69da29 100644 --- a/docs/parsers/env.md +++ b/docs/parsers/env.md @@ -3,7 +3,10 @@ # jc.parsers.env jc - JSON CLI output utility `env` and `printenv` command output parser -This parser will output a list of dictionaries each containing `name` and `value` keys. If you would like a simple dictionary output, then use the `-r` command-line option or the `raw=True` argument in the `parse()` function. +This parser will output a list of dictionaries each containing `name` and +`value` keys. If you would like a simple dictionary output, then use the +`-r` command-line option or the `raw=True` argument in the `parse()` +function. Usage (cli): diff --git a/docs/parsers/file.md b/docs/parsers/file.md index 2438ac23..d5a66b54 100644 --- a/docs/parsers/file.md +++ b/docs/parsers/file.md @@ -56,11 +56,11 @@ Examples: }, { "filename": "cd_catalog.xml", - "type": "XML 1.0 document text, ASCII text, with CRLF line terminators" + "type": "XML 1.0 document text, ASCII text, with CRLF line ..." }, { "filename": "centosserial.sh", - "type": "Bourne-Again shell script text executable, UTF-8 Unicode text" + "type": "Bourne-Again shell script text executable, UTF-8 ..." }, ... ] diff --git a/docs/parsers/history.md b/docs/parsers/history.md index 2c8dfb92..4b2efbb7 100644 --- a/docs/parsers/history.md +++ b/docs/parsers/history.md @@ -3,9 +3,13 @@ # jc.parsers.history jc - JSON CLI output utility `history` command output parser -This parser will output a list of dictionaries each containing `line` and `command` keys. If you would like a simple dictionary output, then use the `-r` command-line option or the `raw=True` argument in the `parse()` function. +This parser will output a list of dictionaries each containing `line` and +`command` keys. If you would like a simple dictionary output, then use the +`-r` command-line option or the `raw=True` argument in the `parse()` +function. -The "Magic" syntax is not supported since the `history` command is a shell builtin. +The "Magic" syntax is not supported since the `history` command is a shell +builtin. Usage (cli): diff --git a/docs/parsers/ini.md b/docs/parsers/ini.md index 2cd75ec5..67a4889f 100644 --- a/docs/parsers/ini.md +++ b/docs/parsers/ini.md @@ -3,9 +3,13 @@ # jc.parsers.ini jc - JSON CLI output utility `INI` file parser -Parses standard `INI` files and files containing simple key/value pairs. Delimiter can be `=` or `:`. Missing values are supported. Comment prefix can be `#` or `;`. Comments must be on their own line. +Parses standard `INI` files and files containing simple key/value pairs. +Delimiter can be `=` or `:`. Missing values are supported. Comment prefix +can be `#` or `;`. Comments must be on their own line. -Note: Values starting and ending with quotation marks will have the marks removed. If you would like to keep the quotation marks, use the `-r` command-line argument or the `raw=True` argument in `parse()`. +Note: Values starting and ending with quotation marks will have the marks +removed. If you would like to keep the quotation marks, use the `-r` +command-line argument or the `raw=True` argument in `parse()`. Usage (cli): @@ -23,11 +27,8 @@ Usage (module): Schema: - ini or key/value document converted to a dictionary - see configparser standard - library documentation for more details. - - Note: Values starting and ending with quotation marks will have the marks removed. - If you would like to keep the quotation marks, use the -r or raw=True argument. + ini or key/value document converted to a dictionary - see the + configparser standard library documentation for more details. { "key1": string, diff --git a/docs/parsers/iostat_s.md b/docs/parsers/iostat_s.md index c0b4832b..19da43bd 100644 --- a/docs/parsers/iostat_s.md +++ b/docs/parsers/iostat_s.md @@ -14,14 +14,16 @@ Usage (cli): Usage (module): import jc - result = jc.parse('iostat_s', iostat_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parse('iostat_s', iostat_command_output.splitlines()) for item in result: # do something or import jc.parsers.iostat_s - result = jc.parsers.iostat_s.parse(iostat_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parsers.iostat_s.parse(iostat_command_output.splitlines()) for item in result: # do something @@ -78,9 +80,12 @@ Schema: "percent_util": float, "percent_rrqm": float, "percent_wrqm": float, - "_jc_meta": # This object only exists if using -qq or ignore_exceptions=True + + # Below object only exists if using -qq or ignore_exceptions=True + + "_jc_meta": { - "success": boolean, # true if successfully parsed, false if error + "success": boolean, # false if error parsing "error": string, # exists if "success" is false "line": string # exists if "success" is false } @@ -89,13 +94,13 @@ Schema: Examples: $ iostat | jc --iostat-s - {"percent_user":0.14,"percent_nice":0.0,"percent_system":0.16,"percent_iowait":0.0,"percent_steal":0.0,"percent_idle":99.7,"type":"cpu"} - {"device":"sda","tps":0.24,"kb_read_s":5.28,"kb_wrtn_s":1.1,"kb_read":203305,"kb_wrtn":42368,"type":"device"} + {"percent_user":0.14,"percent_nice":0.0,"percent_system":0.16,...} + {"device":"sda","tps":0.24,"kb_read_s":5.28,"kb_wrtn_s":1.1...} ... $ iostat | jc --iostat-s -r - {"percent_user":"0.14","percent_nice":"0.00","percent_system":"0.16","percent_iowait":"0.00","percent_steal":"0.00","percent_idle":"99.70","type":"cpu"} - {"device":"sda","tps":"0.24","kb_read_s":"5.28","kb_wrtn_s":"1.10","kb_read":"203305","kb_wrtn":"42368","type":"device"} + {"percent_user":"0.14","percent_nice":"0.00","percent_system":"0.16"...} + {"device":"sda","tps":"0.24","kb_read_s":"5.28","kb_wrtn_s":"1.10"...} ... @@ -114,7 +119,9 @@ Main text parsing generator function. Returns an iterator object. Parameters: - data: (iterable) line-based text data to parse (e.g. sys.stdin or str.splitlines()) + data: (iterable) line-based text data to parse + (e.g. sys.stdin or str.splitlines()) + raw: (boolean) output preprocessed JSON if True quiet: (boolean) suppress warning messages if True ignore_exceptions: (boolean) ignore parsing exceptions if True diff --git a/docs/parsers/iw_scan.md b/docs/parsers/iw_scan.md index 9b7d6d50..ce4b95f8 100644 --- a/docs/parsers/iw_scan.md +++ b/docs/parsers/iw_scan.md @@ -3,7 +3,8 @@ # jc.parsers.iw_scan jc - JSON CLI output utility `iw dev scan` command output parser -This parser is considered beta quality. Not all fields are parsed and there are not enough samples to test. +This parser is considered beta quality. Not all fields are parsed and there +are not enough samples to test. Usage (cli): @@ -27,7 +28,7 @@ Schema: [ { - "foo": string/integer/float, # best guess based on value + "foo": string/integer/float, # best guess based on value "bar": string/integer/float, "baz": string/integer/float } diff --git a/docs/parsers/jar_manifest.md b/docs/parsers/jar_manifest.md index 776784f8..38dcf7f9 100644 --- a/docs/parsers/jar_manifest.md +++ b/docs/parsers/jar_manifest.md @@ -29,15 +29,16 @@ Schema: Examples: $ cat MANIFEST.MF | jc --jar-manifest -p - $ unzip -c apache-log4j-2.16.0-bin/log4j-core-2.16.0.jar META-INF/MANIFEST.MF | jc --jar-manifest -p - $ unzip -c 'apache-log4j-2.16.0-bin/*.jar' META-INF/MANIFEST.MF | jc --jar-manifest -p + $ unzip -c log4j-core-2.16.0.jar META-INF/MANIFEST.MF | \ + jc --jar-manifest -p + $ unzip -c 'apache-log4j-2.16.0-bin/*.jar' META-INF/MANIFEST.MF | \ + jc --jar-manifest -p $ cat MANIFEST.MF | jc --jar-manifest -p - [ { - "Import_Package": "com.conversantmedia.util.concurrent;resolution:=optional,com.fasterxml.jackson.annotation;version="[2.12,3)";resolution:=optional,com.fasterxml.jackson.core;version="[2.12,3)";resolution:=optional,com.fasterxml.jackson.core.type;version="[2.12,3)";resolution:=optional,com.fasterxml.jackson.cor...", - "Export_Package": "org.apache.logging.log4j.core;uses:="org.apache.logging.log4j,org.apache.logging.log4j.core.config,org.apache.logging.log4j.core.impl,org.apache.logging.log4j.core.layout,org.apache.logging.log4j.core.time,org.apache.logging.log4j.message,org.apache.logging.log4j.spi,org.apache.logging.log4j.status...", + "Import_Package": "com.conversantmedia.util.concurrent;resoluti...", + "Export_Package": "org.apache.logging.log4j.core;uses:="org.ap...", "Manifest_Version": "1.0", "Bundle_License": "https://www.apache.org/licenses/LICENSE-2.0.txt", "Bundle_SymbolicName": "org.apache.logging.log4j.core", @@ -50,28 +51,28 @@ Examples: } ] - $ unzip -c 'apache-log4j-2.16.0-bin/*.jar' META-INF/MANIFEST.MF | jc --jar-manifest -p - + $ unzip -c 'apache-log4j-2.16.0-bin/*.jar' META-INF/MANIFEST.MF | \ + jc --jar-manifest -p [ ... { - "Archive": "apache-log4j-2.16.0-bin/log4j-spring-boot-2.16.0-sources.jar", + "Archive": "apache-log4j-2.16.0-bin/log4j-spring-boot-2.16.0-so...", "Manifest_Version": "1.0", "Built_By": "matt", "Created_By": "Apache Maven 3.8.4", "Build_Jdk": "1.8.0_312" }, { - "Archive": "apache-log4j-2.16.0-bin/log4j-spring-boot-2.16.0-javadoc.jar", + "Archive": "apache-log4j-2.16.0-bin/log4j-spring-boot-2.16.0-ja...", "Manifest_Version": "1.0", "Built_By": "matt", "Created_By": "Apache Maven 3.8.4", "Build_Jdk": "1.8.0_312" }, { - "Bundle_SymbolicName": "org.apache.logging.log4j.spring-cloud-config-client.logging.log4j.core.util;version="[2.16,3)",org.springframework.boot.autoconfigure.condition,org.springframework.cloud.context.environment,org.springframework.context,org.springframework.stereotype", - "Export_Package": "org.apache.logging.log4j.spring.cloud.config.controller;version="2.16.0"ient", - "Archive": "apache-log4j-2.16.0-bin/log4j-spring-cloud-config-client-2.16.0.jar", + "Bundle_SymbolicName": "org.apache.logging.log4j.spring-cloud-c...", + "Export_Package": "org.apache.logging.log4j.spring.cloud.config...", + "Archive": "apache-log4j-2.16.0-bin/log4j-spring-cloud-config-c...", "Manifest_Version": "1.0", "Bundle_License": "https://www.apache.org/licenses/LICENSE-2.0.txt", ... diff --git a/docs/parsers/jobs.md b/docs/parsers/jobs.md index 99528ab6..4a58727c 100644 --- a/docs/parsers/jobs.md +++ b/docs/parsers/jobs.md @@ -5,7 +5,8 @@ jc - JSON CLI output utility `jobs` command output parser Also supports the `-l` option. -The "Magic" syntax is not supported since the `jobs` command is a shell builtin. +The "Magic" syntax is not supported since the `jobs` command is a shell +builtin. Usage (cli): diff --git a/docs/parsers/kv.md b/docs/parsers/kv.md index 42adb604..bbe886db 100644 --- a/docs/parsers/kv.md +++ b/docs/parsers/kv.md @@ -3,9 +3,13 @@ # jc.parsers.kv jc - JSON CLI output utility `Key/Value` file parser -Supports files containing simple key/value pairs. Delimiter can be `=` or `:`. Missing values are supported. Comment prefix can be `#` or `;`. Comments must be on their own line. +Supports files containing simple key/value pairs. Delimiter can be `=` or +`:`. Missing values are supported. Comment prefix can be `#` or `;`. +Comments must be on their own line. -Note: Values starting and ending with quotation marks will have the marks removed. If you would like to keep the quotation marks, use the `-r` command-line argument or the `raw=True` argument in `parse()`. +Note: Values starting and ending with quotation marks will have the marks +removed. If you would like to keep the quotation marks, use the `-r` +command-line argument or the `raw=True` argument in `parse()`. Usage (cli): @@ -23,7 +27,8 @@ Usage (module): Schema: - key/value document converted to a dictionary - see configparser standard library documentation for more details. + key/value document converted to a dictionary - see the + configparser standard library documentation for more details. { "key1": string, diff --git a/docs/parsers/last.md b/docs/parsers/last.md index 0e0c35c5..38362c89 100644 --- a/docs/parsers/last.md +++ b/docs/parsers/last.md @@ -5,7 +5,9 @@ jc - JSON CLI output utility `last` and `lastb` command output parser Supports `-w` and `-F` options. -Calculated epoch time fields are naive (i.e. based on the local time of the system the parser is run on) since there is no timezone information in the `last` command output. +Calculated epoch time fields are naive (i.e. based on the local time of the +system the parser is run on) since there is no timezone information in the +`last` command output. Usage (cli): @@ -35,9 +37,9 @@ Schema: "login": string, "logout": string, "duration": string, - "login_epoch": integer, # (naive) available with last -F option - "logout_epoch": integer, # (naive) available with last -F option - "duration_seconds": integer # available with last -F option + "login_epoch": integer, # (naive) available with last -F option + "logout_epoch": integer, # (naive) available with last -F option + "duration_seconds": integer # available with last -F option } ] diff --git a/docs/parsers/ls.md b/docs/parsers/ls.md index 60930aef..ce7e0e8a 100644 --- a/docs/parsers/ls.md +++ b/docs/parsers/ls.md @@ -7,11 +7,17 @@ Options supported: - `lbaR1` - `--time-style=full-iso` -Note: The `-1`, `-l`, or `-b` option of `ls` should be used to correctly parse filenames that include newline characters. Since `ls` does not encode newlines in filenames when outputting to a pipe it will cause `jc` to see multiple files instead of a single file if `-1`, `-l`, or `-b` is not used. Alternatively, `vdir` can be used, which is the same as running `ls -lb`. +Note: The `-1`, `-l`, or `-b` option of `ls` should be used to correctly +parse filenames that include newline characters. Since `ls` does not encode +newlines in filenames when outputting to a pipe it will cause `jc` to see +multiple files instead of a single file if `-1`, `-l`, or `-b` is not used. +Alternatively, `vdir` can be used, which is the same as running `ls -lb`. -The `epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `epoch` calculated timestamp field is naive. (i.e. based on the local +time of the system the parser is run on) -The `epoch_utc` calculated timestamp field is timezone-aware and is only available if the timezone field is UTC. +The `epoch_utc` calculated timestamp field is timezone-aware and is only +available if the timezone field is UTC. Usage (cli): @@ -43,11 +49,14 @@ Schema: "group": string, "size": integer, "date": string, - "epoch": integer, # naive timestamp if date field exists and can be converted - "epoch_utc": integer # timezone aware timestamp if date field is in UTC and can be converted + "epoch": integer, # [0] + "epoch_utc": integer # [1] } ] + [0] naive timestamp if date field exists and can be converted + [1] timezone aware timestamp if date field is in UTC and can be converted + Examples: $ ls /usr/bin | jc --ls -p diff --git a/docs/parsers/ls_s.md b/docs/parsers/ls_s.md index cbf1d8d2..a0e51224 100644 --- a/docs/parsers/ls_s.md +++ b/docs/parsers/ls_s.md @@ -1,17 +1,22 @@ [Home](https://kellyjonbrazil.github.io/jc/) # jc.parsers.ls_s -jc - JSON CLI output utility `ls` and `vdir` command output streaming parser +jc - JSON CLI output utility `ls` and `vdir` command output streaming +parser > This streaming parser outputs JSON Lines -Requires the `-l` option to be used on `ls`. If there are newline characters in the filename, then make sure to use the `-b` option on `ls`. +Requires the `-l` option to be used on `ls`. If there are newline characters +in the filename, then make sure to use the `-b` option on `ls`. -The `jc` `-qq` option can be used to ignore parsing errors. (e.g. filenames with newline characters, but `-b` was not used) +The `jc` `-qq` option can be used to ignore parsing errors. (e.g. filenames +with newline characters, but `-b` was not used) -The `epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `epoch` calculated timestamp field is naive (i.e. based on the local time +of the system the parser is run on) -The `epoch_utc` calculated timestamp field is timezone-aware and is only available if the timezone field is UTC. +The `epoch_utc` calculated timestamp field is timezone-aware and is only +available if the timezone field is UTC. Usage (cli): @@ -20,14 +25,16 @@ Usage (cli): Usage (module): import jc - result = jc.parse('ls_s', ls_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parse('ls_s', ls_command_output.splitlines()) for item in result: # do something or import jc.parsers.ls_s - result = jc.parsers.ls_s.parse(ls_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parsers.ls_s.parse(ls_command_output.splitlines()) for item in result: # do something @@ -42,28 +49,34 @@ Schema: "group": string, "size": integer, "date": string, - "epoch": integer, # naive timestamp if date field exists and can be converted - "epoch_utc": integer, # timezone aware timestamp if date field is in UTC and can be converted - "_jc_meta": # This object only exists if using -qq or ignore_exceptions=True + "epoch": integer, # [0] + "epoch_utc": integer, # [1] + + # Below object only exists if using -qq or ignore_exceptions=True + + "_jc_meta": { - "success": boolean, # true if successfully parsed, false if error + "success": boolean, # false if error parsing "error": string, # exists if "success" is false "line": string # exists if "success" is false } } + [0] naive timestamp if date field exists and can be converted + [1] timezone aware timestamp if date field is in UTC and can be converted + Examples: $ ls -l /usr/bin | jc --ls-s - {"filename":"2to3-","flags":"-rwxr-xr-x","links":4,"owner":"root","group":"wheel","size":925,"date":"Feb 22 2019"} - {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/Python.framework/Versions/2.7/bin/2to3-2.7","flags":"lrwxr-xr-x","links":1,"owner":"root","group":"wheel","size":74,"date":"May 4 2019"} - {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":1,"owner":"root","group":"wheel","size":55152,"date":"May 3 2019"} + {"filename":"2to3-","flags":"-rwxr-xr-x","links":4,"owner":"root","...} + {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/P...} + {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":1,...} ... $ ls -l /usr/bin | jc --ls-s -r - {"filename":"2to3-","flags":"-rwxr-xr-x","links":"4","owner":"root","group":"wheel","size":"925","date":"Feb 22 2019"} - {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/Python.framework/Versions/2.7/bin/2to3-2.7","flags":"lrwxr-xr-x","links":"1","owner":"root","group":"wheel","size":"74","date":"May 4 2019"} - {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":"1","owner":"root","group":"wheel","size":"55152","date":"May 3 2019"} + {"filename":"2to3-","flags":"-rwxr-xr-x","links":"4","owner":"roo"..."} + {"filename":"2to3-2.7","link_to":"../../System/Library/Frameworks/P...} + {"filename":"AssetCacheLocatorUtil","flags":"-rwxr-xr-x","links":"1...} ... @@ -82,7 +95,9 @@ Main text parsing generator function. Returns an iterator object. Parameters: - data: (iterable) line-based text data to parse (e.g. sys.stdin or str.splitlines()) + data: (iterable) line-based text data to parse + (e.g. sys.stdin or str.splitlines()) + raw: (boolean) output preprocessed JSON if True quiet: (boolean) suppress warning messages if True ignore_exceptions: (boolean) ignore parsing exceptions if True diff --git a/docs/parsers/lsblk.md b/docs/parsers/lsblk.md index a8b10ede..8bdb8ccc 100644 --- a/docs/parsers/lsblk.md +++ b/docs/parsers/lsblk.md @@ -93,7 +93,10 @@ Examples: ... ] - $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p + $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,\ + STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,\ + SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,\ + PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p [ { "name": "sda", @@ -182,7 +185,10 @@ Examples: ... ] - $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p -r + $ lsblk -o +KNAME,FSTYPE,LABEL,UUID,PARTLABEL,PARTUUID,RA,MODEL,SERIAL,\ + STATE,OWNER,GROUP,MODE,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,\ + SCHED,RQ-SIZE,DISC-ALN,DISC-GRAN,DISC-MAX,DISC-ZERO,WSAME,WWN,RAND,\ + PKNAME,HCTL,TRAN,REV,VENDOR | jc --lsblk -p -r [ { "name": "sda", diff --git a/docs/parsers/lsusb.md b/docs/parsers/lsusb.md index 5ab28a78..d8b551d0 100644 --- a/docs/parsers/lsusb.md +++ b/docs/parsers/lsusb.md @@ -25,8 +25,9 @@ Usage (module): Schema: - Note: object keynames are assigned directly from the lsusb output. - If there are duplicate names in a section, only the last one is converted. + Note: object keynames are assigned directly from the lsusb + output. If there are duplicate names in a section, only the + last one is converted. [ { diff --git a/docs/parsers/netstat.md b/docs/parsers/netstat.md index 9c5c8d4c..38f47928 100644 --- a/docs/parsers/netstat.md +++ b/docs/parsers/netstat.md @@ -5,7 +5,8 @@ jc - JSON CLI output utility `netstat` command output parser Caveats: - Use of multiple `l` options is not supported on OSX (e.g. `netstat -rlll`) -- Use of the `A` option is not supported on OSX when using the `r` option (e.g. `netstat -rA`) +- Use of the `A` option is not supported on OSX when using the `r` option + (e.g. `netstat -rA`) Usage (cli): diff --git a/docs/parsers/ping.md b/docs/parsers/ping.md index 4e1978e3..bf027db8 100644 --- a/docs/parsers/ping.md +++ b/docs/parsers/ping.md @@ -7,7 +7,8 @@ Supports `ping` and `ping6` output. Usage (cli): - Note: Use the ping `-c` (count) option, otherwise data will not be piped to `jc`. + Note: Use the ping `-c` (count) option, otherwise data will not be + piped to `jc`. $ ping -c 3 1.2.3.4 | jc --ping @@ -31,7 +32,7 @@ Schema: "source_ip": string, "destination_ip": string, "data_bytes": integer, - "pattern": string, # (null if not set) + "pattern": string, # null if not set "destination": string, "packets_transmitted": integer, "packets_received": integer, @@ -43,8 +44,8 @@ Schema: "round_trip_ms_stddev": float, "responses": [ { - "type": string, # 'reply', 'timeout', 'unparsable_line', etc. See `_error_type.type_map` for all options - "unparsed_line": string, # only if an 'unparsable_line' type + "type": string, # [0] + "unparsed_line": string, # [1] "timestamp": float, "bytes": integer, "response_ip": string, @@ -52,21 +53,26 @@ Schema: "ttl": integer, "time_ms": float, "duplicate": boolean, - "vr": integer, # hex value converted to decimal - "hl": integer, # hex value converted to decimal - "tos": integer, # hex value converted to decimal - "len": integer, # hex value converted to decimal - "id": integer, # hex value converted to decimal - "flg": integer, # hex value converted to decimal - "off": integer, # hex value converted to decimal - "pro": integer, # hex value converted to decimal - "cks": ingeger, # hex value converted to decimal + "vr": integer, # [2] + "hl": integer, # [2] + "tos": integer, # [2] + "len": integer, # [2] + "id": integer, # [2] + "flg": integer, # [2] + "off": integer, # [2] + "pro": integer, # [2] + "cks": ingeger, # [2] "src": string, "dst": string } ] } + [0] 'reply', 'timeout', 'unparsable_line', etc. See + `_error_type.type_map` for all options + [1] only if an 'unparsable_line' type + [2] hex value converted to decimal + Examples: $ ping -c 3 -p ff cnn.com | jc --ping -p diff --git a/docs/parsers/ping_s.md b/docs/parsers/ping_s.md index ea09a90c..3139e821 100644 --- a/docs/parsers/ping_s.md +++ b/docs/parsers/ping_s.md @@ -11,66 +11,79 @@ Usage (cli): $ ping | jc --ping-s -> Note: When piping `jc` converted `ping` output to other processes it may appear the output is hanging due to the OS pipe buffers. This is because `ping` output is too small to quickly fill up the buffer. Use the `-u` option to unbuffer the `jc` output if you would like immediate output. See the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output) for more information. +> Note: When piping `jc` converted `ping` output to other processes it may + appear the output is hanging due to the OS pipe buffers. This is because + `ping` output is too small to quickly fill up the buffer. Use the `-u` + option to unbuffer the `jc` output if you would like immediate output. + See the[readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output) + for more information. Usage (module): import jc - result = jc.parse('ping_s', ping_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parse('ping_s', ping_command_output.splitlines()) for item in result: # do something or import jc.parsers.ping_s - result = jc.parsers.ping_s.parse(ping_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parsers.ping_s.parse(ping_command_output.splitlines()) for item in result: # do something Schema: { - "type": string, # 'reply', 'timeout', 'summary', etc. See `_error_type.type_map` for all options. - "source_ip": string, - "destination_ip": string, - "sent_bytes": integer, - "pattern": string, # (null if not set) - "destination": string, - "timestamp": float, - "response_bytes": integer, - "response_ip": string, - "icmp_seq": integer, - "ttl": integer, - "time_ms": float, - "duplicate": boolean, - "packets_transmitted": integer, - "packets_received": integer, - "packet_loss_percent": float, - "duplicates": integer, - "round_trip_ms_min": float, - "round_trip_ms_avg": float, - "round_trip_ms_max": float, - "round_trip_ms_stddev": float, - "_jc_meta": # This object only exists if using -qq or ignore_exceptions=True + "type": string, # [0] + "source_ip": string, + "destination_ip": string, + "sent_bytes": integer, + "pattern": string, # (null if not set) + "destination": string, + "timestamp": float, + "response_bytes": integer, + "response_ip": string, + "icmp_seq": integer, + "ttl": integer, + "time_ms": float, + "duplicate": boolean, + "packets_transmitted": integer, + "packets_received": integer, + "packet_loss_percent": float, + "duplicates": integer, + "round_trip_ms_min": float, + "round_trip_ms_avg": float, + "round_trip_ms_max": float, + "round_trip_ms_stddev": float, + + # Below object only exists if using -qq or ignore_exceptions=True + + "_jc_meta": { - "success": boolean, # true if successfully parsed, false if error - "error": string, # exists if "success" is false - "line": string # exists if "success" is false + "success": boolean, # false if error parsing + "error": string, # exists if "success" is false + "line": string # exists if "success" is false } } + [0] 'reply', 'timeout', 'summary', etc. See `_error_type.type_map` + for all options. + Examples: $ ping 1.1.1.1 | jc --ping-s - {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"pattern":null,"response_bytes":64,"response_ip":"1.1.1.1","icmp_seq":0,"ttl":56,"time_ms":23.703} - {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"pattern":null,"response_bytes":64,"response_ip":"1.1.1.1","icmp_seq":1,"ttl":56,"time_ms":22.862} - {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"pattern":null,"response_bytes":64,"response_ip":"1.1.1.1","icmp_seq":2,"ttl":56,"time_ms":22.82} + {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...} + {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...} + {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":56,"patte...} ... $ ping 1.1.1.1 | jc --ping-s -r - {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","pattern":null,"response_bytes":"64","response_ip":"1.1.1.1","icmp_seq":"0","ttl":"56","time_ms":"23.054"} - {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","pattern":null,"response_bytes":"64","response_ip":"1.1.1.1","icmp_seq":"1","ttl":"56","time_ms":"24.739"} - {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","pattern":null,"response_bytes":"64","response_ip":"1.1.1.1","icmp_seq":"2","ttl":"56","time_ms":"23.232"} + {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...} + {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...} + {"type":"reply","destination_ip":"1.1.1.1","sent_bytes":"56","patte...} ... @@ -89,7 +102,9 @@ Main text parsing generator function. Returns an iterator object. Parameters: - data: (iterable) line-based text data to parse (e.g. sys.stdin or str.splitlines()) + data: (iterable) line-based text data to parse + (e.g. sys.stdin or str.splitlines()) + raw: (boolean) output preprocessed JSON if True quiet: (boolean) suppress warning messages if True ignore_exceptions: (boolean) ignore parsing exceptions if True diff --git a/docs/parsers/ps.md b/docs/parsers/ps.md index 9f97451b..edbe6bda 100644 --- a/docs/parsers/ps.md +++ b/docs/parsers/ps.md @@ -61,7 +61,7 @@ Examples: "stime": "Nov01", "tty": null, "time": "00:00:11", - "cmd": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22" + "cmd": "/usr/lib/systemd/systemd --switched-root --system --dese..." }, { "uid": "root", @@ -96,7 +96,7 @@ Examples: "stime": "Nov01", "tty": "?", "time": "00:00:11", - "cmd": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22" + "cmd": "/usr/lib/systemd/systemd --switched-root --system --dese..." }, { "uid": "root", @@ -134,7 +134,7 @@ Examples: "stat": "Ss", "start": "Nov09", "time": "0:08", - "command": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22" + "command": "/usr/lib/systemd/systemd --switched-root --system --..." }, { "user": "root", @@ -178,7 +178,7 @@ Examples: "stat": "Ss", "start": "Nov09", "time": "0:08", - "command": "/usr/lib/systemd/systemd --switched-root --system --deserialize 22" + "command": "/usr/lib/systemd/systemd --switched-root --system --..." }, { "user": "root", diff --git a/docs/parsers/rpm_qi.md b/docs/parsers/rpm_qi.md index e4588564..1c82a9a6 100644 --- a/docs/parsers/rpm_qi.md +++ b/docs/parsers/rpm_qi.md @@ -5,9 +5,11 @@ jc - JSON CLI output utility `rpm -qi` command output parser Works with `rpm -qi [package]` or `rpm -qia`. -The `..._epoch` calculated timestamp fields are naive (i.e. based on the local time of the system the parser is run on) +The `..._epoch` calculated timestamp fields are naive. (i.e. based on the +local time of the system the parser is run on) -The `..._epoch_utc` calculated timestamp fields are timezone-aware and is only available if the timezone field is UTC. +The `..._epoch_utc` calculated timestamp fields are timezone-aware and is +only available if the timezone field is UTC. Usage (cli): @@ -37,16 +39,16 @@ Schema: "release": string, "architecture": string, "install_date": string, - "install_date_epoch": integer, # naive timestamp - "install_date_epoch_utc": integer, # Aware timestamp if timezone is UTC + "install_date_epoch": integer, # [0] + "install_date_epoch_utc": integer, # [1] "group": string, "size": integer, "license": string, "signature": string, "source_rpm": string, "build_date": string, - "build_epoch": integer, # naive timestamp - "build_epoch_utc": integer, # Aware timestamp if timezone is UTC + "build_epoch": integer, # [0] + "build_epoch_utc": integer, # [1] "build_host": string, "relocations": string, "packager": string, @@ -57,6 +59,9 @@ Schema: } ] + [0] naive timestamp + [1] Aware timestamp if timezone is UTC + Examples: $ rpm -qia | jc --rpm-qi -p @@ -71,7 +76,7 @@ Examples: "group": "Development/Tools", "size": 1160660, "license": "GPLv2+", - "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ID 24c6a8a7f4a80eb5", + "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ...", "source_rpm": "make-3.82-24.el7.src.rpm", "build_date": "Thu 08 Aug 2019 05:47:25 PM PDT", "build_host": "x86-01.bsys.centos.org", @@ -79,8 +84,8 @@ Examples: "packager": "CentOS BuildSystem ", "vendor": "CentOS", "url": "http://www.gnu.org/software/make/", - "summary": "A GNU tool which simplifies the build process for users", - "description": "A GNU tool for controlling the generation of executables and other...", + "summary": "A GNU tool which simplifies the build process for ...", + "description": "A GNU tool for controlling the generation of ex...", "build_epoch": 1565311645, "build_epoch_utc": null, "install_date_epoch": 1571242902, @@ -95,7 +100,7 @@ Examples: "group": "System Environment/Base", "size": 503608, "license": "GPLv2+", - "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ID 24c6a8a7f4a80eb5", + "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ...", "source_rpm": "kbd-1.15.5-15.el7.src.rpm", "build_date": "Tue 30 Oct 2018 03:40:00 PM PDT", "build_host": "x86-01.bsys.centos.org", @@ -104,7 +109,7 @@ Examples: "vendor": "CentOS", "url": "http://ftp.altlinux.org/pub/people/legion/kbd", "summary": "Legacy data for kbd package", - "description": "The kbd-legacy package contains original keymaps for kbd package...", + "description": "The kbd-legacy package contains original keymap...", "build_epoch": 1540939200, "build_epoch_utc": null, "install_date_epoch": 1565891588, @@ -125,7 +130,7 @@ Examples: "group": "Development/Tools", "size": "1160660", "license": "GPLv2+", - "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ID 24c6a8a7f4a80eb5", + "signature": "RSA/SHA256, Thu 22 Aug 2019 02:34:59 PM PDT, Key ...", "source_rpm": "make-3.82-24.el7.src.rpm", "build_date": "Thu 08 Aug 2019 05:47:25 PM PDT", "build_host": "x86-01.bsys.centos.org", @@ -133,8 +138,8 @@ Examples: "packager": "CentOS BuildSystem ", "vendor": "CentOS", "url": "http://www.gnu.org/software/make/", - "summary": "A GNU tool which simplifies the build process for users", - "description": "A GNU tool for controlling the generation of executables and other..." + "summary": "A GNU tool which simplifies the build process for...", + "description": "A GNU tool for controlling the generation of exe..." }, { "name": "kbd-legacy", @@ -145,7 +150,7 @@ Examples: "group": "System Environment/Base", "size": "503608", "license": "GPLv2+", - "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ID 24c6a8a7f4a80eb5", + "signature": "RSA/SHA256, Mon 12 Nov 2018 07:17:49 AM PST, Key ...", "source_rpm": "kbd-1.15.5-15.el7.src.rpm", "build_date": "Tue 30 Oct 2018 03:40:00 PM PDT", "build_host": "x86-01.bsys.centos.org", @@ -154,7 +159,7 @@ Examples: "vendor": "CentOS", "url": "http://ftp.altlinux.org/pub/people/legion/kbd", "summary": "Legacy data for kbd package", - "description": "The kbd-legacy package contains original keymaps for kbd package..." + "description": "The kbd-legacy package contains original keymaps..." }, ... ] diff --git a/docs/parsers/sfdisk.md b/docs/parsers/sfdisk.md index ff583912..e804b5c5 100644 --- a/docs/parsers/sfdisk.md +++ b/docs/parsers/sfdisk.md @@ -58,7 +58,7 @@ Schema: "boot": boolean, "start": integer, "end": integer, - "size": string, # Note: will be integer when using deprecated -d sfdisk option + "size": string, # [0] "cyls": integer, "mib": integer, "blocks": integer, @@ -71,6 +71,8 @@ Schema: } ] + [0] will be integer when using deprecated -d sfdisk option + Examples: # sfdisk -l | jc --sfdisk -p @@ -80,7 +82,7 @@ Examples: "cylinders": 2610, "heads": 255, "sectors_per_track": 63, - "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, counting from 0", + "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, ...", "partitions": [ { "device": "/dev/sda1", @@ -145,7 +147,7 @@ Examples: "cylinders": "2610", "heads": "255", "sectors_per_track": "63", - "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, counting from 0", + "units": "cylinders of 8225280 bytes, blocks of 1024 bytes, co...", "partitions": [ { "device": "/dev/sda1", diff --git a/docs/parsers/ss.md b/docs/parsers/ss.md index 5a8b1a86..849b7b1f 100644 --- a/docs/parsers/ss.md +++ b/docs/parsers/ss.md @@ -3,7 +3,8 @@ # jc.parsers.ss jc - JSON CLI output utility `ss` command output parser -Extended information options like -e and -p are not supported and may cause parsing irregularities. +Extended information options like -e and -p are not supported and may cause +parsing irregularities. Usage (cli): @@ -25,7 +26,8 @@ Usage (module): Schema: - Information from https://www.cyberciti.biz/files/ss.html used to define field names + Information from https://www.cyberciti.biz/files/ss.html used to define + field names [ { diff --git a/docs/parsers/stat.md b/docs/parsers/stat.md index b334ac99..018f71c1 100644 --- a/docs/parsers/stat.md +++ b/docs/parsers/stat.md @@ -3,9 +3,11 @@ # jc.parsers.stat jc - JSON CLI output utility `stat` command output parser -The `xxx_epoch` calculated timestamp fields are naive (i.e. based on the local time of the system the parser is run on) +The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the +local time of the system the parser is run on) -The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are only available if the timezone field is UTC. +The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are +only available if the timezone field is UTC. Usage (cli): diff --git a/docs/parsers/stat_s.md b/docs/parsers/stat_s.md index 9ce938d4..21e3465f 100644 --- a/docs/parsers/stat_s.md +++ b/docs/parsers/stat_s.md @@ -5,9 +5,11 @@ jc - JSON CLI output utility `stat` command output streaming parser > This streaming parser outputs JSON Lines -The `xxx_epoch` calculated timestamp fields are naive (i.e. based on the local time of the system the parser is run on). +The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the +local time of the system the parser is run on). -The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are only available if the timezone field is UTC. +The `xxx_epoch_utc` calculated timestamp fields are timezone-aware and are +only available if the timezone field is UTC. Usage (cli): @@ -16,14 +18,16 @@ Usage (cli): Usage (module): import jc - result = jc.parse('stat_s', stat_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parse('stat_s', stat_command_output.splitlines()) for item in result: # do something or import jc.parsers.stat_s - result = jc.parsers.stat_s.parse(stat_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parsers.stat_s.parse(stat_command_output.splitlines()) for item in result: # do something @@ -61,9 +65,12 @@ Schema: "rdev": integer, "block_size": integer, "unix_flags": string, - "_jc_meta": # This object only exists if using -qq or ignore_exceptions=True + + # Below object only exists if using -qq or ignore_exceptions=True + + "_jc_meta": { - "success": boolean, # true if successfully parsed, false if error + "success": boolean, # false if error parsing "error": string, # exists if "success" is false "line": string # exists if "success" is false } @@ -72,10 +79,10 @@ Schema: Examples: $ stat | jc --stat-s - {"file":"(stdin)","unix_device":1027739696,"inode":1155,"flags":"crw--w----","links":1,"user":"kbrazil","group":"tty","rdev":268435456,"size":0,"access_time":"Jan 4 15:27:44 2022","modify_time":"Jan 4 15:27:44 2022","change_time":"Jan 4 15:27:44 2022","birth_time":"Dec 31 16:00:00 1969","block_size":131072,"blocks":0,"unix_flags":"0","access_time_epoch":1641338864,"access_time_epoch_utc":null,"modify_time_epoch":1641338864,"modify_time_epoch_utc":null,"change_time_epoch":1641338864,"change_time_epoch_utc":null,"birth_time_epoch":null,"birth_time_epoch_utc":null} + {"file":"(stdin)","unix_device":1027739696,"inode":1155,"flags":"cr...} $ stat | jc --stat-s -r - {"file":"(stdin)","unix_device":"1027739696","inode":"1155","flags":"crw--w----","links":"1","user":"kbrazil","group":"tty","rdev":"268435456","size":"0","access_time":"Jan 4 15:28:08 2022","modify_time":"Jan 4 15:28:08 2022","change_time":"Jan 4 15:28:08 2022","birth_time":"Dec 31 16:00:00 1969","block_size":"131072","blocks":"0","unix_flags":"0"} + {"file":"(stdin)","unix_device":"1027739696","inode":"1155","flag...} ## info @@ -93,7 +100,9 @@ Main text parsing generator function. Returns an iterator object. Parameters: - data: (iterable) line-based text data to parse (e.g. sys.stdin or str.splitlines()) + data: (iterable) line-based text data to parse + (e.g. sys.stdin or str.splitlines()) + raw: (boolean) output preprocessed JSON if True quiet: (boolean) suppress warning messages if True ignore_exceptions: (boolean) ignore parsing exceptions if True diff --git a/docs/parsers/sysctl.md b/docs/parsers/sysctl.md index d06feb9e..e500aea4 100644 --- a/docs/parsers/sysctl.md +++ b/docs/parsers/sysctl.md @@ -3,7 +3,10 @@ # jc.parsers.sysctl jc - JSON CLI output utility `sysctl -a` command output parser -Note: Since `sysctl` output is not easily parsable only a very simple key/value object will be output. An attempt is made to convert obvious integers and floats. If no conversion is desired, use the `-r` command-line argument or the `raw=True` argument in `parse()`. +Note: Since `sysctl` output is not easily parsable only a very simple + key/value object will be output. An attempt is made to convert obvious + integers and floats. If no conversion is desired, use the `-r` + command-line argument or the `raw=True` argument in `parse()`. Usage (cli): @@ -26,7 +29,7 @@ Usage (module): Schema: { - "key1": string/integer/float, # best guess based on value + "key1": string/integer/float, # best guess based on value "key2": string/integer/float, "key3": string/integer/float } diff --git a/docs/parsers/systemctl.md b/docs/parsers/systemctl.md index 8f056de3..31a64eab 100644 --- a/docs/parsers/systemctl.md +++ b/docs/parsers/systemctl.md @@ -42,14 +42,14 @@ Examples: "load": "loaded", "active": "active", "sub": "waiting", - "description": "Arbitrary Executable File Formats File System Automount Point" + "description": "Arbitrary Executable File Formats File System ..." }, { "unit": "dev-block-8:2.device", "load": "loaded", "active": "active", "sub": "plugged", - "description": "LVM PV 3klkIj-w1qk-DkJi-0XBJ-y3o7-i2Ac-vHqWBM on /dev/sda2 2" + "description": "LVM PV 3klkIj-w1qk-DkJi-0XBJ-y3o7-i2Ac-vHqWBM o..." }, { "unit": "dev-cdrom.device", diff --git a/docs/parsers/systemctl_ls.md b/docs/parsers/systemctl_ls.md index 1dbe9159..a6f81f37 100644 --- a/docs/parsers/systemctl_ls.md +++ b/docs/parsers/systemctl_ls.md @@ -1,7 +1,8 @@ [Home](https://kellyjonbrazil.github.io/jc/) # jc.parsers.systemctl_ls -jc - JSON CLI output utility `systemctl list-sockets` command output parser +jc - JSON CLI output utility `systemctl list-sockets` command output +parser Usage (cli): diff --git a/docs/parsers/systemctl_luf.md b/docs/parsers/systemctl_luf.md index a10f62d7..d5ba7175 100644 --- a/docs/parsers/systemctl_luf.md +++ b/docs/parsers/systemctl_luf.md @@ -1,7 +1,8 @@ [Home](https://kellyjonbrazil.github.io/jc/) # jc.parsers.systemctl_luf -jc - JSON CLI output utility `systemctl list-unit-files` command output parser +jc - JSON CLI output utility `systemctl list-unit-files` command output +parser Usage (cli): diff --git a/docs/parsers/systeminfo.md b/docs/parsers/systeminfo.md index f0252d0e..f941e8f5 100644 --- a/docs/parsers/systeminfo.md +++ b/docs/parsers/systeminfo.md @@ -5,9 +5,13 @@ jc - JSON CLI output utility `systeminfo` command output parser Blank or missing elements are set to `null`. -The `original_install_date_epoch` and `system_boot_time_epoch` calculated timestamp fields are naive (i.e. based on the local time of the system the parser is run on) +The `original_install_date_epoch` and `system_boot_time_epoch` calculated +timestamp fields are naive. (i.e. based on the local time of the system the +parser is run on) -The `original_install_date_epoch_utc` and `system_boot_time_epoch_utc` calculated timestamp fields are timezone-aware and are only available if the timezone field is UTC. +The `original_install_date_epoch_utc` and `system_boot_time_epoch_utc` +calculated timestamp fields are timezone-aware and are only available if +the timezone field is UTC. Usage (cli): @@ -36,11 +40,11 @@ Schema: "registered_organization": string, "product_id": string, "original_install_date": string, - "original_install_date_epoch": integer, # naive timestamp - "original_install_date_epoch_utc": integer, # timezone-aware timestamp + "original_install_date_epoch": integer, # [0] + "original_install_date_epoch_utc": integer, # [1] "system_boot_time": string, - "system_boot_time_epoch": integer, # naive timestamp - "system_boot_time_epoch_utc": integer, # timezone-aware timestamp + "system_boot_time_epoch": integer, # [0] + "system_boot_time_epoch_utc": integer, # [1] "system_manufacturer": string, "system_model": string, "system_type": string, @@ -85,6 +89,9 @@ Schema: } } + [0] naive timestamp + [1] timezone-aware timestamp + Examples: $ systeminfo | jc --systeminfo -p diff --git a/docs/parsers/time.md b/docs/parsers/time.md index e45b6347..0fccc5ff 100644 --- a/docs/parsers/time.md +++ b/docs/parsers/time.md @@ -3,15 +3,19 @@ # jc.parsers.time jc - JSON CLI output utility `/usr/bin/time` command output parser -Output from `/usr/bin/time` is sent to `STDERR`, so the `-o` option can be used to redirect the output to a file that can be read by `jc`. +Output from `/usr/bin/time` is sent to `STDERR`, so the `-o` option can be +used to redirect the output to a file that can be read by `jc`. -Alternatively, the output from `/usr/bin/time` can be redirected to `STDOUT` so `jc` can receive it. +Alternatively, the output from `/usr/bin/time` can be redirected to `STDOUT` +so `jc` can receive it. -Note: `/usr/bin/time` is similar but different from the Bash builtin `time` command. +Note: `/usr/bin/time` is similar but different from the Bash builtin + `time` command. Usage (cli): - $ /usr/bin/time -o timefile.out sleep 2.5; cat timefile.out | jc --time -p + $ /usr/bin/time -o timefile.out sleep 2; cat timefile.out | \ + jc --time -p Usage (module): @@ -44,8 +48,8 @@ Schema: "average_unshared_stack_size": integer, "average_shared_memory_size": integer, "maximum_resident_set_size": integer, - "block_input_operations": integer, # aka File system inputs - "block_output_operations": integer, # aka File system outputs + "block_input_operations": integer, # [0] + "block_output_operations": integer, # [1] "major_pagefaults": integer, "minor_pagefaults": integer, "swaps": integer, @@ -65,15 +69,19 @@ Schema: "exit_status": integer } + [0] aka File system inputs + [1] aka File system outputs + Examples: - $ /usr/bin/time --verbose -o timefile.out sleep 2.5; cat timefile.out | jc --time -p + $ /usr/bin/time --verbose -o timefile.out sleep 2; cat timefile.out | \ + jc --time -p { - "command_being_timed": "sleep 2.5", + "command_being_timed": "sleep 2", "user_time": 0.0, "system_time": 0.0, "cpu_percent": 0, - "elapsed_time": "0:02.50", + "elapsed_time": "0:02.00", "average_shared_text_size": 0, "average_unshared_data_size": 0, "average_stack_size": 0, @@ -99,13 +107,14 @@ Examples: "elapsed_time_total_seconds": 2.5 } - $ /usr/bin/time --verbose -o timefile.out sleep 2.5; cat timefile.out | jc --time -p -r + $ /usr/bin/time --verbose -o timefile.out sleep 2; cat timefile.out | \ + jc --time -p -r { - "command_being_timed": ""sleep 2.5"", + "command_being_timed": ""sleep 2"", "user_time": "0.00", "system_time": "0.00", "cpu_percent": "0", - "elapsed_time": "0:02.50", + "elapsed_time": "0:02.00", "average_shared_text_size": "0", "average_unshared_data_size": "0", "average_stack_size": "0", diff --git a/docs/parsers/timedatectl.md b/docs/parsers/timedatectl.md index f838cd56..51c7e48d 100644 --- a/docs/parsers/timedatectl.md +++ b/docs/parsers/timedatectl.md @@ -3,7 +3,8 @@ # jc.parsers.timedatectl jc - JSON CLI output utility `timedatectl` command output parser -The `epoch_utc` calculated timestamp field is timezone-aware and is only available if the `universal_time` field is available. +The `epoch_utc` calculated timestamp field is timezone-aware and is only +available if the `universal_time` field is available. Usage (cli): @@ -28,7 +29,7 @@ Schema: { "local_time": string, "universal_time": string, - "epoch_utc": integer, # timezone-aware timestamp + "epoch_utc": integer, # timezone-aware "rtc_time": string, "time_zone": string, "ntp_enabled": boolean, diff --git a/docs/parsers/traceroute.md b/docs/parsers/traceroute.md index 2f7b22ca..4f134946 100644 --- a/docs/parsers/traceroute.md +++ b/docs/parsers/traceroute.md @@ -5,7 +5,10 @@ jc - JSON CLI output utility `traceroute` command output parser Supports `traceroute` and `traceroute6` output. -Note: On some operating systems you will need to redirect `STDERR` to `STDOUT` for destination info since the header line is sent to `STDERR`. A warning message will be printed to `STDERR` if the header row is not found. +Note: On some operating systems you will need to redirect `STDERR` to + `STDOUT` for destination info since the header line is sent to + `STDERR`. A warning message will be printed to `STDERR` if the + header row is not found. e.g. `$ traceroute 8.8.8.8 2>&1 | jc --traceroute` diff --git a/docs/parsers/ufw.md b/docs/parsers/ufw.md index a9b926f0..cea8a709 100644 --- a/docs/parsers/ufw.md +++ b/docs/parsers/ufw.md @@ -48,7 +48,7 @@ Schema: "end": integer } ], - "to_service": string, # null if any to ports or port_ranges are set + "to_service": string, # [0] "from_ip": string, "from_ip_prefix": integer, "from_interface": string, @@ -62,12 +62,15 @@ Schema: "end": integer } ], - "from_service": string, # null if any from ports or port_ranges are set + "from_service": string, # [1] "comment": string # null if no comment } ] } + [0] null if any 'to' ports or port_ranges are set + [1] null if any 'from' ports or port_ranges are set + Examples: $ ufw status verbose | jc --ufw -p diff --git a/docs/parsers/ufw_appinfo.md b/docs/parsers/ufw_appinfo.md index 707d4e4c..6f35c0e3 100644 --- a/docs/parsers/ufw_appinfo.md +++ b/docs/parsers/ufw_appinfo.md @@ -1,11 +1,15 @@ [Home](https://kellyjonbrazil.github.io/jc/) # jc.parsers.ufw_appinfo -jc - JSON CLI output utility `ufw app info [application]` command output parser +jc - JSON CLI output utility `ufw app info [application]` command +output parser -Supports individual apps via `ufw app info [application]` and all apps list via `ufw app info all`. +Supports individual apps via `ufw app info [application]` and all apps list +via `ufw app info all`. -Because `ufw` application definitions allow overlapping ports and port ranges, this parser preserves that behavior, but also provides `normalized` lists and ranges that remove duplicate ports and merge overlapping ranges. +Because `ufw` application definitions allow overlapping ports and port +ranges, this parser preserves that behavior, but also provides `normalized` +lists and ranges that remove duplicate ports and merge overlapping ranges. Usage (cli): @@ -46,31 +50,35 @@ Schema: ], "udp_ranges": [ { - "start": integer, # 'any' is converted to start/end: 0/65535 + "start": integer, # [0] "end": integer } ], "normalized_tcp_list": [ - integers # duplicates and overlapping are removed + integers # [1] ], "normalized_tcp_ranges": [ { - "start": integer, # 'any' is converted to start/end: 0/65535 - "end": integers # overlapping are merged + "start": integer, # [0] + "end": integers # [2] } ], "normalized_udp_list": [ - integers # duplicates and overlapping are removed + integers # [1] ], "normalized_udp_ranges": [ { - "start": integer, # 'any' is converted to start/end: 0/65535 - "end": integers # overlapping are merged + "start": integer, # [0] + "end": integers # [2] } ] } ] + [0] 'any' is converted to start/end: 0/65535 + [1] duplicates and overlapping are removed + [2] overlapping are merged + Examples: $ ufw app info MSN | jc --ufw-appinfo -p diff --git a/docs/parsers/upower.md b/docs/parsers/upower.md index 58a10431..9721547d 100644 --- a/docs/parsers/upower.md +++ b/docs/parsers/upower.md @@ -3,9 +3,11 @@ # jc.parsers.upower jc - JSON CLI output utility `upower` command output parser -The `updated_epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `updated_epoch` calculated timestamp field is naive. (i.e. based on the +local time of the system the parser is run on) -The `updated_epoch_utc` calculated timestamp field is timezone-aware and is only available if the timezone field is UTC. +The `updated_epoch_utc` calculated timestamp field is timezone-aware and is +only available if the timezone field is UTC. Usage (cli): @@ -34,8 +36,8 @@ Schema: "native_path": string, "power_supply": boolean, "updated": string, - "updated_epoch": integer, # null if date-time conversion fails - "updated_epoch_utc": integer, # null if date-time conversion fails + "updated_epoch": integer, # [0] + "updated_epoch_utc": integer, # [0] "updated_seconds_ago": integer, "has_history": boolean, "has_statistics": boolean, @@ -87,12 +89,14 @@ Schema: } ] + [0] null if date-time conversion fails + Examples: $ upower -i /org/freedesktop/UPower/devices/battery | jc --upower -p [ { - "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/power_supply/BAT0", + "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/p...", "vendor": "NOTEBOOK", "model": "BAT", "serial": "0001", @@ -151,7 +155,7 @@ Examples: $ upower -i /org/freedesktop/UPower/devices/battery | jc --upower -p -r [ { - "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/power_supply/BAT0", + "native_path": "/sys/devices/LNXSYSTM:00/device:00/PNP0C0A:00/p...", "vendor": "NOTEBOOK", "model": "BAT", "serial": "0001", diff --git a/docs/parsers/vmstat.md b/docs/parsers/vmstat.md index d2a40d62..c46b62f4 100644 --- a/docs/parsers/vmstat.md +++ b/docs/parsers/vmstat.md @@ -5,9 +5,11 @@ jc - JSON CLI output utility `vmstat` command output parser Options supported: `-a`, `-w`, `-d`, `-t` -The `epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `epoch` calculated timestamp field is naive. (i.e. based on the local +time of the system the parser is run on) -The `epoch_utc` calculated timestamp field is timezone-aware and is only available if the timezone field is UTC. +The `epoch_utc` calculated timestamp field is timezone-aware and is only +available if the timezone field is UTC. Usage (cli): @@ -63,11 +65,14 @@ Schema: "io_seconds": integer, "timestamp": string, "timezone": string, - "epoch": integer, # naive timestamp if -t flag is used - "epoch_utc": integer # aware timestamp if -t flag is used and UTC TZ + "epoch": integer, # [0] + "epoch_utc": integer # [1] } ] + [0] naive timestamp if -t flag is used + [1] aware timestamp if -t flag is used and UTC TZ + Examples: $ vmstat | jc --vmstat -p diff --git a/docs/parsers/vmstat_s.md b/docs/parsers/vmstat_s.md index 1a7ef443..205eef6a 100644 --- a/docs/parsers/vmstat_s.md +++ b/docs/parsers/vmstat_s.md @@ -7,83 +7,100 @@ jc - JSON CLI output utility `vmstat` command output streaming parser Options supported: `-a`, `-w`, `-d`, `-t` -The `epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `epoch` calculated timestamp field is naive. (i.e. based on the local +time of the system the parser is run on) -The `epoch_utc` calculated timestamp field is timezone-aware and is only available if the timezone field is UTC. +The `epoch_utc` calculated timestamp field is timezone-aware and is only +available if the timezone field is UTC. Usage (cli): $ vmstat | jc --vmstat-s -> Note: When piping `jc` converted `vmstat` output to other processes it may appear the output is hanging due to the OS pipe buffers. This is because `vmstat` output is too small to quickly fill up the buffer. Use the `-u` option to unbuffer the `jc` output if you would like immediate output. See the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output) for more information. +> Note: When piping `jc` converted `vmstat` output to other processes it may +appear the output is hanging due to the OS pipe buffers. This is because +`vmstat` output is too small to quickly fill up the buffer. Use the `-u` +option to unbuffer the `jc` output if you would like immediate output. See +the [readme](https://github.com/kellyjonbrazil/jc/tree/master#unbuffering-output) +for more information. Usage (module): import jc - result = jc.parse('vmstat_s', vmstat_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parse('vmstat_s', vmstat_command_output.splitlines()) for item in result: # do something or import jc.parsers.vmstat_s - result = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines()) # result is an iterable object + # result is an iterable object (generator) + result = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines()) for item in result: # do something Schema: { - "runnable_procs": integer, - "uninterruptible_sleeping_procs": integer, - "virtual_mem_used": integer, - "free_mem": integer, - "buffer_mem": integer, - "cache_mem": integer, - "inactive_mem": integer, - "active_mem": integer, - "swap_in": integer, - "swap_out": integer, - "blocks_in": integer, - "blocks_out": integer, - "interrupts": integer, - "context_switches": integer, - "user_time": integer, - "system_time": integer, - "idle_time": integer, - "io_wait_time": integer, - "stolen_time": integer, - "disk": string, - "total_reads": integer, - "merged_reads": integer, - "sectors_read": integer, - "reading_ms": integer, - "total_writes": integer, - "merged_writes": integer, - "sectors_written": integer, - "writing_ms": integer, - "current_io": integer, - "io_seconds": integer, - "timestamp": string, - "timezone": string, - "epoch": integer, # naive timestamp if -t flag is used - "epoch_utc": integer # aware timestamp if -t flag is used and UTC TZ - "_jc_meta": # This object only exists if using -qq or ignore_exceptions=True + "runnable_procs": integer, + "uninterruptible_sleeping_procs": integer, + "virtual_mem_used": integer, + "free_mem": integer, + "buffer_mem": integer, + "cache_mem": integer, + "inactive_mem": integer, + "active_mem": integer, + "swap_in": integer, + "swap_out": integer, + "blocks_in": integer, + "blocks_out": integer, + "interrupts": integer, + "context_switches": integer, + "user_time": integer, + "system_time": integer, + "idle_time": integer, + "io_wait_time": integer, + "stolen_time": integer, + "disk": string, + "total_reads": integer, + "merged_reads": integer, + "sectors_read": integer, + "reading_ms": integer, + "total_writes": integer, + "merged_writes": integer, + "sectors_written": integer, + "writing_ms": integer, + "current_io": integer, + "io_seconds": integer, + "timestamp": string, + "timezone": string, + "epoch": integer, # [0] + "epoch_utc": integer # [1] + + # Below object only exists if using -qq or ignore_exceptions=True + + "_jc_meta": { - "success": boolean, # true if successfully parsed, false if error - "error": string, # exists if "success" is false - "line": string # exists if "success" is false + "success": boolean, # [2] + "error": string, # [3] + "line": string # [3] } } + [0] naive timestamp if -t flag is used + [1] aware timestamp if -t flag is used and UTC TZ + [2] false if error parsing + [3] exists if "success" is false + Examples: $ vmstat | jc --vmstat-s - {"runnable_procs":2,"uninterruptible_sleeping_procs":0,"virtual_mem_used":0,"free_mem":2794468,"buffer_mem":2108,"cache_mem":741208,"inactive_mem":null,"active_mem":null,"swap_in":0,"swap_out":0,"blocks_in":1,"blocks_out":3,"interrupts":29,"context_switches":57,"user_time":0,"system_time":0,"idle_time":99,"io_wait_time":0,"stolen_time":0,"timestamp":null,"timezone":null} + {"runnable_procs":2,"uninterruptible_sleeping_procs":0,"virtual_mem...} ... $ vmstat | jc --vmstat-s -r - {"runnable_procs":"2","uninterruptible_sleeping_procs":"0","virtual_mem_used":"0","free_mem":"2794468","buffer_mem":"2108","cache_mem":"741208","inactive_mem":null,"active_mem":null,"swap_in":"0","swap_out":"0","blocks_in":"1","blocks_out":"3","interrupts":"29","context_switches":"57","user_time":"0","system_time":"0","idle_time":"99","io_wait_time":"0","stolen_time":"0","timestamp":null,"timezone":null} + {"runnable_procs":"2","uninterruptible_sleeping_procs":"0","virtua...} ... @@ -102,7 +119,9 @@ Main text parsing generator function. Returns an iterator object. Parameters: - data: (iterable) line-based text data to parse (e.g. sys.stdin or str.splitlines()) + data: (iterable) line-based text data to parse + (e.g. sys.stdin or str.splitlines()) + raw: (boolean) output preprocessed JSON if True quiet: (boolean) suppress warning messages if True ignore_exceptions: (boolean) ignore parsing exceptions if True diff --git a/docs/parsers/who.md b/docs/parsers/who.md index c26d2a73..f8c52308 100644 --- a/docs/parsers/who.md +++ b/docs/parsers/who.md @@ -5,7 +5,8 @@ jc - JSON CLI output utility `who` command output parser Accepts any of the following who options (or no options): `-aTH` -The `epoch` calculated timestamp field is naive (i.e. based on the local time of the system the parser is run on) +The `epoch` calculated timestamp field is naive. (i.e. based on the local +time of the system the parser is run on) Usage (cli): @@ -34,7 +35,7 @@ Schema: "writeable_tty": string, "tty": string, "time": string, - "epoch": integer, # naive timestamp. null if time cannot be converted + "epoch": integer, # [0] "idle": string, "pid": integer, "from": string, @@ -42,6 +43,8 @@ Schema: } ] + [0] naive timestamp. null if time cannot be converted + Examples: $ who -a | jc --who -p