doc update

docs/parsers/csv_s.md

@@ -73,6 +73,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -85,7 +86,10 @@ Parameters:
 
     raw:               (boolean)   unprocessed output if True
     quiet:             (boolean)   suppress warning messages if True
-    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True.
+                                   This can be used directly or
+                                   (preferably) by being passed to the
+                                   @add_jc_meta decorator.
 
 Yields:
 
@@ -98,4 +102,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
 
-Version 1.2 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.3 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/iostat_s.md

@@ -110,6 +110,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -122,7 +123,10 @@ Parameters:
 
     raw:               (boolean)   unprocessed output if True
     quiet:             (boolean)   suppress warning messages if True
-    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True.
+                                   This can be used directly or
+                                   (preferably) by being passed to the
+                                   @add_jc_meta decorator.
 
 Yields:
 
@@ -135,4 +139,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux
 
-Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ls_s.md

@@ -87,6 +87,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -99,7 +100,10 @@ Parameters:
 
     raw:               (boolean)   unprocessed output if True
     quiet:             (boolean)   suppress warning messages if True
-    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True.
+                                   This can be used directly or
+                                   (preferably) by being passed to the
+                                   @add_jc_meta decorator.
 
 Yields:
 
@@ -112,4 +116,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, cygwin, aix, freebsd
 
-Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/ping_s.md

@@ -93,6 +93,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -105,7 +106,10 @@ Parameters:
 
     raw:               (boolean)   unprocessed output if True
     quiet:             (boolean)   suppress warning messages if True
-    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True.
+                                   This can be used directly or
+                                   (preferably) by being passed to the
+                                   @add_jc_meta decorator.
 
 Yields:
 
@@ -118,4 +122,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/rsync_s.md

@@ -96,7 +96,8 @@ Examples:
 ### parse
 
 ```python
-def parse(data: Iterable[str], raw: bool = False, quiet: bool = False, ignore_exceptions: bool = False) -> Iterable[Dict]
+@add_jc_meta
+def parse(data: Iterable[str], raw: bool = False, quiet: bool = False, ignore_exceptions: bool = False) -> Union[Iterable[Dict], tuple]
 ```
 
 Main text parsing generator function. Returns an iterator object.
@@ -108,7 +109,10 @@ Parameters:
 
     raw:               (boolean)   unprocessed output if True
     quiet:             (boolean)   suppress warning messages if True
-    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True.
+                                   This can be used directly or
+                                   (preferably) by being passed to the
+                                   @add_jc_meta decorator.
 
 Yields:
 
@@ -121,4 +125,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.1 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/stat_s.md

@@ -91,6 +91,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -103,7 +104,10 @@ Parameters:
 
     raw:               (boolean)   unprocessed output if True
     quiet:             (boolean)   suppress warning messages if True
-    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True.
+                                   This can be used directly or
+                                   (preferably) by being passed to the
+                                   @add_jc_meta decorator.
 
 Yields:
 
@@ -116,4 +120,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux, darwin, freebsd
 
-Version 0.5 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/vmstat_s.md

@@ -110,6 +110,7 @@ Examples:
 ### parse
 
 ```python
+@add_jc_meta
 def parse(data, raw=False, quiet=False, ignore_exceptions=False)
 ```
 
@@ -122,7 +123,10 @@ Parameters:
 
     raw:               (boolean)   unprocessed output if True
     quiet:             (boolean)   suppress warning messages if True
-    ignore_exceptions: (boolean)   ignore parsing exceptions if True
+    ignore_exceptions: (boolean)   ignore parsing exceptions if True.
+                                   This can be used directly or
+                                   (preferably) by being passed to the
+                                   @add_jc_meta decorator.
 
 Yields:
 
@@ -135,4 +139,4 @@ Returns:
 ### Parser Information
 Compatibility:  linux
 
-Version 0.6 by Kelly Brazil (kellyjonbrazil@gmail.com)
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/utils.md

@@ -10,6 +10,7 @@
   * [convert\_to\_bool](#jc.utils.convert_to_bool)
   * [stream\_success](#jc.utils.stream_success)
   * [stream\_error](#jc.utils.stream_error)
+  * [add\_jc\_meta](#jc.utils.add_jc_meta)
   * [input\_type\_check](#jc.utils.input_type_check)
   * [streaming\_input\_type\_check](#jc.utils.streaming_input_type_check)
   * [streaming\_line\_input\_type\_check](#jc.utils.streaming_line_input_type_check)
@@ -186,6 +187,45 @@ def stream_error(e: BaseException, ignore_exceptions: bool, line: str) -> Dict
 Reraise the stream exception with annotation or print an error
 `_jc_meta` field if `ignore_exceptions=True`.
 
+<a id="jc.utils.add_jc_meta"></a>
+
+### add\_jc\_meta
+
+```python
+def add_jc_meta(func)
+```
+
+Decorator for streaming parsers to add stream_success and stream_error
+objects. This simplifies the yield lines in the streaming parsers.
+
+With the decorator on parse():
+
+    # successfully parsed line:
+    yield output_line if raw else _process(output_line)
+
+    # unsuccessfully parsed line:
+    except Exception as e:
+        yield e, line
+
+Without the decorator on parse():
+
+    # successfully parsed line:
+    yield stream_success(output_line, ignore_exceptions) if raw else stream_success(_process(output_line), ignore_exceptions)
+
+    # unsuccessfully parsed line:
+    except Exception as e:
+        yield stream_error(e, ignore_exceptions, line)
+
+In all cases above:
+
+    output_line:  (Dict):  successfully parsed line yielded as a dict
+
+    e:            (BaseException):  exception object as the first value
+                  of the tuple if the line was not successfully parsed.
+
+    line:         (str):  string of the original line that did not
+                  successfully parse.
+
 <a id="jc.utils.input_type_check"></a>
 
 ### input\_type\_check