streaming doc formatting update

docs/parsers/csv_s.md

@@ -5,7 +5,8 @@
 
 jc - JSON Convert `csv` file streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 The `csv` streaming parser will attempt to automatically detect the
 delimiter character. If the delimiter cannot be detected it will default
@@ -21,19 +22,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 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:

docs/parsers/iostat_s.md

@@ -5,7 +5,8 @@
 
 jc - JSON Convert `iostat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 Note: `iostat` version 11 and higher include a JSON output option
 
@@ -13,22 +14,21 @@ Usage (cli):
 
     $ iostat | jc --iostat-s
 
+> Note: When piping `jc` converted `iostat` output to other processes it may
+  appear the output is hanging due to the OS pipe buffers. This is because
+  `iostat` 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 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 is an iterable object (generator)
-    result = jc.parsers.iostat_s.parse(iostat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

docs/parsers/ls_s.md

@@ -3,10 +3,10 @@
 
 # jc.parsers.ls\_s
 
-jc - JSON Convert `ls` and `vdir` command output streaming
+jc - JSON Convert `ls` and `vdir` command output streaming parser
-parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 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`.
@@ -27,19 +27,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.ls_s.parse(ls_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

docs/parsers/pidstat_s.md

@@ -15,6 +15,13 @@ Usage (cli):
 
     $ pidstat | jc --pidstat-s
 
+> Note: When piping `jc` converted `pidstat` output to other processes it
+  may appear the output is hanging due to the OS pipe buffers. This is
+  because `pidstat` 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

docs/parsers/ping_s.md

@@ -5,7 +5,8 @@
 
 jc - JSON Convert `ping` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 Supports `ping` and `ping6` output.
 
@@ -23,19 +24,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.ping_s.parse(ping_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

docs/parsers/rsync_s.md

@@ -5,7 +5,8 @@
 
 jc - JSON Convert `rsync` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of 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
@@ -22,19 +23,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('rsync_s', rsync_command_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.rsync_s
-    # result is an iterable object (generator)
-    result = jc.parsers.rsync_s.parse(rsync_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

docs/parsers/stat_s.md

@@ -5,7 +5,8 @@
 
 jc - JSON Convert `stat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the
 local time of the system the parser is run on).
@@ -20,19 +21,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.stat_s.parse(stat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

docs/parsers/vmstat_s.md

@@ -5,7 +5,8 @@
 
 jc - JSON Convert `vmstat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 Options supported: `-a`, `-w`, `-d`, `-t`
 
@@ -29,19 +30,11 @@ for more information.
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

jc/parsers/csv_s.py

@@ -1,6 +1,7 @@
 """jc - JSON Convert `csv` file streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 The `csv` streaming parser will attempt to automatically detect the
 delimiter character. If the delimiter cannot be detected it will default
@@ -16,19 +17,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 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:

jc/parsers/foo_s.py

@@ -1,6 +1,7 @@
 """jc - JSON Convert `foo` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 <<Short foo description and caveats>>
 
@@ -11,19 +12,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('foo_s', foo_command_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.foo_s
-    # result is an iterable object (generator)
-    result = jc.parsers.foo_s.parse(foo_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

jc/parsers/iostat_s.py

@@ -1,6 +1,7 @@
 """jc - JSON Convert `iostat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 Note: `iostat` version 11 and higher include a JSON output option
 
@@ -8,22 +9,21 @@ Usage (cli):
 
     $ iostat | jc --iostat-s
 
+> Note: When piping `jc` converted `iostat` output to other processes it may
+  appear the output is hanging due to the OS pipe buffers. This is because
+  `iostat` 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 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 is an iterable object (generator)
-    result = jc.parsers.iostat_s.parse(iostat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

jc/parsers/ls_s.py

@@ -1,7 +1,7 @@
-"""jc - JSON Convert `ls` and `vdir` command output streaming
+"""jc - JSON Convert `ls` and `vdir` command output streaming parser
-parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 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`.
@@ -22,19 +22,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.ls_s.parse(ls_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

jc/parsers/pidstat_s.py

@@ -10,6 +10,13 @@ Usage (cli):
 
     $ pidstat | jc --pidstat-s
 
+> Note: When piping `jc` converted `pidstat` output to other processes it
+  may appear the output is hanging due to the OS pipe buffers. This is
+  because `pidstat` 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

jc/parsers/ping_s.py

@@ -1,6 +1,7 @@
 """jc - JSON Convert `ping` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 Supports `ping` and `ping6` output.
 
@@ -18,19 +19,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.ping_s.parse(ping_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

jc/parsers/rsync_s.py

@@ -1,6 +1,7 @@
 """jc - JSON Convert `rsync` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of 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
@@ -17,19 +18,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # result is an iterable object (generator)
+
     result = jc.parse('rsync_s', rsync_command_output.splitlines())
     for item in result:
         # do something
 
-    or
-
-    import jc.parsers.rsync_s
-    # result is an iterable object (generator)
-    result = jc.parsers.rsync_s.parse(rsync_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

jc/parsers/stat_s.py

@@ -1,6 +1,7 @@
 """jc - JSON Convert `stat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 The `xxx_epoch` calculated timestamp fields are naive. (i.e. based on the
 local time of the system the parser is run on).
@@ -15,19 +16,11 @@ Usage (cli):
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.stat_s.parse(stat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {

jc/parsers/vmstat_s.py

@@ -1,6 +1,7 @@
 """jc - JSON Convert `vmstat` command output streaming parser
 
-> This streaming parser outputs JSON Lines
+> This streaming parser outputs JSON Lines (cli) or returns a Generator
+  iterator of Dictionaries (module)
 
 Options supported: `-a`, `-w`, `-d`, `-t`
 
@@ -24,19 +25,11 @@ for more information.
 Usage (module):
 
     import jc
-    # 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 is an iterable object (generator)
-    result = jc.parsers.vmstat_s.parse(vmstat_command_output.splitlines())
-    for item in result:
-        # do something
-
 Schema:
 
     {