add some docs for new feature

Change-Id: I61be883ab438f1f05aef9470156292d308d78070

arishem/arishem_def_opts.go

@@ -43,7 +43,7 @@ var (
 
 func WithDefMaxParallels() Option {
 	return func(cfg *Configuration) {
-		cfg.MaxParallel = 10 * (1 << 12)
+		cfg.MaxParallel = 1 << 12
 	}
 }
 

arishem/arishem_lw_api.go

@@ -58,14 +58,17 @@ func AddSubCondition(pairs ...string) error {
 	if size%2 != 0 {
 		return errors.New("pair number not valid")
 	}
+	if arishemConfiguration.SubCond == nil {
+		return errors.New("sub condition not enabled")
+	}
 	for i := 0; i < size; i += 2 {
 		condName := pairs[i]
 		condition := pairs[i+1]
 		tree, err := ParseRuleTree(condition, ExprTypeCondition)
 		if err != nil {
 			return err
 		}
-		if arishemConfiguration.SubCond != nil && tree != nil && tree.Tree != nil {
+		if tree != nil && tree.Tree != nil {
 			arishemConfiguration.SubCond.WhenConditionParsed(condName, condition, tree.Tree)
 		}
 	}

doc/zh/CALLBACK_zh.md

@@ -1,72 +1,5 @@
 # Arishem自定义配置和回调
 
-## 自定义配置
-
-arishem支持多个配置的自定义，包括规则运算时的缓存实现、批大小的计算方式以及无优先级的最大并大数量等。在arishem初始化的时候传入你的自定义配置：
-
-```go
-func DefaultConfiguration() *core.Configuration {
-    c := new(core.Configuration)
-    core.ApplyOptions(c,
-        WithDefTreeCache(),
-        WithDefMaxParallels(),
-        WithDefGranularity(),
-        WithDefRuleComputePool(),
-        WithDefFeatureFetchPool(),
-        WithDefFeatFetcherFactory(),
-        WithDefFeatVisitCache(),
-    )
-    return c
-}
-```
-
-- WithDefTreeCache
-
-TreeCache是arishem解析规则时使用的缓存，加上这个缓存后，arishem在解析到同一个条件/目的表达式时，将不再调用Antlr4的解析方法，直接从缓存中获取，默认512条。
-
-- WithDefMaxParallels
-
-MaxParallels是arishem在运算非优先级规则时的最大并发度，arishem默认配置中，对非优先级的规则运算采用全部并发执行的配置，但不会超过MaxParallels。
-
-- WithDefGranularity
-
-Granularity是arishem在运算多条规则时的分批算法，入参是当前的规则组的数量和运算的场景(优先级/非优先级)。默认配置如下：
-
-```go
-
-func granularity(ruleGroupSize int, model core.ExecuteModel) int {
-    if model == core.ExecuteModelNoPriority {
-        if ruleGroupSize <= arishemConfiguration.MaxParallel {
-            return ruleGroupSize
-        }
-        return arishemConfiguration.MaxParallel
-    }
-    // dCpu is the double of cpu core num.
-    if ruleGroupSize < dCpu {
-        return ruleGroupSize
-    }
-    if ruleGroupSize < dCpu*2 {
-        return ruleGroupSize / 2
-    }
-    if dCpu <= 1 { // when x = 1，2*√x intersects with 2*x
-        return 1
-    }
-    return (dCpu*2 - factor) * 2
-}
-```
-
-- WithDefRuleComputePool/WithDefFeatureFetchPool
-
-RuleComputePool/FeatureFetchPool分别是arishem在规则运算时和Feature获取时使用的协程池。
-
-- FeatFetcherFactory
-
-FeatFetcherFactory是用户在使用了featureExpr后必须自实现的FeatureFetcher工厂方法。
-
-- FeatVisitCache
-
-Feature在规则表达式解析阶段也会有缓存，默认大小是512个
-
 ## 回调监听
 
 arishem一共定义了两种回调类型，分别是规则运算回调和FeatureFetch过程的回调，他们的接口定义如下：

doc/zh/EXPR_zh.md

@@ -16,6 +16,7 @@ arishem的最小构成为Expr类型，在arishem中**必须由一对大括号包
 | FuncExpr      | FuncExpr    | 使用arishem内置函数                     |
 | VarExpr       | VarExpr     | 从实时数据中获取数据的路径表达式                  |
 | FeatureExpr   | FeatureExpr | 从外部网络中获取数据的路径表达式                  |
+| SubCondExpr <font color="red"><sup>new</sup></font>  | SubCondExpr | 右值是作为子条件进行运算的方式 |
 | null          | 无           | 空类型的Expr                          |
 
 按照拆解的原则，ListExpr和MapExpr都是Expr的特定组合，故先从最小的Expr类型进行说明。
@@ -109,7 +110,7 @@ arishem解析后
 ["name", 1.234, false]
 ```
 
-## 3. VarExpr
+## 3. VarExpr <font color="red"><sup>new</sup></font>
 
 VarExpr表示一个路径，该路径表示某个值在**实时数据**
 中的取值路径。arishem的取值路径和JSON相似，但又有所不同。VarExpr的格式为a.b.c。每一个用'.'分割的元素都是实时数据中的某个value的key，
@@ -159,6 +160,52 @@ arishem解析后
 20
 ```
 
+- 支持list类型的元素收集，语法为list元素后紧跟‘##’,只支持单个字段的收集
+
+ 如有这么一段数据
+```json
+{
+    "item_info": {
+        "item_list": [
+            {
+                "name": "name@1",
+                "price": 100
+            },
+            {
+                "name": "name@2",
+                "price": 102.13
+            },
+            {
+                "name": "name@3",
+                "price": 200
+            },
+            {
+                "name": "name@4",
+                "price": 100
+            },
+            {
+                "name": "name@5",
+                "price": 101
+            },
+            {
+                "name": "name@6",
+                "price": 303.1234
+            }
+        ]
+    }
+}
+```
+收集里面的所有price字段
+```json
+{
+    "VarExpr": "item_info.item_list##price"
+}
+```
+那么arishem解析后为
+```json
+[100,102.13,200,100,101,303.1234]
+```
+
 ## 4. FeatureExpr
 
 arishem将依赖外部网络的数据定义为feature，使用FeatureExpr表示该数据从外部网络中获取，FeatureExpr由FeaturePath和BuiltinParam(
@@ -384,3 +431,98 @@ MapExpr和ListExpr类型相似，表示有一个或多个由Expr类型组成的
 }
 ```
 
+## 9. SubCondExpr <font color="red"><sup>new</sup></font>
+使用该表达式必须启用了arishem对子条件的判断支持，详见[快速开始的配置部分](STARTUP_zh.md)
+
+该表达式表示一个子条件，只能作用于条件的右值表达式，并用CondName指定要使用子条件，举个具体的例子，要判断入参中的商品列表里的每一个商品都满足 名称包含xxx 并且 价格 大于100:
+
+入参：
+```json
+{
+    "item_info": {
+        "item_list": [
+            {
+                "name": "name@1",
+                "price": 100
+            },
+            {
+                "name": "name@2",
+                "price": 102.13
+            },
+            {
+                "name": "name@3",
+                "price": 200
+            },
+            {
+                "name": "name@4",
+                "price": 100
+            },
+            {
+                "name": "name@5",
+                "price": 101
+            },
+            {
+                "name": "name@6",
+                "price": 303.1234
+            }
+        ]
+    }
+}
+```
+规则的条件表达式:
+```json
+{
+  "OpLogic": "&&",
+  "Conditions": [
+    {
+      "Operator": "FOREACH SUB_COND and",
+      "Lhs": {
+        "VarExpr": "item_info.item_list"
+      },
+      "Rhs": {
+        "SubCondExpr": {
+          "CondName": "NameAndPriceMatch"
+        }
+      }
+    }
+  ]
+}
+```
+在运算上述条件前，请确保你已经向arishem中注册了NameAndPriceMatch这样一个子条件
+```json
+{
+    "OpLogic": "&&",
+    "Conditions": [
+        {
+            "Operator": ">",
+            "Lhs": {
+                "VarExpr": "price"
+            },
+            "Rhs": {
+                "Const": {
+                    "NumConst": 10
+                }
+            }
+        },
+        {
+            "Operator": "STRING_CONTAINS",
+            "Lhs": {
+                "VarExpr": "name"
+            },
+            "Rhs": {
+                "Const": {
+                    "StrConst": "name@"
+                }
+            }
+        }
+    ]
+}
+```
+代码描述
+```go
+err := AddSubCondition("NameAndPriceMatch", ${sub condition expression})
+assert.Nil(t, err)
+pass, err := JudgeConditionWithFactMeta(context.Background(), ${this rule conition}, ${FactData})
+assert.Nil(t, err)
+assert.True(t, pass)
+```

doc/zh/INDEX_zh.md

@@ -1,5 +1,7 @@
 # Arishem文档
 
+## [快速开始](STARTUP_zh.md)
+
 ## 语法
 
 ### 1. Expr类型
@@ -30,6 +32,6 @@
 
 [Arishem实现网络数据访问](./FEATURE_zh.md)
 
-## 自定义配置和监听回调
+## 监听回调
 
-[Arishem自定义配置和监听回调](./CALLBACK_zh.md)
+[Arishem监听回调](./CALLBACK_zh.md)