add custom functions feature

[narcoticfresh]

Hello ;-)

With envy I have seen that jmespath.py added a custom function feature in jmespath/jmespath.py#102 - and that is something I need for the PHP implementation too ;-) so I created this PR that should add this feature - I also added tests and documentation.

let me know if anything is missing.

PS: I also changed the singleton handling a bit in FnDispatcher as IMHO the instance should be a defined static class property, not implicitly created in the getInstance() method.

[mtdowling]

Thanks for the PR! I like the direction this PR is headed. The FnDispatcher that is globally available using the static instance is only that way so that it can be reused for expressions that only use the built-in functions. Because it's globally available, I chose to make it immutable so that no custom functions can be added without the end-user explicitly opting into them. I think that is lost in this PR given that the global FnDispatcher is now mutable. In order to use custom functions, I think the user should have to explicitly opt-in to them. This is the same approach taken in the Python implementation you linked.

Custom functions are currently supported in a limited fashion by using a custom function dispatcher. Here's an example: #20 (comment). Some of the things that this technique does not currently support:

1. Access to the built-in type validation: Custom functions? #20 (comment). Type validation is private, and not a very JMESPath specific API. If built-in type validation were to be made publicly accessible, then I'd like to consider making function signatures a first-class type that are more JMESPath specific. Perhaps a decorator that wraps a callable function (similar to what is in the Python implementation) would work.
2. The TreeCompiler does not currently allow a custom FnDispatcher to be provided when compiling expressions: https://github.com/jmespath/jmespath.php/blob/master/src/TreeCompiler.php#L246. While the TreeComplier compiles expressions into PHP code, it does not compile expression references, but instead relies on using a TreeInterpreter dynamically. The TreeCompiler does allow you to inject a custom TreeInterpreter, but the CompilerRuntime does not expose the ability to inject a custom interpreter: https://github.com/jmespath/jmespath.php/blob/master/src/CompilerRuntime.php#L26. Furthermore, the TreeInterpreter does not currently expose the FnDispatcher it uses: https://github.com/jmespath/jmespath.php/blob/master/src/TreeInterpreter.php#L19. If the TreeInterpreter exposed the ability to get it's FnDispatcher through a public method, and the CompilerRuntime exposed the ability to inject a custom interpreter, and the TreeCompiler used the FnDispatcher owned by the TreeInterpreter passed into each compiled function, then we'd have the ability to use custom functions in compiled expressions without needing all custom functions to be registered globally.

In addition to the above changes, maybe there are some ergonomic changes that could be made to make it easier to add custom functions. For example, perhaps a new function dispatcher class could be added that decorate the built-in dispatcher with custom functions, and allows for mutability to add custom functions.

[narcoticfresh]

@mtdowling
thanks for the feedback.

as I understand it, this PR currently has the following Pro's:

• supports using built-in validation
• works with any Runtime without any effort

But the big cons:

• global fnDispatcher is now mutable
• possible clashes between different projects registering different custom functions as they share the instance.

So you propose the solution to still pass a custom fnDispatcher (maybe providing a more explicit API to register custom functions?) and pass that down to every component (Tree* classes and such) involved?

Given the fact that I don't know the Lexer/Parser/Compiler part of this library, it's hard to see for me which modifications are necessary at what point. And I have limited time on my hands ;-/

[mtdowling]

After thinking about this for a few years... I don't think custom functions are actually a desirable feature in JMESPath implementations. They add a larger API surface area than I think each language implementation should. Ideally, I'd like to see the Rust implementation of JMESPath get bindings for each of our supported languages, and the language specific implementations work transparently with the Rust implementation if found or the language specific implementation if not.

This works much more easily if the language bindings for JMESpath across implementations are as small and constrained as possible.

[datashaman]

On the contrary, I find this PR to be the thing that makes a constrained toolkit really useful.

I was stymied by the lack of simple primitives for things like substr, date, etc.

Now I can make the experience more comfortable for the template creator without breaking out of the JMESPath specification method.

I can name the functions with an underscore (or similar) to signal to the template creator that these are not native functions, and point them to where they are defined.