153 lines
4.5 KiB
Plaintext
153 lines
4.5 KiB
Plaintext
:toc:
|
||
|
||
= Custom Syntax Elements
|
||
|
||
This section systematically outlines the interfaces and capabilities in QLExpress4 for customizing syntax elements.
|
||
|
||
== Overview
|
||
|
||
* Custom functions
|
||
** Implement the CustomFunction interface
|
||
** Use Java functional interfaces
|
||
** Register via annotation scanning
|
||
** Add via QLExpress script
|
||
** Implement QLFunctionalVarargs
|
||
* Custom operators
|
||
** Implement CustomBinaryOperator
|
||
** Replace built-in operators
|
||
** Use Java functional interfaces
|
||
** Add aliases
|
||
** Implement QLFunctionalVarargs
|
||
* Extension functions
|
||
** Extend ExtensionFunction
|
||
** Implement QLFunctionalVarargs
|
||
* Aliases for operators and functions
|
||
|
||
== Custom Functions
|
||
|
||
=== Implement the CustomFunction interface
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/test/function/HelloFunction.java[]
|
||
----
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=customComplexFunction]
|
||
----
|
||
|
||
=== Use Java functional interfaces
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=addFunctionWithJavaFunctional]
|
||
----
|
||
|
||
=== Register via annotations
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=annoObj]
|
||
----
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=addFunctionByAnnotationObject]
|
||
----
|
||
|
||
=== Add via QLExpress script
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=joinFunctionVarargsObj]
|
||
----
|
||
|
||
=== Implement QLFunctionalVarargs
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=addFunctionByVarargs]
|
||
----
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=addFunctionByVarargs]
|
||
----
|
||
|
||
== Custom Operators
|
||
|
||
=== Implement CustomBinaryOperator and set precedence
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=addOperatorWithPrecedence]
|
||
----
|
||
|
||
=== Replace built-in operators
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=replaceDefaultOperator]
|
||
----
|
||
|
||
=== Use Java functional interfaces
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=addOperatorBiFunction]
|
||
----
|
||
|
||
=== Implement QLFunctionalVarargs
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=addOperatorByVarargs]
|
||
----
|
||
|
||
== Extension Functions
|
||
|
||
=== Extend ExtensionFunction
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=defineExtensionFunctionByExtensionFunction]
|
||
----
|
||
|
||
=== Implement QLFunctionalVarargs
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=defineExtensionFunctionByQLFunctionalVarargs]
|
||
----
|
||
|
||
== QLFunctionalVarargs: One object defines three kinds of operations
|
||
|
||
The same QLFunctionalVarargs object can serve as the implementation of a function, an operator, and an extension function at the same time, making it easy to reuse unified semantics and implementation across multiple places. This capability comes from the interface’s varargs design; see the example and interface definition below. For background discussion, refer to link:https://github.com/alibaba/QLExpress/issues/407[issue407]:
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/docs/CustomItemsDocTest.java[tag=qlfunctionalvarargsAllInOne]
|
||
----
|
||
|
||
=== Interface definition
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/main/java/com/alibaba/qlexpress4/api/QLFunctionalVarargs.java[]
|
||
----
|
||
|
||
== Aliases for operators and functions (keyword aliases also supported)
|
||
|
||
[source,java,indent=0]
|
||
----
|
||
include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=addAlias]
|
||
----
|
||
|
||
== Notes and recommendations
|
||
|
||
- Under the QLFunctionalVarargs calling convention, when invoking an extension function the first actual argument is the receiver object, followed by the call arguments; functions and operators do not include a receiver.
|
||
- Set the precedence of custom operators according to the intended expression semantics to avoid confusion with existing rules.
|
||
- Annotation-based registration only processes public methods, and duplicate names will fail to register; the batch registration result contains both success and failure lists.
|
||
|