How to: Streaming Parsers
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 outputting 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
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.

> Note: Streaming parsers cannot be used with the "magic" syntax

#### Ignoring Errors

You may want to ignore parsing errors when using streaming parsers since these
may be used in long-lived processing pipelines and errors can break the pipe. To
ignore parsing errors, use the `-qq` cli option or the `ignore_exceptions=True`
argument with the `parse()` function. This will add a `_jc_meta` object to the
JSON output with a `success` attribute. If `success` is `true`, then there were
no issues parsing the line. If `success` is `false`, then a parsing issue was
found and `error` and `line` fields will be added to include a short error
description and the contents of the unparsable line, respectively:

Successfully parsed line with `-qq` option:
```json
{
  "command_data": "data",
  "_jc_meta": {
    "success": true
  }
}
```

Unsuccessfully parsed line with `-qq` option:
```json
{
  "_jc_meta": {
    "success": false,
    "error": "error message",
    "line": "original line data"
  }
}
```

#### Unbuffering Output

Most operating systems will buffer output that is being piped from process to
process. The buffer is usually around 4KB. When viewing the output in the
terminal the OS buffer is not engaged so output is immediately displayed on the
screen. When piping multiple processes together, though, it may seem as if the
output is hanging when the input data is very slow (e.g. `ping`):
```
$ ping 1.1.1.1 | jc --ping-s | jq
```

This is because the OS engages the 4KB buffer between `jc` and `jq` in this
example. To display the data on the terminal in realtime, you can disable the
buffer with the `-u` (unbuffer) cli option:
```
$ ping 1.1.1.1 | jc --ping-s -u | jq
{"type":"reply","pattern":null,"timestamp":null,"bytes":"64","respons...}
{"type":"reply","pattern":null,"timestamp":null,"bytes":"64","respons...}
...
```

> Note: Unbuffered output can be slower for large data streams.

#### Using Streaming Parsers as Python Modules

Streaming parsers accept any iterable object and return an iterable object
allowing lazy processing of the data. The input data should iterate on lines
of string data. Examples of good input data are `sys.stdin` or
`str.splitlines()`.

To use the returned iterable object in your code, simply loop through it or
use the [next()](https://docs.python.org/3/library/functions.html#next)
builtin function:
```python
import jc

result = jc.parse('ls_s', ls_command_output.splitlines())
for item in result:
    print(item["filename"])
```