add execute source adoc

Author: DQinYuan

.github/workflows/reduce-adoc.yml

@@ -4,6 +4,8 @@ on:
     paths:
       - README-source.adoc
       - README-EN-source.adoc
+      - docs/execute-source.adoc
+      - docs/execute-en-source.adoc
     branches: ['**']
 jobs:
   build:
@@ -17,9 +19,12 @@ jobs:
         # to preserve preprocessor conditionals, add the --preserve-conditionals option
         run: asciidoctor-reducer --preserve-conditionals -o README.adoc README-source.adoc
       - name: Reduce README-EN
-        # to preserve preprocessor conditionals, add the --preserve-conditionals option
         run: asciidoctor-reducer --preserve-conditionals -o README-EN.adoc README-EN-source.adoc
+      - name: Reduce docs/execute
+        run: asciidoctor-reducer --preserve-conditionals -o docs/execute.adoc docs/execute-source.adoc
+      - name: Reduce docs/execute-en
+        run: asciidoctor-reducer --preserve-conditionals -o docs/execute-en.adoc docs/execute-en-source.adoc
       - name: Commit and Push README files
         uses: EndBug/add-and-commit@v9
         with:
-          add: README.adoc README-EN.adoc
+          add: README.adoc README-EN.adoc docs/execute.adoc docs/execute-en.adoc

docs/execute-en-source.adoc

@@ -0,0 +1,50 @@
+:toc:
+
+= Expression Execution
+
+This section describes the different ways to execute expressions in QLExpress4.
+
+== Use Map as the context
+
+- `execute(String, Map<String,Object>, QLOptions)`
+- Description: According to the method comments, use a `Map` as the context; the keys in the `Map` are the variable names used in the script, and the values are the corresponding variable values.
+- Typical scenario: Build a `Map` from external business data and pass it in so the script can access variables directly by name.
+
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=firstQl]
+----
+
+== Use object fields as the context
+
+- `execute(String, Object, QLOptions)`
+- Description: Use a plain Java object as the context; variable names in the script correspond to the object's field names (or accessible getters).
+- Typical scenario: When you already have a DTO/POJO that carries the context data, pass the object directly so the script can read its fields.
+
+// Note: This references the test code for execution with an object context.
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=executeWithObject]
+----
+
+== Use a set of aliased objects
+
+- `executeWithAliasObjects(String, QLOptions, Object...)`
+- Description: Pass objects annotated with `@QLAlias`; the annotation value becomes the variable name in the context. Objects without the annotation are ignored.
+- Typical scenario: Expose object properties/methods with Chinese (or domain-specific) aliases so rule authors can write scripts more intuitively.
+
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=qlAlias]
+----
+
+== Use a custom `ExpressContext`
+
+- `execute(String, ExpressContext, QLOptions)`
+- Description: This overload allows passing a custom context that implements `ExpressContext` (for example, a dynamic variable context). The other `execute` overloads ultimately delegate to this method.
+- Typical scenario: When you need on-demand, by-name evaluation of variable values, read/write isolation, or integration with external storage, a custom context is the most flexible choice.
+
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=dynamicVar]
+----

docs/execute-source.adoc

@@ -0,0 +1,50 @@
+:toc:
+
+= 表达式执行
+
+本节说明在 QLExpress4 中执行表达式的多种方式。
+
+== 使用 Map 作为上下文：
+
+- `execute(String, Map<String,Object>, QLOptions)`
+- 说明：根据方法注释，使用 `Map` 作为上下文，`Map` 的 key 即为脚本中的变量名，value 为对应变量值。
+- 典型场景：从外部业务数据构造一个 `Map` 传入，直接在脚本里以变量名访问。
+
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=firstQl]
+----
+
+== 使用对象字段作为上下文
+
+- `execute(String, Object, QLOptions)`
+- 说明：根据方法注释，使用一个普通 Java 对象作为上下文，脚本中的变量名对应该对象的字段名（或可访问的 getter）。
+- 典型场景：已有一个承载上下文数据的 DTO/POJO，直接将对象传入以便脚本读取其字段。
+
+// 说明：此处引用对象上下文执行的测试代码。
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=executeWithObject]
+----
+
+== 使用带别名的对象集合
+
+- `executeWithAliasObjects(String, QLOptions, Object...)`
+- 说明：根据方法注释，传入标记了 `@QLAlias` 的对象，注解值将作为上下文中的变量名；未标记的对象会被忽略。
+- 典型场景：以中文（或领域语言）别名暴露对象属性/方法，供规则编写者直观地编写脚本。
+
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=qlAlias]
+----
+
+== 使用自定义 `ExpressContext`
+
+- `execute(String, ExpressContext, QLOptions)`
+- 说明：该重载允许传入实现了 `ExpressContext` 的自定义上下文（例如动态变量上下文）。其它 `execute` 重载最终也会委托到此方法。
+- 典型场景：需要按需按名计算变量值、隔离读写、或接入外部存储等高级能力时，自定义上下文最灵活。
+
+[source,java,indent=0]
+----
+include::../src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java[tag=dynamicVar]
+----

src/test/java/com/alibaba/qlexpress4/Express4RunnerTest.java

@@ -1251,13 +1251,15 @@ public static class MyObj {
 
     @Test
     public void executeWithObjContextTest() {
+        // tag::executeWithObject[]
         MyObj myObj = new MyObj();
         myObj.a = 1;
         myObj.b = "test";
 
         Express4Runner express4Runner = new Express4Runner(InitOptions.DEFAULT_OPTIONS);
         Object result = express4Runner.execute("a+b", myObj, QLOptions.DEFAULT_OPTIONS).getResult();
         assertEquals("1test", result);
+        // end::executeWithObject[]
     }
 
     @Test