toml tests and doc update

docs/parsers/toml.md

@@ -0,0 +1,81 @@
+[Home](https://kellyjonbrazil.github.io/jc/)
+<a id="jc.parsers.toml"></a>
+
+# jc.parsers.toml
+
+jc - JSON Convert TOML file parser
+
+Usage (cli):
+
+    $ cat file.toml | jc --toml
+
+Usage (module):
+
+    import jc
+    result = jc.parse('toml', toml_file_output)
+
+Schema:
+
+TOML Document converted to a Dictionary.
+See https://toml.io/en/ for details.
+
+    {
+      "key1":     string/int/float/boolean/null/array/object,
+      "key2":     string/int/float/boolean/null/array/object
+    }
+
+Examples:
+
+    $ cat file.toml
+    title = "TOML Example"
+
+    [owner]
+    name = "Tom Preston-Werner"
+    dob = 1979-05-27T07:32:00-08:00
+
+    [database]
+    enabled = true
+    ports = [ 8000, 8001, 8002 ]
+
+    $ cat file.toml | jc --toml -p
+    {
+      "title": "TOML Example",
+      "owner": {
+        "name": "Tom Preston-Werner",
+        "dob": 296667120,
+        "dob_iso": "1979-05-27T07:32:00-08:00"
+      },
+      "database": {
+        "enabled": true,
+        "ports": [
+          8000,
+          8001,
+          8002
+        ]
+      }
+    }
+
+<a id="jc.parsers.toml.parse"></a>
+
+### parse
+
+```python
+def parse(data: str, raw: bool = False, quiet: bool = False) -> JSONDictType
+```
+
+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:
+
+    Dictionary. Raw or processed structured data.
+
+### Parser Information
+Compatibility:  linux, darwin, cygwin, win32, aix, freebsd
+
+Version 1.0 by Kelly Brazil (kellyjonbrazil@gmail.com)

docs/parsers/yaml.md

@@ -18,8 +18,8 @@ Usage (module):
 
 Schema:
 
-    YAML Document converted to a Dictionary
-    See https://pypi.org/project/ruamel.yaml for details
+YAML Document converted to a Dictionary.
+See https://pypi.org/project/ruamel.yaml for details.
 
     [
       {
@@ -30,7 +30,7 @@ Schema:
 
 Examples:
 
-    $ cat istio-mtls-permissive.yaml
+    $ cat file.yaml
     apiVersion: "authentication.istio.io/v1alpha1"
     kind: "Policy"
     metadata:
@@ -51,7 +51,7 @@ Examples:
         tls:
           mode: ISTIO_MUTUAL
 
-    $ cat istio-mtls-permissive.yaml | jc --yaml -p
+    $ cat file.yaml | jc --yaml -p
     [
       {
         "apiVersion": "authentication.istio.io/v1alpha1",

jc/parsers/toml.py

@@ -7,25 +7,48 @@ Usage (cli):
 Usage (module):
 
     import jc
-    result = jc.parse('toml', toml_file)
+    result = jc.parse('toml', toml_file_output)
 
 Schema:
 
-    [
+TOML Document converted to a Dictionary.
+See https://toml.io/en/ for details.
+
     {
-        "toml":     string,
-        "bar":     boolean,
-        "baz":     integer
+      "key1":     string/int/float/boolean/null/array/object,
+      "key2":     string/int/float/boolean/null/array/object
     }
-    ]
 
 Examples:
 
-    $ toml | jc --toml -p
-    []
+    $ cat file.toml
+    title = "TOML Example"
 
-    $ toml | jc --toml -p -r
-    []
+    [owner]
+    name = "Tom Preston-Werner"
+    dob = 1979-05-27T07:32:00-08:00
+
+    [database]
+    enabled = true
+    ports = [ 8000, 8001, 8002 ]
+
+    $ cat file.toml | jc --toml -p
+    {
+      "title": "TOML Example",
+      "owner": {
+        "name": "Tom Preston-Werner",
+        "dob": 296667120,
+        "dob_iso": "1979-05-27T07:32:00-08:00"
+      },
+      "database": {
+        "enabled": true,
+        "ports": [
+          8000,
+          8001,
+          8002
+        ]
+      }
+    }
 """
 from typing import Any
 from jc.jc_types import JSONDictType

jc/parsers/yaml.py

@@ -13,8 +13,8 @@ Usage (module):
 
 Schema:
 
-    YAML Document converted to a Dictionary
-    See https://pypi.org/project/ruamel.yaml for details
+YAML Document converted to a Dictionary.
+See https://pypi.org/project/ruamel.yaml for details.
 
     [
       {
@@ -25,7 +25,7 @@ Schema:
 
 Examples:
 
-    $ cat istio-mtls-permissive.yaml
+    $ cat file.yaml
     apiVersion: "authentication.istio.io/v1alpha1"
     kind: "Policy"
     metadata:
@@ -46,7 +46,7 @@ Examples:
         tls:
           mode: ISTIO_MUTUAL
 
-    $ cat istio-mtls-permissive.yaml | jc --yaml -p
+    $ cat file.yaml | jc --yaml -p
     [
       {
         "apiVersion": "authentication.istio.io/v1alpha1",

tests/fixtures/generic/toml-example.json

@@ -0,0 +1 @@
+{"title":"TOML Example","owner":{"name":"Lance Uppercut","dob":296667120,"dob_iso":"1979-05-27T07:32:00-08:00"},"database":{"server":"192.168.1.1","ports":[8001,8001,8002],"connection_max":5000,"enabled":true},"servers":{"alpha":{"ip":"10.0.0.1","dc":"eqdc10"},"beta":{"ip":"10.0.0.2","dc":"eqdc10"}},"clients":{"data":[["gamma","delta"],[1,2]],"hosts":["alpha","omega"]}}

tests/fixtures/generic/toml-example2.json

@@ -0,0 +1,27 @@
+{
+  "fruit": [
+    {
+      "name": "apple",
+      "physical": {
+        "color": "red",
+        "shape": "round"
+      },
+      "variety": [
+        {
+          "name": "red delicious"
+        },
+        {
+          "name": "granny smith"
+        }
+      ]
+    },
+    {
+      "name": "banana",
+      "variety": [
+        {
+          "name": "plantain"
+        }
+      ]
+    }
+  ]
+}

tests/fixtures/generic/toml-example2.toml

@@ -0,0 +1,18 @@
+[[fruit]]
+  name = "apple"
+
+  [fruit.physical]
+    color = "red"
+    shape = "round"
+
+  [[fruit.variety]]
+    name = "red delicious"
+
+  [[fruit.variety]]
+    name = "granny smith"
+
+[[fruit]]
+  name = "banana"
+
+  [[fruit.variety]]
+    name = "plantain"

tests/test_toml.py

@@ -0,0 +1,59 @@
+import os
+import unittest
+import json
+from typing import Dict
+from jc.parsers.toml import parse
+
+THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+class MyTests(unittest.TestCase):
+    f_in: Dict = {}
+    f_json: Dict = {}
+
+    @classmethod
+    def setUpClass(cls):
+        fixtures = {
+            'toml1': (
+                'fixtures/generic/toml-example.toml',
+                'fixtures/generic/toml-example.json'),
+            'toml2': (
+                'fixtures/generic/toml-example2.toml',
+                'fixtures/generic/toml-example2.json')
+        }
+
+        for file, filepaths in fixtures.items():
+            with open(os.path.join(THIS_DIR, filepaths[0]), 'r', encoding='utf-8') as a, \
+                 open(os.path.join(THIS_DIR, filepaths[1]), 'r', encoding='utf-8') as b:
+                cls.f_in[file] = a.read()
+                cls.f_json[file] = json.loads(b.read())
+
+
+    def test_toml_nodata(self):
+        """
+        Test 'toml' with no data
+        """
+        self.assertEqual(parse('', quiet=True), {})
+
+
+    def test_toml_example1(self):
+        """
+        Test 'toml' with first example file
+        """
+        self.assertEqual(
+            parse(self.f_in['toml1'], quiet=True),
+            self.f_json['toml1']
+        )
+
+    def test_toml_example2(self):
+        """
+        Test 'toml' with second example file
+        """
+        self.assertEqual(
+            parse(self.f_in['toml2'], quiet=True),
+            self.f_json['toml2']
+        )
+
+
+if __name__ == '__main__':
+    unittest.main()