diff --git a/README.md b/README.md index 259e5a31..2d6e009f 100644 --- a/README.md +++ b/README.md @@ -311,11 +311,11 @@ color output will override both the `NO_COLOR` environment variable and the `-m` option. ### Streaming Parsers -Most parsers load all of the data from STDIN, parse it, then output the entire +Most parsers load all of the data from `STDIN`, parse it, then output the entire JSON document serially. There are some streaming parsers (e.g. `ls-s` and `ping-s`) that immediately start processing and outputing the data line-by-line as [JSON Lines](https://jsonlines.org/) (aka [NDJSON](http://ndjson.org/)) while -it is being received from STDIN. This can significantly reduce the amount of +it is being received from `STDIN`. This can significantly reduce the amount of memory required to parse large amounts of command output (e.g. `ls -lR /`) and can sometimes process the data more quickly. Streaming parsers have slightly different behavior than standard parsers as outlined below. diff --git a/docs/parsers/asciitable_m.md b/docs/parsers/asciitable_m.md index eabc2da0..cd034c56 100644 --- a/docs/parsers/asciitable_m.md +++ b/docs/parsers/asciitable_m.md @@ -31,8 +31,9 @@ except empty strings, which are converted to None/null. > Note: table column separator characters (e.g. `|`) cannot be present > inside the cell data. If detected, a warning message will be printed to -> STDERR and the line will be skipped. The warning message can be suppressed -> by using the `-q` command option or by setting `quiet=True` in `parse()`. +> `STDERR` and the line will be skipped. The warning message can be +> suppressed by using the `-q` command option or by setting `quiet=True` in +> `parse()`. Usage (cli): diff --git a/docs/parsers/rsync.md b/docs/parsers/rsync.md index 30828667..ce9045fd 100644 --- a/docs/parsers/rsync.md +++ b/docs/parsers/rsync.md @@ -6,7 +6,7 @@ jc - JSON Convert `rsync` command output parser Supports the `-i` or `--itemize-changes` options with all levels of -verbosity. This parser will process the STDOUT output or a log file +verbosity. This parser will process the `STDOUT` output or a log file generated with the `--log-file` option. Usage (cli): diff --git a/docs/parsers/rsync_s.md b/docs/parsers/rsync_s.md index 4e62068e..be7be22e 100644 --- a/docs/parsers/rsync_s.md +++ b/docs/parsers/rsync_s.md @@ -9,7 +9,7 @@ jc - JSON Convert `rsync` command output streaming parser > Dictionaries (module) Supports the `-i` or `--itemize-changes` options with all levels of -verbosity. This parser will process the STDOUT output or a log file +verbosity. This parser will process the `STDOUT` output or a log file generated with the `--log-file` option. Usage (cli): diff --git a/docs/parsers/top.md b/docs/parsers/top.md index 51d0cc96..d8cf5e32 100644 --- a/docs/parsers/top.md +++ b/docs/parsers/top.md @@ -8,8 +8,9 @@ jc - JSON Convert `top -b` command output parser Requires batch mode (`-b`). The `-n` option must also be used to limit the number of times `top` is run. -Warning messages will be printed to STDERR if truncated fields are detected. -These warnings can be suppressed with the `-q` or `quiet=True` option. +Warning messages will be printed to `STDERR` if truncated fields are +detected. These warnings can be suppressed with the `-q` or `quiet=True` +option. Usage (cli): diff --git a/docs/utils.md b/docs/utils.md index 4cb037d7..bd8dc212 100644 --- a/docs/utils.md +++ b/docs/utils.md @@ -27,7 +27,7 @@ jc - JSON Convert utils def warning_message(message_lines: List[str]) -> None ``` -Prints warning message to STDERR for non-fatal issues. The first line +Prints warning message to `STDERR` for non-fatal issues. The first line is prepended with 'jc: Warning - ' and subsequent lines are indented. Wraps text as needed based on the terminal width. @@ -47,7 +47,7 @@ Returns: def error_message(message_lines: List[str]) -> None ``` -Prints an error message to STDERR for fatal issues. The first line is +Prints an error message to `STDERR` for fatal issues. The first line is prepended with 'jc: Error - ' and subsequent lines are indented. Wraps text as needed based on the terminal width. @@ -80,7 +80,7 @@ def compatibility(mod_name: str, ``` Checks for the parser's compatibility with the running OS platform and -prints a warning message to STDERR if not compatible and quiet=False. +prints a warning message to `STDERR` if not compatible and quiet=False. Parameters: diff --git a/jc/cli.py b/jc/cli.py index c6fca888..b5fd8fe3 100644 --- a/jc/cli.py +++ b/jc/cli.py @@ -134,7 +134,7 @@ def set_env_colors(env_colors=None): def piped_output(force_color): """ - Return False if stdout is a TTY. True if output is being piped to + Return False if `STDOUT` is a TTY. True if output is being piped to another program and foce_color is True. This allows forcing of ANSI color codes even when using pipes. """ diff --git a/jc/parsers/asciitable_m.py b/jc/parsers/asciitable_m.py index 7485cdd2..d85bfa14 100644 --- a/jc/parsers/asciitable_m.py +++ b/jc/parsers/asciitable_m.py @@ -26,8 +26,9 @@ except empty strings, which are converted to None/null. > Note: table column separator characters (e.g. `|`) cannot be present > inside the cell data. If detected, a warning message will be printed to -> STDERR and the line will be skipped. The warning message can be suppressed -> by using the `-q` command option or by setting `quiet=True` in `parse()`. +> `STDERR` and the line will be skipped. The warning message can be +> suppressed by using the `-q` command option or by setting `quiet=True` in +> `parse()`. Usage (cli): diff --git a/jc/parsers/rsync.py b/jc/parsers/rsync.py index 8664e0dc..c6a15f46 100644 --- a/jc/parsers/rsync.py +++ b/jc/parsers/rsync.py @@ -1,7 +1,7 @@ """jc - JSON Convert `rsync` command output parser Supports the `-i` or `--itemize-changes` options with all levels of -verbosity. This parser will process the STDOUT output or a log file +verbosity. This parser will process the `STDOUT` output or a log file generated with the `--log-file` option. Usage (cli): diff --git a/jc/parsers/rsync_s.py b/jc/parsers/rsync_s.py index 508cce87..692f3395 100644 --- a/jc/parsers/rsync_s.py +++ b/jc/parsers/rsync_s.py @@ -4,7 +4,7 @@ > Dictionaries (module) Supports the `-i` or `--itemize-changes` options with all levels of -verbosity. This parser will process the STDOUT output or a log file +verbosity. This parser will process the `STDOUT` output or a log file generated with the `--log-file` option. Usage (cli): diff --git a/jc/parsers/top.py b/jc/parsers/top.py index 5ac2e067..7bd297a7 100644 --- a/jc/parsers/top.py +++ b/jc/parsers/top.py @@ -3,8 +3,9 @@ Requires batch mode (`-b`). The `-n` option must also be used to limit the number of times `top` is run. -Warning messages will be printed to STDERR if truncated fields are detected. -These warnings can be suppressed with the `-q` or `quiet=True` option. +Warning messages will be printed to `STDERR` if truncated fields are +detected. These warnings can be suppressed with the `-q` or `quiet=True` +option. Usage (cli): diff --git a/jc/utils.py b/jc/utils.py index 39ba98e6..401c527e 100644 --- a/jc/utils.py +++ b/jc/utils.py @@ -31,7 +31,7 @@ def _safe_print(string: str, sep=' ', end='\n', file=sys.stdout, flush=False) -> def warning_message(message_lines: List[str]) -> None: """ - Prints warning message to STDERR for non-fatal issues. The first line + Prints warning message to `STDERR` for non-fatal issues. The first line is prepended with 'jc: Warning - ' and subsequent lines are indented. Wraps text as needed based on the terminal width. @@ -67,7 +67,7 @@ def warning_message(message_lines: List[str]) -> None: def error_message(message_lines: List[str]) -> None: """ - Prints an error message to STDERR for fatal issues. The first line is + Prints an error message to `STDERR` for fatal issues. The first line is prepended with 'jc: Error - ' and subsequent lines are indented. Wraps text as needed based on the terminal width. @@ -114,7 +114,7 @@ def is_compatible(compatible: List) -> bool: def compatibility(mod_name: str, compatible: List, quiet: bool = False) -> None: """ Checks for the parser's compatibility with the running OS platform and - prints a warning message to STDERR if not compatible and quiet=False. + prints a warning message to `STDERR` if not compatible and quiet=False. Parameters: diff --git a/templates/readme_template b/templates/readme_template index 5fe5b0be..d5a2be35 100644 --- a/templates/readme_template +++ b/templates/readme_template @@ -211,11 +211,11 @@ color output will override both the `NO_COLOR` environment variable and the `-m` option. ### Streaming Parsers -Most parsers load all of the data from STDIN, parse it, then output the entire +Most parsers load all of the data from `STDIN`, parse it, then output the entire JSON document serially. There are some streaming parsers (e.g. `ls-s` and `ping-s`) that immediately start processing and outputing the data line-by-line as [JSON Lines](https://jsonlines.org/) (aka [NDJSON](http://ndjson.org/)) while -it is being received from STDIN. This can significantly reduce the amount of +it is being received from `STDIN`. This can significantly reduce the amount of memory required to parse large amounts of command output (e.g. `ls -lR /`) and can sometimes process the data more quickly. Streaming parsers have slightly different behavior than standard parsers as outlined below.