From b204c423c1b947c17cb251a5dd3c444cd71dd2c0 Mon Sep 17 00:00:00 2001 From: Kelly Brazil Date: Tue, 22 Mar 2022 07:05:14 -0700 Subject: [PATCH] doc update --- README.md | 1 + docs/parsers/asciitable_m.md | 122 +++++++++++++++++++++++++++++++++++ jc/parsers/asciitable_m.py | 78 ++++++++++++++++++---- man/jc.1 | 7 +- 4 files changed, 193 insertions(+), 15 deletions(-) create mode 100644 docs/parsers/asciitable_m.md diff --git a/README.md b/README.md index 46316b3d..83613911 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,7 @@ option. - `--airport` enables the `airport -I` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/airport)) - `--airport-s` enables the `airport -s` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/airport_s)) - `--arp` enables the `arp` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/arp)) +- `--asciitable-m` enables the multi-line ASCII and Unicode table parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/asciitable_m)) - `--blkid` enables the `blkid` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/blkid)) - `--cksum` enables the `cksum` and `sum` command parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/cksum)) - `--crontab` enables the `crontab` command and file parser ([documentation](https://kellyjonbrazil.github.io/jc/docs/parsers/crontab)) diff --git a/docs/parsers/asciitable_m.md b/docs/parsers/asciitable_m.md new file mode 100644 index 00000000..23056ca9 --- /dev/null +++ b/docs/parsers/asciitable_m.md @@ -0,0 +1,122 @@ +[Home](https://kellyjonbrazil.github.io/jc/) + + +# jc.parsers.asciitable\_m + +jc - JSON Convert `asciitable-m` parser + +This parser converts various styles of ASCII and Unicode text tables with +multi-line rows. Tables must have a header row and separator line between +rows. + +For example: + + ╒══════════╤═════════╤════════╕ + │ foo │ bar baz │ fiz │ + │ │ │ buz │ + ╞══════════╪═════════╪════════╡ + │ good day │ 12345 │ │ + │ mate │ │ │ + ├──────────┼─────────┼────────┤ + │ hi there │ abc def │ 3.14 │ + │ │ │ │ + ╘══════════╧═════════╧════════╛ + +Cells with multiple lines within rows will be joined with a new-line +character ('\n'). + +Headers (keys) are converted to snake case and newlines between multi-line +headers are joined with an underscore. All values are returned as strings. + +Usage (cli): + + $ cat table.txt | jc --asciitable-m + +Usage (module): + + import jc + result = jc.parse('asciitable_m', asciitable-string) + +Schema: + + [ + { + "column_name1": string, + "column_name2": string + } + ] + +Examples: + + $ echo ' + > +----------+---------+--------+ + > | foo | bar | baz | + > | | | buz | + > +==========+=========+========+ + > | good day | 12345 | | + > | mate | | | + > +----------+---------+--------+ + > | hi there | abc def | 3.14 | + > | | | | + > +==========+=========+========+' | jc --asciitable-m -p + [ + { + "foo": "good day\nmate", + "bar": "12345", + "baz_buz": "" + }, + { + "foo": "hi there", + "bar": "abc def", + "baz_buz": "3.14" + } + ] + + $ echo ' + > ╒══════════╤═════════╤════════╕ + > │ foo │ bar │ baz │ + > │ │ │ buz │ + > ╞══════════╪═════════╪════════╡ + > │ good day │ 12345 │ │ + > │ mate │ │ │ + > ├──────────┼─────────┼────────┤ + > │ hi there │ abc def │ 3.14 │ + > │ │ │ │ + > ╘══════════╧═════════╧════════╛' | jc --asciitable-m -p + [ + { + "foo": "good day\nmate", + "bar": "12345", + "baz_buz": "" + }, + { + "foo": "hi there", + "bar": "abc def", + "baz_buz": "3.14" + } + ] + + + +### parse + +```python +def parse(data: str, raw: bool = False, quiet: bool = False) -> List[Dict] +``` + +Main text parsing function + +Parameters: + + data: (string) text data to parse + raw: (boolean) unprocessed output if True + quiet: (boolean) suppress warning messages if True + +Returns: + + List of Dictionaries. Raw or processed structured data. + +### Parser Information +Compatibility: linux, darwin, cygwin, win32, aix, freebsd + +Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com) diff --git a/jc/parsers/asciitable_m.py b/jc/parsers/asciitable_m.py index b80fbadd..bf19edb9 100644 --- a/jc/parsers/asciitable_m.py +++ b/jc/parsers/asciitable_m.py @@ -1,7 +1,8 @@ """jc - JSON Convert `asciitable-m` parser -This parser converts ASCII and Unicode text tables with multi-line rows. -Tables must have some sort of separator line between rows. +This parser converts various styles of ASCII and Unicode text tables with +multi-line rows. Tables must have a header row and separator line between +rows. For example: @@ -16,6 +17,12 @@ For example: │ │ │ │ ╘══════════╧═════════╧════════╛ +Cells with multiple lines within rows will be joined with a new-line +character ('\n'). + +Headers (keys) are converted to snake case and newlines between multi-line +headers are joined with an underscore. All values are returned as strings. + Usage (cli): $ cat table.txt | jc --asciitable-m @@ -29,19 +36,60 @@ Schema: [ { - "asciitable-m": string, - "bar": boolean, - "baz": integer + "column_name1": string, + "column_name2": string } ] Examples: - $ asciitable-m | jc --asciitable-m -p - [] + $ echo ' + > +----------+---------+--------+ + > | foo | bar | baz | + > | | | buz | + > +==========+=========+========+ + > | good day | 12345 | | + > | mate | | | + > +----------+---------+--------+ + > | hi there | abc def | 3.14 | + > | | | | + > +==========+=========+========+' | jc --asciitable-m -p + [ + { + "foo": "good day\nmate", + "bar": "12345", + "baz_buz": "" + }, + { + "foo": "hi there", + "bar": "abc def", + "baz_buz": "3.14" + } + ] - $ asciitable-m | jc --asciitable-m -p -r - [] + $ echo ' + > ╒══════════╤═════════╤════════╕ + > │ foo │ bar │ baz │ + > │ │ │ buz │ + > ╞══════════╪═════════╪════════╡ + > │ good day │ 12345 │ │ + > │ mate │ │ │ + > ├──────────┼─────────┼────────┤ + > │ hi there │ abc def │ 3.14 │ + > │ │ │ │ + > ╘══════════╧═════════╧════════╛' | jc --asciitable-m -p + [ + { + "foo": "good day\nmate", + "bar": "12345", + "baz_buz": "" + }, + { + "foo": "hi there", + "bar": "abc def", + "baz_buz": "3.14" + } + ] """ import re from typing import Iterable, Tuple, List, Dict @@ -91,7 +139,7 @@ def _lstrip(string: str) -> str: def _rstrip(string: str) -> str: - """find the rightmost non-whitespace character and rstrip to that index""" + """find the rightmost non-whitespace character and rstrip and pad to that index""" rstrip_list = [x for x in string.splitlines() if not len(x.strip()) == 0] end_points = (len(x.rstrip()) for x in rstrip_list) max_point = max(end_points) @@ -110,10 +158,12 @@ def _table_sniff(string: str) -> str: # pretty tables for line in string.splitlines(): line = line.strip() - if line.startswith('╞═') and line.endswith('═╡')\ - or line.startswith('├─') and line.endswith('─┤')\ - or line.startswith('+=') and line.endswith('=+')\ - or line.startswith('+-') and line.endswith('-+'): + if any(( + line.startswith('╞═') and line.endswith('═╡'), + line.startswith('├─') and line.endswith('─┤'), + line.startswith('+=') and line.endswith('=+'), + line.startswith('+-') and line.endswith('-+') + )): return 'pretty' # markdown tables diff --git a/man/jc.1 b/man/jc.1 index d88db55f..e29c47d6 100644 --- a/man/jc.1 +++ b/man/jc.1 @@ -1,4 +1,4 @@ -.TH jc 1 2022-03-14 1.18.6 "JSON Convert" +.TH jc 1 2022-03-22 1.18.6 "JSON Convert" .SH NAME jc \- JSONifies the output of many CLI tools and file-types .SH SYNOPSIS @@ -37,6 +37,11 @@ Parsers: \fB--arp\fP `arp` command parser +.TP +.B +\fB--asciitable-m\fP +multi-line ASCII and Unicode table parser + .TP .B \fB--blkid\fP