Implement callable subscripts (#14)

* Implement callable subscripts

Implements `length()` function for JSON arrays, and `entries()`, `keys()` and `values()` functions for JSON objects.

* Resolve autopep8 and pylint warnings

* Resolve pylint warnings

* Resolve flake8 E501 warning

* Call length() on JSON string

* Resolve pylint warnings

* Resolve pylint warnings

* Fix pre-commit and update pylint

Signed-off-by: David Brown <dmlb2000@gmail.com>

* Resolve pylint warnings

* Resolve pylint warnings

* Implement subscript(number[,number]) callable subscript

* 100% coverage

* Resolve pylint warnings

* Resolve pylint warnings

* Resolve pylint warnings

* Resolve pylint warnings

* Resolve pylint warnings

* Resolve pylint warnings

* Resolve pylint warnings

* Resolve pylint warnings

* Rename callable subscript classes

* Implement Array.entries, Array.keys and Array.values methods

* Update README.md

* Remove unnecessary diffs

* Rename __match__ to __call__

* Move callable subscript names into class properties

* Construct dictionary of callable subscripts

* Resolve pylint warnings

* Update README.md

* Update typing for callable subscripts

* track provenance of callable subscript arguments

* Resolve pylint warnings

* Rename "number" to "int"

* Document callables in README

* Transform list into table

* Add link to pull request

Author: markborkum

README.md

@@ -7,7 +7,7 @@ This repository contains an implementation of [JSONPath](http://goessner.net/art
 
 ### `Path` class
 
-The `jsonpath2.Path.Path` class represents a JSONPath.
+The `jsonpath2.path.Path` class represents a JSONPath.
 
 ```python
 >>> s = '{"hello":"Hello, world!"}'
@@ -24,7 +24,7 @@ The `jsonpath2.Path.Path` class represents a JSONPath.
 ['$["hello"]']
 ```
 
-This class is constructed with respect to the given instance of the `jsonpath2.Path.RootNode` class (viz., the `root_node` property).
+This class is constructed with respect to the given instance of the `jsonpath2.nodes.root.RootNode` class (viz., the `root_node` property).
 
 #### `parse_str(strdata)` class method
 
@@ -37,7 +37,7 @@ Parse the contents of the given file and return a new instance of this class.
 #### `match(root_value)` instance method
 
 Match the given JSON data structure against this instance.
-For each match, yield an instance of the `jsonpath2.Node.MatchData` class.
+For each match, yield an instance of the `jsonpath2.node.MatchData` class.
 
 #### `__eq__(other)` instance method
 
@@ -53,7 +53,7 @@ The root node of the abstract syntax tree for this instance.
 
 ### `Node` abstract class
 
-The `jsonpath2.Node.Node` class represents the abstract syntax tree for a JSONPath.
+The `jsonpath2.node.Node` class represents the abstract syntax tree for a JSONPath.
 
 #### `__eq__(other)` instance method
 
@@ -66,15 +66,15 @@ Yields the lexer tokens for the string representation of this instance.
 #### `match(root_value, current_value)` instance method
 
 Match the given root and current JSON data structures against this instance.
-For each match, yield an instance of the `jsonpath2.Node.MatchData` class.
+For each match, yield an instance of the `jsonpath2.node.MatchData` class.
 
 #### `tojsonpath()` instance method
 
 Returns the string representation of this instance.
 
 ### `MatchData` class
 
-The `jsonpath2.Node.MatchData` class represents the JSON value and context for a JSONPath match.
+The `jsonpath2.node.MatchData` class represents the JSON value and context for a JSONPath match.
 
 This class is constructed with respect to a root JSON value, a current JSON value, and an abstract syntax tree node.
 
@@ -111,10 +111,125 @@ The abstract syntax tree node.
 | JSONPath Filter Expression | Description |
 | - | - |
 | `$` or `@` | nested JSONPath (returns `true` if any match exists; otherwise, returns `false`) |
-| `=`, `!=`, `>`, `>=`, `<`, `<=` | binary operator, where left-hand operand is a nested JSONPath and right-right operand is a JSON value (returns `true` if any match exists; otherwise, returns `false`) |
+| `=`, `!=`, `>`, `>=`, `<`, `<=` | binary operator, where left- and right-hand operands are nested JSONPaths or JSON values (returns `true` if any match exists; otherwise, returns `false`) |
 | `and`, `or`, `not` | Boolean operator, where operands are JSONPath filter expressions |
 | `(` ... `)` | parentheses |
 
+## Functions
+
+> See [#14](https://github.com/pacifica/python-jsonpath2/pull/14) for more information.
+
+The syntax for a function call is the name of the function followed by the arguments in parentheses, i.e., `name(arg1, arg2, ..., argN)`, where the arguments are either JSONPaths or JSON values.
+
+```python
+>>> s = '{"hello":"Hello, world!"}'
+'{"hello":"Hello, world!"}'
+>>> import json
+>>> d = json.loads(s)
+{'hello':'Hello, world!'}
+>>> from jsonpath2.path import Path
+>>> p = Path.parse_str('$["hello"][length()]')
+<jsonpath2.path.Path object>
+>>> list(map(lambda match_data: match_data.current_value, p.match(d)))
+[13]
+>>> list(map(lambda match_data: match_data.node.tojsonpath(), p.match(d)))
+['$["hello"][length()]']
+```
+
+| JavaScript Function | Signature |
+| - | - |
+| [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) | `length(): int` |
+| [`Array.prototype.entries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries) | `entries(): List[Tuple[int, Any]]` |
+| [`Array.prototype.keys()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/keys) | `keys(): List[int]` |
+| [`Array.prototype.values()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/values) | `values(): List[Any]` |
+| [`Object.entries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries) | `entries(): List[Tuple[str, Any]]` |
+| [`Object.keys()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys) | `keys(): List[str]` |
+| [`Object.values()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values) | `values(): List[Any]` |
+| [`string.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length) | `length(): int` |
+| [`String.prototype.charAt()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt) | `charAt(index: int): str` |
+| [`String.prototype.substring()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) | `substring(indexStart: int, indexEnd: Optional[int]): str` |
+
+<!-- | `Array.prototype.concat()` | |
+| `Array.prototype.fill()` | |
+| `Array.prototype.flat()` | |
+| `Array.prototype.includes()` | |
+| `Array.prototype.indexOf()` | |
+| `Array.prototype.join()` | |
+| `Array.prototype.lastIndexOf()` | |
+| `Array.prototype.slice()` | |
+| `Array.prototype.sort()` | |
+| `Array.prototype.splice()` | |
+| `JSON.parse()` | |
+| `JSON.stringify()` | |
+| `Math.abs()` | |
+| `Math.acos()` | |
+| `Math.acosh()` | |
+| `Math.asin()` | |
+| `Math.asinh()` | |
+| `Math.atan()` | |
+| `Math.atan2()` | |
+| `Math.atanh()` | |
+| `Math.cbrt()` | |
+| `Math.ceil()` | |
+| `Math.clz32()` | |
+| `Math.cos()` | |
+| `Math.cosh()` | |
+| `Math.exp()` | |
+| `Math.expm1()` | |
+| `Math.floor()` | |
+| `Math.fround()` | |
+| `Math.hypot()` | |
+| `Math.imul()` | |
+| `Math.log()` | |
+| `Math.log10()` | |
+| `Math.log1p()` | |
+| `Math.log2()` | |
+| `Math.max()` | |
+| `Math.min()` | |
+| `Math.pow()` | |
+| `Math.random()` | |
+| `Math.round()` | |
+| `Math.sign()` | |
+| `Math.sin()` | |
+| `Math.sinh()` | |
+| `Math.sqrt()` | |
+| `Math.tan()` | |
+| `Math.tanh()` | |
+| `Math.trunc()` | |
+| `Number.isFinite()` | |
+| `Number.isInteger()` | |
+| `Number.isNaN()` | |
+| `Number.isSafeInteger()` | |
+| `Number.parseFloat()` | |
+| `Number.parseInt()` | |
+| `String.prototype.codeCharAt()` | |
+| `String.prototype.codePointAt()` | |
+| `String.prototype.concat()` | |
+| `String.prototype.endsWith()` | |
+| `String.prototype.includes()` | |
+| `String.prototype.indexOf()` | |
+| `String.prototype.lastIndexOf()` | |
+| `String.prototype.localeCompare()` | |
+| `String.prototype.match()` | |
+| `String.prototype.normalize()` | |
+| `String.prototype.padEnd()` | |
+| `String.prototype.padStart()` | |
+| `String.prototype.repeat()` | |
+| `String.prototype.replace()` | |
+| `String.prototype.search()` | |
+| `String.prototype.slice()` | |
+| `String.prototype.split()` | |
+| `String.prototype.startsWith()` | |
+| `String.prototype.toLocaleLowerCase()` | |
+| `String.prototype.toLocaleUpperCase()` | |
+| `String.prototype.toLowerCase()` | |
+| `String.prototype.toUpperCase()` | |
+| `String.prototype.trim()` | |
+| `String.prototype.trimEnd()` | |
+| `String.prototype.trimStart()` | | -->
+
+In the above table, the type aliases (`Any`, `List`, `Optional` and `Tuple`) are defined by the [`typing`](https://docs.python.org/3/library/typing.html) module from the Python Standard Library.
+
 ## Grammar and parser
 
 The [ANTLR v4](https://github.com/antlr/antlr4) grammar for JSONPath is available at `jsonpath2/parser/JSONPath.g4`.

jsonpath2/parser/JSONPath.g4

@@ -54,8 +54,12 @@ subscriptables
    : BRACKET_LEFT subscriptable ( COMMA subscriptable )* BRACKET_RIGHT
    ;
 
+subscriptableArguments
+   : PAREN_LEFT ( jsonpath__ ( COMMA jsonpath__ )* )? PAREN_RIGHT
+   ;
+
 subscriptableBareword
-   : ID
+   : ID subscriptableArguments?
    | WILDCARD_SUBSCRIPT
    ;
 
@@ -66,6 +70,7 @@ subscriptable
    | WILDCARD_SUBSCRIPT
    | QUESTION PAREN_LEFT expression PAREN_RIGHT
    | jsonpath_
+   | ID subscriptableArguments
    ;
 
 sliceable