Add handy shortcut to match string path

README.md

@@ -5,6 +5,19 @@ This repository contains an implementation of [JSONPath](http://goessner.net/art
 
 ## API
 
+
+### `match` shortcut function
+
+The `jsonpath2.match` function is a shortcut to match a given JSON data
+structure against a JSONPath string
+
+```python
+>>> import jsonpath2
+>>> doc = {'hello': 'Hello, world!'}
+>>> [x.current_value for x in jsonpath2.match('$.hello', doc)]
+['Hello, world!']
+```
+
 ### `Path` class
 
 The `jsonpath2.path.Path` class represents a JSONPath.

jsonpath2/__init__.py

@@ -1,3 +1,13 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 """The jsonpath2 module."""
+
+from typing import Generator
+from .path import Path
+from .node import MatchData
+
+
+def match(path_str: str, root_value: object) -> Generator[MatchData, None, None]:
+    """Match root value of the path."""
+    path = Path.parse_str(path_str)
+    return path.match(root_value)

jsonpath2/test/shortcuts_test.py

@@ -0,0 +1,18 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+"""Test package level shortcuts."""
+
+from unittest import TestCase
+import jsonpath2
+
+
+class TestShortcuts(TestCase):
+    """Test package level shortcuts."""
+
+    def test_match(self):
+        """Test match shortcut works."""
+        data = {'hello': 'Hello, World!'}
+        self.assertEqual(
+            [x.current_value for x in jsonpath2.match('$.hello', data)],
+            ['Hello, World!']
+        )