diff --git a/docs/index.md b/docs/index.md index 099adbfb..5f97b07e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,8 +13,8 @@ - 代码风格：`tsl/code_style.md` - 命名规范：`tsl/naming.md` - 语法手册（只处理“语言怎么写”）：`tsl/syntax/index.md` -- 金融业务入口（指标、选股、回测与策略流程）：`tsl/finance/index.md` -- 模块与集成入口（pyTSL、微信消息、Python 互操作、回测框架）：`tsl/modules/index.md` +- 模块与集成入口（pyTSL、微信消息、回测框架）：`tsl/modules/index.md` +- 金融函数事实：`tsl/reference/catalog/datawarehouse.md` - 函数检索入口（模块目录位于 `tsl/reference/catalog/`）：`tsl/reference/index.md` - 工具链与验证命令（模板）：`tsl/toolchain.md` diff --git a/docs/tsl/code_style.md b/docs/tsl/code_style.md index ca333faf..9d5e23a6 100644 --- a/docs/tsl/code_style.md +++ b/docs/tsl/code_style.md @@ -1,20 +1,20 @@ -# TSL 代码风格（Code Style） +# TSL 代码风格 -文档类型：规范页 +文档类型：风格偏好页 是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：否 -是否含已验证反例：否 -遇到不确定时跳转到：[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md) +是否含可直接照写示例：否 +是否含不可照写反例：否 +遇到不确定时：[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md) -本章节规定 TSL 代码的结构与格式约定。 +本页记录本仓库代码风格偏好，不代表 TSL 语法事实。 以下出现的 ``、`<...>`、模板占位和单独标成 `反例 / 不可照写` 的块，只用于说明风格或反例，不等于可直接复制的源码字面量。 -本页里的 `反例 / 不可照写` 仅表示风格上的不推荐写法，不等于语法主线里“已验证会编译失败/运行失败”的反向边界；因此页头里的 `是否含已验证反例` 仍保持为 `否`。 +本页里的 `反例 / 不可照写` 仅表示风格上的不推荐写法，不等于语法主线里“会编译失败/运行失败”的反向边界；因此页头里的 `是否含不可照写反例` 仍保持为 `否`。 相关文档： -- 命名规范：`docs/tsl/naming.md` +- 命名偏好：`docs/tsl/naming.md` - 工具链与验证命令（模板）：`docs/tsl/toolchain.md` ## 1. 文件与组织 @@ -81,11 +81,11 @@ ```tsl if cond then begin - DoSomething() + DoSomething(); end else begin - DoOther() + DoOther(); end ``` @@ -173,7 +173,7 @@ if !ok then return err; 不推荐这样写： 代码块身份：反例 / 不可照写 -代码块说明：风格反例，不是已验证语法反例。 +代码块说明：风格反例，不是语法主线反例。 ```tsl count := count + 1; // obvious @@ -265,7 +265,7 @@ function Func(a: string; b: ClassName): void; 不推荐这样写： 代码块身份：反例 / 不可照写 -代码块说明：风格反例，不是已验证语法反例。 +代码块说明：风格反例，不是语法主线反例。 ```tsl function ExportReport( @@ -324,11 +324,11 @@ function ExportReport(path: string; rows: array; options: ExportOptions): void; function ReadOptionalCache(path: string); begin try - return LoadCacheValue(path) + return LoadCacheValue(path); except // best-effort: cache 仅用于提速，失败不应影响主流程 - RecordCacheWarning(path) - return nil + RecordCacheWarning(path); + return nil; end end; ``` @@ -351,6 +351,6 @@ function ParseConfig(text: string): array; function LoadConfig(path: string): array; begin text := LoadConfigText(path); - return ParseConfig(text) + return ParseConfig(text); end; ``` diff --git a/docs/tsl/finance/backtest_and_trade_flow.md b/docs/tsl/finance/backtest_and_trade_flow.md deleted file mode 100644 index 8845c803..00000000 --- a/docs/tsl/finance/backtest_and_trade_flow.md +++ /dev/null @@ -1,64 +0,0 @@ -# Backtest And Trade Flow - -文档类型：业务骨架 -是否可直接用于生成代码：否 -遇到不确定时跳转到：项目实际接口定义、[../modules/tsbacktesting.md](../modules/tsbacktesting.md)、[selection_and_signal_patterns.md](selection_and_signal_patterns.md)、[../syntax/index.md](../syntax/index.md) - -这一篇收拢回测、组合、交易与结果读取流程。 - -## Agent 回测/交易判断规则 - -- 先判断比例类组合还是数量类组合，再看交易输入和结果读取。 -- 本页只给业务流程骨架，不给对象 API 真值。 -- 对象创建方式、交易数据入口、结果接口和项目封装必须回项目实际接口定义。 -- 不要发明项目实际接口、回测对象创建方式、交易入口或结果读取调用链。 - -## 这一篇解决什么问题 - -回答“回测对象如何组织、交易流程如何设置、结果怎样取出和解释”。 - -## 必须记住的规则 - -- 回测流程属于业务框架使用，不属于语言层语法。 -- 在回测场景里，先分清“框架对象怎么配置”和“语法怎么写”是两件不同的事。 -- 本层只给业务流程骨架，不给回测对象 API 真值。 -- 本层优先解释流程、对象职责和结果读取入口。 -- 如果问题已经落到回测对象创建方式、交易数据入口名、结果接口真值或项目封装差异，停止在 finance / modules 层继续推断，直接回项目实际接口定义。 - -## 最小任务骨架 - -1. 先确认回测对象类型、周期、资金和组合类型。 -2. 再确认项目侧是否已经封装好最小可用对象模型、交易输入入口和结果读取链路。 -3. 然后配置交易约束、价格口径、费用和基准。 -4. 再准备交易输入：目标权重、成交明细或其他框架要求的输入数据。 -5. 再执行回测。 -6. 最后按任务读取净值、成交、持仓和绩效结果。 - -## 进入前先回答的问题 - -- 你做的是比例类组合，还是数量类组合。 -- 你需要哪些交易约束、费用模型和基准口径。 -- 结果要给人看，还是要交给后续分析 / 执行链路。 - -## 结果读取骨架 - -- 这里说的是结果类型，不是保证存在的接口名；任何读取方法都先以项目实际接口定义为准。 -- 读净值 / 收益率时间序列。 -- 读成交 / 调仓结果。 -- 读持仓、资产和绩效指标。 -- 读基准或扩展结果时，先确认对应接口是否已经在项目里封装好。 - -## 常见误判 - -- 把回测框架的字段和方法误当成 TSL 语言内建语法。 -- 在没确认组合类型、资金约束和结果接口前，就直接复制零散片段。 -- 只看到 `BackTest()`，就跳过交易输入准备和结果读取设计。 -- 把“概念流程”误写成“独立可编译模板”。 - -## 跳转指引 - -- finance 总入口：见 [entry_decision.md](entry_decision.md) -- 参考现有回测资料：见 [../modules/tsbacktesting.md](../modules/tsbacktesting.md) -- 具体字段、交易数据入口、结果接口真值或项目封装差异：回项目实际接口定义 -- 选股与信号：见 [selection_and_signal_patterns.md](selection_and_signal_patterns.md) -- 回到语言层：见 [../syntax/index.md](../syntax/index.md) diff --git a/docs/tsl/finance/entry_decision.md b/docs/tsl/finance/entry_decision.md deleted file mode 100644 index 9446d061..00000000 --- a/docs/tsl/finance/entry_decision.md +++ /dev/null @@ -1,62 +0,0 @@ -# Finance Entry Decision - -文档类型：检索页 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[market_data_context.md](market_data_context.md)、[../syntax/index.md](../syntax/index.md)、[../reference/index.md](../reference/index.md) - -这里是金融层的入口决策页，不是代码页。它只解决“业务任务该往哪一层跳”，不重新定义语言基础语法。 - -## Agent Finance Entry 判断规则 - -- 先判断任务属于市场数据、序列指标、选股信号还是回测交易。 -- finance 只给业务组织方式；代码细节必须回 syntax、reference 或项目实际接口。 -- 不要发明项目实际接口、数据字段、函数签名或业务上下文。 - -## 这一篇解决什么问题 - -回答“什么时候应该进入 finance 层、进入后先去哪个业务主题页，以及什么时候该回到 syntax / reference 层”。 - -## 必须记住的规则 - -- finance 只解释业务任务怎样组织，不解释语言规则本身。 -- finance 可以给出“语法 + 金融函数结合示例”，但不拥有语言规则的解释权。 -- 不需要先通读完整 syntax；先进入最相关的业务主题页，需要时再回补语法或函数查阅。 - -## 适用场景 - -- 你在问市场数据语境、序列/指标组织、选股/信号任务、回测/交易流程。 -- 你已经知道自己在做金融任务，但还没决定应该先读哪一篇业务页。 -- 你需要业务层的“任务骨架”，而不是单条语法结论。 - -## 进入 finance 前至少要掌握什么 - -- 知道 TSL 的最短骨架怎么写：见 [../syntax/02_quickstart.md](../syntax/02_quickstart.md) -- 知道当前文件属于哪种顶层模型：见 [../syntax/03_core_model.md](../syntax/03_core_model.md) -- 知道高频误写不要怎么踩：见 [../syntax/12_pitfalls.md](../syntax/12_pitfalls.md) - -## 进入后先去哪里 - -- 如果你要先理解市场数据从哪里来、脚本运行在什么语境里：去 [market_data_context.md](market_data_context.md) -- 如果你要先理清序列、指标、逐 bar 计算和窗口依赖：去 [series_and_indicator_model.md](series_and_indicator_model.md) -- 如果你要组织选股条件、筛选条件、信号输出：去 [selection_and_signal_patterns.md](selection_and_signal_patterns.md) -- 如果你要配置回测对象、交易流程和结果读取：去 [backtest_and_trade_flow.md](backtest_and_trade_flow.md) - -## 什么时候回到别的层 - -- 如果问题变成“这句语法怎么写”：回 [../syntax/index.md](../syntax/index.md) -- 如果问题变成“这个函数在哪个目录、怎么查签名”：回 [../reference/index.md](../reference/index.md) -- 如果问题变成“现成模块或互操作能力怎么接”：回 [../modules/index.md](../modules/index.md) - -## 常见误判 - -- 把金融数据上下文误当成语言通用规则。 -- 还没澄清业务任务类型，就先去补读整套 syntax。 -- 把 finance 页里的任务骨架误当成独立可编译模板。 - -## 跳转指引 - -- 市场数据语境：见 [market_data_context.md](market_data_context.md) -- 序列与指标模型：见 [series_and_indicator_model.md](series_and_indicator_model.md) -- 选股与信号：见 [selection_and_signal_patterns.md](selection_and_signal_patterns.md) -- 回测与交易：见 [backtest_and_trade_flow.md](backtest_and_trade_flow.md) -- 回到语法层：见 [../syntax/index.md](../syntax/index.md) diff --git a/docs/tsl/finance/index.md b/docs/tsl/finance/index.md deleted file mode 100644 index 2ed2f3b9..00000000 --- a/docs/tsl/finance/index.md +++ /dev/null @@ -1,36 +0,0 @@ -# Finance Index - -文档类型：检索页 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[../syntax/index.md](../syntax/index.md)（优先）、[market_data_context.md](market_data_context.md)、[../reference/index.md](../reference/index.md) - -这里是业务层入口。只讨论金融任务如何使用 TSL，不重讲基础语法。 - -## Agent Finance 路由规则 - -- 只用 finance 判断金融业务任务该怎么分层，不用 finance 重写语法规则。 -- 金融任务需要真实数据字段、回测接口或项目封装时，先回项目实际接口定义。 -- 不要发明项目实际接口、字段名、对象创建方式或函数签名。 - -## 先看这 5 条 - -- 如果你的问题是“语言怎么写”，不要留在 finance，回到 [../syntax/index.md](../syntax/index.md)。 -- 如果你的问题是“某个金融任务怎么组织”，从下面最接近的业务主题开始。 -- [entry_decision.md](entry_decision.md) 是入口决策页，不是代码页。 -- 先进入 finance 的业务主题页；只有业务页需要补语法或函数细节时，再回到语法手册或函数查阅层。 -- 只进入一个最相关的主题文件，需要时再跳到相邻主题。 - -## 按任务跳转 - -| 当前任务 | 先读哪里 | -| ------------------------------ | -------------------------------------------------------------------- | -| 先判断是否该进入业务层 | [entry_decision.md](entry_decision.md)（决策页，不是代码页） | -| 理解市场数据上下文与运行场景 | [market_data_context.md](market_data_context.md) | -| 理解序列、指标、时序计算模型 | [series_and_indicator_model.md](series_and_indicator_model.md) | -| 写选股、信号、筛选表达模式 | [selection_and_signal_patterns.md](selection_and_signal_patterns.md) | -| 写回测对象、交易流程、结果读取 | [backtest_and_trade_flow.md](backtest_and_trade_flow.md) | - -## 切换到别的层 - -- 回到语法层：见 [../syntax/index.md](../syntax/index.md) -- 回到函数库查找层：见 [../reference/index.md](../reference/index.md) diff --git a/docs/tsl/finance/market_data_context.md b/docs/tsl/finance/market_data_context.md deleted file mode 100644 index 0a8608f5..00000000 --- a/docs/tsl/finance/market_data_context.md +++ /dev/null @@ -1,45 +0,0 @@ -# Market Data Context - -文档类型：业务骨架 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[series_and_indicator_model.md](series_and_indicator_model.md)、[../syntax/index.md](../syntax/index.md)、[../modules/tsbacktesting.md](../modules/tsbacktesting.md) - -本页用于判断金融脚本运行时的数据语境，不提供独立语法模板。 - -这一篇整理金融场景中的市场数据语境与执行环境。 - -## Agent 市场数据判断规则 - -- 先确认脚本运行时是否已经有市场数据上下文。 -- 只把本页用于判断业务语境，不把市场字段当成 TSL 通用语法。 -- 如果字段来源、周期、复权口径或数据入口不明确，回项目实际接口定义。 -- 不要发明项目实际接口、市场字段或默认数据上下文。 - -## 这一篇解决什么问题 - -回答“金融脚本运行时的数据上下文是什么、哪些概念属于业务层而不是语言层”。 - -## 必须记住的规则 - -- 这里讨论的是市场数据语境，不是语言语法。 -- 当问题变成“`if` / `function` / `array` 怎么写”时，应回到 syntax 层。 -- 当问题变成“当前 bar、序列窗口、市场字段从哪里来”时，才留在 finance 层。 - -## 适用边界 - -- 本文不新增语法规则，语法仍以 `docs/tsl/syntax/` 为准。 - -## 为什么这里不放独立示例 - -- 本文不放单独的语法示例，避免把业务上下文误写成语言规则。 - -## 常见误写 - -- 把市场数据上下文误当成所有 TSL 文件默认自带的语言能力。 -- 在还没确认数据语境前，先去排查语法。 - -## 跳转指引 - -- 回到语法层：见 [../syntax/03_core_model.md](../syntax/03_core_model.md) -- 看指标与序列：见 [series_and_indicator_model.md](series_and_indicator_model.md) -- 参考现有业务资料：见 [../modules/tsbacktesting.md](../modules/tsbacktesting.md) diff --git a/docs/tsl/finance/selection_and_signal_patterns.md b/docs/tsl/finance/selection_and_signal_patterns.md deleted file mode 100644 index 834a3339..00000000 --- a/docs/tsl/finance/selection_and_signal_patterns.md +++ /dev/null @@ -1,56 +0,0 @@ -# Selection And Signal Patterns - -文档类型：业务骨架 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[series_and_indicator_model.md](series_and_indicator_model.md)、[backtest_and_trade_flow.md](backtest_and_trade_flow.md)、[../syntax/index.md](../syntax/index.md) - -这一篇收拢选股、筛选和信号生成的业务模式。 - -## Agent 选股/信号判断规则 - -- 先确认任务输出是筛选结果、交易信号、评分排序还是回测输入。 -- 条件表达的语法回 syntax；金融任务组织留在 finance。 -- 需要真实字段、信号函数或输出接口时，回项目实际接口定义。 -- 不要发明项目实际接口、字段名、信号函数签名或输出结构。 - -## 这一篇解决什么问题 - -回答“如何把条件表达和金融筛选任务组织成稳定的选股/信号脚本”。 - -## 必须记住的规则 - -- 选股和信号属于业务层模式，不是通用语言规则。 -- 语言层只回答“条件怎么写”；finance 层回答“这些条件怎样组成选股/信号任务”。 -- 如果问题开始变成某个基础运算符怎么写，应回到 syntax 层。 - -## 任务骨架 - -1. 先写条件表达：澄清你在筛什么、比较什么、窗口是多少。 -2. 再生成信号：决定输出是布尔筛选、买卖信号，还是评分 / 排序结果。 -3. 最后整理结果输出：决定是输出标的列表、信号列、分数字段，还是交给下游回测。 - -## 常见任务形态 - -- 单次筛选：给定条件，输出满足条件的标的集合。 -- 连续信号：按时间推进，逐 bar 产生买入 / 卖出 / 持有信号。 -- 评分排序：先算分，再做阈值过滤、排名或分组。 - -## 写之前先决定 - -- 条件是在“当前 bar 是否成立”，还是“最近 N 个 bar 的模式是否成立”。 -- 信号是即时使用，还是要保存成后续回测 / 执行的输入。 -- 输出面向人看，还是面向下游框架消费。 - -## 常见误判 - -- 把一个业务筛选范式误写成“所有 TSL 都应这样写”的基础语法结论。 -- 不区分“条件表达成立”与“选股任务组织合理”这两件事。 -- 还没确认输出形式，就先把条件堆成很长的单条表达式。 -- 把筛选条件、信号生成和结果输出混写在一个不可拆分的大块里。 - -## 跳转指引 - -- 指标与序列：见 [series_and_indicator_model.md](series_and_indicator_model.md) -- 市场上下文：见 [market_data_context.md](market_data_context.md) -- 回测与交易：见 [backtest_and_trade_flow.md](backtest_and_trade_flow.md) -- 基础语法：见 [../syntax/index.md](../syntax/index.md) diff --git a/docs/tsl/finance/series_and_indicator_model.md b/docs/tsl/finance/series_and_indicator_model.md deleted file mode 100644 index 21ff43cb..00000000 --- a/docs/tsl/finance/series_and_indicator_model.md +++ /dev/null @@ -1,58 +0,0 @@ -# Series And Indicator Model - -文档类型：业务骨架 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[market_data_context.md](market_data_context.md)、[selection_and_signal_patterns.md](selection_and_signal_patterns.md)、[../syntax/index.md](../syntax/index.md) - -这一篇处理金融序列与指标计算模式。 - -## Agent 序列/指标判断规则 - -- 先确认输入是单值还是逐 bar 序列。 -- 指标公式只在业务上下文里成立，不替代 syntax 的表达式规则。 -- 需要真实字段、指标函数或窗口口径时，回项目实际接口定义或 reference 参数事实页。 -- 不要发明项目实际接口、字段名、指标函数签名或历史窗口语义。 - -## 这一篇解决什么问题 - -回答“指标、序列、逐 bar 计算和相关金融表达方式如何组织，以及 AI 应该先建立什么样的业务心智模型”。 - -## 必须记住的规则 - -- 序列与指标属于业务模型，不属于通用语法。 -- 当你需要解释循环、表达式、数组和字符串时，应回到 syntax 层。 -- 当你需要解释“指标如何依赖历史序列”时，才留在这里。 - -## 输入上下文 - -- 先确认标的、周期、起止区间和复权口径。 -- 先确认你在处理“单值输入”还是“逐 bar 序列输入”。 -- 先确认指标依赖多少历史窗口，以及窗口未满时如何处理。 - -## 逐 bar 心智模型 - -- 每个 bar 只应使用当前 bar 及其之前已经可见的信息。 -- 先准备输入序列，再计算当前 bar 的指标值，最后再决定当前 bar 的输出。 -- 不要把后面的 bar 结果回填到前面的 bar。 -- 不要把“能写成一个表达式”误解成“就不需要业务上下文”。 - -## 窗口依赖 - -- 任何均线、滚动统计、历史比较，先写清窗口长度。 -- 窗口未满前，先决定是跳过、返回空值，还是走 warm-up 逻辑。 -- 多条序列一起参与计算时，先确认时间轴是否对齐。 -- 当结果依赖前值时，先确认你是在做“当前 bar 计算”还是“状态延续”。 - -## 常见误判 - -- 把指标写法误当成“TSL 基础表达式”的定义来源。 -- 在没有澄清数据频率、窗口和上下文前，就直接抽象成通用语法规则。 -- 把未来数据混进当前 bar 的计算里。 -- 先写公式，再补上下文，导致窗口长度和序列来源都不明确。 - -## 跳转指引 - -- 市场数据上下文：见 [market_data_context.md](market_data_context.md) -- 选股与信号：见 [selection_and_signal_patterns.md](selection_and_signal_patterns.md) -- 回测与交易：见 [backtest_and_trade_flow.md](backtest_and_trade_flow.md) -- 表达式与控制流语法：见 [../syntax/07_expressions_and_operators.md](../syntax/07_expressions_and_operators.md) 与 [../syntax/08_control_flow.md](../syntax/08_control_flow.md) diff --git a/docs/tsl/index.md b/docs/tsl/index.md index ba43c5ab..b4e83520 100644 --- a/docs/tsl/index.md +++ b/docs/tsl/index.md @@ -1,134 +1,83 @@ -# TSL Index +# TSL 文档入口 文档类型：检索页 是否可直接用于生成代码：否 -是否含已验证可执行示例：否 -是否含已验证反例：否 -遇到不确定时跳转到：[syntax/index.md](syntax/index.md)、[finance/index.md](finance/index.md)、[reference/index.md](reference/index.md)、[modules/index.md](modules/index.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置 +是否含可直接照写示例：否 +是否含不可照写反例：否 +遇到不确定时：先按本文“任务路由”分层；语法问题看 [syntax/index.md](syntax/index.md)，函数库查询看 [reference/index.md](reference/index.md)，模块 / 集成看 [modules/index.md](modules/index.md)，项目执行问题回项目自身文档、`scripts/*` 入口脚本和 CI 配置 -这个入口文件只负责一件事：让 agent 先判断主问题属于哪一层，再进入最相关的单个入口页。这里的语法文档面向 agent 决策，不按人类教程组织；回答和生成代码时必须按流程读，不要凭语言相似性补全。 +本入口只负责一件事：让智能体先判断主问题属于哪一层，再进入最相关的单个入口页。本套 TSL 文档面向智能体决策，不按人类教程组织；回答和生成代码时必须按流程读，不要凭语言相似性补全。 -## 先记住这些规则 +## 起手规则 -- 先读本文件，不要默认通读全部 TSL 文档。 -- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，再根据用户交付目标判断。 -- `.tsl` 是可执行脚本；`.tsf` 是部署到解释器 `funcext` 的模块/函数扩展文件。 -- 写 `.tsl` 时按两段理解：语句区在前并按顺序执行；函数/类声明区在后，供前面的语句调用或运行时解析。 -- 写 `.tsf` 时按模块/扩展理解；顶层函数部署到 `funcext` 后，`.tsl` 脚本可以直接调用。 -- 语言怎么写的问题，先从 `docs/tsl/syntax/` 开始。 -- 指标、选股、回测和策略流程的问题，先从 `docs/tsl/finance/` 开始；不要先把业务问题拆成纯语法问题。 -- 某个函数怎么用、属于哪个函数库分类或目录，先从 `docs/tsl/reference/` 开始。 -- 现成模块、外部集成和互操作问题，先从 [modules/index.md](modules/index.md) 开始。 -- 账户体系、真实接口名、部署方式、脚本入口、权限模型、环境变量、CI、验证命令这类问题，先按“项目依赖 / 项目执行”处理；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置。 -- [toolchain.md](toolchain.md) 不是 TSL 语法子类，而是项目执行类辅证页；只有当前项目已经补齐工具链与验证信息时才使用；如果这页仍是模板，不把它当主入口。 -- 生成 `.tsl` 代码时，优先从脚本语句区开始；如果关键词要求函数或类，把声明放在语句区之后。 -- 不要在 `.tsl` 的函数/类声明区之后再追加新的脚本语句。 -- 任何语法判断都先看正式语法页结论。 -- 如果涉及较新写法、资料冲突或解释器差异，先回到 `docs/tsl/syntax/index.md`，再按主题跳到对应语法页；对应主题页仍然没有结论时，不要自行补语法。 -- 如果涉及高频误写、反例或负向边界，优先回到 `docs/tsl/syntax/12_pitfalls.md`；结论缺失时不要把猜测写成语法事实。 -- 模板、错误示例和输出片段不算可独立编译代码。 +1. 先判断主问题层：语法、函数库、模块 / 集成，还是项目执行。 +2. 只进入命中的单个入口页；不要同时展开语法、业务、函数库、模块和工具链。 +3. 如果要生成或修改 TSL 代码，先做文件模型初判；详细规则见 [syntax/02_core_model.md](syntax/02_core_model.md)： + - 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。 + - 用户未给后缀时，按交付目标判断：入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用函数、过程、类、模块或扩展对应 `.tsf`。 + - 仍不明确时先向用户确认，不要靠相似语言补全。 +4. 写代码前找 `代码块身份：可直接照写示例`；遇到 `反例 / 不可照写`、输出片段或概念骨架必须避开。 +5. 语法细节统一进入 [syntax/index.md](syntax/index.md) 后再分流；本页只保留跨层路由需要的最小提醒。 +6. 本手册没有结论时，不要发明语法；改为向用户确认、记录文档缺口，或交由维护者补充文档结论。 ## 元数据与证据标签 - 页头里的 `是否可直接用于生成代码` 只做页面级粗判断；如果页内已经给出 `代码块身份`，一律以块级标签为准。 - `是否可直接用于生成代码` 有三种值：`是`、`否`、`仅部分`；其中 `仅部分` 表示页内既有可直接参考的块，也有依赖多文件、查找路径或运行时环境的块，必须继续看块级标签。 -- `是否含已验证可执行示例` 只统计已经跑通、可以直接参考外形的正向代码示例。 -- `是否含已验证反例` 只统计已经确认不能照写的负向例子。 -- `代码块身份` 只使用固定词表：`已验证可执行示例`、`已验证输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。 +- `是否含可直接照写示例` 只统计可直接照写的正向代码示例。 +- `是否含不可照写反例` 只统计不可照写的负向例子。 +- `代码块身份` 只使用固定词表：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。 - 如果还需要补充用途、限制或复用建议，单独写 `代码块说明`，不要把说明文字继续拼进 `代码块身份`。 -- 如果页头里的 `遇到不确定时跳转到` 列出多个目标，默认第一项是优先入口，后面的目标只用于分流或补证。 +- 如果页头里的 `遇到不确定时` 列出多个目标，普通专题页默认第一项是优先入口；总入口页例外，必须先按任务路由分层。 -## 维护者入文档前验证 +## 语法事实使用规则 -- TSL 语法页面向 agent 生成代码；所有写成语法事实的代码库样例，必须先由维护者在项目验证环境中确认。 -- 正向代码库样例只有在环境验证通过后，才能标成 `已验证可执行示例`；对应输出只能标成 `已验证输出片段`。 -- 负向代码库样例只有在环境中确认失败形态后，才能标成 `反例 / 不可照写`。 -- 未经过环境验证的写法不能写成语法事实；只能作为文档缺口、待验证项，或标成 `配置片段 / 概念骨架`。 -- 验证过程不写进语法页；解释器路径、Docker、Windows、Ubuntu、环境变量和执行命令属于项目执行层，不能混入通用语法事实。 -- agent 不需要自行执行验证；agent 只根据维护者已经写入文档的证据标签生成代码，遇到未覆盖写法时不要发明语法。 +- TSL 语法页面面向智能体生成代码；写成语法事实的内容就是生成依据，不再要求智能体自行证明。 +- `可直接照写示例` 用于参考代码外形、语句顺序和块级结构。 +- `输出片段` 只用于理解返回结果或错误形态，不作为代码照写。 +- `反例 / 不可照写` 只用于避开对应写法，不反向推导新的语法。 +- `配置片段 / 概念骨架` 只说明结构或配置位置，不代表可直接运行。 +- 文档没有覆盖的写法不能生成；应向用户确认、记录文档缺口，或回到项目实际代码寻找证据。 +- 执行环境细节不写进语法页；项目执行信息不能混入通用 TSL 事实。 -## 新 session 起手规则 +## 任务路由 -### Agent 读取流程 +| 任务 | 先读哪里 | +| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| 我要系统入门 TSL | [syntax/index.md](syntax/index.md) | +| 我要先核对语言核心事实 | [syntax/01_quickstart.md](syntax/01_quickstart.md) | +| 我要写最短可运行骨架 | [syntax/01_quickstart.md](syntax/01_quickstart.md) | +| 我要判断“这句语法能不能写” | [syntax/index.md](syntax/index.md) | +| 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界 | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页 | +| 我要核对高频误写 / 反例 / 负向边界 | [syntax/11_pitfalls.md](syntax/11_pitfalls.md) | +| 我要查行情 / 财务 / 板块 / 选股等金融函数 | [reference/catalog/datawarehouse.md](reference/catalog/datawarehouse.md) | +| 我要用 Python 调 TSL 服务器函数或取金融数据 | [modules/pytsl_api.md](modules/pytsl_api.md) | +| 我要写回测框架 / 读取回测结果 | [modules/tsbacktesting.md](modules/tsbacktesting.md) | +| 我要看模块 / 集成 / 互操作入口 | [modules/index.md](modules/index.md) | +| 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；有项目文档时再看 [toolchain.md](toolchain.md) | +| 我要查函数库 | [reference/index.md](reference/index.md) | -1. 识别目标层：语法、金融业务、函数库、模块/集成、项目执行。 -2. 识别用户指定的文件后缀；用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。 -3. 用户未给后缀时，按交付目标判断：可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。 -4. 对 `.tsl`，先生成语句区；需要本文件函数/类时，再生成声明区。 -5. 对 `.tsf`，生成模块/扩展声明；部署后的顶层函数可由脚本直接调用。 -6. 只读取当前任务命中的单个入口页；不要同时展开语法、业务、函数库和工具链。 -7. 生成代码前找 `代码块身份：已验证可执行示例`；遇到 `反例 / 不可照写` 必须避开。 +## 路由冲突处理 -### If / Then 路由 +- 如果一个问题同时涉及业务和语法，先按主问题分层。 +- 如果主问题是业务实现，先走 `modules/`、`reference/catalog/datawarehouse.md` 或项目实际接口文档，语法只作辅证，不反过来吞掉业务入口。 +- 如果主问题是语言写法，先走 `syntax/`，金融或模块页只作为示例和上下文。 +- 如果主问题已经落到真实接入参数、账号来源、部署依赖、执行入口或权限模型，直接转“项目依赖 / 项目执行”确认，不继续在 `modules/`、`syntax/` 或模板型 `toolchain.md` 里兜圈子。 -- If 问题在问“语言怎么写”，then 先从 [syntax/index.md](syntax/index.md) 开始。 -- If 问题在问“指标 / 选股 / 回测怎么组织”，then 先从 [finance/index.md](finance/index.md) 开始。 -- If 问题在问“某个函数怎么用”或“函数属于哪个函数库分类 / 目录”，then 先从 [reference/index.md](reference/index.md) 开始。 -- If 问题在问“现成模块 / 集成 / 互操作”，then 先从 [modules/index.md](modules/index.md) 开始。 -- If 问题依赖项目实际接口、账户体系、部署方式、脚本入口、权限模型、环境变量、CI 或验证命令，then 不把它当通用 TSL 事实；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置；只有当前项目已补齐时，才把 [toolchain.md](toolchain.md) 当辅证页。 -- If 问题在问“这句语法能不能写”，then 先从 [syntax/index.md](syntax/index.md) 开始。 -- If 问题在问“较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界”，then 先看 [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页。 -- If 问题在问“高频误写 / 反例核对 / 负向边界”，then 先看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)。 +## 通用 TSL 语法骨架路径 -### Tie-Break +只有主问题是语言写法、最短骨架或语法有效性时，才从本节起手；如果主问题是模块集成、函数库查询或项目执行，先回到“任务路由”。 -- If 一个问题同时涉及业务和语法，then 先按主问题分层。 -- If 主问题是业务实现，then 先走 `finance/` 或 `modules/`，语法只作辅证，不反过来吞掉业务入口。 -- If 主问题是语言写法，then 先走 `syntax/`，金融或模块页只作为示例和上下文。 -- If 主问题已经落到真实接入参数、账号来源、部署依赖、执行入口或权限模型，then 直接转“项目依赖 / 项目执行”确认，不继续在 `modules/`、`syntax/` 或模板型 `toolchain.md` 里兜圈子。 +1. 先看 [syntax/01_quickstart.md](syntax/01_quickstart.md) 的语言核心事实和最短骨架。 +2. 再按 [syntax/index.md](syntax/index.md) 进入命中的语法专题。 +3. 涉及反例、常见误写或负向边界时，看 [syntax/11_pitfalls.md](syntax/11_pitfalls.md)。 -### 语言事实 +## 智能体提交前最低自检 -- 可以先把 TSL 当成 Pascal 风格语言去理解：`function`、`begin`、`end`、`unit`、`uses` 都很接近；但这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。 -- 涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、`function / procedure` 外形、`unit` 骨架、命名参数、`type Name = class`、数组 / 字符串下标这类高频硬规则，统一以 [syntax/02_quickstart.md](syntax/02_quickstart.md) 的“语言核心事实速查”为准；当前页只保留跨层路由所需的最小提醒。 - -#### 写代码前先记住 - -- 写代码前先把高频硬规则收口到 [syntax/02_quickstart.md](syntax/02_quickstart.md)，不要分别从入口页、介绍页和文件模型页拼接结论。 -- `.tsl` 仍优先按“语句区在前、声明区在后”的脚本模型理解；`.tsf` 仍优先按部署到 `funcext` 的模块/扩展理解。 -- 模板、错误示例和输出片段不算可独立编译代码；真正落代码时优先看块级 `代码块身份`。 - -### 手册建模规则 - -- 更可靠的识别方式是同时看任务目标和顶层内容，而不是只看文件扩展名。 -- 顶层允许出现 `uses`，但这里只把它当辅助语句，不把它当主体声明。 -- 下游大量 `program test; begin ... end.` 形式，只作为自包含验证样例外壳，不作为这里归纳的正式顶层模型。 - -## 如果你马上要写 TSL - -- 先看 [syntax/02_quickstart.md](syntax/02_quickstart.md) -- 再看 [syntax/index.md](syntax/index.md) -- 然后看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md) -- 最后按需补看相应专题页 - -## 最短跳转 - -| 当前任务 | 先读哪里 | -| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| 我要系统入门 TSL | [syntax/index.md](syntax/index.md) | -| 我要先核对语言核心事实 | [syntax/02_quickstart.md](syntax/02_quickstart.md) | -| 我要写最短可运行骨架 | [syntax/02_quickstart.md](syntax/02_quickstart.md) | -| 我要判断“这句语法能不能写” | [syntax/index.md](syntax/index.md) | -| 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界 | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页 | -| 我要核对高频误写 / 反例 / 负向边界 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) | -| 我要知道正式语法手册现在还差什么 | [syntax/coverage_map.md](syntax/coverage_map.md) | -| 我要写金融指标 / 选股 / 回测 | [finance/index.md](finance/index.md) | -| 我要看模块 / 集成 / 互操作入口 | [modules/index.md](modules/index.md) | -| 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [toolchain.md](toolchain.md) | -| 我要看回测框架模块 | [modules/tsbacktesting.md](modules/tsbacktesting.md) | -| 我要看 Python 互操作 | [modules/tsl_python_interop.md](modules/tsl_python_interop.md) | -| 我要看微信消息推送 | [modules/wechat_message.md](modules/wechat_message.md) | -| 我要看 Python API | [modules/pytsl_api.md](modules/pytsl_api.md) | -| 我要查函数库 | [reference/index.md](reference/index.md) | -| 当前项目已补齐工具链时，看工具链 / 项目执行辅证 | [toolchain.md](toolchain.md) | -| 我要避开高频误写 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) | - -## 进入之后怎么读 - -1. 先判断主问题属于语法、业务、函数库、模块/集成，还是项目依赖 / 项目执行。 -2. 如果主问题是项目依赖 / 项目执行，直接回项目自身文档、`scripts/*` 入口脚本或 CI 配置；只有当前项目已经补齐时，才把 [toolchain.md](toolchain.md) 当辅证。 -3. 否则先进入一个最相关的入口页，不要同时展开多个层。 -4. 当前页如果已经给出结论，先采用；准备编写时优先找已验证正例，再落代码；只有需要补充时再跳到相邻页。 -5. 遇到“资料写法不一致”且偏较新写法、资料冲突或解释器差异时，先回 [syntax/index.md](syntax/index.md) 按主题跳到对应语法页。 -6. 遇到“资料写法不一致”且偏高频误写、反例或负向边界时，先看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)。 -7. 如果当前手册没有给出结论，不要发明语法；改为向用户确认、记录文档缺口，或等待维护者用项目环境补充已验证结论。 +1. 是否已经判断主问题属于语法、函数库、模块/集成或项目执行。 +2. 如果要生成代码，是否已经确认 `.tsl` / `.tsf` 文件模型。 +3. 是否优先参考了 `代码块身份：可直接照写示例`。 +4. 是否避开了 `反例 / 不可照写`、输出片段和概念骨架。 +5. 是否没有凭 Pascal、Python、JavaScript、TypeScript 或其它语言相似性补全 TSL 语法。 +6. 是否没有把项目执行信息、账户体系、真实接口或验证命令写成通用 TSL 事实。 +7. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。 diff --git a/docs/tsl/modules/index.md b/docs/tsl/modules/index.md index e6b57d21..0ca7bf92 100644 --- a/docs/tsl/modules/index.md +++ b/docs/tsl/modules/index.md @@ -1,44 +1,54 @@ -# Modules Index +# 模块入口 -文档类型：检索页 +文档类型：模块决策路由页 是否可直接用于生成代码：否 -遇到不确定时跳转到：[tsbacktesting.md](tsbacktesting.md)、[tsl_python_interop.md](tsl_python_interop.md)、[../finance/index.md](../finance/index.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置 +遇到不确定时：[pytsl_api.md](pytsl_api.md)、[tsbacktesting.md](tsbacktesting.md)、[wechat_message.md](wechat_message.md)、[../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置 -这里处理“现成模块、外部集成和互操作”，不处理基础语法教学，也不替代金融业务主线。 +本页只负责把“现成模块、外部集成和模块 API”任务路由到正确事实页。目标页是模块 API 事实页时，智能体可以继续使用该页的签名、参数表、返回值和代码骨架；本页自身不生成代码。 -模块摘要页只负责确认能力边界和选路，不负责给出项目账户体系、真实接口名、部署方式、权限模型或脚本入口的真值。 +## 智能体模块路由规则 -## Agent Modules 路由规则 +- 先判断任务是否属于模块 API、业务流程、通用语法、通用函数库或项目执行上下文。 +- 命中下面“决策顺序”中的一行后，先进入对应页面，不继续向下泛化。 +- 真实账号、密码、服务地址、部署入口、脚本入口、权限模型和项目私有字段必须来自项目上下文。 +- 不要发明模块专属 API 参数、项目账号来源、部署路径、服务节点、模板字段、证券池或策略信号。 -- 先判断任务是在问模块能力、业务流程、语法规则还是项目真实接入参数。 -- modules 只给集成边界和选路；真实账号、部署入口、权限模型和接口细节必须回项目文档。 -- 不要发明模块专属 API 参数、项目账号来源、部署路径或脚本入口。 +## 决策顺序 -## If / Then 路由 +| 顺序 | 用户任务特征 | 先读哪里 | 命中后动作 | +| ---- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------- | +| 1 | 询问真实账号、密码、服务地址、配置文件、部署入口、脚本入口、CI、权限模型 | 项目自身文档、`scripts/*`、CI 配置 | 退出通用模块层，不从模块页猜项目事实 | +| 2 | 用 Python 执行 TSL、调用服务器 TSL 函数、查行情、批量取数、异步取数 | [pytsl_api.md](pytsl_api.md) | 使用 pyTSL 类、函数、参数和返回结构 | +| 3 | 发送微信通知、微信告警、微信模板消息、查询微信消息发送状态 | [wechat_message.md](wechat_message.md) | 使用微信消息接口、模板字段和展示规则 | +| 4 | 写策略回测框架、组合回测、读取回测资产/持仓/交易/绩效结果 | [tsbacktesting.md](tsbacktesting.md) | 使用 `TSBackTesting` 对象模型、成员变量和查询接口 | +| 5 | 查询行情、财务、板块、选股等金融函数 | [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md) | 使用数据仓库函数事实 | +| 6 | 询问 TSL 语言语法怎么写 | [../syntax/index.md](../syntax/index.md) | 回到语法主线 | +| 7 | 查询通用函数库函数签名、参数或返回值 | [../reference/index.md](../reference/index.md) | 回到函数库检索入口 | -- If 问题在问“策略回测框架怎么组织、怎么取结果”，then 先读 [tsbacktesting.md](tsbacktesting.md)。 -- If 问题在问“TSL 和 Python 怎样双向调用或嵌入”，then 先读 [tsl_python_interop.md](tsl_python_interop.md)。 -- If 问题在问“微信消息怎样发送、查询状态”，then 先读 [wechat_message.md](wechat_message.md)。 -- If 问题在问“官方 Python SDK / pyTSL 客户端怎么用”，then 先读 [pytsl_api.md](pytsl_api.md)。 -- If 问题在问模块的真实接入参数、账号来源、部署依赖、权限模型或脚本入口，then 这已经不是模块能力识别；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置，必要时再把对应模块页当边界说明。 +## 模块页职责 -## Tie-Break +| 模块页 | 负责回答 | 不负责回答 | +| -------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------- | +| [pytsl_api.md](pytsl_api.md) | Python SDK 的类、函数、参数、返回结构、同步/异步/批量调用选择 | 真实凭证、服务地址、权限范围、业务字段口径 | +| [wechat_message.md](wechat_message.md) | 微信发送接口、异步状态查询、模板字段、首屏/详情展示规则 | 真实 `userid`、`username`、授权关系、项目封装函数 | +| [tsbacktesting.md](tsbacktesting.md) | `TSBackTesting` 子类骨架、组合类别、交易字段、成员变量、查询接口 | 策略信号、证券池、资金参数、费用口径、真实行情来源 | -- If 主问题是业务流程、选股逻辑或回测指标组织，then 先回 [../finance/index.md](../finance/index.md)。 -- If 主问题是现成模块或集成能力，then 先留在 `modules/`；语法只作辅证。 -- If 主问题已经落到 TSL 通用函数库签名或通用语法参数细节，then 再回 [../reference/index.md](../reference/index.md) 或对应语法页。 -- If 主问题已经落到模块专属 API / SDK 参数细节，then 先回对应模块页，并以该页指向的官方文档、项目文档或调用侧文档为准。 -- If 主问题已经落到真实接入参数、账号来源、部署依赖、权限模型或执行入口，then 退出模块摘要层，直接转项目依赖确认。 +## 冲突处理 + +- Python 执行一段 TSL 或调用服务器函数时，先读 [pytsl_api.md](pytsl_api.md)；TSL 代码本身再按 [../syntax/index.md](../syntax/index.md) 或 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md) 补充。 +- Python 调用回测脚本时，先读 [pytsl_api.md](pytsl_api.md) 确认执行方式，再读 [tsbacktesting.md](tsbacktesting.md) 确认回测框架写法。 +- 回测框架、交易字段和结果接口优先读 [tsbacktesting.md](tsbacktesting.md)；策略信号、证券池、费用口径等项目事实必须来自用户需求或项目实际接口。 +- 微信通知内容来自业务结果时，先用业务页确定内容，再用 [wechat_message.md](wechat_message.md) 组织模板字段。 +- 模块页和项目文档冲突时，以项目文档的账号、部署、权限和入口为准；模块页只保留通用 API 事实。 ## 最短跳转 -| 当前任务 | 先读哪里 | -| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| 我要看回测框架 | [tsbacktesting.md](tsbacktesting.md) | -| 我要看 Python 互操作 | [tsl_python_interop.md](tsl_python_interop.md) | -| 我要看微信消息推送 | [wechat_message.md](wechat_message.md) | -| 我要看 Python API | [pytsl_api.md](pytsl_api.md) | -| 我要确认模块的真实接入参数 / 账号来源 / 部署依赖 / 脚本入口 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [../toolchain.md](../toolchain.md) | -| 我要回到业务主线 | [../finance/index.md](../finance/index.md) | -| 我要回到语法主线 | [../syntax/index.md](../syntax/index.md) | -| 我要查函数库 | [../reference/index.md](../reference/index.md) | +| 任务 | 先读哪里 | +| ------------------------------------------------- | ------------------------------------------------------------------------------ | +| 我要用 Python 调 TSL / 查行情 / 批量取数 | [pytsl_api.md](pytsl_api.md) | +| 我要发微信通知 / 告警 / 查询状态 | [wechat_message.md](wechat_message.md) | +| 我要写 `TSBackTesting` 回测框架 | [tsbacktesting.md](tsbacktesting.md) | +| 我要查行情 / 财务 / 板块 / 选股函数 | [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md) | +| 我要确认 TSL 语法 | [../syntax/index.md](../syntax/index.md) | +| 我要查通用函数库 | [../reference/index.md](../reference/index.md) | +| 我要确认真实账号 / 服务地址 / 部署入口 / 脚本入口 | 项目自身文档、`scripts/*`、CI 配置 | diff --git a/docs/tsl/modules/pytsl_api.md b/docs/tsl/modules/pytsl_api.md index a04cda69..3a626e57 100644 --- a/docs/tsl/modules/pytsl_api.md +++ b/docs/tsl/modules/pytsl_api.md @@ -1,92 +1,947 @@ # 天软 pyTSL 接口使用说明 -文档类型：模块摘要 -是否可直接用于生成代码：仅部分 -遇到不确定时跳转到：项目级部署文档、官方 pyTSL 详细接口文档、[tsl_python_interop.md](tsl_python_interop.md)、[index.md](index.md) +文档类型：模块 API 事实页 +是否可直接用于生成代码：是，但真实账号、密码、服务地址、配置文件路径和权限范围必须来自项目上下文 +遇到不确定时：[index.md](index.md)、项目自身部署文档、官方 pyTSL 接口文档 -本页用于确认 pyTSL 的接入方向和最小链路，不替代项目级部署文档或完整接口手册。 +本页整理 pyTSL 官方 Python SDK 的可调用接口。它负责告诉智能体“pyTSL 有哪些类、函数、参数和返回结构”，不负责提供真实凭证、项目账号来源、服务权限或业务数据口径。 -- 如果登录方式、凭证来源、环境变量、部署入口、连接上下文或返回结构没有确认，不继续生成接入代码，直接回项目级部署文档或官方 pyTSL 详细接口文档。 +## 智能体 pyTSL 决策规则 -## Agent pyTSL 边界规则 +- 用户要“用 Python 调 TSL / 执行 TSL 代码 / 调天软函数 / 查行情 / 并发或异步取数”时，优先使用本页。 +- 用户只是要执行一段 TSL 并马上拿结果，默认使用 `pyTSL.Client.exec()`。 +- 用户要调用服务器上已有 TSL 函数，默认使用 `pyTSL.Client.call()`。 +- 用户要按证券、周期、开始时间、结束时间取标准行情字段，默认使用 `pyTSL.Client.query()`。 +- 用户要一次性提交很多独立任务，先考虑 `pyTSL.Batch`；不要把大量循环直接写成频繁登录、退出。 +- 用户明确要求 asyncio，才使用 `pyTSL.AsyncClient` 或 `pyTSL.async_util`。 +- 不要发明真实账号、密码、服务地址、代理、配置文件路径、服务节点、字段名或业务函数名。 +- 不要把登录脚本、临时验证脚本或私有凭证写进生成代码；示例只能使用占位值或从项目配置读取。 -- 先确认项目是否已经给出 pyTSL 安装方式、登录方式、凭证来源和返回结构。 -- 本页只给 SDK 能力分类和最小链路，不替代官方接口手册。 -- 不要发明登录参数、连接上下文、查询语句来源或返回数据结构。 +## 安装与支持范围 -## 定位 +### 包与导入 -- 官方 Python SDK，面向取数/执行/批量/异步与数据转换。 +| 项目 | 事实 | +| ---------- | ------------------------------------------------------------------------- | +| 安装包名 | `tspytsl` | +| 导入模块名 | `pyTSL` | +| 在线安装 | `pip install tspytsl` | +| 升级 | `pip install tspytsl -U` | +| 离线安装 | 下载对应 `.whl` 后执行 `pip install 文件名.whl` | +| 手动安装 | 解压对应平台的 `.pyd` 或 `.so`，放入 Python 的 `site-packages` 或项目目录 | -## 结构索引 +### Python 与平台 -- 安装与配置 -- pyTSL 接口说明（Client / AsyncClient / async_util / Batch / Task / Const / TSResultValue） -- pyTSLPy 兼容说明 -- 示例与数据类型转换 -- 附录与常见问题 +- pyTSL 支持 Python 3.6+。 +- 官方文档截至 2025-10-13 列出 Python 3.6 到 3.14 的 Windows、Linux x86_64、Linux arm64、MacOS x86_64 支持。 +- MacOS arm64 从 Python 3.8 到 3.14 支持，Python 3.6 和 3.7 不支持。 +- Windows 需要确认已安装 VS2019 C++ 运行时库；其他系统不需要这一步。 -## 安装方式（摘要） +## 最小同步链路 -- `pip install tspytsl`（在线安装） -- 离线安装与手动部署 +优先写成“一次登录，多次交互，最后退出”。`logout()` 后再次调用 `Client` 方法可能触发自动重新登录，频繁登录退出可能占用多个登录数。 -## 同步 / 异步怎么选 +```python +import pyTSL +from datetime import datetime -- 同步：任务短、交互简单、立即取结果时优先用 `pyTSL.Client`。 -- 异步：任务长、需要并发或批量调度时再看 `pyTSL.AsyncClient` 与 `async_util`。 -- 如果只是先打通最小链路，先用同步客户端，不要一开始就上异步。 +c = pyTSL.Client("user", "password", "tsl.tinysoft.com.cn", 443) +try: + if c.login() == 0: + raise RuntimeError(c.last_error()) -## 核心类与模块 + r = c.exec("return close();", stock="SZ000002", time=datetime(2024, 7, 30)) + if r.error(): + raise RuntimeError(r.message()) -- `pyTSL.Client`：同步客户端 -- `pyTSL.AsyncClient`：异步客户端 -- `pyTSL.async_util`：异步工具函数 -- `TSBatch` / `Task`：批量与任务 -- `TSResultValue`：统一返回结果封装 -- `pyTSL.Const`：常量与字段 + value = r.value() +finally: + c.logout() +``` -## 关键方法（常用） +## `pyTSL.Client` -- `login` / `logout` -- `exec` / `call` / `query` -- `download_list` / `download` / `upload` / `remove` -- `DatetimeToDouble` / `DoubleToDatetime` -- `EncodeStream` / `DecodeStream` -- `DataFrameToTSArray` +同步客户端。构造一个 `Client` 会占用一个登录数。 -## 最小成功路径 +### 构造函数：账号参数方式 -1. 先回项目级部署文档确认登录方式、凭证来源、环境变量和部署入口。 -2. 安装 `tspytsl`。 -3. 创建 `pyTSL.Client(...)`。 -4. 调 `login()` 登录。 -5. 用 `query(...)`、`exec(...)` 或 `call(...)` 执行任务。 -6. 从返回结果里读取你真正需要的内容；常见起手是 `result.dataframe()`。 -7. 完成后显式 `logout()`。 +签名： -## 返回结果与失败处理 +```python +pyTSL.Client(user, password, ip, port, proxy_ip=None, proxy_port=None, proxy_user=None, proxy_password=None) +``` -- 常见返回会落在 `TSResultValue` 这一层；真正用之前，先确认你要的是表格、标量还是其他结构。 -- 最小起手路径可以先看 `result.dataframe()` 是否符合预期，再扩展到别的读取方式。 -- 登录、查询和退出应当成对出现；不要把长期未退出的连接当默认用法。 -- 如果失败，先检查安装、登录上下文、查询语句和返回结构，再决定是否切到异步客户端。 -- 如果还不能确认登录方式、凭证来源或返回结构，不继续扩展接入代码，先回项目级部署文档和官方接口文档。 +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | -------------------------------------------------- | +| 1 | `user` | 是 | `str` | 天软账号 | +| 2 | `password` | 是 | `str` | 天软账号密码；支持用客户端工具生成的加密密码字符串 | +| 3 | `ip` | 是 | `str` | 天软服务器机群地址 | +| 4 | `port` | 是 | `int` | 天软服务器访问端口 | +| 5 | `proxy_ip` | 否 | `str` | 代理服务器地址 | +| 6 | `proxy_port` | 否 | `int` | 代理服务器端口 | +| 7 | `proxy_user` | 否 | `str` | 代理服务器验证账号 | +| 8 | `proxy_password` | 否 | `str` | 代理服务器验证密码 | -## 示例（Python） +常见服务器： -示例里的 `"user"` / `"password"` 只表示调用外形，不代表项目里的真实登录方式或凭证来源。 +| 服务器 | `ip` | `port` | 默认服务节点 | +| ---------------- | ------------------------- | -------------- | ------------------- | +| 深圳服务器 | `"tsl.tinysoft.com.cn"` | `443` 或 `444` | `"正式版"` | +| 武汉服务器 | `"wh.tinysoft.com.cn"` | `443` 或 `444` | `"Default Service"` | +| 深圳新节点服务器 | `"sznew.tinysoft.com.cn"` | `4433` | `"Default Service"` | -下面代码只表示调用外形；真实登录方式、凭证和查询来源以项目文档为准。 +### 构造函数：ini 文件方式 + +签名： + +```python +pyTSL.Client(ini_file) +``` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------ | +| 1 | `ini_file` | 是 | `str` | 连接服务器信息 `.ini` 文件的绝对路径 | + +ini 文件字段： + +```ini +user= +password= +ip= +port= +proxy_user= +proxy_password= +proxy_ip= +proxy_port= +``` + +路径含中文并报找不到文件时，可把路径按 GBK 编码后传入。 + +### Client 方法总表 + +| 方法 | 签名 | 返回 | 用途 | +| ----------------- | --------------------------------------- | --------------- | ------------------------------------------- | +| `login` | `login()` | `bool` | 登录天软服务器；成功 `1`，失败 `0` | +| `last_error` | `last_error()` | `list` | 最近一次错误，结构为 `[错误代码, 错误信息]` | +| `logout` | `logout()` | `int` | 断开连接；成功 `0` | +| `exec` | `exec(code, **kwargs)` | `TSResultValue` | 执行 TSL 代码串 | +| `call` | `call(funcname, *args, **kwargs)` | `TSResultValue` | 调用 TSL 函数 | +| `query` | `query(**kwargs)` | `TSResultValue` | 提取行情数据 | +| `list_bgrun` | `list_bgrun()` | `list` | 列出委托执行任务 | +| `stop_bgrun` | `stop_bgrun(handle)` | `int` | 停止指定委托执行任务；成功 `1` | +| `admin` | `admin(**kwargs)` | `str` | 执行天软客户端任务管理命令 | +| `set_callback` | `set_callback(function)` | 未说明 | 设置 `rdo2` 回调函数 | +| `default_service` | `default_service(service)` | `str` | 设置或返回默认服务节点 | +| `server_list` | `server_list()` | `list` | 返回服务节点列表 | +| `download_list` | `download_list(type, timeout=0)` | `list` | 下载指定类型列表 | +| `download` | `download(type, key, ver=0, timeout=0)` | `list` | 下载指定关键字内容 | +| `upload` | `upload(type, key, data, timeout=0)` | `list` | 上传数据至指定关键字 | +| `remove` | `remove(type, key, timeout=0)` | `list` | 删除指定关键字内容 | +| `is_logined` | `is_logined()` | `bool` | 已登录返回 `1`，未登录返回 `0` | +| `is_closed` | `is_closed()` | `bool` | 已断开返回 `1`，未断开返回 `0` | + +### `exec(code, **kwargs)` + +执行 TSL 代码串。结果通过 `TSResultValue` 读取。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------- | +| 1 | `code` | 是 | `str` | 要执行的 TSL 代码串 | +| 2 | `**kwargs` | 否 | 见下表 | 执行上下文属性 | + +### `call(funcname, *args, **kwargs)` + +调用 TSL 函数。`*args` 会自动转换常见 Python 类型到 TSL 类型。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| 1 | `funcname` | 是 | `str` | 函数名 | +| 2 | `*args` | 否 | `float` / `int` / `bool` / `str` / `bytes` / `list` / `dict` / `tuple` / `pandas.DataFrame` / `numpy.ndarray` / 日期时间类型 | 传给 TSL 函数的位置参数 | +| 3 | `**kwargs` | 否 | 见下表 | 执行上下文属性，可通过 `code` 传入临时函数定义 | + +Python 到 TSL 的自动转换： + +| Python 类型 | TSL 类型 | +| ----------------------------------------------------------------------------- | -------------------- | +| `float` / `numpy.float32` / `numpy.float64` / `datetime` / `numpy.datetime64` | `real` / `tdatetime` | +| `bool` / `int` / `numpy.int32` / `numpy.int64` | `int` | +| `str` / `bytes` | `str` | +| `list` / `dict` / `tuple` / `pandas.DataFrame` / `numpy.ndarray` | `array` | + +### `exec` / `call` 共享 `kwargs` + +| 参数名 | 必填 | 接收类型 | 默认值 | 说明 | +| ------------ | ---- | ------------------------------------ | ---------------- | ------------------------------------------------------------------------------------ | +| `stock` | 否 | `str` | `None` | 当前股票代码，如 `"SZ000002"` | +| `cycle` | 否 | `str` | `"日线"` | 当前周期 | +| `time` | 否 | `datetime` / `int` / `float` / `str` | 今天 | 当前时间，如 `datetime(2019, 10, 1)`、`43739.0`、`20191001`、`"2019-10-01 14:03:01"` | +| `rate` | 否 | `int` | `0` | 复权方式：`0` 不复权，`1` 比例复权，`2` 复杂复权 | +| `rateday` | 否 | `datetime` / `int` / `float` / `str` | `0` | 复权基准日：`0` 最后交易日，`-1` 上市日，其他值为指定基准日 | +| `precision` | 否 | `int` | `-1` | 浮点数精度 | +| `viewpoint` | 否 | `datetime` / `int` / `float` / `str` | `0` | 仿真时点 | +| `code` | 否 | `str` | `None` | 临时定义函数代码段，不必先保存到服务器 | +| `service` | 否 | `str` | 由登录服务器决定 | 指定执行服务节点 | +| `timeout` | 否 | `int` | `None` | 超时，单位毫秒；`None` 表示无超时时限 | +| `bgrun` | 否 | `int` | `0` | 委托执行；`1` 表示委托执行 | +| `resultname` | 否 | `str` | `None` | 仅 `exec` 支持；`bgrun=1` 时用于指定委托保存的结果集名称 | +| `reportmode` | 否 | `int` | `-1` | 报表数据规则 | +| `emptymode` | 否 | `int` | `0` | 空记录模式 | + +### `query(**kwargs)` + +提取行情数据。适合标准证券、周期、时间区间、字段查询。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------------------- | +| 1 | `**kwargs` | 是 | 见下表 | 查询属性，必须包含 `stock`、`cycle`、`begin_time`、`end_time` | + +| 参数名 | 必填 | 接收类型 | 默认值 | 说明 | +| ------------- | ---- | ------------------------------------ | ---------------- | ------------------------------------------------ | +| `stock` | 是 | `str` / 一维数组 | `None` | 当前股票代码；可指定多只股票 | +| `cycle` | 是 | `str` | `"日线"` | 当前周期 | +| `begin_time` | 是 | `datetime` / `int` / `float` / `str` | `None` | 数据开始时间 | +| `end_time` | 是 | `datetime` / `int` / `float` / `str` | `None` | 数据结束时间 | +| `fields` | 否 | `str` / `tuple` / `list` | 所有字段 | 查询字段；字符串用逗号分隔 | +| `rate` | 否 | `int` | `0` | 复权方式：`0` 不复权，`1` 比例复权，`2` 复杂复权 | +| `rateday` | 否 | `datetime` / `int` / `float` / `str` | `0` | 复权基准日 | +| `precision` | 否 | `int` | `-1` | 浮点数精度 | +| `viewpoint` | 否 | `datetime` / `int` / `float` / `str` | `0` | 仿真时点 | +| `service` | 否 | `str` | 由登录服务器决定 | 指定执行服务节点 | +| `timeout` | 否 | `int` | `None` | 超时，单位毫秒 | +| `cyclefilter` | 否 | `int` | `0` | 周期过滤器以及集合竞价分离器 | + +### 委托、任务管理和服务节点方法 + +#### `list_bgrun()` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------- | +| 无 | 无 | 否 | 无 | 不接收参数 | + +返回 `["+OK", [委托任务1], ...]`。委托任务结构为 `[handle, 执行的函数名, 开始执行时间, 已运行时间]`。 + +#### `stop_bgrun(handle)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------ | +| 1 | `handle` | 是 | `float` | 委托任务编号 | + +返回整数，成功为 `1`。 + +#### `admin(**kwargs)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ----------------------------------------- | +| 1 | `**kwargs` | 是 | `str` | 天软客户端任务管理命令，如 `"oa"`、`"ou"` | + +返回对应指令的查询信息。 + +#### `set_callback(function)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ----------------- | -------------------- | +| 1 | `function` | 是 | Python 可调用对象 | 设置 `rdo2` 回调函数 | + +`rdo2 callback(...)` 调用时会回到 Python 函数；不要把已经通过 `register_proc` 注册过的函数再当作该回调。 + +#### `default_service(service)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | ---------------------------------------------- | +| 1 | `service` | 否 | `str` | 为空时返回当前服务节点；非空时设置当前服务节点 | + +返回字符串，内容为服务节点。 + +#### `server_list()` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------- | +| 无 | 无 | 否 | 无 | 不接收参数 | + +返回服务节点列表。 + +### 下载、上传和删除 + +#### 类型取值 + +| 类型值 | 可用于 | 说明 | +| -------- | -------------------------------------------------- | ---------------- | +| `0x2001` | `download_list` / `download` | 系统板块 | +| `0x2002` | `download_list` / `download` / `upload` / `remove` | 用户板块 | +| `0x5001` | `download_list` / `download` | 系统基本面表描述 | +| `0x6001` | `download_list` / `download` / `upload` / `remove` | 用户函数 | +| `0x6002` | `download_list` / `download` | 共享函数 | +| `0x6003` | `download_list` / `download` | 系统公用函数 | +| `0x6004` | `download_list` / `download` | 系统函数 | +| `0x8001` | `download_list` / `download` / `upload` / `remove` | 用户数据表 | + +#### `download_list(type, timeout=0)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | --------------------------------------- | +| 1 | `type` | 是 | `int` | 指定类型 | +| 2 | `timeout` | 否 | `int` | 超时，单位毫秒；默认 `0` 表示无超时限制 | + +返回长度为 2 的列表。无错误返回 `[0, 结果列表]`，有错误返回 `[错误代码, 错误信息]`。结果列表中的单项结构为 `[关键字, 版本, 修改时间]`。 + +#### `download(type, key, ver=0, timeout=0)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | --------------------------------------- | +| 1 | `type` | 是 | `int` | 指定类型 | +| 2 | `key` | 是 | `str` | 关键字，如函数名、板块名 | +| 3 | `ver` | 否 | `int` | 关键字版本；默认 `0` 表示最新版本 | +| 4 | `timeout` | 否 | `int` | 超时，单位毫秒；默认 `0` 表示无超时限制 | + +无错误返回 `[0, 结果]`，有错误返回 `[错误代码, 错误信息]`。结果结构包含： + +| 键 | 说明 | +| ---------------- | -------------------------------------------------------- | +| `"data"` | 关键字内容，TSL 流格式，可用 `pyTSL.DecodeStream()` 转换 | +| `"LastModified"` | 版本 | +| `"LastTime"` | 修改时间 | + +#### `upload(type, key, data, timeout=0)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | --------------------------------------- | +| 1 | `type` | 是 | `int` | 只支持 `0x2002`、`0x6001`、`0x8001` | +| 2 | `key` | 是 | `str` | 关键字，如函数名、板块名、用户数据名 | +| 3 | `data` | 是 | `Any` | 上传至关键字的数据 | +| 4 | `timeout` | 否 | `int` | 超时，单位毫秒；默认 `0` 表示无超时限制 | + +无错误返回 `[0, 结果]`，有错误返回 `[错误代码, 错误信息]`。 + +#### `remove(type, key, timeout=0)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | --------------------------------------- | +| 1 | `type` | 是 | `int` | 只支持 `0x2002`、`0x6001`、`0x8001` | +| 2 | `key` | 是 | `str` | 关键字，如函数名、用户数据名 | +| 3 | `timeout` | 否 | `int` | 超时，单位毫秒；默认 `0` 表示无超时限制 | + +无错误返回 `[0, 结果]`，有错误返回 `[错误代码, 错误信息]`。 + +## `pyTSL.AsyncClient` + +异步客户端，适用于 Python `asyncio`。与 `Client` 一样会占用登录数；异步任务数量受账号并发数限制，普通账号常见并发数为 5，应保留资源。 + +构造方式同 `Client`： + +```python +pyTSL.AsyncClient("user", "password", "tsl.tinysoft.com.cn", 443) +pyTSL.AsyncClient("E:\\my.ini") +``` + +也支持空构造后复用已有 `Client`： + +```python +c = pyTSL.Client("user", "password", "tsl.tinysoft.com.cn", 443) +ac = pyTSL.AsyncClient() +ac.c = c +``` + +| 方法 | 签名 | 返回 | 参数来源 | +| --------------- | --------------------------------------- | --------------- | -------------------------------- | +| `login` | `login()` | `bool` | 无参数；成功 `1`，失败 `0` | +| `logout` | `logout()` | `int` | 无参数；成功 `0` | +| `exec` | `exec(code, **kwargs)` | `TSResultValue` | 同 `Client.exec` | +| `call` | `call(funcname, *args, **kwargs)` | `TSResultValue` | 同 `Client.call` | +| `query` | `query(**kwargs)` | `TSResultValue` | 同 `Client.query` | +| `admin` | `admin(**kwargs)` | `str` | 同 `Client.admin` | +| `download_list` | `download_list(type, timeout=0)` | `list` | 同 `Client.download_list` | +| `download` | `download(type, key, ver=0, timeout=0)` | `list` | 同 `Client.download` | +| `upload` | `upload(type, key, data, timeout=0)` | `list` | 同 `Client.upload` | +| `remove` | `remove(type, key, timeout=0)` | `list` | 同 `Client.remove` | +| `task_list` | `task_list()` | `list` | 返回异步任务列表 | +| `task_cancel` | `task_cancel(task)` | `int` | 取消异步任务；成功 `1`，失败 `0` | + +最小异步示例： + +```python +import asyncio +import pyTSL +from datetime import datetime + +async def main(): + c = pyTSL.AsyncClient("user", "password", "tsl.tinysoft.com.cn", 443) + try: + if await c.login() == 0: + raise RuntimeError("login failed") + r = await c.exec("return close();", stock="SZ000002", time=datetime(2024, 7, 30)) + if r.error(): + raise RuntimeError(r.message()) + return r.value() + finally: + await c.logout() + +value = asyncio.run(main()) +``` + +## `pyTSL.async_util` + +`async_util` 把普通 `Client` 的操作包装为可 `await` 的函数。所有函数第一个参数都是 `pyTSL.Client` 实例。 + +| 函数 | 签名 | 返回 | 对应同步方法 | +| --------------------- | ------------------------------------------------ | --------------- | ---------------------- | +| `async_login` | `async_login(c)` | `bool` | `c.login()` | +| `async_logout` | `async_logout(c)` | `int` | `c.logout()` | +| `async_exec` | `async_exec(c, code, **kwargs)` | `TSResultValue` | `c.exec(...)` | +| `async_call` | `async_call(c, funcname, *args, **kwargs)` | `TSResultValue` | `c.call(...)` | +| `async_query` | `async_query(c, **kwargs)` | `TSResultValue` | `c.query(...)` | +| `async_admin` | `async_admin(c, **kwargs)` | `str` | `c.admin(...)` | +| `async_download_list` | `async_download_list(c, type, timeout=0)` | `list` | `c.download_list(...)` | +| `async_download` | `async_download(c, type, key, ver=0, timeout=0)` | `list` | `c.download(...)` | +| `async_upload` | `async_upload(c, type, key, data, timeout=0)` | `list` | `c.upload(...)` | +| `async_remove` | `async_remove(c, type, key, timeout=0)` | `list` | `c.remove(...)` | + +## pyTSL 全局方法 + +### `DatetimeToDouble(datetime, timezone=8)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------------------------------- | -------------------------- | +| 1 | `datetime` | 是 | `datetime.date` / `datetime.datetime` | Python 日期或日期时间 | +| 2 | `timezone` | 否 | `int` | 时区，默认 `8`，即北京时间 | + +返回 TSL 的时间类型 `TDateTime`，精度到毫秒。 + +### `DoubleToDatetime(t)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------------------- | ------------ | +| 1 | `t` | 是 | `TDateTime` / `float` | TSL 时间类型 | + +返回 Python `datetime`，精度到毫秒。 + +### `DataFrameDiff(df1, df2)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ------------------ | ------------------------------------- | +| 1 | `df1` | 是 | `pandas.DataFrame` | 第一个 DataFrame，结构需与 `df2` 一致 | +| 2 | `df2` | 是 | `pandas.DataFrame` | 第二个 DataFrame，结构需与 `df1` 一致 | + +返回两个 DataFrame 的不同数据以及行列位置。 + +### `EncodeStream(obj)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ----------- | -------------------- | +| 1 | `obj` | 是 | Python 变量 | 要转换的 Python 对象 | + +返回 TSL 流格式。 + +### `DecodeStream(bytes, parse_date=False)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------- | ------------------------------------ | +| 1 | `bytes` | 是 | TSL 流格式 | 要解码的 TSL 流 | +| 2 | `parse_date` | 否 | `bool` / `list` / `tuple` | 是否把日期字段转成 Python `datetime` | + +`parse_date` 取值： + +| 取值 | 说明 | +| ------------------------ | ------------------------------------------------------- | +| `False` | 默认值，不转换，TSL `TDateTime` 保持实数 | +| `True` | 将 TSL `TDateTime` 或日期字符串转换为 Python `datetime` | +| `["date"]` / `("date",)` | 只转换指定字段 | + +返回 Python 变量。 + +### `register_proc(funcname1, funcname2)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ----------------- | ------------------------ | +| 1 | `funcname1` | 是 | `str` | TSL 本地调用时使用的名称 | +| 2 | `funcname2` | 是 | Python 可调用对象 | Python 中定义的函数 | + +将 Python 函数注册为天软函数，可在交互语句中用 `rdo2` 调用。`importfile` 和 `exportfile` 已有默认实现，不要注册同名函数。 + +### `DataFrameToTSArray(DataFrame)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------------ | ------------------ | +| 1 | `DataFrame` | 是 | `pandas.DataFrame` | 要转换的 DataFrame | + +返回 TSL 的 `array` 数据结构。`Client.call()` 传入 DataFrame 时也会自动转换。 + +### `start_network_threads(n)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------- | +| 1 | `n` | 是 | `int` | 额外启动的网络 IO 处理线程数 | + +返回 `None`。pyTSL 默认有 1 个线程处理网络 IO；多连接场景可以增加线程。 + +## `pyTSL.Batch` + +用于并发执行多个天软任务，只占用一个登录数。并发数受账号资源限制，不是越大越好；普通账号常见并发数为 5，建议保守设置。 + +### 构造函数 + +签名： + +```python +pyTSL.Batch(parallel=5, reconnect=0) +``` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ---------------------------------------------------- | +| 1 | `parallel` | 否 | `int` | 并行任务数，默认 `5` | +| 2 | `reconnect` | 否 | `int` | 是否重新连接；`0` 不重新连接，`1` 重新连接，默认 `0` | + +### Batch 方法 + +| 方法 | 签名 | 返回 | 说明 | +| --------- | --------------------------------------------- | ------ | ------------------------------------------------ | +| `exec` | `exec(client, code, **kwargs)` | `list` | 并发执行 TSL 代码串 | +| `call` | `call(client, functionname, *args, **kwargs)` | `list` | 并发调用 TSL 函数 | +| `query` | `query(client, **kwargs)` | `list` | 并发查询行情数据 | +| `__len__` | `__len__()` | `int` | 通过 `len(iter(batch))` 返回迭代器中剩余元素个数 | + +`Batch.exec()` 参数： + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ---------------- | ------------------------------ | +| 1 | `client` | 是 | `pyTSL.Client` | 已构造的客户端实例 | +| 2 | `code` | 是 | `str` | TSL 代码串 | +| 3 | `**kwargs` | 否 | 见 `Client.exec` | 不支持委托执行；额外支持 `key` | + +`Batch.call()` 参数： + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------------- | ------------------------------ | +| 1 | `client` | 是 | `pyTSL.Client` | 已构造的客户端实例 | +| 2 | `functionname` | 是 | `str` | TSL 函数名 | +| 3 | `*args` | 否 | 见 `Client.call` | 传给 TSL 函数的位置参数 | +| 4 | `**kwargs` | 否 | 见 `Client.call` | 不支持委托执行；额外支持 `key` | + +`Batch.query()` 参数： + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ----------------- | ------------------------------ | +| 1 | `client` | 是 | `pyTSL.Client` | 已构造的客户端实例 | +| 2 | `**kwargs` | 是 | 见 `Client.query` | 不支持委托执行；额外支持 `key` | + +`key` 参数： + +| 参数名 | 必填 | 接收类型 | 默认值 | 说明 | +| ------ | ---- | -------- | ------ | ------------------------------------------------- | +| `key` | 否 | `str` | `""` | 标识每个任务；也可通过返回的 `Task.key(str)` 设置 | + +返回结构： + +| 情况 | 返回 | +| -------- | --------------------- | +| 提交成功 | `[1, Task对象]` | +| 提交失败 | `[0, 错误信息字符串]` | + +结果读取： + +```python +for r in iter(batch): + print(r.key(), r.value()) +``` + +遍历时每个 `r` 是 `TSResultValue`。 + +## `pyTSL.Task` + +`Batch` 执行任务的标识。 + +| 方法 | 签名 | 返回 | 说明 | +| ----- | --------------- | ----- | ------------------------------------------ | +| `id` | `id()` | `int` | 返回任务 ID | +| `key` | `key(str=None)` | `str` | 有参数时设置关键字；无参数时返回当前关键字 | + +## `TSResultValue` + +`Client.exec()`、`Client.call()`、`Client.query()`、异步方法和 `Batch` 迭代结果都会返回或产出 `TSResultValue`。 + +| 方法 | 签名 | 返回 | 说明 | +| ----------- | ------------------------- | -------------------- | --------------------------------------- | +| `error` | `error()` | `int` | `0` 表示无错误，非 `0` 表示出错 | +| `message` | `message()` | `str` | 有错误时返回错误信息，无错误时为空 | +| `value` | `value(parse_date=False)` | `list` / 标量 / 对象 | 返回结果值 | +| `dataframe` | `dataframe()` | `pandas.DataFrame` | 输出 DataFrame；相当于把 `value()` 转表 | +| `stream` | `stream()` | TSL 流格式 | 返回 TSL 流格式结果 | +| `stn` | `stn()` | `str` | 返回 TSL STN 格式结果 | +| `key` | `key()` | `str` | 返回任务关键字，配合 `Batch` 使用 | +| `cancelled` | `cancelled()` | `bool` | 返回任务是否被取消 | + +`value(parse_date=...)`： + +| 取值 | 说明 | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `False` | 默认值，不转换日期，TSL `TDateTime` 保持实数 | +| `True` | 将一维数组或单个值中的 TSL 日期时间、日期字符串转换为 Python `datetime`；`query()` 的默认行为是转换日期 | +| `["date1", "date2"]` / `("date1", "date2")` | 对二维数组或表格中的指定日期字段做转换 | + +推荐错误处理： + +```python +r = c.exec("return 1 + 1;") +if r.error(): + raise RuntimeError(r.message()) +value = r.value() +``` + +## `pyTSL.Const` + +常量模块包含周期、行情字段、文件导入导出类型和文件读写类型。导入方式： + +```python +from pyTSL.Const import * +``` + +### 周期常量 + +| 常量 | 对应值 | +| ------------- | ---------------- | +| `cy_month` | `"月线"` | +| `cy_day` | `"日线"` | +| `cy_week` | `"周线"` | +| `cy_quarter` | `"季线"` | +| `cy_halfyear` | `"半年线"` | +| `cy_1m` | `"1分钟线"` | +| `cy_2m` | `"2分钟线"` | +| `cy_3m` | `"3分钟线"` | +| `cy_5m` | `"5分钟线"` | +| `cy_10m` | `"10分钟线"` | +| `cy_15m` | `"15分钟线"` | +| `cy_20m` | `"20分钟线"` | +| `cy_30m` | `"30分钟线"` | +| `cy_40m` | `"40分钟线"` | +| `cy_60m` | `"60分钟线"` | +| `cy_120m` | `"120分钟线"` | +| `cy_detail` | `"成交明细"` | +| `cy_halfs` | `"半秒线"` | +| `cy_1s` | `"1秒线"` | +| `cy_2s` | `"2秒线"` | +| `cy_3s` | `"3秒线"` | +| `cy_4s` | `"4秒线"` | +| `cy_5s` | `"5秒线"` | +| `cy_6s` | `"6秒线"` | +| `cy_10s` | `"10秒线"` | +| `cy_12s` | `"12秒线"` | +| `cy_15s` | `"15秒线"` | +| `cy_20s` | `"20秒线"` | +| `cy_30s` | `"30秒线"` | +| `cy_f30m` | `"期货30分钟线"` | +| `cy_f60m` | `"期货60分钟线"` | + +### 行情字段常量 + +| 常量 | 字段值 | 说明 | +| ----------------------- | ------------------------- | -------------------- | +| `STOCKID` | `"StockID"` | 股票代码 | +| `STOCKNAME` | `"StockName"` | 股票名称 | +| `DATE` | `"date"` | 当前时间 | +| `PRICE` | `"price"` | 价格 | +| `CLOSE` | `"close"` | 收盘价 | +| `OPEN` | `"open"` | 开盘价 | +| `HIGH` | `"high"` | 最高价 | +| `LOW` | `"low"` | 最低价 | +| `VOL` | `"vol"` | 成交量 | +| `AMOUNT` | `"amount"` | 成交金额 | +| `CJBS` | `"cjbs"` | 成交笔数 | +| `YCLOSE` | `"yclose"` | 上次价 | +| `SYL1` | `"syl1"` | 市盈率 1 | +| `SYL2` | `"syl2"` | 市盈率 2 | +| `BUY1` | `"buy1"` | 买一价 | +| `BUY2` | `"buy2"` | 买二价 | +| `BUY3` | `"buy3"` | 买三价 | +| `BUY4` | `"buy4"` | 买四价 | +| `BUY5` | `"buy5"` | 买五价 | +| `SALE1` | `"sale1"` | 卖一价 | +| `SALE2` | `"sale2"` | 卖二价 | +| `SALE3` | `"sale3"` | 卖三价 | +| `SALE4` | `"sale4"` | 卖四价 | +| `SALE5` | `"sale5"` | 卖五价 | +| `BC1` | `"bc1"` | 买一量 | +| `BC2` | `"bc2"` | 买二量 | +| `BC3` | `"bc3"` | 买三量 | +| `BC4` | `"bc4"` | 买四量 | +| `BC5` | `"bc5"` | 买五量 | +| `SC1` | `"sc1"` | 卖一量 | +| `SC2` | `"sc2"` | 卖二量 | +| `SC3` | `"sc3"` | 卖三量 | +| `SC4` | `"sc4"` | 卖四量 | +| `SC5` | `"sc5"` | 卖五量 | +| `WB` | `"wb"` | 委比 | +| `LB` | `"lb"` | 量比 | +| `ZMM` | `"zmm"` | 买卖标识 | +| `BUY_VOL` | `"buy_vol"` | 主买量 | +| `BUY_AMOUNT` | `"buy_amount"` | 主买金额 | +| `SALE_VOL` | `"sale_vol"` | 主卖量 | +| `SALE_AMOUNT` | `"sale_amount"` | 主卖金额 | +| `W_BUY` | `"w_buy"` | 委买 | +| `W_SALE` | `"w_sale"` | 委卖 | +| `SECTIONAL_BUY_VOL` | `"sectional_buy_vol"` | 时点当日累计主买量 | +| `SECTIONAL_BUY_AMOUNT` | `"sectional_buy_amount"` | 时点当日累计主买金额 | +| `SECTIONAL_SALE_VOL` | `"sectional_sale_vol"` | 时点当日累计主卖量 | +| `SECTIONAL_SALE_AMOUNT` | `"sectional_sale_amount"` | 时点当日累计主卖金额 | +| `SECTIONAL_W_BUY` | `"sectional_w_buy"` | 时点当日累计委买 | +| `SECTIONAL_W_SALE` | `"sectional_w_sale"` | 时点当日累计委卖 | +| `SECTIONAL_YCLOSE` | `"sectional_yclose"` | 前日收盘 | +| `SECTIONAL_OPEN` | `"sectional_open"` | 时点当日开盘 | +| `SECTIONAL_HIGH` | `"sectional_high"` | 时点当日最高 | +| `SECTIONAL_LOW` | `"sectional_low"` | 时点当日最低 | +| `SECTIONAL_VOL` | `"sectional_vol"` | 时点当日累计成交量 | +| `SECTIONAL_AMOUNT` | `"sectional_amount"` | 时点当日累计成交金额 | +| `SECTIONAL_CJBS` | `"sectional_cjbs"` | 时点当日累计成交笔数 | +| `SECTIONAL_WB` | `"sectional_wb"` | 时点当日累计委比 | + +### 文件导入导出类型常量 + +| 常量 | 值 | 说明 | +| ---------- | --- | --------------------------- | +| `ftCSV` | `0` | 逗号分割文件类型 | +| `ftXLS` | `1` | Excel 文件类型 | +| `ftStream` | `2` | 天软对象流文件类型 | +| `ftString` | `3` | 天软对象字符串文件类型 | +| `ftADO` | `4` | ADO 文件类型 | +| `ftXML` | `5` | XML 文件类型 | +| `ftXLS2` | `6` | 支持多表头的 Excel 文件类型 | +| `ftXLS3` | `7` | Excel 文件类型 | +| `ftDBF` | `8` | DBF 文件类型 | + +### 文件读写类型常量 + +| 常量 | 值 | 说明 | +| ---------- | --- | ---------------- | +| `rwByte` | `0` | 字节流读写类型 | +| `rwInt` | `1` | 整数流读写类型 | +| `rwReal` | `2` | 实数流读写类型 | +| `rwStr` | `3` | 字符串流读写类型 | +| `rwObj` | `4` | 对象流读写类型 | +| `rwRaw` | `5` | 原始读写类型 | +| `rwBinary` | `6` | 二进制读写类型 | + +## `query` 周期与字段 + +### 周期字符串 + +| 分类 | 可用值 | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 低频 | `"日线"`、`"周线"`、`"月线"`、`"季线"`、`"半年线"`、`"年线"` | +| 高频 | `"1分钟线"`、`"2分钟线"`、`"3分钟线"`、`"5分钟线"`、`"10分钟线"`、`"15分钟线"`、`"20分钟线"`、`"30分钟线"`、`"40分钟线"`、`"60分钟线"`、`"120分钟线"` | +| 超高频 | `"成交明细"`、`"半秒线"`、`"1秒线"`、`"2秒线"`、`"3秒线"`、`"4秒线"`、`"5秒线"`、`"6秒线"`、`"10秒线"`、`"12秒线"`、`"15秒线"`、`"20秒线"`、`"30秒线"` | +| 其他 | `"任意周期"`、`"期货30分钟线"`、`"期货60分钟线"` | + +### 低频字段 + +| 字段 | 数据类型 | 名称 | 说明 | +| ----------- | ---------- | -------- | ------------------------------------------------------------------ | +| `StockID` | `string` | 代码 | 股票 ID | +| `StockName` | `string` | 名称 | 股票名称 | +| `date` | `datetime` | 日期 | 当前时间 | +| `price` | `real` | 最新价 | 该周期内最后一笔成交价 | +| `open` | `real` | 开盘价 | 交易所公布的开盘价 | +| `close` | `real` | 收盘价 | 交易所公布的收盘价 | +| `high` | `real` | 最高价 | 周期内最高价 | +| `low` | `real` | 最低价 | 周期内最低价 | +| `vol` | `real` | 成交量 | 周期内成交量；股票单位为股，基金单位为份，期货和期权单位为合约数量 | +| `amount` | `real` | 成交金额 | 周期内成交金额 | +| `cjbs` | `real` | 成交笔数 | 股票为成交笔数；期货/期权可表示持仓变动量，日线表示当日持仓量 | +| `yclose` | `real` | 系统昨收 | 交易所发布的考虑分红送股后的价格 | +| `syl1` | `real` | 市盈率 1 | 期货/期权日线表示当日结算价；其他通常为 `0` | +| `syl2` | `real` | 市盈率 2 | 期货/期权表示昨日结算价；ETF/LOF 表示时点净值；其他通常为 `0` | + +### 高频与 Level1 字段 + +| 字段 | 数据类型 | 名称 | 说明 | +| ----------------------- | ---------- | -------------------- | --------------------------------------------------------------------------------------------------- | +| `StockID` | `string` | 代码 | 股票 ID | +| `StockName` | `string` | 名称 | 股票名称 | +| `date` | `datetime` | 时间 | 当前时间 | +| `price` | `real` | 价格 | 交易明细为该时间点最后一笔成交价；其他为该周期最后一笔成交价 | +| `vol` | `real` | 成交量 | 周期内成交量；分钟周期表示该分钟成交量，不是开盘累计 | +| `amount` | `real` | 成交金额 | 周期内成交金额；分钟周期表示该分钟成交金额 | +| `cjbs` | `real` | 成交笔数 | 股票为成交笔数；期货/期权为周期内持仓变动量 | +| `yclose` | `real` | 上次价 | 上一周期的收盘价 | +| `syl1` | `real` | 市盈率 1 | 期货/期权分钟线或秒线中，当日结算价存储在当日最后成交记录中；其他通常为 `0` | +| `syl2` | `real` | 市盈率 2 | 期货/期权为昨日结算价；ETF/LOF 为时点净值；其他通常为 `0` | +| `buy1` 至 `buy5` | `real` | 买一价至买五价 | 期货没有 `buy2` 至 `buy5` | +| `sale1` 至 `sale5` | `real` | 卖一价至卖五价 | 期货没有 `sale2` 至 `sale5` | +| `bc1` 至 `bc5` | `int` | 买一量至买五量 | 对应价位的委买量 | +| `sc1` 至 `sc5` | `int` | 卖一量至卖五量 | 对应价位的委卖量 | +| `wb` | `real` | 委比 | 公式为委买/委卖 | +| `lb` | `int` | 量比 | 秒线取交易明细最后一笔；1 分钟线按过去 5 日均量和当日累计开市时间计算；其他分钟线取周期内最后一分钟 | +| `zmm` | `int` | 买卖标识 | 交易明细中 `1` 主买，`2` 主卖，`3` 集合竞价/涨停/跌停等；非交易明细无意义 | +| `buy_vol` | `real` | 主买量 | 主买成交量加买卖标识为 `3` 的成交量一半 | +| `buy_amount` | `real` | 主买金额 | 主买成交金额加买卖标识为 `3` 的成交金额一半 | +| `sale_vol` | `real` | 主卖量 | 主卖成交量加买卖标识为 `3` 的成交量一半 | +| `sale_amount` | `real` | 主卖金额 | 主卖成交金额加买卖标识为 `3` 的成交金额一半 | +| `w_buy` | `real` | 委买 | 一个周期内的委买量 | +| `w_sale` | `real` | 委卖 | 一个周期内的委卖量 | +| `sectional_buy_vol` | `real` | 时点当日累计主买量 | 从开盘到当前时间的主买量之和 | +| `sectional_buy_amount` | `real` | 时点当日累计主买金额 | 从开盘到当前时间的主买金额之和 | +| `sectional_sale_vol` | `real` | 时点当日累计主卖量 | 从开盘到当前时间的主卖量之和 | +| `sectional_sale_amount` | `real` | 时点当日累计主卖金额 | 从开盘到当前时间的主卖金额之和 | +| `sectional_w_buy` | `real` | 时点当日累计委买 | 从开盘到当前时间的委买量之和 | +| `sectional_w_sale` | `real` | 时点当日累计委卖 | 从开盘到当前时间的委卖量之和 | +| `sectional_yclose` | `real` | 前日收盘 | 上一交易日收盘价，与 `yclose` 的“上一周期收盘价”不同 | +| `sectional_open` | `real` | 时点当日开盘 | 今天开盘价 | +| `sectional_high` | `real` | 时点当日最高 | 从开盘到当前时间的最高价 | +| `sectional_low` | `real` | 时点当日最低 | 从开盘到当前时间的最低价 | +| `sectional_vol` | `real` | 时点当日累计成交量 | 从开盘到当前时间成交量之和 | +| `sectional_amount` | `real` | 时点当日累计成交金额 | 从开盘到当前时间成交金额之和 | +| `sectional_cjbs` | `int` | 时点当日累计成交笔数 | 股票为成交笔数；股指期货/期权可表示市场现有持仓量 | +| `sectional_wb` | `real` | 时点当日累计委比 | 当日累计委买/当日累计委卖 | + +## 数据类型转换规则 + +| TSL | Python | TSL 转 Python | Python 转 TSL | +| ------------ | ------------------ | --------------------------- | ---------------------------- | +| 数值型 | `float` / `int` | 自动转换 | 自动转换 | +| 字符串 | `str` | 自动转换 | 自动转换 | +| 布尔型 | `bool` / `int` | 自动转换 | 自动转换为整数语义 | +| 日期时间实数 | `datetime` | `pyTSL.DoubleToDatetime()` | `pyTSL.DatetimeToDouble()` | +| `array` | `pandas.DataFrame` | `TSResultValue.dataframe()` | `pyTSL.DataFrameToTSArray()` | +| TSL 流 | Python 变量 | `pyTSL.DecodeStream()` | `pyTSL.EncodeStream()` | + +TSL 日期时间是一个实数，例如 `20240730.145533T` 对应日期和时间；`Client.call()` 中的日期时间参数可直接传 Python `datetime`，pyTSL 会自动转换。 + +## `pyTSLPy` 兼容模块 + +`pyTSLPy` 是用 `pyTSL` 实现旧版 `TSLPy3.pyd` 功能的兼容模块。安装命令： + +```bash +pip install pyTSLPy +``` + +迁移入口： + +```python +import pyTSLPy as ts +``` + +支持情况： + +| 旧接口 | 支持情况 | 说明 | +| ----------------------------------------------- | ---------- | --------------------------------------------- | +| `DefaultConnectAndLogin` | 支持 | 通过配置文件登录 | +| `ConnectServer` | 支持 | 连接服务器 | +| `LoginServer` | 支持 | 登录用户 | +| `Disconnect` | 支持 | 断开连接 | +| `Logined` | 支持 | 判断是否连接 | +| `SetService` | 支持 | 设置服务器类型 | +| `GetService` | 支持 | 获得服务器类型 | +| `RemoteExecute` | 不完全支持 | 不支持本地交互 | +| `RemoteCallFunc` | 不完全支持 | 不支持本地交互 | +| `EncodeDate` / `EncodeTime` / `EncodeDateTime` | 支持 | 在 Python 中构造 TSL 日期、时间、日期时间 | +| `DecodeDate` / `DecodeTime` / `DecodeDateTime` | 支持 | 将 TSL 日期、时间、日期时间转换到 Python 数组 | +| `SetComputeBitsOption` / `GetComputeBitsOption` | 暂不支持 | 计算服务器位数相关 | +| `SetSysParam` / `GetSysParam` | 暂不支持 | 系统参数相关 | + +如果旧代码使用本地交互函数，`pyTSLPy` 只直接支持 `ExportFile` 和 `ImportFile`；其他本地交互函数应通过 `pyTSL.register_proc()` 注册。 + +## 常见风险 + +- `import pyTSL` 失败并提示找不到模块时，Windows 先确认 VC 运行库。 +- 旧版本出现字符串对象分配错误时，先升级 pyTSL。 +- MacOS 导入报签名或权限问题时，需要按系统权限策略放开对应模块。 +- `Client(ini_file)` 路径含中文时，可传入 GBK 编码后的路径。 +- `logout()` 后再次执行 `Client` 方法可能自动重新登录；生成长期任务时遵循一次登录、多次交互。 +- pyTSL 返回值编码为 UTF-8，不需要再手动从 GBK 转码。 +- 使用代理时，代理需要支持 HTTP CONNECT；只支持应用层代理的环境需要使用官方协议网关方案。 +- Linux 旧版本在子进程场景可能出现网络线程初始化问题；应使用较新 pyTSL。 +- 非中国时区下日期时间转换有偏差时，使用 `DatetimeToDouble(datetime, timezone)` 显式指定时区。 + +## 常用示例 + +### 执行 TSL 代码串 ```python import pyTSL -c = pyTSL.Client("user", "password") -c.login() +c = pyTSL.Client("user", "password", "tsl.tinysoft.com.cn", 443) +try: + if c.login() == 0: + raise RuntimeError(c.last_error()) -result = c.query("select close from market where stock = 'SZ000001' end") -print(result.dataframe()) - -c.logout() + r = c.exec("return 1 + 1;") + if r.error(): + raise RuntimeError(r.message()) + print(r.value()) +finally: + c.logout() +``` + +### 查询行情并转 DataFrame + +```python +import pyTSL +from datetime import datetime + +c = pyTSL.Client("user", "password", "tsl.tinysoft.com.cn", 443) +try: + if c.login() == 0: + raise RuntimeError(c.last_error()) + + r = c.query( + stock=["SZ000001", "SZ000002"], + cycle="日线", + begin_time=datetime(2020, 1, 1), + end_time=datetime(2020, 3, 20), + fields="StockID,StockName,date,close", + ) + if r.error(): + raise RuntimeError(r.message()) + df = r.dataframe() +finally: + c.logout() +``` + +### 通过 `code` 临时定义并调用 TSL 函数 + +```python +import pyTSL +from datetime import date + +tsl_code = """ +function getValue(begt, endt); +begin + n := tradeDays(begt, endt); + return nday(n, "date", dateToStr(spTime()), "close", close(), "vol", vol(), "amount", amount()); +end; +""" + +c = pyTSL.Client("user", "password", "tsl.tinysoft.com.cn", 443) +try: + if c.login() == 0: + raise RuntimeError(c.last_error()) + + r = c.call("getValue", date(2019, 4, 10), date(2019, 4, 18), code=tsl_code, stock="SH000001", cycle="日线") + if r.error(): + raise RuntimeError(r.message()) + df = r.dataframe() +finally: + c.logout() +``` + +### 并发任务 + +```python +import pyTSL + +c = pyTSL.Client("user", "password", "tsl.tinysoft.com.cn", 443) +try: + if c.login() == 0: + raise RuntimeError(c.last_error()) + + batch = pyTSL.Batch(3, 0) + for stock in ["SH600028", "SH600030", "SH600036"]: + ok, task = batch.exec(c, "return stockMarketValue(20240410T);", stock=stock, key=stock) + if ok == 0: + print(task) + + for r in iter(batch): + if r.error(): + print(r.key(), r.message()) + else: + print(r.key(), r.value()) +finally: + c.logout() ``` diff --git a/docs/tsl/modules/tsbacktesting.md b/docs/tsl/modules/tsbacktesting.md index 6ea6cbe5..31519168 100644 --- a/docs/tsl/modules/tsbacktesting.md +++ b/docs/tsl/modules/tsbacktesting.md @@ -1,57 +1,615 @@ # 策略回测框架 TSBackTesting -文档类型：模块摘要 -是否可直接用于生成代码：否 -遇到不确定时跳转到：项目实际接口定义、[../finance/backtest_and_trade_flow.md](../finance/backtest_and_trade_flow.md)、[index.md](index.md) +文档类型：模块 API 事实页 +是否可直接用于生成代码：是，但策略逻辑、交易数据来源、资金参数、费用参数和实际证券池必须来自用户需求或项目上下文 +遇到不确定时：[index.md](index.md)、[pytsl_api.md](pytsl_api.md)、[../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)、项目实际接口定义 -本页不足以直接生成回测代码，只用于确认回测任务的组织顺序，以及哪些地方必须回到项目实际接口定义继续核对。 +本页整理 `TSBackTesting` 回测框架的对象模型、成员变量、必须重写的方法、交易数据字段和查询接口。它负责告诉智能体“回测框架怎么组织代码、哪些属性控制行为、哪些方法可调用”，不负责替用户创造策略、证券池、费用口径或交易信号。 -- 只要任务已经进入对象创建、交易输入入口、结果读取方法或项目封装差异，就先停止生成，直接回项目实际接口定义，不要先拼调用链。 +## 智能体 TSBackTesting 决策规则 -## Agent TSBackTesting 边界规则 +- 用户要“写回测 / 策略回测 / 回测框架 / 组合回测 / 绩效评价 / 持仓和交易结果”时，优先使用本页。 +- 用户给的是目标持仓、目标比例、调仓、选股、多因子、行业中性，默认 `FGroupType := 1`。 +- 用户给的是成交明细、成交量、成交价、动作、高频交易、真实交易回放，默认 `FGroupType := 2`。 +- 用户做期权或期权组合策略回测时，只使用数量类组合，即 `FGroupType := 2`。 +- 写代码时默认新建 `TSBackTesting` 子类并重写 `GetTradeOrder(vEndT)`；只有自定义调仓周期时才重写 `GetTimeSeries()`。 +- 初始化对象时默认使用 `new MyBackTesting()`；`CreateObject("MyBackTesting")` 只作为兼容创建方式。 +- 调用顺序固定为：声明子类 -> 设置成员变量 -> `BackTest()` -> 查询结果。 +- 不要把 `BackTest()` 当成会自动生成策略信号；策略信号必须由 `GetTradeOrder(vEndT)` 返回。 +- 不要发明股票池、费用、基准、初始资金、调仓周期、成交价来源或结果指标；这些值必须来自用户需求或项目上下文。 -- 只把本页用于识别回测框架任务顺序和常见字段类别。 -- 对象创建方式、最小必填字段、交易入口和结果接口都以项目实际接口定义为准。 -- 不要发明 `TSBackTesting` 构造方式、交易输入函数或结果读取调用链。 +## 最小代码骨架 -## 适用场景 +下面骨架用于生成最小可运行结构；策略信号、资金参数和查询指标按用户需求替换。 -- 任务已经进入“回测框架怎么配置、怎么执行、怎么读结果”。 -- 你处理的是组合型任务，而不是单纯的表达式或单次筛选。 -- 你已经知道自己要做比例类组合还是数量类组合，或者正在先判断这件事。 +```tsl +type MyBackTesting = class(TSBackTesting) +public + function GetTradeOrder(vEndT); override; +end; -## 当前只确认的范围 +function MyBackTesting.GetTradeOrder(vEndT); override; +begin + return -1; +end; -- 当前页已经确认的范围是：对象名 `TSBackTesting`、典型任务顺序、组合类型差异、常见字段组和常见结果接口类别。 -- 下面出现的字段名和结果接口名，只用于检索候选和理解类别，不是可以直接假定存在的项目接口真值。 -- 任务顺序可以先按这条主线理解：组合类型选择 → 交易数据准备 → 回测执行 → 结果查询与分析。 -- 组合类型先按两类理解：比例类组合提供目标权重，数量类组合提供成交量或成交价等交易明细。 -- 常见字段组可以先按以下几类检索： - - 时间与周期：`FBegT`、`FEndT`、`FCycle` - - 组合类型：`FGroupType` - - 资金与价格：`FIniCash`、`FPriceType`、`FPriceType1..4` - - 交易约束：`FNoZT`、`FNoDT`、`FMinVol`、`FMinAmount`、`FMaxVolPercent`、`FMaxAmountPercent` - - 费用与分红：`FFeeType`、`FlowestFeeType`、`FDividendType` - - 基准与输出：`FBMType`、`FBMDetail`、`FBMOption`、`FHFDataOutPut` -- 常见结果接口可以先按以下类别检索：`GetTimeSeries`、`GetTradeOrder`、`GetNetAssetValue` / `GetAssetData` / `GetHoldData`、`GetPercent`、`GetIRRReturn`、`ReturnBenchmark`。 +function RunBackTest(begT, endT); +begin + obj := new MyBackTesting(); + obj.FBegT := begT; + obj.FEndT := endT; + obj.FCycle := cy_day(); + obj.FGroupType := 1; + obj.FIniCash := 10000000; + obj.FIndexId := "SH000300"; + obj.BackTest(); + return array( + "资产配置": obj.GetAssetData(begT, endT), + "持仓": obj.GetHoldData(begT, endT), + "区间收益": obj.GetPortfolioReturn(begT, endT) + ); +end; +``` -## 任务骨架（非代码模板） +返回规则： -1. 先判断任务属于比例类组合还是数量类组合。 -2. 然后先回到项目实际接口定义，确认最小可用对象模型、对象创建方式、最小必填项和交易数据输入入口。 -3. 再确认起止时间、组合类型和初始资金是不是项目里的最小必填项。 -4. 执行回测。 -5. 最后先按项目实际接口定义确认结果读取链路，再读取净值时间序列、成交结果或持仓结果，再补看绩效指标。 +- `GetTradeOrder(vEndT)` 返回二维数组：表示当前时点的目标持仓或交易明细。 +- `GetTradeOrder(vEndT)` 返回空数组：比例类组合表示完全清仓。 +- `GetTradeOrder(vEndT)` 返回 `-1`：表示当前时点不调仓或不交易。 -## 不要猜的部分 +## 回测开发流程 -- 当前页没有确认的范围是：对象创建方式、最小必填字段的强制集合、交易数据入口名、最小输入结构、结果读取完整链路。 -- 如果没有项目实际接口定义，不要根据本页直接写 `new TSBackTesting()`、`SetTradeData(...)` 或其他具体调用链。 -- 各字段可选值和更细接口，以实际接口定义为准；当前页只负责告诉你要核对哪些位置，不负责补全细节。 +| 步骤 | 动作 | 决策点 | +| ---- | -------------------------------------------------------------------- | -------------------------------------- | +| 1 | 继承 `TSBackTesting` | 必须声明子类 | +| 2 | 重写 `GetTradeOrder(vEndT)` | 必须返回比例类目标持仓或数量类交易明细 | +| 3 | 设置 `FBegT`、`FEndT`、`FCycle`、`FGroupType`、`FIniCash` 等成员变量 | 按策略类型设置 | +| 4 | 调用 `BackTest()` | 触发时间序列循环、交易数据获取和清算 | +| 5 | 调用查询接口 | 读取资产、持仓、交易、收益、风险指标 | -## 跳转指引 +## 组合类别 -- 业务组织问题：见 [../finance/backtest_and_trade_flow.md](../finance/backtest_and_trade_flow.md) -- 具体字段、交易数据入口、对象创建方式和结果接口真值：回项目实际接口定义 -- 回到模块入口：见 [index.md](index.md) -- 只在需要查 TSL 通用函数归类时，才回 [../reference/index.md](../reference/index.md) +| `FGroupType` | 组合类别 | 用户提供 | 典型场景 | +| ------------ | ---------- | ------------------------------------------ | ------------------------------------------ | +| `1` | 比例类组合 | 目标持仓、方向、目标比例；成交量由框架计算 | 单因子、多因子、行业选股、配置类策略 | +| `2` | 数量类组合 | 成交明细、成交价、成交量、动作 | 技术指标、高频交易、真实交易回放、期权组合 | + +## 交易数据字段 + +### 比例类组合字段 + +`FGroupType := 1` 时，`GetTradeOrder(vEndT)` 返回目标持仓和目标比例。 + +| 字段 | 必填 | 接收类型 | 说明 | +| --------------- | ---- | ---------- | -------------------------------------------------------- | +| `截止日` | 是 | `DateTime` | 通常等于 `vEndT` | +| `代码` | 是 | 字符串 | 目标持仓证券代码 | +| `方向` | 是 | 整数 | `1` 多单；`0` 空单；缺省时按多单处理 | +| `比例(%)` | 是 | 数值 | 目标持仓比例；`FRateType <> -1` 时可由框架按配比方式计算 | +| `成交价` | 否 | 数值 | 比例类通常由 `FPriceType` 或 `FPriceRateTo0` 决定 | +| `乘数` | 否 | 数值 | 默认 `1` | +| `保证金比例(%)` | 否 | 数值 | 默认 `100` | +| `开仓费率(%)` | 是 | 数值 | 开仓费率；股票、基金常见默认 `0.1` | +| `平仓费率(%)` | 是 | 数值 | 平仓费率；期货常见默认 `0.01` | + +比例类方向值： + +| 方向 | 含义 | 常见对应 | +| ---- | ---- | ------------------------------------------------ | +| `1` | 多单 | 股票多头、融资买入、融资偿还、期货买开、期货卖平 | +| `0` | 空单 | 融券卖出、融券偿还、期货卖开、期货买平 | + +比例类规则： + +- 动作不由用户给定，框架根据目标持仓和当前持仓差值生成交易。 +- `FRateType := -1` 时，返回数据必须包含 `比例(%)`。 +- 一期比例合计不得超过 `100`。 +- 只想配置 `80%` 仓位时，直接让比例合计为 `80`；不要额外添加现金代码。 +- 完全清仓可返回空数组。 + +### 数量类组合字段 + +`FGroupType := 2` 时，`GetTradeOrder(vEndT)` 返回交易明细。 + +| 字段 | 必填 | 接收类型 | 说明 | +| ----------------- | -------- | ---------- | -------------------------------------------------- | +| `截止日` | 是 | `DateTime` | 通常等于 `vEndT` | +| `代码` | 是 | 字符串 | 交易证券代码 | +| `方向` | 是 | 整数 | `1` 多单；`0` 空单；缺省时按多单处理 | +| `动作` | 是 | 整数 | `0` 开仓；`1` 平仓；缺省时按开仓处理 | +| `成交量` | 条件必填 | 数值 | `FOpenVolType := 1` 或 `FCloseVolType := 1` 时提供 | +| `资金` | 条件必填 | 数值 | `FOpenVolType := 2` 时提供 | +| `剩余资金占比(%)` | 条件必填 | 数值 | `FOpenVolType := 3` 时提供 | +| `平仓数量占比(%)` | 条件必填 | 数值 | `FCloseVolType := 2` 时提供 | +| `成交价` | 是 | 数值 | 交易成交价 | +| `乘数` | 否 | 数值 | 默认 `1` | +| `保证金比例(%)` | 否 | 数值 | 默认 `100` | +| `费率(%)` | 条件必填 | 数值 | `FFeeType := 1` 时提供 | +| `费用` | 条件必填 | 数值 | `FFeeType := 2` 时提供；只适合数量类 | + +数量类方向和动作： + +| 交易含义 | 方向 | 动作 | +| ------------- | ---- | ---- | +| 买开 / 开多单 | `1` | `0` | +| 卖平 / 平多单 | `1` | `1` | +| 卖开 / 开空单 | `0` | `0` | +| 买平 / 平空单 | `0` | `1` | + +股票常见方向和动作： + +| 交易含义 | 方向 | 动作 | +| -------------- | ---- | ---- | +| 买入、融资买入 | `1` | `0` | +| 卖出、融资偿还 | `1` | `1` | +| 融券卖出 | `0` | `0` | +| 融券偿还 | `0` | `1` | + +### 期权组合策略字段 + +期权组合策略使用数量类组合。 + +| 字段 | 必填 | 接收类型 | 说明 | +| ------------------- | -------- | ---------- | -------------------------------------------------------- | +| `组 ID` | 是 | 字符串 | 同一组合内成分合约使用同一个组 ID | +| `截止日` | 是 | `DateTime` | 交易时点 | +| `代码` | 是 | 字符串 | 期权或期货合约代码 | +| `方向` | 是 | 整数 | `1` 权利仓或多单；`0` 义务仓或空单 | +| `动作` | 是 | 整数 | `0` 开仓；`1` 平仓；`32` 构建期权组合；`33` 解锁期权组合 | +| `成交价` | 是 | 数值 | 构建、解锁交易中可为任意大于 `0` 的实数 | +| `成交量` | 是 | 数值 | 合约数量 | +| `费率(%)` 或 `费用` | 条件必填 | 数值 | 由 `FFeeType` 决定 | +| `乘数` | 否 | 数值 | 按品种设置 | +| `保证金比例(%)` | 否 | 数值 | 按品种设置 | +| `组合类型` | 条件必填 | 字符串 | 组合策略标识，如 `CNSJC`、`STD` 等 | + +期权组合动作： + +| 动作 | 含义 | +| ---- | -------------------- | +| `0` | 开仓 | +| `1` | 平仓 | +| `32` | 申请构建期权组合策略 | +| `33` | 期权组合策略解锁 | + +## 成员变量 + +### 基本设置 + +| 成员变量 | 类型 | 默认值 | 说明 | +| ------------ | -------------- | ----------------------- | ---------------------- | +| `FBegT` | `DateTime` | 当前系统时间往前推 1 年 | 回测开始时间 | +| `FEndT` | `DateTime` | 当前系统时间 | 回测截止时间 | +| `FCycle` | 字符串或周期值 | 月线 | 调仓或交易周期 | +| `FGroupType` | 整数 | `1` | `1` 比例类；`2` 数量类 | +| `FIndexId` | 字符串 | `SH000300` | 基准代码 | +| `FIniCash` | 实数 | `10000000` | 初始资金，单位元 | + +### 成交和费用 + +| 成员变量 | 类型 | 默认值 | 取值 | +| ---------------- | ---- | ------ | --------------------------------------------------------------------------- | +| `FPriceType` | 整数 | `3` | `-1` 自定义；`1` 时点价格；`2` 收盘价；`3` 日均价；`4` 开盘价；`5` 系统昨收 | +| `FPriceType1` | 整数 | `3` | 多头开仓价 | +| `FPriceType2` | 整数 | `3` | 多头平仓价 | +| `FPriceType3` | 整数 | `3` | 空头开仓价 | +| `FPriceType4` | 整数 | `3` | 空头平仓价 | +| `FVolModType` | 整数 | `-1` | `0` 不取整；`-1` 按证券类型自适应取整 | +| `FFeeType` | 整数 | `1` | `1` 费率法；`2` 费用法 | +| `FLowestFeeType` | 整数 | `0` | `0` 不考虑最低费用；`1` 启用最低费用限制 | +| `FLowestFee` | 实数 | `5.0` | 最低费用 | +| `FOLowestFee` | 实数 | `5.0` | 开仓最低费用 | +| `FCLowestFee` | 实数 | `5.0` | 平仓最低费用 | + +取整规则： + +| `FVolModType` | 股票买入 | 股票卖出 | 期货 | 基金 | 债券 | +| ------------- | ------------ | ---------- | ---------- | ------------ | ----------- | +| `-1` | 100 的整数倍 | 1 的整数倍 | 1 的整数倍 | 小数点后三位 | 10 的整数倍 | +| `0` | 不取整 | 不取整 | 不取整 | 不取整 | 不取整 | + +### 比例类专用 + +| 成员变量 | 类型 | 默认值 | 说明 | +| ---------------------- | ---- | ----------------- | -------------------------------------------------- | +| `FRateType` | 整数 | `4` | 比例类组合配比方式 | +| `FSumOfRate` | 数值 | `100` | 比例类配比之和；可用于非满仓 | +| `FFeeType2` | 整数 | `1` | 比例类费率来源 | +| `FPriceRateTo0` | 整数 | `3` | 自定义成交价且目标持仓没有旧持仓证券时的清仓价类别 | +| `FIndustryMethod` | 整数 | `0` | `0` 不行业中性；`1` 行业中性 | +| `FIndustryType` | 整数 | `1` | 行业分类 | +| `FAdjustPositionPrice` | 整数 | 等于 `FPriceType` | 比例类调仓价 | +| `FAdjustPriceType` | 整数 | `0` | `0` 调仓价等于成交价；`1` 用户自设调仓价 | + +`FRateType` 取值： + +| 值 | 含义 | 规则 | +| ---- | ------------------ | ---------------------------------- | +| `-1` | 用户自定义 | `GetTradeOrder` 必须返回 `比例(%)` | +| `0` | 总市值加权 | 按总市值分配 | +| `1` | 流通市值加权 | 按流通市值分配 | +| `4` | 等权重 | 每只证券等比例 | +| `5` | 等股数 | 按等股数分配 | +| `6` | 流通市值平方根加权 | 按流通市值平方根分配 | +| `7` | 总市值平方根加权 | 按总市值平方根分配 | + +`FPriceRateTo0` 取值： + +| 值 | 含义 | +| ---- | ---------------------------- | +| `1` | 时点价格 | +| `2` | 收盘价 | +| `3` | 日均价 | +| `4` | 开盘价 | +| `5` | 系统昨收 | +| `-1` | 用户重写 `GetClearancePrice` | + +### 数量类专用 + +| 成员变量 | 类型 | 默认值 | 说明 | +| --------------- | ---- | ------ | ------------ | +| `FOpenVolType` | 整数 | `1` | 开仓数量类别 | +| `FCloseVolType` | 整数 | `1` | 平仓数量类别 | + +`FOpenVolType` 取值： + +| 值 | 含义 | `GetTradeOrder` 字段 | +| --- | -------------- | -------------------- | +| `1` | 固定成交量法 | `成交量` | +| `2` | 固定金额法 | `资金` | +| `3` | 剩余资金占比法 | `剩余资金占比(%)` | + +`FCloseVolType` 取值： + +| 值 | 含义 | `GetTradeOrder` 字段 | +| --- | ---------------- | -------------------- | +| `1` | 固定成交量法 | `成交量` | +| `2` | 可平仓数量占比法 | `平仓数量占比(%)` | + +### 分红、配股和止盈止损 + +| 成员变量 | 类型 | 默认值 | 说明 | +| ------------------- | ------ | -------- | --------------------------------------------------- | +| `FDividendType` | 整数 | `0` | `0` 分红不再投资；`1` 分红再投资；`-1` 用户重载 | +| `FDividendType2` | 整数 | `1` | 货币基金是否分红再投资 | +| `FAllotmentType` | 整数 | `0` | `0` 不自动参与配股；`1` 自动参与配股；`-1` 用户重载 | +| `FGLType` | 整数 | `-1` | `-1` 不止盈止损；`0` 低频止盈止损；`1` 日内止盈止损 | +| `FMaxGainRatio` | 整数 | `10^8` | 止盈率，`FGLType` 为 `0` 或 `1` 时有效 | +| `FMaxLossRatio` | 整数 | `-100` | 止损率，`FGLType` 为 `0` 或 `1` 时有效 | +| `FMaxGainCondition` | 字符串 | `"CBJ"` | 止盈基准价表达式 | +| `FMaxLossCondition` | 字符串 | `"CBJ"` | 止损基准价表达式 | +| `FGainName` | 字符串 | `"止盈"` | 止盈交易备注 | +| `FLossName` | 字符串 | `"止损"` | 止损交易备注 | + +止盈止损规则： + +- `FGLType := 0`：低频止盈止损，按交易日判断。 +- `FGLType := 1`：日内止盈止损，按当前时点价格判断。 +- 期权及期权组合策略不参与止盈止损。 + +### 交易约束 + +| 成员变量 | 类型 | 默认值 | 说明 | +| ------------------- | ---- | ------ | ---------------------------------------- | +| `FTradeOption` | 整数 | `0` | `0` 非交易日可交易；`1` 非交易日不可交易 | +| `FNoZT` | 整数 | `0` | `0` 涨停可买入；`1` 涨停不可买入 | +| `FNoDT` | 整数 | `0` | `0` 跌停可卖出；`1` 跌停不可卖出 | +| `FNoOverSold` | 整数 | `0` | `0` 允许超卖；`1` 不允许超卖 | +| `FPartialjy` | 整数 | `0` | `0` 超卖时可部分成交；`1` 超卖时不可卖出 | +| `FMinVol` | 实数 | `-1` | 最小成交量 | +| `FMinAmount` | 实数 | `-1` | 最小成交金额 | +| `FMaxVolPercent` | 实数 | `-1` | 最大成交量占比 | +| `FMaxAmountPercent` | 实数 | `-1` | 最大成交金额占比 | +| `FMinBuyVol` | 实数 | `-1` | 最小买入数量 | +| `FMinSellVol` | 实数 | `-1` | 最小卖出数量 | +| `FMinBuyCash` | 实数 | `-1` | 最小买入金额 | +| `FMinSellCash` | 实数 | `-1` | 最小卖出金额 | +| `FMinBuyRatio` | 实数 | `-1` | 最小买入占比 | +| `FMinSellRatio` | 实数 | `-1` | 最小卖出占比 | + +被交易约束剔除的交易，通过 `GetDelTradeData(vBegT, vEndT)` 查询。 + +### 期权、衍生品和主力合约 + +| 成员变量 | 类型 | 默认值 | 说明 | +| -------------------- | ---- | ------ | ---------------------------------------------------- | +| `FOptionRs` | 整数 | `0` | `0` 盘后不自动构成备兑组合；`1` 盘后自动构成备兑组合 | +| `FAMType` | 整数 | `0` | `0` 盘中不追加资金；`1` 盘中追加资金 | +| `FAMType2` | 整数 | `0` | `0` 盘后不追加资金；`1` 盘后追加资金 | +| `FWithdrawableRatio` | 数值 | `100` | 衍生品可提资金比例 | +| `FTradeOfDelist` | 整数 | `1` | `0` 到期不自动平仓；`1` 到期自动平仓 | +| `FMainFutureMap` | 整数 | `0` | `0` 主力连续合约不映射；`1` 映射到实际合约交易 | + +### 输出和基准 + +| 成员变量 | 类型 | 默认值 | 说明 | +| ----------------- | ------ | --------------------------- | ------------------------------------------------------ | +| `FHisFlag` | 整数 | `1` | `0` 不输出历史持仓；`1` 输出历史持仓 | +| `FVersionID` | 整数 | `1` | `1` 不输出本地；`2` 每日一个文件；`3` 所有数据一个文件 | +| `FDestDir` | 字符串 | `"C:\\Test\\MyPortfolio\\"` | 本地输出目录 | +| `FDateToStr` | 整数 | `0` | `0` 日期型；`1` 查询结果日期转字符串 | +| `FHFDataOutPut` | 整数 | `0` | `0` 不输出高频每周期清算数据；`1` 输出 | +| `FisCashToAdjust` | 整数 | `0` | `0` 不调整；`1` 现金小于 0 时调整买入量 | +| `FOrdertype` | 整数 | `3` | 买入量调整顺序 | +| `FBMType` | 整数 | `0` | `0` 单一基准；`1` 复合基准 | +| `FBMDetail` | 数组 | `array()` | 复合基准成分，字段为 `代码`、`比例(%)` | +| `FBMOption` | 整数 | `0` | `0` 累乘；`1` 累加 | + +`FOrdertype` 取值： + +| 值 | 资金分配顺序 | +| --- | -------------------------------------------------- | +| `0` | 资金先分配给符合交易约束的买入交易 | +| `1` | 按交易约束后的交易顺序分配 | +| `2` | 比例类按目标比例从小到大；数量类按成交金额从小到大 | +| `3` | 比例类按目标比例从大到小；数量类按成交金额从大到小 | + +复合基准示例： + +```tsl +obj.FBMType := 1; +obj.FBMDetail := array( + ("代码": "SH000001", "比例(%)": 40), + ("代码": "SH000300", "比例(%)": 60) +); +obj.FBMOption := 0; +``` + +## 成员方法 + +### `BackTest()` + +用途：回测主函数。 + +参数个数：0 +返回值：数组；结果读取通常通过查询接口完成。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +执行行为： + +1. 调用 `GetTimeSeries()` 获取回测时间序列。 +2. 对每个时间点调用 `GetTradeOrder(vEndT)`。 +3. 根据交易数据、当前持仓、资产、费用和约束清算。 +4. 生成最新持仓、资产配置和绩效数据。 + +### `GetTimeSeries()` + +用途：获取调仓或交易时间序列。 + +参数个数：0 +返回值：一维时间序列数组。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +重写规则： + +- 基类默认按 `FBegT`、`FEndT`、`FCycle` 生成市场交易日序列。 +- 自定义调仓日、事件驱动调仓、非固定周期交易时重写。 +- 比例类组合返回需要发生调仓的时点。 +- 数量类组合返回需要发生交易的时点。 + +### `GetTradeOrder(vEndT)` + +用途：获取当前时点目标持仓或交易明细。 + +参数个数：1 +返回值：二维数组、空数组或 `-1`。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ---------- | ----------------------------------------------------------------- | +| 1 | `vEndT` | 是 | `DateTime` | 当前调仓或交易时点，由 `BackTest()` 从 `GetTimeSeries()` 结果传入 | + +重写规则： + +- 必须在子类中重写。 +- 不要在 `GetTradeOrder(vEndT)` 中修改 `vEndT`。 +- 如果要使用历史区间，从 `vEndT` 推导，例如 `stockzf(incMonth(vEndT, -1), vEndT)`。 + +### 可重写方法 + +| 方法 | 参数个数 | 返回值 | 用途 | +| ---------------------------------------------- | -------- | -------- | ------------------------------------------------ | +| `GetTA(vEndT)` | 1 | 二维数组 | 获取申购赎回、资金转入转出数据 | +| `StockFee(stockId, vEndT, actionId, position)` | 4 | 实数 | 获取证券交易费率 | +| `GetPercent(t, vEndT)` | 2 | 二维数组 | 比例类组合中计算目标持仓比例 | +| `ReturnBenchmark(vBegT, vEndT, t)` | 3 | 二维数组 | 获取区间基准收益率序列；复合基准或高频基准可重写 | +| `GetOtherData(vEndT)` | 1 | 二维数组 | 自定义分红、送股、配股数据 | +| `GetClearancePrice(t, vEndT, ptype)` | 3 | 实数 | 比例类自定义清仓价 | +| `GetIntVol(stype, actionId, modType, vJYSL)` | 4 | 实数 | 自定义成交量取整 | + +### 当前状态读取方法 + +| 方法 | 参数个数 | 返回值 | 用途 | +| ------------------------- | -------- | -------- | -------------------------------------------------- | +| `GetSurplusFund()` | 0 | 实数 | 最新剩余资金 | +| `GetNetAssetValue()` | 0 | 实数 | 最新资产净值 | +| `GetAssetData()` | 0 | 二维数组 | 最新资产配置 | +| `GetAssetJZValue()` | 0 | 实数 | 最新单位净值 | +| `GetHoldData()` | 0 | 二维数组 | 最新持仓 | +| `GetSellpool()` | 0 | 二维数组 | 当前可卖品种和数量 | +| `CalcashByTradeData(tjy)` | 1 | 一维数组 | 根据指定日交易数据计算交易资金变动和交易后剩余资金 | + +`GetTA(vEndT)` 返回字段： + +| 字段 | 必填 | 接收类型 | 说明 | +| ---------- | ---- | ---------- | ------------------ | +| `截止日` | 是 | `DateTime` | 资金发生日期 | +| `业务类型` | 是 | 整数 | `2` 出金；`3` 入金 | +| `成交金额` | 是 | 数值 | 出入金额 | +| `备注` | 是 | 字符串 | 出金或入金说明 | + +`GetOtherData(vEndT)` 返回字段： + +| 字段 | 必填 | 接收类型 | 说明 | +| --------------- | ---- | ---------- | ---------------------------- | +| `截止日` | 是 | `DateTime` | 事件日期 | +| `代码` | 是 | 字符串 | 证券代码 | +| `方向` | 是 | 整数 | `1` 多单；`0` 空单 | +| `动作` | 是 | 整数 | `2` 分红；`3` 送股；`4` 配股 | +| `成交量` | 是 | 数值 | 动作为 `2` 时为 `0` | +| `成交价` | 是 | 数值 | 动作为 `2`、`3` 时为 `0` | +| `成交金额` | 是 | 数值 | 分红金额或配股金额 | +| `乘数` | 否 | 数值 | 默认 `1` | +| `保证金比例(%)` | 否 | 数值 | 默认 `100` | +| `费率(%)` | 否 | 数值 | 默认 `0` | +| `备注` | 否 | 字符串 | 分红、配股等说明 | + +## 查询接口 + +### 资产和持仓 + +| 方法 | 参数个数 | 返回值 | 用途 | +| ---------------------------------- | -------- | -------- | ------------------ | +| `GetAssetData(vEndT)` | 1 | 二维数组 | 指定日资产配置 | +| `GetAssetData(vBegT, vEndT)` | 2 | 二维数组 | 区间资产配置 | +| `GetAssetJZData(vEndT)` | 1 | 实数 | 指定日单位净值 | +| `GetAssetJZData(vBegT, vEndT)` | 2 | 二维数组 | 区间单位净值 | +| `GetHoldData(vEndT)` | 1 | 二维数组 | 指定日持仓 | +| `GetHoldData(vBegT, vEndT)` | 2 | 二维数组 | 区间持仓 | +| `GetOptionGroupData()` | 0 | 二维数组 | 当前期权组合持仓 | +| `GetOptionGroupData(vEndT)` | 1 | 二维数组 | 指定日期权组合持仓 | +| `GetOptionGroupData(vBegT, vEndT)` | 2 | 二维数组 | 区间期权组合持仓 | + +### 交易和剔除数据 + +| 方法 | 参数个数 | 返回值 | 用途 | +| -------------------------------------- | -------- | -------- | -------------------------------------------------------- | +| `GetTradeData(vBegT, vEndT)` | 2 | 二维数组 | 区间交易数据 | +| `GetDelTradeData(vBegT, vEndT)` | 2 | 二维数组 | 被成交量约束、交易约束、期权组合构建或解锁失败剔除的交易 | +| `GetTAData(vBegT, vEndT)` | 2 | 二维数组 | 区间资金进出数据 | +| `GetPortfolioPercent(vBegT, vEndT)` | 2 | 二维数组 | 区间组合配比；比例类专用 | +| `GetJyByPercent(pfInfoData, tPercent)` | 2 | 二维数组 | 根据 T-1 调整后持仓和 T 日目标比例生成 T 日交易 | + +### 盈亏和收益 + +| 方法 | 参数个数 | 返回值 | 用途 | +| ------------------------------------------ | -------- | -------- | ------------------------------------ | +| `GetGainandLoss(vBegT, vEndT)` | 2 | 二维数组 | 区间组合、分类资产每日盈亏和累计盈亏 | +| `GetTradingAmount(vBegT, vEndT)` | 2 | 二维数组 | 区间每日买入、卖出、分红、净买卖金额 | +| `GetGainandLossBySecurity(vBegT, vEndT)` | 2 | 二维数组 | 区间按个券汇总盈亏 | +| `GetTradingAmountBySecurity(vBegT, vEndT)` | 2 | 二维数组 | 区间按个券汇总交易金额 | +| `GetPortfolioReturn()` | 0 | 实数 | 最新组合收益率 | +| `GetPortfolioReturn(vBegT, vEndT)` | 2 | 实数 | 区间组合收益率 | +| `GetPortfolioAccumulativeReturn()` | 0 | 实数 | 组合成立以来收益率 | +| `GetPortfolioReturn2(vBegT, vEndT)` | 2 | 二维数组 | 区间组合和基准每日收益率序列 | +| `GetTrailingReturn(vEndT)` | 1 | 二维数组 | 指定日阶段收益率 | +| `GetRollingReturn(vBegT, vEndT, cy)` | 3 | 二维数组 | 区间滚动收益率 | +| `GetStockBuyandHoldReturn(vBegT, vEndT)` | 2 | 二维数组 | 区间持仓不动收益和交易贡献 | +| `GetIRRReturn(vBegT, vEndT, vAnnual)` | 3 | 实数 | 区间现金流内部收益率 | + +### 风险评价和行业配置 + +| 方法 | 参数个数 | 返回值 | 用途 | +| -------------------------------------- | -------- | -------- | --------------------------------------------- | +| `GetSectorAllocation(vEndT)` | 1 | 二维数组 | 指定日行业配置 | +| `GetReturnandRisk(vBegT, vEndT)` | 2 | 二维数组 | 区间累计收益、标准差、夏普等风险回报 | +| `GetRelativePerformance(vBegT, vEndT)` | 2 | 二维数组 | 区间超额收益、alpha、beta、跟踪误差等相对表现 | + +通用日期参数： + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---------- | ---------- | ------ | +| 1 | `vBegT` | 视签名而定 | `DateTime` | 开始日 | +| 2 | `vEndT` | 视签名而定 | `DateTime` | 截止日 | + +## 查询结果关键字段 + +### `GetAssetData` + +| 字段 | 说明 | +| ------------------- | -------------------------- | +| `截止日` | 资产配置日期 | +| `现金市值` | 当前现金 | +| `股票市值` | 股票资产市值 | +| `基金市值` | 基金资产市值 | +| `债券市值` | 债券资产市值 | +| `金融衍生品市值` | 金融衍生品保证金市值 | +| `资产净值` | 组合资产净值 | +| `股票占净值比例(%)` | 股票市值 / 资产净值 \* 100 | +| `现金占净值比例(%)` | 现金市值 / 资产净值 \* 100 | + +### `GetHoldData` + +| 字段 | 说明 | +| --------------- | -------------------------------------- | +| `组 ID` | 期权组合或组合持仓标识；全为空时不返回 | +| `截止日` | 持仓日期 | +| `代码` | 证券代码 | +| `方向` | 多单或空单 | +| `数量` | 持仓数量 | +| `收盘` | 收盘价格 | +| `市值` | `收盘 * 数量` | +| `保证金占用` | `收盘 * 数量 * 保证金比例` | +| `占净值比例(%)` | 保证金占用 / 资产净值 \* 100 | +| `总成本` | 持仓总成本 | +| `成本价` | 持仓成本价 | +| `浮动盈亏` | 市值 - 总成本 | +| `浮盈率(%)` | 浮动盈亏 / 总成本 | +| `证券类别` | 证券类型 | +| `行业名称` | 行业分类名称 | +| `组合类型` | 期权组合策略类型；全为空时不返回 | + +### `GetTradeData` + +| 字段 | 说明 | +| ------------------ | ------------------------ | +| `组 ID` | 期权组合或组合交易标识 | +| `截止日` | 交易日期 | +| `代码` | 证券代码 | +| `名称` | 证券名称 | +| `方向` | 多单或空单 | +| `动作` | 开仓、平仓、构建、解锁等 | +| `成交价` | 成交价格 | +| `成交量` | 成交数量 | +| `费率(%)` | 交易费率 | +| `成交金额（税前）` | 成交价 \* 成交量 | +| `费用` | 手续费 | +| `成交金额` | 税后成交金额 | +| `组合类型` | 期权组合策略类型 | +| `备注` | 交易备注 | +| `止盈止损基准价` | 有止盈止损交易时可能返回 | +| `止盈止损成交价` | 有止盈止损交易时可能返回 | + +## 常见专项规则 + +### 高频回测 + +- 高频策略通常设置 `FCycle` 为分钟线或秒线周期。 +- 高频策略若要以当前时点价格成交，设置 `FPriceType := 1`。 +- 高频回测需要返回每个周期清算数据时，设置 `FHFDataOutPut := 1`。 +- 高频并且重写 `ReturnBenchmark` 时，基准收益率也要按每个时点计算。 + +### 现金不足调整 + +- 全股票组合经过涨停、跌停、停牌、超卖、最大最小成交量和成交金额约束后，如果可用资金小于 `0`，可设置 `FisCashToAdjust := 1`。 +- `FOrdertype` 决定买入量调整顺序。 +- 调整后仍应通过 `GetAssetData()` 检查现金市值。 + +### 主力连续合约 + +- `FMainFutureMap := 0` 时，不对期货主力连续合约做映射。 +- `FMainFutureMap := 1` 时，将主力连续合约映射到当时实际合约。 +- 比例类组合中，主力变更日若是调仓日，以当日调仓数据为准。 +- 数量类组合中，主力变更日无论是否为交易时点，都需要处理主力换仓交易。 + +### 自定义成交价 + +- 比例类目标持仓使用自定义成交价时，设置 `FPriceType := -1`。 +- `GetTradeOrder(vEndT)` 返回目标持仓中可提供 `成交价`。 +- 原持仓证券在本期目标持仓中不存在时，清仓价由 `FPriceRateTo0` 决定。 +- `FPriceRateTo0 := -1` 时，重写 `GetClearancePrice(t, vEndT, ptype)`。 + +## 缺失输入处理 + +| 情况 | 生成处理 | +| ------------------------------ | ----------------------------------------------------------------- | +| 只有“写回测框架”，没有策略逻辑 | 生成 `TSBackTesting` 子类骨架，`GetTradeOrder(vEndT)` 先返回 `-1` | +| 没有证券池、调仓规则或交易明细 | 只生成框架和参数入口，不生成具体交易信号 | +| 没有期权需求 | 使用比例类或数量类普通字段，不加入期权组合字段 | +| `FGroupType := 1` | `GetTradeOrder(vEndT)` 返回目标持仓和目标比例字段 | +| `FGroupType := 2` | `GetTradeOrder(vEndT)` 返回成交明细、成交价、成交量和动作字段 | +| 高频且要求当前时点价格成交 | 设置 `FPriceType := 1` | +| `FDateToStr := 1` | 查询结果里的日期按字符串处理；后续日期计算先转换回日期值 | diff --git a/docs/tsl/modules/tsl_python_interop.md b/docs/tsl/modules/tsl_python_interop.md deleted file mode 100644 index 1e877727..00000000 --- a/docs/tsl/modules/tsl_python_interop.md +++ /dev/null @@ -1,97 +0,0 @@ -# 天软平台和 Python 的交互 - -文档类型：模块摘要 -是否可直接用于生成代码：否 -遇到不确定时跳转到：项目级部署文档、对应官方文档、[pytsl_api.md](pytsl_api.md)、[index.md](index.md) - -本页用于接入决策和最小链路确认，不替代项目级部署文档。 - -- 如果登录方式、凭证来源、位数、环境变量、连接通道或部署入口没有确认，不继续生成接入代码，直接回项目级部署文档或对应官方文档。 - -## Agent Python 互操作边界规则 - -- 先判断是 Python 调 TSL、TSL 调 Python，还是服务器侧 Python 服务。 -- 本页只给接入路径和接口类别；真实登录方式、位数、环境变量和部署入口必须回项目级部署文档。 -- 不要发明凭证来源、连接通道、Python 路径或服务部署方式。 - -## 摘要 - -- 覆盖三类交互：Python 调用 TSL、TSL 调用 Python、落地服务器开启 Python 服务。 -- 提供 COM/远程登录两种路径，以及 `PyRun`/`PyCall` 体系。 - -## 怎么选路 - -| 场景 | 先选哪条路 | 最小前置条件 | 常见失败点 | -| ----------------------------------- | -------------------------- | ------------------------------------------------------- | ---------------------------------------------------- | -| Python 作为主控，远程执行或调用 TSL | Python 调 TSL | Python 环境、TSLPy 模块、可用连接方式（COM / 远程登录） | 位数不一致、环境变量没配好、服务器未登录 | -| TSL 脚本里需要调用现有 Python 代码 | TSL 调 Python | TSL 与 Python 位数一致、`PYTHONHOME` 等环境正确 | Python 环境未就绪、模块找不到、网格场景不支持 | -| 落地服务器侧长期提供 Python 能力 | 落地服务器开启 Python 服务 | 服务端环境、部署权限、可维护的脚本入口 | 服务端环境和本地环境不一致、依赖未部署、运行权限不足 | - -## 结构索引 - -- 支持版本 -- Python 调用 TSL：配置步骤 / 接口说明 / 范例 -- TSL 调用 Python：配置步骤 / 接口说明 / 范例 -- do Python 方式 -- 落地服务器开启 Python 服务 -- sklearn 机器学习接口 -- 附录与 FAQ - -## Python 调用 TSL（核心步骤） - -1. 先确认项目级部署文档里的天软目录、Python 目录、位数、连接通道和登录方式。 -2. 配置环境变量（天软目录、Python 目录）。 -3. 加载 TSLPy 模块（直接加载或修改包名）。 -4. 选择连接方式（COM / 远程登录）。 -5. 登录服务器后，再执行 `RemoteExecute` / `RemoteCallFunc`。 -6. 完成后显式断开连接。 - -## 主要接口（Python 侧） - -- 服务器：`ConnectServer` / `LoginServer` / `Disconnect` -- 执行：`RemoteExecute` / `RemoteCallFunc` -- 系统参数：`SetSysParam` / `GetSysParam` -- 日期转换：`EncodeDate` / `DecodeDate` / `EncodeDateTime` / `DecodeDateTime` - -## TSL 调用 Python（核心接口） - -- `PyPutVar` / `PyGetVar` -- `PyRun`（执行脚本） -- `PyCall`（调用 Python 函数，支持命名参数） -- `PyError` / `PyRelease` / `PyEnsure` - -## TSL 调用 Python（核心步骤） - -1. 先回项目级部署文档确认位数、`PYTHONHOME`、解释器路径和可用模块。 -2. 用 `PyEnsure` 确认 Python 运行时已经就绪。 -3. 需要把输入传给 Python 时，先用 `PyPutVar` 放入变量。 -4. 选择执行方式：执行整段脚本用 `PyRun`，直接调函数用 `PyCall`。 -5. 需要取回结果时，再用 `PyGetVar` 读取输出变量。 -6. 失败时先看 `PyError`，结束后显式 `PyRelease`。 - -## 最小前置条件 - -- Python 与 TSL 位数必须一致。 -- 多版本 Python 需同步设置 `PYTHONHOME`。 -- 落地前先决定是谁主控：Python 主控还是 TSL 主控。 - -## do Python 方式 - -- 适合快速执行 Python 脚本，省去显式接口调用。 - -## 落地服务器开启 Python 服务（核心步骤） - -1. 先回项目级部署文档确认服务入口、部署权限、依赖目录和守护方式。 -2. 在服务器上准备与项目要求一致的 Python 运行时和依赖包。 -3. 放置一个稳定的 Python 脚本或服务入口，先只承载一条最小调用链。 -4. 按项目约定把这个入口接到天软侧的调用路径或调度入口。 -5. 用最小请求先验证“能启动、能调用、能返回”，再扩展业务逻辑。 -6. 再补日志、重启方式和运维监控；如果这些入口还没确认，不继续生成部署代码。 - -## 注意事项（精简） - -- Python 与 TSL 位数必须一致。 -- 多版本 Python 需同步设置 `PYTHONHOME`。 -- TSL 调 Python 不支持网格调用。 -- 出现调用失败时，优先先检查环境、位数和登录状态，再排查业务逻辑。 -- 如果登录方式、凭证来源、位数、环境变量、连接通道或部署入口任一没有确认，不继续生成接入代码。 diff --git a/docs/tsl/modules/wechat_message.md b/docs/tsl/modules/wechat_message.md index b40c0bf3..ac6bcc7d 100644 --- a/docs/tsl/modules/wechat_message.md +++ b/docs/tsl/modules/wechat_message.md @@ -1,90 +1,246 @@ # 发送微信消息使用说明 -文档类型：模块摘要 -是否可直接用于生成代码：仅部分 -遇到不确定时跳转到：调用侧账户体系文档、项目实际接口说明、[index.md](index.md) +文档类型：模块 API 事实页 +是否可直接用于生成代码：是，但 `userid`、`username`、模板标题、模板关键字含义和真实通知内容必须来自用户需求或项目上下文 +遇到不确定时：[index.md](index.md)、调用侧账户体系文档、项目实际接口说明、天软科技服务号模板列表 -本页用于确认接口名称、参数含义和风险边界，不替代项目级接入文档。 +本页整理通过“天软科技服务号”发送微信模板消息的接口事实。它负责告诉智能体“该调用哪个函数、参数顺序是什么、同步和异步怎么选择、状态如何查询”，不负责替用户创造账户、授权关系、模板映射或通知内容。 -## Agent 微信消息边界规则 +## 智能体微信消息决策规则 -- 先确认调用侧已经提供 `userid`、模板类型、关键字含义和必要的账户字段。 -- 本页只给接口外形和参数含义；账户体系、授权关系和模板映射以项目实际接口说明为准。 -- 不要发明 `username` 来源、模板关键字含义、项目封装函数或账户映射。 - -## 适用场景 - -- 通过“天软科技服务号”向微信客户端发送模板消息。 -- 支持同步/异步发送，异步可用消息 ID 查询状态。 +- 用户要“发送微信通知 / 微信消息 / 微信告警 / 微信模板消息 / 查询微信发送状态”时，优先使用本页。 +- 紧急通知、需要立刻知道发送结果时，默认使用 `send_wechat_message(...)`。 +- 非紧急通知、批量通知、发送后可稍后查询状态时，默认使用 `send_wechat_message_async(...)`。 +- 用户要求查询异步状态时，生成 `get_wechat_message_status(userid, username, wechat_message_id)`；三个实参必须来自参数、已知变量或项目上下文。 +- 参数必须严格按接口顺序传入；所有参数按字符串处理。 +- `url` 是固定位置参数；无详情地址时传空字符串 `""`。 +- `k1` 到 `k6` 的含义由模板标题决定；只按模板映射或用户输入填充，不要发明关键字含义。 +- 用户要求“通知第一眼看到”的内容时，放入带字段名的 `kN` 参数；`first` 和 `remark` 只作为点入通知后的详情文本。 +- 给他人发消息时，必须使用接收者授权给发送者的 `userid`，不要把发送者自己的 `userid` 当成接收者标识。 +- 不要发明 `userid`、`username`、项目封装函数、模板标题、模板关键字、授权关系或账号映射。 ## 前置条件 -- 用户关注并绑定天软科技服务号，获得 `userid`。 -- 给他人发送消息需对方授权其 `userid`。 +| 条件 | 说明 | +| ------------------------------- | -------------------------------------------------------------------------------------- | +| 已绑定服务号 | 首次使用需要关注并绑定“天软科技服务号”，绑定后取得 `userid` | +| 已取得 `userid` | `userid` 与用户账户和微信绑定关系相关，应由调用侧提供 | +| 给他人发送时已授权 | 接收者绑定后在服务号 `userid` 页面授权发送者账号，发送者使用接收者提供的 `userid` 发送 | +| 查询异步状态时已取得 `username` | `username` 是账号名，脚本查询发送状态时需要；来源以项目账户体系为准 | -## 核心接口 +## 接口总览 -- `send_wechat_message(userid, url, title, first, remark[, k1..k6])` - - 同步发送；成功返回 `success`，否则返回错误信息。 -- `send_wechat_message_async(userid, url, title, first, remark[, k1..k6])` - - 异步发送；返回 16 位消息 ID（时间戳 + 随机数）。 -- `get_wechat_message_status(userid, username, wechat_message_id)` - - 查询异步发送结果；返回 “成功” 或错误信息。 +| 函数 | 用途 | 返回值 | +| ---------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------- | +| `send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])` | 同步发送模板消息 | 成功返回字符串 `success`；失败返回错误信息 | +| `send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])` | 异步发送模板消息 | 返回 16 位字符串消息 ID | +| `get_wechat_message_status(userid, username, wechat_message_id)` | 查询异步发送结果 | 成功返回字符串 `成功`；否则返回状态信息或错误信息 | -## 参数说明（模板消息） +## 同步发送 -- `userid`：绑定账户后获取的用户标识（必需）。 -- `username`：查询异步发送状态时使用的用户名 / 账户标识；当前页只确认查询接口需要它，具体来源以项目实际账户体系或调用侧约定为准。如果调用侧拿不到该值，当前页不支持生成状态查询代码。 -- `url`：详情地址（必需，可为空字符串）。 -- `title`：模板消息标题（必需）。 -- `first`：副标题（一般需要）。 -- `remark`：备注（一般需要）。 -- `k1..k6`：模板关键字参数（根据模板类型变化）。常见模板示例： - - 监控报告通知：运行状态/时间 - - 系统运行简报：系统名称/简报内容/发布时间 - - 告警通知：告警内容/发生时间 +签名： -## 同步 vs 异步 - -- 同步：阻塞等待结果，适合紧急通知。 -- 异步：立即返回，适合非紧急通知；用 `get_wechat_message_status` 查询。 -- 如果你无法确认 `username` 的来源，不要自行猜测；先回调用侧或账户体系文档确认。 - -## 当前只确认的范围 - -- 当前页已经确认的范围是：发送接口名、异步发送会返回消息 ID、状态查询接口需要 `userid` + `username` + `wechat_message_id`。 -- 当前页没有确认的范围是：`username` 的正式来源、不同模板关键字的完整映射、项目侧的统一封装方式。 - -## 不要猜的部分 - -- 不要把 `"username"` 当成可用实参，也不要凭空拼接账户名。 -- 如果调用侧没有提供 `username`，当前页只支持生成发送代码，不支持生成状态查询代码。 -- `k1..k6` 的含义随模板类型变化；需要和具体模板一起核对。 - -## 发送示例（配置片段，可参考参数组织） - -下面代码只表示参数组织方式；真实账户、模板关键字和调用侧封装以项目实际接口说明为准。 - -```tsl -// 定义参数 -url := "http://tinysoft.com.cn"; -user_id := "190F1826267E0EB45658FB81836636A7"; - -title := "监控报告通知"; -first := "运行状态"; -keyword_1 := "运行正常"; -keyword_2 := ""; -DateTimeToString(keyword_2, "YYYY-MM-DD HH:NN:SS", Now()); -remark := "如有疑问请与技术人员联系！"; - -// 同步发送 -echo send_wechat_message(user_id, url, title, first, remark, keyword_1, keyword_2); - -// 异步发送 -wechat_message_id := send_wechat_message_async(user_id, url, title, first, remark, keyword_1, keyword_2); +```text +send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6]) ``` -## 状态查询示例 +参数表： -- 当前页不提供状态查询代码块。 -- 只有在调用侧已经明确提供 `username` 来源时，才继续生成 `get_wechat_message_status(...)` 调用。 +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | -------- | -------- | ----------------------------------------------------------------- | +| 1 | `userid` | 是 | 字符串 | 绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 `userid` | +| 2 | `url` | 是 | 字符串 | 详情地址；没有详情地址时传 `""` | +| 3 | `title` | 是 | 字符串 | 模板消息标题，例如 `监控报告通知` | +| 4 | `first` | 是 | 字符串 | 详情页开头文本；不作为通知列表首屏字段 | +| 5 | `remark` | 是 | 字符串 | 详情页结尾备注；不作为通知列表首屏字段 | +| 6 | `k1` | 条件必填 | 字符串 | 模板关键字 1；带字段名的 `kN` 行属于首屏展示字段 | +| 7 | `k2` | 条件必填 | 字符串 | 模板关键字 2；带字段名的 `kN` 行属于首屏展示字段 | +| 8 | `k3` | 否 | 字符串 | 模板关键字 3；部分模板需要 | +| 9 | `k4` | 否 | 字符串 | 模板关键字 4；部分模板需要 | +| 10 | `k5` | 否 | 字符串 | 模板关键字 5；部分模板需要 | +| 11 | `k6` | 否 | 字符串 | 模板关键字 6；部分模板需要 | + +返回值： + +| 返回值 | 含义 | +| ---------- | ------------ | +| `success` | 同步发送成功 | +| 其他字符串 | 错误信息 | + +使用规则： + +- 同步发送会阻塞当前程序，必须等待发送函数执行完毕后才进入下一步。 +- 紧急通知优先使用同步发送。 +- 返回值不是 `success` 时，按错误信息处理。 + +## 异步发送 + +签名： + +```text +send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6]) +``` + +参数表： + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | -------- | -------- | ----------------------------------------------------------------- | +| 1 | `userid` | 是 | 字符串 | 绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 `userid` | +| 2 | `url` | 是 | 字符串 | 详情地址；没有详情地址时传 `""` | +| 3 | `title` | 是 | 字符串 | 模板消息标题 | +| 4 | `first` | 是 | 字符串 | 详情页开头文本；不作为通知列表首屏字段 | +| 5 | `remark` | 是 | 字符串 | 详情页结尾备注；不作为通知列表首屏字段 | +| 6 | `k1` | 条件必填 | 字符串 | 模板关键字 1；带字段名的 `kN` 行属于首屏展示字段 | +| 7 | `k2` | 条件必填 | 字符串 | 模板关键字 2；带字段名的 `kN` 行属于首屏展示字段 | +| 8 | `k3` | 否 | 字符串 | 模板关键字 3；部分模板需要 | +| 9 | `k4` | 否 | 字符串 | 模板关键字 4；部分模板需要 | +| 10 | `k5` | 否 | 字符串 | 模板关键字 5；部分模板需要 | +| 11 | `k6` | 否 | 字符串 | 模板关键字 6；部分模板需要 | + +返回值： + +| 返回值 | 含义 | +| ----------- | ---------------------------------------------------------- | +| 16 位字符串 | 异步消息 ID；前 10 位为 1900 年以来的秒数，后 6 位为随机数 | + +使用规则： + +- 异步发送把命令提交给服务器后立即返回，不等待最终发送结果。 +- 非紧急通知优先使用异步发送。 +- 需要最终结果时，保存返回的 `wechat_message_id`，再调用 `get_wechat_message_status(...)` 查询。 + +## 查询异步发送状态 + +签名： + +```text +get_wechat_message_status(userid, username, wechat_message_id) +``` + +参数表： + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | -------- | ---------------------------------------------------- | +| 1 | `userid` | 是 | 字符串 | 发送时使用的用户标识 | +| 2 | `username` | 是 | 字符串 | 账号名；脚本执行查询时需要，来源以项目账户体系为准 | +| 3 | `wechat_message_id` | 是 | 字符串 | `send_wechat_message_async(...)` 返回的 16 位消息 ID | + +返回值： + +| 返回值 | 含义 | +| ---------- | ------------------ | +| `成功` | 异步消息发送成功 | +| 其他字符串 | 状态信息或错误信息 | + +调用规则： + +- 状态查询用于异步发送后的结果确认。 +- `username` 按账号名参数、已知变量或项目上下文传入，不写字面量 `"username"`。 +- `wechat_message_id` 使用 `send_wechat_message_async(...)` 的返回值。 + +## 模板展示规则 + +| 模板片段 | 展示位置 | 生成规则 | +| ----------------------------------- | ---------------------- | ------------------------------------------------ | +| `字段名：{{kN}}` | 通知列表首屏可见 | 用户要求“第一眼看到”的信息放到对应 `kN` | +| `{{first}}` | 点入通知后的详情页开头 | 放说明、背景、摘要引导；不承载首屏必须展示的信息 | +| `{{remark}}` | 点入通知后的详情页结尾 | 放补充说明、处理建议、联系人等尾部信息 | +| 字面标题行，例如 `监控报告通知` | 模板固定内容 | 不作为接口参数；接口参数 `title` 仍使用模板标题 | +| 动态标签行，例如 `{{k5}}幅：{{k6}}` | 通知列表首屏可见 | `k5` 填字段标签的一部分，`k6` 填对应数值 | + +生成规则： + +- `title` 决定模板，`k1` 到 `k6` 按模板字段名依次填入。 +- 有名称的 `kN` 行是首屏展示字段；需要首屏展示的信息优先放入 `kN`。 +- `first` 和 `remark` 是详情页内容；不要把“第一眼必须看到”的核心字段放入 `first` 或 `remark`。 +- 模板未列出的 `kN` 不主动传入；需要扩展字段时先换模板或由用户提供模板映射。 + +## 模板关键字映射 + +### 系统监控类 + +| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` | +| -------------------- | ------------ | ------------ | ------------ | ---- | ---- | ---- | +| `系统运行简报` | 系统名称 | 简报内容 | 发布时间 | | | | +| `监控报告通知` | 运行状态 | 时间 | | | | | +| `监控结果通知` | 监控项目 | 内容 | 时间 | | | | +| `告警通知` | 告警内容 | 告警发生时间 | | | | | +| `故障恢复通知` | 故障信息 | 恢复时间 | | | | | +| `服务器异常监控通知` | 监控通知 | 监控通知类型 | 监控通知内容 | | | | +| `服务器宕机通知` | 故障时间 | 故障原因 | | | | | +| `服务器恢复通知` | 故障停止时间 | 故障持续时间 | | | | | + +### 交易通知类 + +| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` | +| -------------- | -------- | -------- | -------- | -------- | -------- | -------- | +| `交易成功通知` | 交易金额 | 交易类型 | 交易时间 | 交易单号 | | | +| `交易完成通知` | 股票简称 | 股票代码 | 股票价格 | 交易状态 | 股票数量 | | +| `交易下单通知` | 交易品种 | 下单方向 | 下单价格 | 止损价格 | 下单时间 | | +| `成交回报提示` | 证券名称 | 证券代码 | 买卖标识 | 成交价格 | 成交数量 | 成交时间 | +| `委托成交提醒` | 数量 | 价格 | 时间 | | | | + +### 策略通知类 + +| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` | +| ------------------ | -------- | ---------- | ------------ | ---------- | ------------------------- | ------ | +| `投资策略更新提醒` | 策略名称 | 操作风格 | 目前策略收益 | | | | +| `股票调仓通知` | 股票名称 | 操作类型 | 调仓时间 | 调仓价格 | 调仓仓位 | | +| `实时建仓提醒` | 品种 | 方向 | 仓位 | 价格 | 止盈止损 | | +| `个股到价通知` | 股票名 | 当前成交价 | 预警价 | | | | +| `个股涨跌幅通知` | 股票名 | 当前成交价 | 对比日期 | 对比收盘价 | 动态标签，组成 `{{k5}}幅` | 动态值 | + +### 其他通知类 + +| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` | +| ------------------ | -------- | -------- | ---- | ---- | ---- | ---- | +| `账号绑定成功通知` | 账号名称 | 绑定时间 | | | | | +| `服务开启通知` | | | | | | | +| `授权请求通知` | 申请人 | 请求权限 | | | | | + +`服务开启通知` 当前只记录模板标题，未固定 `k1` 到 `k6` 的字段映射。 + +## 发送示例 + +同步发送系统运行简报： + +```tsl +function SendSystemBrief(user_id); +begin + url := ""; + title := "系统运行简报"; + first := "系统运行情况如下。"; + k1 := "风控服务"; + k2 := "运行正常"; + dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now()); + remark := "如有疑问请联系值班人员。"; + + return send_wechat_message(user_id, url, title, first, remark, k1, k2, k3); +end; +``` + +异步发送并保留消息 ID： + +```tsl +function SendSystemBriefAsync(user_id); +begin + url := ""; + title := "系统运行简报"; + first := "系统运行情况如下。"; + k1 := "风控服务"; + k2 := "运行正常"; + dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now()); + remark := "如有疑问请联系值班人员。"; + + return send_wechat_message_async(user_id, url, title, first, remark, k1, k2, k3); +end; +``` + +查询异步发送结果： + +```tsl +function QueryWechatMessageStatus(user_id, username, wechat_message_id); +begin + return get_wechat_message_status(user_id, username, wechat_message_id); +end; +``` diff --git a/docs/tsl/naming.md b/docs/tsl/naming.md index 8662df6c..4d4a341e 100644 --- a/docs/tsl/naming.md +++ b/docs/tsl/naming.md @@ -1,13 +1,12 @@ -# TSL 命名规范（Naming） +# TSL 命名偏好 -文档类型：规范页 +文档类型：风格偏好页 是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：否 -是否含已验证反例：否 -遇到不确定时跳转到：[code_style.md](code_style.md)、[syntax/index.md](syntax/index.md)、[syntax/03_core_model.md](syntax/03_core_model.md) +是否含可直接照写示例：否 +是否含不可照写反例：否 +遇到不确定时：[code_style.md](code_style.md)、[syntax/index.md](syntax/index.md)、[syntax/02_core_model.md](syntax/02_core_model.md) -本仓库命名规则与 Google C++ Style -Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。 +本页记录本仓库/作者的命名偏好，不代表 TSL 语法事实。命名偏好与 Google C++ Style Guide 的实体形状思路对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。 以下出现的 `<...>` 形式只表示命名或注释模板占位，不是源码字面量。 @@ -51,7 +50,7 @@ Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函 ## 3. 类型命名（Type Names） AI 先按 `.tsl` 可执行脚本与 `.tsf` 模块/函数扩展判断文件模型。`.tsl` 里的语句区按顺序执行，函数/类声明区放在语句区之后；`.tsf` 用于可复用顶层声明并部署到解释器 `funcext`。本页只覆盖“需要命名的顶层实体”，不覆盖脚本语句本身；文件模型判断本身以 -`docs/tsl/syntax/03_core_model.md` 为准。 +`docs/tsl/syntax/02_core_model.md` 为准。 - **类与单元**使用 `PascalCase`，不带下划线；名称应为名词/名词短语（通常单数），避免动词开头。 @@ -69,13 +68,13 @@ AI 先按 `.tsl` 可执行脚本与 `.tsf` 模块/函数扩展判断文件模型 TSL 的语法要求（仅 `.tsf`）：每个 `.tsf` 文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。 -- 更可靠的判断方式仍然是先看顶层内容，而不是只看扩展名；命名规范只是补充“命名后的实体如何取名”，不替代文件模型判断。 +- 更可靠的判断方式仍然是先看顶层内容，而不是只看扩展名；命名偏好只是补充“命名后的实体如何取名”，不替代文件模型判断。 - 需要命名的顶层实体可以是 `function / procedure`、`type Name = class`、`unit`。 - `.tsf` 代码文件：用于库/模块等“顶层声明”的首选承载文件；顶层声明可为 `function / procedure`、`type Name = class`、`unit`，文件基名需与之同名。 - `.tsl` 脚本文件：用于入口/编排层；允许直接写语句（如 - `a := 1; echo a;`），也可能出现顶层 `function / procedure` 骨架或 `program test;` - 这类验证样例外壳；如果同时出现脚本语句和函数/类声明，语句区在前，声明区在后；但风格上不把 `.tsl` 当成可复用顶层声明的默认落点，也不要求文件基名与函数名一致；可复用逻辑优先下沉到 + `a := 1; echo a;`），也可能出现顶层 `function / procedure` 骨架 + 这类示例脚本外壳；如果同时出现脚本语句和函数/类声明，语句区在前，声明区在后；但风格上不把 `.tsl` 当成可复用顶层声明的默认落点，也不要求文件基名与函数名一致；可复用逻辑优先下沉到 `.tsf`（见 `docs/tsl/code_style.md`）。 - 注：`.tsf` 也是 TSL 源文件，命名/风格与 `.tsl` 遵循同一套规则。 - **硬规则（仅 @@ -85,7 +84,7 @@ TSL 的语法要求（仅 `.tsf`）：每个 `.tsf` - 基名统一使用 `PascalCase`，与顶层声明的推荐写法一致。 - 示例： - - `DailyEntry.tsl` 作为入口 / 编排脚本，主体是松散语句或验证样例外壳。 + - `DailyEntry.tsl` 作为入口 / 编排脚本，主体是松散语句或示例脚本外壳。 - `UserAccount.tsf` 中定义 `type UserAccount = class ... end;`. - `DocxEnumerations.tsf` 中定义 `unit DocxEnumerations; ... end.` - `ParseConfig.tsf` 中定义 `function ParseConfig(...)`. diff --git a/docs/tsl/reference/catalog/base.md b/docs/tsl/reference/catalog/base.md index e9de4685..07e0a6c1 100644 --- a/docs/tsl/reference/catalog/base.md +++ b/docs/tsl/reference/catalog/base.md @@ -1,720 +1,54 @@ # 基础函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实路由页 +是否可直接用于生成代码：是；进入分类详情页后按函数事实条目生成调用 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页是基础函数的轻量入口，不直接承载全部函数事实。生成函数调用时，先按分类目录进入详情页，再只读取命中的函数条目和参数表。 ## 模块范围 - 说明：字符串、数组、日期时间、类型转换与常用基础能力 -- 主题数：41 -- 函数数：574 - -## 主题目录 - -### 数字 - -- `FloatN` -- `FloatToStrEx` -- `FormatFloatExt` -- `WebZero` -- `RoundTo5` -- `SimpleRoundTo2` -- `DivValue` -- `Dataisequal` - -### 日期时间 - -- `ISO8601` - -### 日期时间 / 常用日期时间函数 - -- `Time` -- `DecodeTime` -- `DayOfWeek` -- `EncodeTime` -- `Now` -- `DecodeDate` -- `Date` -- `TryEncodeDate` -- `TryEncodeTime` -- `DecodeDateFully` -- `EncodeDate` -- `TryStrToDate` -- `StrToDateTimeDef` -- `DateTimeToInternetStr` -- `IncAMonth` -- `StrToTime` -- `CurrentYear` -- `TryStrToTime` -- `StrToDate` -- `DateTimeGMTToHttpStr` -- `DateToStr` -- `StrToTimeDef` -- `DateTimeToStr` -- `DateTimeToString` -- `Strtodatetime2` -- `FormatDateTime` -- `DateTimeGMTToCookieStr` -- `StrToDateTime` -- `IsLeapYear` -- `GMTToLocalDateTime` -- `TimeToStr` -- `StrToDateDef` -- `TryStrToDateTime` - -### 日期时间 / 简单转换函数 - -- `DateToInt` -- `IntToDate` -- `StrToDateExt` -- `ExcelIntToDate` -- `ExcelDateToInt` -- `FormatStrToDateTime2` - -### 日期时间 / 普通日期函数 - -- `IsInLeapYear` -- `IsPM` -- `IsValidDate` -- `IsValidTime` -- `IsValidDateTime` -- `IsValidDateDay` -- `IsValidDateWeek` -- `IsValidDateMonthWeek` -- `WeeksInYear` -- `WeeksInAYear` -- `DaysInYear` -- `DaysInAYear` -- `DaysInMonth` -- `DaysInAMonth` -- `Today` -- `Yesterday` -- `Tomorrow` -- `IsToday` -- `IsSameDay` - -### 日期时间 / 分解函数 - -- `DateOf` -- `TimeOf` -- `YearOf` -- `MonthOf` -- `DayOf` -- `HourOf` -- `MinuteOf` -- `SecondOf` -- `MilliSecondOf` - -### 日期时间 / 起始结束函数 - -- `StartOfTheYear` -- `EndOfTheYear` -- `StartOfAYear` -- `EndOfAYear` -- `StartOfTheMonth` -- `EndOfTheMonth` -- `StartOfAMonth` -- `EndOfAMonth` -- `StartOfTheWeek` -- `EndOfTheWeek` -- `StartOfAWeek` -- `EndOfAWeek` -- `StartOfTheDay` -- `EndOfTheDay` -- `StartOfADay` -- `EndOfADay` -- `StartOfTheHalfYear` -- `StartOfTheQuarter` -- `EndOfTheQuarter` -- `EndOfTheHalfYear` - -### 日期时间 / 关系函数 - -- `HourOfTheYear` -- `HourOfTheMonth` -- `MonthOfTheYear` -- `MilliSecondOfTheYear` -- `WeekOfTheYear` -- `WeekOfTheMonth` -- `MinuteOfTheYear` -- `SecondOfTheYear` -- `DayOfTheYear` -- `DayOfTheMonth` -- `SecondOfTheMinute` -- `HourOfTheWeek` -- `SecondOfTheMonth` -- `DayOfTheWeek` -- `MinuteOfTheDay` -- `MilliSecondOfTheSecond` -- `SecondOfTheWeek` -- `MinuteOfTheMonth` -- `MinuteOfTheHour` -- `MinuteOfTheWeek` -- `MilliSecondOfTheDay` -- `MilliSecondOfTheMonth` -- `HourOfTheDay` -- `MilliSecondOfTheHour` -- `SecondOfTheHour` -- `MilliSecondofTheMinute` -- `SecondOfTheDay` -- `MilliSecondOfTheWeek` - -### 日期时间 / 范围判定函数 - -- `WithinPastYears` -- `WithinPastMonths` -- `WithinPastWeeks` -- `WithinPastDays` -- `WithinPastHours` -- `WithinPastMinutes` -- `WithinPastSeconds` -- `WithinPastMilliSeconds` - -### 日期时间 / 范围获得函数 - -- `YearsBetween` -- `MonthsBetween` -- `WeeksBetween` -- `DaysBetween` -- `HoursBetween` -- `MinutesBetween` -- `SecondsBetween` -- `MilliSecondsBetween` - -### 日期时间 / 范围生成函数 - -- `YearSpan` -- `MonthSpan` -- `WeekSpan` -- `DaySpan` -- `HourSpan` -- `MinuteSpan` -- `SecondSpan` -- `MilliSecondSpan` - -### 日期时间 / 时间推移函数 - -- `IncYear` -- `IncHalfYear` -- `IncQuarter` -- `IncMonth` -- `IncWeek` -- `IncDay` -- `IncHour` -- `IncMinute` -- `IncSecond` -- `IncMilliSecond` - -### 日期时间 / 组合、分解日期函数 - -- `EncodeDateTime` -- `DecodeDateTime` -- `EncodeDateWeek` -- `DecodeDateWeek` -- `DecodeDateDay` -- `EncodeDateMonthWeek` -- `DecodeDateMonthWeek` -- `TryEncodeDateTime` -- `TryEncodeDateWeek` -- `TryEncodeDateDay` -- `TryEncodeDateMonthWeek` - -### 日期时间 / 日期重组函数 - -- `RecodeYear` -- `RecodeMonth` -- `RecodeDay` -- `RecodeHour` -- `RecodeMinute` -- `RecodeSecond` -- `RecodeMilliSecond` -- `RecodeDate` -- `RecodeTime` -- `RecodeDateTime` -- `TryRecodeDateTime` -- `CompareDateTime` -- `SameDateTime` -- `CompareDate` -- `SameDate` -- `CompareTime` -- `SameTime` -- `NthDayOfWeek` -- `DecodeDayOfWeekInMonth` -- `EncodeDayOfWeekInMonth` -- `TryEncodeDayOfWeekInMonth` - -### 日期时间 / 日期格式的转换 - -- `DateTimeToJulianDate` -- `JulianDateToDateTime` -- `TryJulianDateToDateTime` -- `DateTimeToModifiedJulianDate` -- `ModifiedJulianDateToDateTime` -- `TryModifiedJulianDateToDateTime` -- `DateTimeToUnix` -- `UnixToDateTime` -- `FileDateToDateTime` -- `DateTimeToFileDate` -- `ExcelRDate` - -### 日期时间 / 宽字节日期格式转换函数 - -- `DateTimeGMTToCookieStrw` -- `DateTimeGMTToHttpStrw` -- `DateTimeToInternetStrw` -- `Datetimetostrw` -- `TimetoStrw` -- `DateToStrw` - -### 字符串 / 常用字符串函数 - -- `StrCmp` -- `Chr` -- `WideChr` -- `Str2Array` -- `Concat` -- `Array2Str` -- `Format` -- `Ord` -- `SetLength` -- `CompareText` -- `Copy` -- `UpperCase` -- `LeftBStr` -- `RightBStr` -- `MidBStr` -- `GetFormatLocalCode` -- `Str` -- `RightStr` -- `CompareStr` -- `LeftStr` -- `Trim` -- `SameText` -- `SetChar` -- `AppendStr` -- `GetChar` -- `LowerCase` -- `SetFormatLocalCode` -- `Val` -- `Pos` -- `TrimRight` -- `AnsiFormat` -- `TrimLeft` -- `StrToIntDef` -- `FormatFloat` -- `StrToCurrDef` -- `Booltostr2` -- `StrToFloatDef` -- `IntToHex` -- `TryStrToInt` -- `FloatToStr` -- `TryStrToFloat` -- `FormatCurr` -- `TryStrToCurr` -- `StrToInt` -- `BoolToStr` -- `CurrToStr` -- `TryStrToBool` -- `SpaceByNumber` -- `IsValidIdent` -- `StrToBool` -- `StrToFloat` -- `StrToBoolDef` -- `IntToStr` -- `StrToCurr` -- `AnsiStr2Array` -- `TryUppercase` -- `TryLowercase` -- `SysEncodecryptStr` -- `Letters` -- `DecToInt64` -- `DecToInt64def` -- `TryDecToInt64` -- `DecToInt32` -- `DecToInt32def` -- `TryDecToInt32` -- `StrToInt64` -- `StrToInt64Def` -- `TryStrToInt64` -- `StrToInt32` -- `StrToInt32Def` -- `TryStrToInt32` -- `DecToInt` -- `DecToIntDef` -- `TryDecToInt` - -### 字符串 / 判定函数 - -- `AnsiContainsText` -- `AnsiStartsText` -- `AnsiEndsText` -- `AnsiMatchText` -- `AnsiContainsStr` -- `AnsiStartsStr` -- `AnsiEndsStr` -- `AnsiMatchStr` -- `FormatStrExt` - -### 字符串 / 替换以及处理函数 - -- `StuffString` -- `AnsiReplaceText` -- `AnsiReplaceStr` -- `ReplaceText` -- `ReplaceStr` -- `WrapText` -- `AdjustLineBreaks` -- `ReverseString` -- `SeprateStrToTotal` -- `TotalStrToSeprate` -- `DateStrToArr` -- `RdateStrToArr` - -### 字符串 / 字符串数组相关函数 - -- `AnsiIndexText` -- `AnsiIndexStr` - -### 字符串 / 重复函数 - -- `DupeString` - -### 字符串 / 多字节语言支持函数 - -- `LengthW` -- `MidStr` - -### 字符串 / 字节函数 - -- `ContainsText` -- `StartsText` -- `EndsText` -- `ContainsStr` -- `StartsStr` -- `EndsStr` -- `StuffbString` -- `ReversebString` - -### 字符串 / 发音相关函数 - -- `SoundEx` -- `SoundexInt` -- `DecodeSoundexInt` -- `SoundexWord` -- `DecodeSoundexWord` -- `SoundexSimilar` -- `SoundexCompare` -- `SoundexProc` -- `AnsiResemblesText` - -### 字符串 / 正则表达式函数 - -- `ParseRegExpr` -- `GetLikeFlag` -- `SetLikeFlag` -- `ReplaceStrByReg` -- `ReplaceTextByReg` -- `ParseRegExpr3` - -### 字符串 / 多语言支持函数 - -- `NextCharIndex` -- `AnsiToUTF8` -- `UTF8ToAnsi` -- `CharToByteIndex` -- `ByteToCharLen` -- `AnsiQuotedStr` -- `AnsiPos` -- `AnsiDequotedStr` -- `CharToByteLen` -- `CharLength` -- `ByteToCharIndex` -- `ByteType` -- `Booltostrw` -- `UnicodeESC` -- `unUnicodeESC2` -- `FloattoStrw` -- `UnicodeESC2` -- `unUnicodeESCw` -- `UnicodetoUTF8` -- `CurrtoStrw` -- `Inttostrw` -- `Booltostrw2` -- `Strw` -- `Inttohexw` -- `LCMapString` -- `MultibytetoUnicodew` -- `UTF8toUnicode` -- `Exportjsonstring` -- `unUnicodeESC2w` -- `unUnicodeESC` -- `Ifwstring` -- `Importjsonstring` -- `ExportJsonStringUTF8` -- `ExportJSONStringMBCS` - -### 字符串 / 文件名以及目录名相关处理函数 - -- `ChangeFileExt` -- `ExtractFilePath` -- `ExtractFileDir` -- `ExtractFileDrive` -- `ExtractFileName` -- `ExtractFileExt` -- `ExtractRelativePath` -- `IsPathDelimiter` -- `IsDelimiter` -- `IncludeTrailingPathDelimiter` -- `IncludeTrailingBackslash` -- `ExcludeTrailingPathDelimiter` -- `ExcludeTrailingBackslash` -- `LastDelimiter` -- `AnsiCompareFileName` -- `SameFileName` -- `AnsiLowerCaseFileName` -- `AnsiUpperCaseFileName` - -### 字符串 / 其它 - -- `GetPYStringList` -- `HztoPY` -- `DataUnitConversion` - -### 数组 / 基本 - -- `FieldCount` -- `FieldExist` -- `FieldNames` -- `FieldName` -- `IsTable` -- `MagicSetArray` -- `NoRecordTable` -- `MagicGetArray` -- `RecordExist` -- `RecordExist2` -- `RecordExist3` -- `FieldNamesOfStrSubscript` -- `StrSubscriptTableToNormal` -- `FieldCountOfStrSubscript` -- `argmax` -- `Argmin` -- `PasswordGen` - -### 数组 / 数组下标以及长度相关函数 - -- `GetStrIndexNum` -- `GetStrIndexs` -- `GetIntIndexs` -- `GetAllIndexs` -- `DeleteIndex` -- `DeleteField` -- `Length` - -### 数组 / 排序函数 - -- `RankIt` -- `RankIt2` -- `RPSIt` -- `SortTableByFieldExt` -- `RankValue` -- `SortArray` -- `SortTableByField` -- `argsort` - -### 数组 / 增删改查 - -- `AppendArray` -- `SeekPosInArray` -- `StockAmount` -- `DeleteNILValueByField` -- `FilterIn` -- `FilterNotIn` -- `IN1` -- `searchsorted` -- `argconfirst` -- `DeleteColumnByField` -- `Inserttablebyrno` -- `GetValuesByFieldValue` -- `Arrayextend` -- `Arrayinsert` -- `Frameinsert` - -### 数组 / 数组操作 - -- `OutPutTableToCanBeUnderstood` -- `SeperateTable` -- `Unitary` -- `Reverse` -- `DescartesJoin` -- `TableVectorizeArray` -- `DataProcess_MF` -- `AbnormalData` -- `QKsplit_Trailing` -- `QKsplit_Resampling` -- `WebFormatToRung` -- `RPSValue` -- `ZValue` -- `QKsplit_ToDate` -- `GroupByFieldValue` -- `FilterOneDimEx2` -- `GroupRankIt` -- `ElementWhere` -- `Histogram` -- `FrameGetSubByReg` -- `Factorize` -- `GroupPercentrankIt` -- `SparseMatFill` -- `ArrayAddGap` -- `dumies_decode` -- `GroupTransformByFunc` -- `Framedrop_duplicates` -- `Field_ReSortCols` -- `Framedrop_na` -- `Framemerge` -- `Frameqcut` -- `Frameupdate` -- `GroupZscoreIt` -- `get_dummies` -- `get_dummies2` -- `framePivot_table` -- `framecut` -- `frameMelt` -- `GroupDemeanIt` -- `ArrDropDuplicate` - -### 数组 / 数组取值 - -- `ColumnValue` -- `GetSubTableByField` -- `GetTopN` -- `FilterTableEx` -- `ColumnValue2` -- `GetBottomN` -- `FilterOneDimEx` -- `GetDistinctValue` -- `GetMiddleN` -- `FilterTable` -- `GetSubField` -- `GetSubTable` -- `Arraygetdefault` -- `Arraysetdefault` -- `Arraysetdefault2` -- `Randomchoice` - -### 数组 / 集合运算 - -- `MergeArray` -- `FilterIntersectionPart` -- `FilterIntersectionPart2` -- `DistinctStr` -- `IntersectionPart` -- `QuickIntersectionPart` -- `Frameconcat` - -### 数组 / 统计函数 - -- `GeoMeanByColumn` -- `SumValueByColumn` -- `AverageValueByColumn` -- `PercentValueByField` -- `MedianByColumn` -- `VarByColumn` -- `SumValueByColumn2` -- `SkewByColumn` -- `AveDevByColumn` -- `SumValueByRow2` -- `MaxValueByColumn` -- `DevsqByColumn` -- `KurtByColumn` -- `SumValueByRow` -- `HarMeanByColumn` -- `StatByColumn` -- `AverageByColumn` -- `StdevByColumn` -- `MinValueByColumn` -- `Describe` -- `Framecorrel` -- `Framecov` -- `Framehhi` -- `Framelag_zf` -- `Framepct_change` -- `Framevaluecounts` -- `Simpledescribe` - -### 数组 / 重构函数 - -- `NormalTabletoStrSubscript` -- `RenameField` -- `Field_AddSuffix` -- `RenameFieldByFormat` -- `Field_AddPrefix` -- `ReIndex` -- `ReIndexCopy` -- `Reshape` -- `Frame_addprefix` -- `Frame_addsuffix` - -### 数组 / 稀疏矩阵 - -- `Sparse1` -- `Sparse2` -- `Speye` -- `Sprand1` -- `Sprand2` -- `Sprandn1` -- `Sprandn2` -- `Sprandsym1` -- `Sprandsym2` -- `Sparsefull` -- `Spones` -- `Spnnz` -- `Spnonzeros` -- `Ifsparse` -- `Spdiags1` -- `Spdiags2` -- `Spdiags3` -- `Spdiags4` - -### 数组 / 数据比较 - -- `TwoRDateCompare_M1` -- `CompareDataOfDifferentDataProvider` - -### 数组 / 表格显示 - -- `Pivot` -- `Pivot_table` -- `Show3DTable` -- `Show2DTable` -- `ShowTableByField` -- `ShowTableByUnit` -- `ShowTableByInverse` -- `QuickRecordExist` -- `RotateTable` -- `NonIntersectionPart` -- `FooterValue` -- `FooterAverage` -- `FooterSum` -- `SetRowDefaultValue` -- `InverseTable` -- `GetSubTableByKey` -- `TableSelect` -- `TableType` -- `GetSubTableFreeParam` -- `ExpandTable` - -### 数组 / 数组下标 - -- `frameIndex_filter` -- `frameIndex_getilocDZ` +- 函数事实数：369 + +## 智能体检索规则 + +1. 用户只描述能力时，先按“分类目录”选择候选详情页。 +2. 用户给出函数名时，优先在 `base/` 子目录中搜索三级函数标题。 +3. 只读取命中的函数条目、相邻分类标题和必要参数表；不要把同页其它函数混进当前调用。 +4. 没有命中函数事实条目时，不要发明函数名；回到 [../index.md](../index.md) 或项目实际代码确认。 + +## 分类目录 + +| 分类 | 详情页 | 函数事实数 | +| ---------------------------- | ------------------------------------------------------------------------------ | ---------: | +| 常用日期时间函数 | [base/01_common_datetime.md](base/01_common_datetime.md) | 32 | +| 简单转换函数 | [base/02_simple_conversion.md](base/02_simple_conversion.md) | 2 | +| 普通日期函数 | [base/03_date_basic.md](base/03_date_basic.md) | 19 | +| 分解函数 | [base/04_datetime_parts.md](base/04_datetime_parts.md) | 9 | +| 起始结束函数 | [base/05_datetime_boundaries.md](base/05_datetime_boundaries.md) | 16 | +| 关系函数 | [base/06_datetime_relations.md](base/06_datetime_relations.md) | 28 | +| 范围判定函数 | [base/07_range_predicates.md](base/07_range_predicates.md) | 8 | +| 范围获得函数 | [base/08_range_getters.md](base/08_range_getters.md) | 8 | +| 范围生成函数 | [base/09_range_span.md](base/09_range_span.md) | 8 | +| 时间推移函数 | [base/10_time_shift.md](base/10_time_shift.md) | 8 | +| 组合、分解日期函数 | [base/11_compose_decompose_datetime.md](base/11_compose_decompose_datetime.md) | 11 | +| 日期重组函数 | [base/12_datetime_recode.md](base/12_datetime_recode.md) | 21 | +| 日期格式的转换 | [base/13_datetime_format_conversion.md](base/13_datetime_format_conversion.md) | 10 | +| 宽字节日期格式转换函数 | [base/14_wide_datetime_conversion.md](base/14_wide_datetime_conversion.md) | 6 | +| 常用字符串函数 | [base/15_string_common.md](base/15_string_common.md) | 69 | +| 判定函数 | [base/16_string_predicates.md](base/16_string_predicates.md) | 8 | +| 替换以及处理函数 | [base/17_string_replace_process.md](base/17_string_replace_process.md) | 8 | +| 字符串数组相关函数 | [base/18_string_array.md](base/18_string_array.md) | 2 | +| 重复函数 | [base/19_repeat.md](base/19_repeat.md) | 1 | +| 多字节语言支持函数 | [base/20_multibyte_language.md](base/20_multibyte_language.md) | 2 | +| 字节函数 | [base/21_byte.md](base/21_byte.md) | 8 | +| 发音相关函数 | [base/22_phonetic.md](base/22_phonetic.md) | 10 | +| 正则表达式函数 | [base/23_regex.md](base/23_regex.md) | 3 | +| 多语言支持函数 | [base/24_multilanguage.md](base/24_multilanguage.md) | 33 | +| 文件名以及目录名相关处理函数 | [base/25_path_filename.md](base/25_path_filename.md) | 18 | +| 基本 | [base/26_array_basic.md](base/26_array_basic.md) | 4 | +| 数组下标以及长度相关函数 | [base/27_array_index_length.md](base/27_array_index_length.md) | 7 | +| 排序函数 | [base/28_array_sort.md](base/28_array_sort.md) | 2 | +| 增删改查 | [base/29_array_crud.md](base/29_array_crud.md) | 6 | +| 重构函数 | [base/30_array_restructure.md](base/30_array_restructure.md) | 2 | diff --git a/docs/tsl/reference/catalog/base/01_common_datetime.md b/docs/tsl/reference/catalog/base/01_common_datetime.md new file mode 100644 index 00000000..b815ea19 --- /dev/null +++ b/docs/tsl/reference/catalog/base/01_common_datetime.md @@ -0,0 +1,391 @@ +# 基础函数 - 常用日期时间函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 常用日期时间函数 + +### `time()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `decodeTime(value, hour, minute, second, millisecond)` + +用途：日期时间处理函数。 + +参数个数：5 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `hour` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `hour` | +| 3 | `minute` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `min` | +| 4 | `second` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `sec` | +| 5 | `millisecond` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `msec` | + +### `dayOfWeek(value)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `encodeTime(hour, minute, second, millisecond)` + +用途：日期时间处理函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------- | +| 1 | `hour` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `minute` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `second` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `millisecond` | 是 | 整数 | 按源文档示例顺序传入 | + +### `now()` + +用途：日期时间相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `decodeDate(value, year, month, day)` + +用途：日期时间处理函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `year` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `year` | +| 3 | `month` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `month` | +| 4 | `day` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `day` | + +### `date()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tryEncodeDate(year, month, day, out_date)` + +用途：日期时间处理函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ----------------------------------------------- | +| 1 | `year` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `month` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `day` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `out_date` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `date` | + +### `tryEncodeTime(hour, minute, second, millisecond, out_time)` + +用途：日期时间处理函数。 + +参数个数：5 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `hour` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `minute` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `second` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `millisecond` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `out_time` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `time` | + +### `decodeDateFully(value, year, month, day, day_of_week)` + +用途：日期时间处理函数。 + +参数个数：5 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `year` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `year` | +| 3 | `month` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `month` | +| 4 | `day` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `day` | +| 5 | `day_of_week` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `dow` | + +### `encodeDate(year, month, day)` + +用途：日期时间处理函数。 + +参数个数：3 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `year` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `month` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `day` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryStrToDate(value, out_date)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ----------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `out_date` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `date` | + +### `strToDateTimeDef(value, default_value)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `default_value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateTimeToInternetStr(end_t, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incAMonth(year, month, day, arg4)` + +用途：常用日期时间函数相关函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `year` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `month` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `day` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `strToTime(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `currentYear()` + +用途：日期时间相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tryStrToTime(value, out_time)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ----------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `out_time` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `time` | + +### `strToDate(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `dateTimeGMTToHttpStr(end_t)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateToStr(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `strToTimeDef(value, default_value)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `default_value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateTimeToStr(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateTimeToString(out_text, format_text, value)` + +用途：将输入值转换为字符串。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------- | +| 1 | `out_text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `format_text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `formatDateTime(format_text, value)` + +用途：按指定格式输出结果。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------- | +| 1 | `format_text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateTimeGMTToCookieStr(end_t)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `strToDateTime(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `isLeapYear(year)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `year` | 是 | 整数 | 按源文档示例顺序传入 | + +### `gmtToLocalDateTime(gmt)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `gmt` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `timeToStr(value)` + +用途：常用日期时间函数相关函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | + +### `strToDateDef(value, default_value)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `default_value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `tryStrToDateTime(value, out_datetime)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | --------------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `out_datetime` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `datetime` | diff --git a/docs/tsl/reference/catalog/base/02_simple_conversion.md b/docs/tsl/reference/catalog/base/02_simple_conversion.md new file mode 100644 index 00000000..bad6f7ff --- /dev/null +++ b/docs/tsl/reference/catalog/base/02_simple_conversion.md @@ -0,0 +1,29 @@ +# 基础函数 - 简单转换函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 简单转换函数 + +### `dateToInt(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | + +### `intToDate(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/03_date_basic.md b/docs/tsl/reference/catalog/base/03_date_basic.md new file mode 100644 index 00000000..d1fe96a5 --- /dev/null +++ b/docs/tsl/reference/catalog/base/03_date_basic.md @@ -0,0 +1,232 @@ +# 基础函数 - 普通日期函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 普通日期函数 + +### `isInLeapYear(date)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `date` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `isPM(arg1)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `isValidDate(value, arg2, arg3)` + +用途：判断条件是否成立。 + +参数个数：3 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isValidTime(value, arg2, arg3, arg4)` + +用途：判断条件是否成立。 + +参数个数：4 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isValidDateTime(value, arg2, arg3, arg4, arg5, arg6, arg7)` + +用途：判断条件是否成立。 + +参数个数：7 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isValidDateDay(value, arg2)` + +用途：判断条件是否成立。 + +参数个数：2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isValidDateWeek(value, arg2, arg3)` + +用途：判断条件是否成立。 + +参数个数：3 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isValidDateMonthWeek(value, arg2, arg3, arg4)` + +用途：判断条件是否成立。 + +参数个数：4 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `weeksInYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `weeksInAYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `daysInYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `daysInAYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `daysInMonth(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `daysInAMonth(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `today()` + +用途：日期时间相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `yesterday()` + +用途：日期时间相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tomorrow()` + +用途：日期时间相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `isToday(aday)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `aday` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isSameDay(aday, today)` + +用途：判断条件是否成立。 + +参数个数：2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `aday` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `today` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/04_datetime_parts.md b/docs/tsl/reference/catalog/base/04_datetime_parts.md new file mode 100644 index 00000000..ad804eed --- /dev/null +++ b/docs/tsl/reference/catalog/base/04_datetime_parts.md @@ -0,0 +1,106 @@ +# 基础函数 - 分解函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 分解函数 + +### `dateOf(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `timeOf(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `yearOf(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `monthOf(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dayOf(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `hourOf(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `minuteOf(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondOf(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondOf(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/05_datetime_boundaries.md b/docs/tsl/reference/catalog/base/05_datetime_boundaries.md new file mode 100644 index 00000000..3818a177 --- /dev/null +++ b/docs/tsl/reference/catalog/base/05_datetime_boundaries.md @@ -0,0 +1,193 @@ +# 基础函数 - 起始结束函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 起始结束函数 + +### `startOfTheYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `endOfTheYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `startOfAYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `endOfAYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `startOfTheMonth(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `endOfTheMonth(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `startOfAMonth(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `endOfAMonth(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `startOfTheWeek(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `endOfTheWeek(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `startOfAWeek(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `endOfAWeek(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `startOfTheDay(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `endOfTheDay(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `startOfADay(arg1, arg2, arg3)` + +用途：起始结束函数相关函数。 + +参数个数：3 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `endOfADay(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/06_datetime_relations.md b/docs/tsl/reference/catalog/base/06_datetime_relations.md new file mode 100644 index 00000000..f126da33 --- /dev/null +++ b/docs/tsl/reference/catalog/base/06_datetime_relations.md @@ -0,0 +1,317 @@ +# 基础函数 - 关系函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 关系函数 + +### `hourOfTheYear(arg1)` + +用途：关系函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `hourOfTheMonth(arg1)` + +用途：关系函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `monthOfTheYear(arg1)` + +用途：关系函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondOfTheYear(arg1)` + +用途：关系函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `weekOfTheYear(arg1)` + +用途：关系函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `weekOfTheMonth(avalue, ayear, amonth)` + +用途：关系函数相关函数。 + +参数个数：3 +返回值：整数，值域是[1，6] + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------------------- | +| 1 | `avalue` | 是 | 任意值 | TDateTime类型，日期时间 | +| 2 | `ayear` | 是 | 整数 | 整数，年，返回值 | +| 3 | `amonth` | 是 | 整数 | 整数，月，返回值 | + +### `minuteOfTheYear(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondOfTheYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dayOfTheYear(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dayOfTheMonth(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondOfTheMinute(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `hourOfTheWeek(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondOfTheMonth(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dayOfTheWeek(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `minuteOfTheDay(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondOfTheSecond(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondOfTheWeek(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `minuteOfTheMonth(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `minuteOfTheHour(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `minuteOfTheWeek(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondOfTheDay(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondOfTheMonth(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `hourOfTheDay(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondOfTheHour(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondOfTheHour(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondofTheMinute(arg1)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondOfTheDay(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondOfTheWeek(arg1)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/07_range_predicates.md b/docs/tsl/reference/catalog/base/07_range_predicates.md new file mode 100644 index 00000000..23ced582 --- /dev/null +++ b/docs/tsl/reference/catalog/base/07_range_predicates.md @@ -0,0 +1,111 @@ +# 基础函数 - 范围判定函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 范围判定函数 + +### `withinPastYears(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `withinPastMonths(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `withinPastWeeks(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `withinPastDays(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `withinPastHours(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `withinPastMinutes(arg1, arg2, arg3)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `withinPastSeconds(arg1, arg2, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `withinPastMilliSeconds(anow, athen, arg3)` + +用途：日期时间相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `anow` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `athen` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/08_range_getters.md b/docs/tsl/reference/catalog/base/08_range_getters.md new file mode 100644 index 00000000..4c3f9740 --- /dev/null +++ b/docs/tsl/reference/catalog/base/08_range_getters.md @@ -0,0 +1,103 @@ +# 基础函数 - 范围获得函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 范围获得函数 + +### `yearsBetween(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `monthsBetween(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `weeksBetween(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `daysBetween(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `hoursBetween(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `minutesBetween(arg1, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondsBetween(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondsBetween(beg_t, end_t)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `beg_t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/09_range_span.md b/docs/tsl/reference/catalog/base/09_range_span.md new file mode 100644 index 00000000..62f8c3e0 --- /dev/null +++ b/docs/tsl/reference/catalog/base/09_range_span.md @@ -0,0 +1,101 @@ +# 基础函数 - 范围生成函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 范围生成函数 + +### `yearSpan(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `monthSpan(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `weekSpan(beg_t, end_t)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `beg_t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `daySpan(beg_t, end_t)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `beg_t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `hourSpan(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `minuteSpan(beg_t, end_t)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `beg_t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secondSpan(beg_t, end_t)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `beg_t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `milliSecondSpan()` + +用途：范围生成函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/base/10_time_shift.md b/docs/tsl/reference/catalog/base/10_time_shift.md new file mode 100644 index 00000000..1ccee605 --- /dev/null +++ b/docs/tsl/reference/catalog/base/10_time_shift.md @@ -0,0 +1,103 @@ +# 基础函数 - 时间推移函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 时间推移函数 + +### `incYear(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incMonth(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incWeek(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incDay(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incHour(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incMinute(arg1, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incSecond(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `incMilliSecond(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/11_compose_decompose_datetime.md b/docs/tsl/reference/catalog/base/11_compose_decompose_datetime.md new file mode 100644 index 00000000..3a10a678 --- /dev/null +++ b/docs/tsl/reference/catalog/base/11_compose_decompose_datetime.md @@ -0,0 +1,171 @@ +# 基础函数 - 组合、分解日期函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 组合、分解日期函数 + +### `encodeDateTime(value, arg2, arg3, arg4, arg5, arg6, arg7)` + +用途：日期时间处理函数。 + +参数个数：7 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入 | + +### `decodeDateTime(end_t, year, month, day, hour, minute, second, millisecond)` + +用途：日期时间处理函数。 + +参数个数：8 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------------------------------------------ | +| 1 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `year` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `year` | +| 3 | `month` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `month` | +| 4 | `day` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `day` | +| 5 | `hour` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `hour` | +| 6 | `minute` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `minute` | +| 7 | `second` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `second` | +| 8 | `millisecond` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `millisecond` | + +### `encodeDateWeek(value, arg2, arg3)` + +用途：日期时间处理函数。 + +参数个数：3 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `decodeDateWeek(value, year, weekofyear, dayofweek)` + +用途：日期时间处理函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ----------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `year` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `year` | +| 3 | `weekofyear` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `weekofyear` | +| 4 | `dayofweek` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `dayofweek` | + +### `decodeDateDay(value, year, dayofyear)` + +用途：日期时间处理函数。 + +参数个数：3 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ---------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `year` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `year` | +| 3 | `dayofyear` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `dayofyear` | + +### `encodeDateMonthWeek(value, arg2, arg3, arg4)` + +用途：日期时间处理函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `decodeDateMonthWeek(value, year, month, weekof_month, day_of_week1)` + +用途：日期时间处理函数。 + +参数个数：5 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------------------------------------ | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `year` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `year` | +| 3 | `month` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `month` | +| 4 | `weekof_month` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `weekofMonth` | +| 5 | `day_of_week1` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `dayOfWeek1` | + +### `tryEncodeDateTime(value, arg2, arg3, arg4, arg5, arg6, arg7, atime)` + +用途：日期时间处理函数。 + +参数个数：8 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入 | +| 8 | `atime` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Atime` | + +### `tryEncodeDateWeek(value, arg2, atime, arg4)` + +用途：日期时间处理函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `atime` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Atime` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryEncodeDateDay(value, arg2, atime)` + +用途：日期时间处理函数。 + +参数个数：3 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `atime` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Atime` | + +### `tryEncodeDateMonthWeek(value, arg2, arg3, arg4, atime)` + +用途：日期时间处理函数。 + +参数个数：5 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `atime` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Atime` | diff --git a/docs/tsl/reference/catalog/base/12_datetime_recode.md b/docs/tsl/reference/catalog/base/12_datetime_recode.md new file mode 100644 index 00000000..dc0d000c --- /dev/null +++ b/docs/tsl/reference/catalog/base/12_datetime_recode.md @@ -0,0 +1,284 @@ +# 基础函数 - 日期重组函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 日期重组函数 + +### `recodeYear(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeMonth(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeDay(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeHour(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeMinute(arg1, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeSecond(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeMilliSecond(arg1, arg2)` + +用途：日期时间相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeDate(value, arg2, arg3, arg4)` + +用途：日期时间处理函数。 + +参数个数：4 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeTime(value, arg2, arg3, arg4, arg5)` + +用途：日期时间处理函数。 + +参数个数：5 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | + +### `recodeDateTime(value, arg2, arg3, arg4, arg5, arg6, arg7, arg8)` + +用途：日期时间处理函数。 + +参数个数：8 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入 | +| 8 | `arg8` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryRecodeDateTime(value, arg2, arg3, arg4, arg5, arg6, arg7, arg8, aresult)` + +用途：日期时间处理函数。 + +参数个数：9 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入 | +| 8 | `arg8` | 是 | 整数 | 按源文档示例顺序传入 | +| 9 | `aresult` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Aresult` | + +### `compareDateTime(value, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sameDateTime(value, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `compareDate(value, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sameDate(value, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `compareTime(value, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sameTime(value, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `nthDayOfWeek(end_t)` + +用途：日期时间相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `decodeDayOfWeekInMonth(endt, ayear, amonth, anth_day_of_week, aday_of_week)` + +用途：日期时间相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | -------- | -------------------------------------------------------- | +| 1 | `endt` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `ayear` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `Ayear` | +| 3 | `amonth` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `Amonth` | +| 4 | `anth_day_of_week` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `ANthDayOfWeek` | +| 5 | `aday_of_week` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `ADayOfWeek` | + +### `encodeDayOfWeekInMonth(arg1, arg2, arg3, arg4)` + +用途：日期时间相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryEncodeDayOfWeekInMonth(arg1, arg2, arg3, arg4, newtime)` + +用途：日期时间相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `newtime` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `newtime` | diff --git a/docs/tsl/reference/catalog/base/13_datetime_format_conversion.md b/docs/tsl/reference/catalog/base/13_datetime_format_conversion.md new file mode 100644 index 00000000..aaf4e341 --- /dev/null +++ b/docs/tsl/reference/catalog/base/13_datetime_format_conversion.md @@ -0,0 +1,119 @@ +# 基础函数 - 日期格式的转换 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 日期格式的转换 + +### `dateTimeToJulianDate(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `julianDateToDateTime(value)` + +用途：日期格式的转换相关函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | + +### `tryJulianDateToDateTime(value, t)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------------------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `t` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `T` | + +### `dateTimeToModifiedJulianDate(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `modifiedJulianDateToDateTime(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | + +### `tryModifiedJulianDateToDateTime(value, t)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------------------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `t` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `t` | + +### `dateTimeToUnix(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `unixToDateTime(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | + +### `fileDateToDateTime(filename)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `dateTimeToFileDate(end_t)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `end_t` | 是 | 任意值 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/14_wide_datetime_conversion.md b/docs/tsl/reference/catalog/base/14_wide_datetime_conversion.md new file mode 100644 index 00000000..cb1063a9 --- /dev/null +++ b/docs/tsl/reference/catalog/base/14_wide_datetime_conversion.md @@ -0,0 +1,74 @@ +# 基础函数 - 宽字节日期格式转换函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 宽字节日期格式转换函数 + +### `dateTimeGMTToCookieStrw(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateTimeGMTToHttpStrw(value)` + +用途：日期时间处理函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateTimeToInternetStrw(value, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `datetimetostrw(value)` + +用途：宽字节日期格式转换函数相关函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `timetoStrw(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `dateToStrw(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 日期 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/15_string_common.md b/docs/tsl/reference/catalog/base/15_string_common.md new file mode 100644 index 00000000..4560e2b1 --- /dev/null +++ b/docs/tsl/reference/catalog/base/15_string_common.md @@ -0,0 +1,818 @@ +# 基础函数 - 常用字符串函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 常用字符串函数 + +### `strCmp(value, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `chr(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `wideChr(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `str2Array(array_value, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------- | +| 1 | `array_value` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `concat(arg1, arg2[, arg3][, arg4])` + +用途：字符串相关函数。 + +参数个数：2 到 4 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `array2Str(arr, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `format(arg1, arg2[, arg3][, arg4])` + +用途：按指定格式输出结果。 + +参数个数：2 到 4 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数/实数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 整数 | 按源文档示例顺序传入 | + +### `ord(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `setLength(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `compareText(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `copy(arg1, arg2, arg3)` + +用途：字符串相关函数。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `upperCase(arg1)` + +用途：进行大小写转换。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `leftBStr(value, arg2)` + +用途：进行字符串提取或替换处理。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `rightBStr(value, arg2)` + +用途：进行字符串提取或替换处理。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `midBStr(value, arg2, arg3)` + +用途：常用字符串函数相关函数。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `getFormatLocalCode()` + +用途：按指定格式输出结果。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `str(value, s)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------------------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `s` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `s` | + +### `rightStr(value, arg2)` + +用途：进行字符串提取或替换处理。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `compareStr(value, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `leftStr(value, arg2)` + +用途：进行字符串提取或替换处理。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `trim(arg1)` + +用途：去除字符串首尾空白字符（空格、换行等）。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------- | +| 1 | `arg1` | 是 | 字符串 | s（字符串） | + +### `sameText(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `setChar(arr, arg2, arg3)` + +用途：字符串相关函数。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `appendStr(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `getChar(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `lowerCase(arg1)` + +用途：进行大小写转换。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `setFormatLocalCode(arg1)` + +用途：按指定格式输出结果。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `val(arg1, v, code)` + +用途：字符串相关函数。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | +| 3 | `code` | 是 | 字符串 | 按源文档示例顺序传入；源文档示例传入变量 `Code` | + +### `pos(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `trimRight(arg1)` + +用途：去除字符串末尾空白字符。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------- | +| 1 | `arg1` | 是 | 字符串 | s（字符串） | + +### `trimLeft(arg1)` + +用途：去除字符串开头空白字符。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------- | +| 1 | `arg1` | 是 | 字符串 | s（字符串） | + +### `strToIntDef(value, arg2)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `formatFloat(arg1, arg2)` + +用途：按指定格式输出结果。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `strToCurrDef(value, arg2)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `booltostr2(value)` + +用途：常用字符串函数相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `strToFloatDef(value, arg2)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `intToHex(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryStrToInt(value, value)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `value` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `value` | + +### `floatToStr(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | + +### `tryStrToFloat(value, s)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `s` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `s` | + +### `formatCurr(arg1, arg2)` + +用途：按指定格式输出结果。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | + +### `tryStrToCurr(value, s)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `s` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `s` | + +### `strToInt(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `boolToStr(value, arg2)` + +用途：将输入值转换为字符串。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `currToStr(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | + +### `tryStrToBool(value, s)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `s` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `s` | + +### `isValidIdent(arg1)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `strToBool(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `strToFloat(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `strToBoolDef(value, arg2)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `intToStr(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | + +### `strToCurr(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiStr2Array(array_value, arg2)` + +用途：常用字符串函数相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------- | +| 1 | `array_value` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sysEncodecryptStr(s, arg2)` + +用途：常用字符串函数相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `decToInt64(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `decToInt64def(arg1, arg2)` + +用途：常用字符串函数相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryDecToInt64(arg1, value)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `value` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `value` | + +### `decToInt32(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `decToInt32def(arg1, arg2)` + +用途：常用字符串函数相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryDecToInt32(arg1, value)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `value` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `value` | + +### `strToInt64(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `strToInt64Def(value, arg2)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryStrToInt64(value, value)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `value` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `value` | + +### `strToInt32(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `strToInt32Def(value, arg2)` + +用途：将字符串转换为对应类型。 + +参数个数：2 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryStrToInt32(value, value)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `value` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `value` | + +### `decToInt(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `decToIntDef(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tryDecToInt(arg1, value)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `value` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `value` | diff --git a/docs/tsl/reference/catalog/base/16_string_predicates.md b/docs/tsl/reference/catalog/base/16_string_predicates.md new file mode 100644 index 00000000..a116e365 --- /dev/null +++ b/docs/tsl/reference/catalog/base/16_string_predicates.md @@ -0,0 +1,103 @@ +# 基础函数 - 判定函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 判定函数 + +### `ansiContainsText(text, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiStartsText(arg1, text)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiEndsText(arg1, text)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiMatchText(atext, avalues)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `avalues` | 是 | 数组 | 按源文档示例顺序传入 | + +### `ansiContainsStr(atext, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiStartsStr(value, atext)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiEndsStr(value, text)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiMatchStr(atext, avalues)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `avalues` | 是 | 数组 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/17_string_replace_process.md b/docs/tsl/reference/catalog/base/17_string_replace_process.md new file mode 100644 index 00000000..735643b9 --- /dev/null +++ b/docs/tsl/reference/catalog/base/17_string_replace_process.md @@ -0,0 +1,108 @@ +# 基础函数 - 替换以及处理函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 替换以及处理函数 + +### `stuffString(atext, arg2, arg3, asub_text)` + +用途：字符串相关函数。 + +参数个数：4 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `asub_text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiReplaceText(atext, afrom_text, ato_text)` + +用途：进行字符串提取或替换处理。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `afrom_text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `ato_text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiReplaceStr(atext, afrom_text, ato_text)` + +用途：进行字符串提取或替换处理。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `afrom_text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `ato_text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `replaceText(atext, afrom_text, ato_text)` + +用途：进行字符串提取或替换处理。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `afrom_text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `ato_text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `replaceStr(atext, afrom_text, ato_text)` + +用途：进行字符串提取或替换处理。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `afrom_text` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `ato_text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `wrapText(const_line, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------- | +| 1 | `const_line` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `adjustLineBreaks(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ----------- | -------------------- | +| 1 | `arg1` | 是 | 字符串/数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `reverseString(value)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/18_string_array.md b/docs/tsl/reference/catalog/base/18_string_array.md new file mode 100644 index 00000000..1901df6c --- /dev/null +++ b/docs/tsl/reference/catalog/base/18_string_array.md @@ -0,0 +1,31 @@ +# 基础函数 - 字符串数组相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 字符串数组相关函数 + +### `ansiIndexText(eg_str, str_arr)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------- | +| 1 | `eg_str` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `str_arr` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiIndexStr(eg_str, str_arr)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------- | +| 1 | `eg_str` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `str_arr` | 是 | 字符串 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/19_repeat.md b/docs/tsl/reference/catalog/base/19_repeat.md new file mode 100644 index 00000000..14a3e29c --- /dev/null +++ b/docs/tsl/reference/catalog/base/19_repeat.md @@ -0,0 +1,19 @@ +# 基础函数 - 重复函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 重复函数 + +### `dupeString(value, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/20_multibyte_language.md b/docs/tsl/reference/catalog/base/20_multibyte_language.md new file mode 100644 index 00000000..94c64229 --- /dev/null +++ b/docs/tsl/reference/catalog/base/20_multibyte_language.md @@ -0,0 +1,31 @@ +# 基础函数 - 多字节语言支持函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 多字节语言支持函数 + +### `lengthW(test_str)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `test_str` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `midStr(test_str, arg2, arg3)` + +用途：字符串相关函数。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `test_str` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/21_byte.md b/docs/tsl/reference/catalog/base/21_byte.md new file mode 100644 index 00000000..8db5bdc1 --- /dev/null +++ b/docs/tsl/reference/catalog/base/21_byte.md @@ -0,0 +1,104 @@ +# 基础函数 - 字节函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 字节函数 + +### `containsText(a, b)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `startsText(arg1, text)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `endsText(arg1, text)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `containsStr(a, b)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `startsStr(value, atext)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `endsStr(value, text)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `stuffbString(atext, arg2, arg3, asub_text)` + +用途：字符串相关函数。 + +参数个数：4 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------- | +| 1 | `atext` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `asub_text` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `reversebString(a)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 任意值 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/22_phonetic.md b/docs/tsl/reference/catalog/base/22_phonetic.md new file mode 100644 index 00000000..78f36649 --- /dev/null +++ b/docs/tsl/reference/catalog/base/22_phonetic.md @@ -0,0 +1,122 @@ +# 基础函数 - 发音相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 发音相关函数 + +### `getPYStringList()` + +用途：获取拼音字符串列表对象。 + +参数个数：0 +返回值：拼音字符串列表对象 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `soundEx(test_str1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------- | +| 1 | `test_str1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `soundexInt(test_str1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------- | +| 1 | `test_str1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `decodeSoundexInt(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `soundexWord(arg1)` + +用途：发音相关函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `decodeSoundexWord(arg1)` + +用途：发音相关函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `soundexSimilar(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `soundexCompare(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `soundexProc(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiResemblesText(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/23_regex.md b/docs/tsl/reference/catalog/base/23_regex.md new file mode 100644 index 00000000..d9d8df96 --- /dev/null +++ b/docs/tsl/reference/catalog/base/23_regex.md @@ -0,0 +1,44 @@ +# 基础函数 - 正则表达式函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 正则表达式函数 + +### `parseRegExpr(arg1, source, arg3, result, mpos, mlen)` + +用途：正则表达式函数相关函数。 + +参数个数：6 +返回值：array(("hello tiny","tiny")) + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `source` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `result` | 是 | 变量引用 | 按源文档示例顺序传入；源文档示例传入变量 `result` | +| 5 | `mpos` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `MPos` | +| 6 | `mlen` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `Mlen` | + +### `getLikeFlag()` + +用途：正则表达式函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `setLikeFlag(arg1)` + +用途：正则表达式函数相关函数。 + +参数个数：1 +返回值：1 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/24_multilanguage.md b/docs/tsl/reference/catalog/base/24_multilanguage.md new file mode 100644 index 00000000..720e4553 --- /dev/null +++ b/docs/tsl/reference/catalog/base/24_multilanguage.md @@ -0,0 +1,383 @@ +# 基础函数 - 多语言支持函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 多语言支持函数 + +### `nextCharIndex(s, arg2)` + +用途：多语言支持函数相关函数。 + +参数个数：2 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `ansiToUTF8(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `utf8ToAnsi(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `charToByteIndex(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `byteToCharLen(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `ansiQuotedStr(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiPos(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiDequotedStr(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `charToByteLen(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `charLength(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `byteToCharIndex(s, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `byteType(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `booltostrw(value)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `unicodeESC(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `unUnicodeESC2(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `floattoStrw(value)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | + +### `unicodeESC2()` + +用途：多语言支持函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `unUnicodeESCw(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `unicodetoUTF8(arg1)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `currtoStrw(value)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | + +### `inttostrw(value)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 整数 | 按源文档示例顺序传入 | + +### `booltostrw2(value)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `strw(value, s)` + +用途：多语言支持函数相关函数。 + +参数个数：2 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------------------------------- | +| 1 | `value` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `s` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `s` | + +### `inttohexw(arg1, arg2)` + +用途：多语言支持函数相关函数。 + +参数个数：2 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `multibytetoUnicodew(arg1, arg2)` + +用途：多语言支持函数相关函数。 + +参数个数：2 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `utf8toUnicode(arg1)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `exportjsonstring(s)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 数组 | 按源文档示例顺序传入 | + +### `importjsonstring(json)` + +用途：将 JSON 字符串解析为 TSL 数据。 + +参数个数：1 +返回值：任意值；JSON 字符串返回字符串，JSON 整数返回整数，JSON 数组返回数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `json` | 是 | 字符串 | 待解析的 JSON 字符串 | + +### `unUnicodeESC2w(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `unUnicodeESC(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ifwstring(value[, arg2])` + +用途：多语言支持函数相关函数。 + +参数个数：1 到 2 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ---------------- | -------------------- | +| 1 | `value` | 是 | 整数/字符串/数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | + +### `exportJsonStringUTF8(a)` + +用途：多语言支持函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `exportJSONStringMBCS(s)` + +用途：将字符串或数组序列化为 JSON 字符串，保留中文原码（MBCS），不转义为 \\uXXXX。 + +参数个数：1 +返回值：JSON 字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `s` | 是 | 数组 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/25_path_filename.md b/docs/tsl/reference/catalog/base/25_path_filename.md new file mode 100644 index 00000000..38241940 --- /dev/null +++ b/docs/tsl/reference/catalog/base/25_path_filename.md @@ -0,0 +1,213 @@ +# 基础函数 - 文件名以及目录名相关处理函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 文件名以及目录名相关处理函数 + +### `changeFileExt(filename, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `extractFilePath(filename)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `extractFileDir(filename)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `extractFileDrive(filename)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `extractFileName(filename)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `extractFileExt(filename)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `extractRelativePath(path, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `isPathDelimiter(path, arg2)` + +用途：判断条件是否成立。 + +参数个数：2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isDelimiter(arg1, arg2, arg3)` + +用途：判断条件是否成立。 + +参数个数：3 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `includeTrailingPathDelimiter(path)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `includeTrailingBackslash(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `excludeTrailingPathDelimiter(path)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `excludeTrailingBackslash(arg1)` + +用途：字符串相关函数。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `lastDelimiter(arg1, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiCompareFileName(filename, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sameFileName(filename, arg2)` + +用途：字符串相关函数。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiLowerCaseFileName(filename)` + +用途：进行大小写转换。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `ansiUpperCaseFileName(filename)` + +用途：进行大小写转换。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/26_array_basic.md b/docs/tsl/reference/catalog/base/26_array_basic.md new file mode 100644 index 00000000..ee3636d9 --- /dev/null +++ b/docs/tsl/reference/catalog/base/26_array_basic.md @@ -0,0 +1,58 @@ +# 基础函数 - 基本 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 基本 + +### `noRecordTable()` + +用途：创建无记录表。 + +参数个数：0 +返回值：空数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `magicSetArray(a, arg2, arg3[, arg4])` + +用途：数组相关函数。 + +参数个数：3 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ----------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数/数组 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数/字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 整数 | 按源文档示例顺序传入 | + +### `magicGetArray(a, arg2[, arg3])` + +用途：基本相关函数。 + +参数个数：2 到 3 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数/数组 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 整数 | 按源文档示例顺序传入 | + +### `passwordGen(arg1, arg2, arg3, arg4)` + +用途：数组相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/27_array_index_length.md b/docs/tsl/reference/catalog/base/27_array_index_length.md new file mode 100644 index 00000000..6afabb08 --- /dev/null +++ b/docs/tsl/reference/catalog/base/27_array_index_length.md @@ -0,0 +1,88 @@ +# 基础函数 - 数组下标以及长度相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 数组下标以及长度相关函数 + +### `getStrIndexNum(arr)` + +用途：数组相关函数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | + +### `getStrIndexs(arr)` + +用途：数组相关函数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | + +### `getIntIndexs(arr)` + +用途：数组下标以及长度相关函数相关函数。 + +参数个数：1 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | + +### `getAllIndexs(arr)` + +用途：数组相关函数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | + +### `deleteIndex(arr, arg2, arg3)` + +用途：数组相关函数。 + +参数个数：3 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `deleteField(arr, arg2, arg3)` + +用途：数组相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `length(arr)` + +用途：数组相关函数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/28_array_sort.md b/docs/tsl/reference/catalog/base/28_array_sort.md new file mode 100644 index 00000000..48b09ecb --- /dev/null +++ b/docs/tsl/reference/catalog/base/28_array_sort.md @@ -0,0 +1,31 @@ +# 基础函数 - 排序函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 排序函数 + +### `sortArray(arr)` + +用途：排序函数相关函数。 + +参数个数：1 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | + +### `sortTableByField(arr, arg2, arg3)` + +用途：排序函数相关函数。 + +参数个数：3 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arr` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/base/29_array_crud.md b/docs/tsl/reference/catalog/base/29_array_crud.md new file mode 100644 index 00000000..2df94392 --- /dev/null +++ b/docs/tsl/reference/catalog/base/29_array_crud.md @@ -0,0 +1,84 @@ +# 基础函数 - 增删改查 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 增删改查 + +### `filterIn(a, arg2, arg3[, arg4])` + +用途：增删改查相关函数。 + +参数个数：3 到 4 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------------- | ------------------------------------------------ | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串/nil/数组 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 布尔值 | 按源文档示例顺序传入；源文档示例传入变量 `false` | + +### `filterNotIn(a, b, arg3[, arg4])` + +用途：增删改查相关函数。 + +参数个数：3 到 4 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ---------- | ------------------------------------------------ | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串/nil | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 布尔值 | 按源文档示例顺序传入；源文档示例传入变量 `false` | + +### `getMiddleN(data, start_pos, end_pos)` + +用途：从数组表中按 1 基位置取中间行区间。 + +参数个数：3 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | --------------------- | +| 1 | `data` | 是 | 数组表 | 原始数组表 | +| 2 | `start_pos` | 是 | 整数 | 起始行位置，按 1 开始 | +| 3 | `end_pos` | 是 | 整数 | 结束行位置，按 1 开始 | + +### `filterTable(data, key_value)` + +用途：从数组表或信息表中筛选匹配键值的记录。 + +参数个数：2 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ---------------------- | ------------------------------------------ | +| 1 | `data` | 是 | 数组表 | 待筛选的数据表 | +| 2 | `key_value` | 是 | 日期整数/整数/任意键值 | 用于匹配记录的键值；信息表场景常传日期整数 | + +### `getSubField(data, field)` + +用途：从数组表中取指定字段或列的值序列。 + +参数个数：2 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ----------- | -------------- | +| 1 | `data` | 是 | 数组表 | 原始数组表 | +| 2 | `field` | 是 | 字符串/整数 | 字段名或列下标 | + +### `getSubTable(data, fields)` + +用途：从数组表中按字段或列下标取子表。 + +参数个数：2 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------------------- | +| 1 | `data` | 是 | 数组表 | 原始数组表 | +| 2 | `fields` | 是 | 数组 | 要保留的字段名或列下标数组 | diff --git a/docs/tsl/reference/catalog/base/30_array_restructure.md b/docs/tsl/reference/catalog/base/30_array_restructure.md new file mode 100644 index 00000000..b53ad4ba --- /dev/null +++ b/docs/tsl/reference/catalog/base/30_array_restructure.md @@ -0,0 +1,33 @@ +# 基础函数 - 重构函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../base.md](../base.md)、[../../index.md](../../index.md) + +## 重构函数 + +### `reIndex(a, arg2[, s])` + +用途：数组相关函数。 + +参数个数：2 到 3 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | nil/数组 | 按源文档示例顺序传入；源文档示例传入变量 `nil` | +| 3 | `s` | 否 | 数组 | 按源文档示例顺序传入 | + +### `reshape(a[, arg2][, arg3])` + +用途：数组相关函数。 + +参数个数：1 到 3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/client.md b/docs/tsl/reference/catalog/client.md index a066fe92..88023556 100644 --- a/docs/tsl/reference/catalog/client.md +++ b/docs/tsl/reference/catalog/client.md @@ -1,66 +1,38 @@ # 客户端函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页描述客户端交互、界面控制与前端协作能力。生成函数调用时，只按函数条目中的参数表传参。 ## 模块范围 - 说明：客户端交互、界面控制与前端协作能力 -- 主题数：8 -- 函数数：19 +- 函数事实数：2 -## 主题目录 +## 客户端行为控制函数 -### 结果处理 / CallBack +### `tsExpert_ClientConfig()` -- `DelPrecodeCallBack` -- `IncPrecodeCallBack` +用途：客户端行为控制函数相关函数。 -### 结果处理 / 层次表格的展开 +参数个数：0 +返回值：处理结果 -- `ExtractData` -- `ExtractDataEx` -- `ExtractDataEx2` -- `ExtractDataLocalRun2` +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | -### 结果处理 / 简单统计 +## 直接函数 -- `SimpleStat` +### `sendRunningData(data[, window_name])` -### 结果处理 / 品种管理 +用途：直接函数相关函数。 -- `GetTypeOfStock` +参数个数：1 到 2 +返回值：处理结果 -### 错误处理 - -- `RaiseError` -- `ASSERT` - -### 客户端行为控制函数 - -- `TSExpert_ClientConfig` - -### 客户端行为控制函数 / 客户端行为控制函数简介 - -- `ChartColor` -- `ChartColorArray` -- `DisabledFuncTypeList` -- `DisabledSystemFuncList` -- `DisabledSysFuncList` -- `FuncTypeList` -- `AutoRun` - -### 直接函数 - -- `SendRunningData` +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------------------- | +| 1 | `data` | 是 | 任意值 | 要发送到运行结果窗口的数据 | +| 2 | `window_name` | 否 | 字符串 | 结果窗口名称；省略时在原窗口输出 | diff --git a/docs/tsl/reference/catalog/compression.md b/docs/tsl/reference/catalog/compression.md index 0e5516f2..36cc0010 100644 --- a/docs/tsl/reference/catalog/compression.md +++ b/docs/tsl/reference/catalog/compression.md @@ -1,31 +1,84 @@ # 压缩和解压函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页描述压缩、解压与归档能力。生成函数调用时，只按函数条目中的参数表传参。 ## 模块范围 - 说明：压缩、解压与归档能力 -- 主题数： -- 函数数：5 +- 函数事实数：5 -## 主题目录 +## 函数事实 -### 直接函数 +### `zipCompress(zip_alias, zip_filename, file_alias, filename, path)` -- `ZipCompress` -- `ZipExtract` -- `RarExtract` -- `unicompress` -- `uniuncompress` +用途：函数事实相关函数。 + +参数个数：5 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ---------------------------------------------------- | +| 1 | `zip_alias` | 是 | 字符串 | ZIP 文件所在目录别名；不用别名时传空字符串 | +| 2 | `zip_filename` | 是 | 字符串 | ZIP 文件路径；不存在时会创建 | +| 3 | `file_alias` | 是 | 字符串 | 被压缩文件或目录的目录别名；不用别名时传空字符串 | +| 4 | `filename` | 是 | 字符串 | 要压缩的文件或目录路径 | +| 5 | `path` | 是 | 字符串 | 压缩后在 ZIP 内部保存的路径；空字符串表示 ZIP 根目录 | + +### `zipExtract(zip_alias, zip_filename, output_alias, output_dir[, password])` + +用途：函数事实相关函数。 + +参数个数：4 到 5 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------------------------ | +| 1 | `zip_alias` | 是 | 字符串 | ZIP 文件所在目录别名；不用别名时传空字符串 | +| 2 | `zip_filename` | 是 | 字符串 | ZIP 文件路径 | +| 3 | `output_alias` | 是 | 字符串 | 解压目标目录别名；不用别名时传空字符串 | +| 4 | `output_dir` | 是 | 字符串 | 解压目标目录 | +| 5 | `password` | 否 | 字符串 | ZIP 密码；普通 ZIP 可省略或传空字符串 | + +### `rarExtract(rar_alias, rar_filename, alias, path[, password])` + +用途：将 RAR 文件解压到指定目录。 + +参数个数：4 到 5 +返回值：是否成功（1/0） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------------------------ | +| 1 | `rar_alias` | 是 | 字符串 | RAR 文件所在目录别名；不用别名时传空字符串 | +| 2 | `rar_filename` | 是 | 字符串 | RAR 文件名称或路径 | +| 3 | `alias` | 是 | 字符串 | 文件解压目录别名；不用别名时传空字符串 | +| 4 | `path` | 是 | 字符串 | 文件解压路径 | +| 5 | `password` | 否 | 字符串 | RAR 加密密码；普通 RAR 可省略 | + +### `unicompress(method, data)` + +用途：函数事实相关函数。 + +参数个数：2 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | --------------------------------- | +| 1 | `method` | 是 | 字符串 | 压缩算法名；源文档示例使用 `zstd` | +| 2 | `data` | 是 | 字符串 | 要压缩的数据 | + +### `uniuncompress(method, data[, length])` + +用途：函数事实相关函数。 + +参数个数：2 到 3 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | ---------- | ------------------------------------------------------ | +| 1 | `method` | 是 | 字符串 | 解压算法名；源文档示例使用 `zstd` | +| 2 | `data` | 是 | 二进制数据 | `unicompress` 返回的压缩数据 | +| 3 | `length` | 否 | 整数 | 原始数据长度；省略时也可解压源文档示例中的 `zstd` 数据 | diff --git a/docs/tsl/reference/catalog/datawarehouse.md b/docs/tsl/reference/catalog/datawarehouse.md new file mode 100644 index 00000000..bf8ee87c --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse.md @@ -0,0 +1,56 @@ +# 数据仓库金融函数 + +文档类型：函数事实路由页 +是否可直接用于生成代码：是；进入分类详情页后按函数事实条目生成调用 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md)、[../../modules/pytsl_api.md](../../modules/pytsl_api.md) + +这一页是数据仓库金融函数的轻量入口，不直接承载全部函数事实。生成函数调用时，先按分类目录进入详情页，再只读取命中的函数条目和参数表。 + +## 模块范围 + +- 说明：数据仓库金融函数，覆盖行情字段、系统参数、财务报表、板块选股、时序统计和向导函数 +- 函数事实数：414 +- 运行边界：多数行情、财务和板块函数依赖当前证券、日期、周期、板块或股票池系统参数；调用前按条目和业务上下文设置 `pn_stock()`、`pn_date()`、`pn_cycle()`、`pn_bk()` 等参数。 + +## 智能体检索规则 + +1. 用户只描述能力时，先按“分类目录”选择候选详情页。 +2. 用户给出函数名时，优先在 `datawarehouse/` 子目录中搜索三级函数标题。 +3. 只读取命中的函数条目、相邻分类标题和必要参数表；不要把整个数据仓库目录页或同页其它函数放进上下文。 +4. 没有命中函数事实条目时，不要根据金融术语发明函数名；回到 [../index.md](../index.md)、[../../modules/pytsl_api.md](../../modules/pytsl_api.md) 或项目实际接口确认。 + +## 分类目录 + +| 分类 | 详情页 | 函数事实数 | +| -------------------------- | -------------------------------------------------------------------------------------------------------- | ---------: | +| 系统参数键 | [datawarehouse/01_system_param_keys.md](datawarehouse/01_system_param_keys.md) | 1 | +| 系统参数名称函数 | [datawarehouse/02_system_param_names.md](datawarehouse/02_system_param_names.md) | 17 | +| 多市场支撑函数 | [datawarehouse/03_multi_market.md](datawarehouse/03_multi_market.md) | 5 | +| 时间相关函数 | [datawarehouse/04_time.md](datawarehouse/04_time.md) | 4 | +| 判定函数 | [datawarehouse/05_predicates.md](datawarehouse/05_predicates.md) | 14 | +| 盘中相关 | [datawarehouse/06_intraday.md](datawarehouse/06_intraday.md) | 1 | +| 盘后相关(在当日可用于盘中) | [datawarehouse/07_after_close_intraday_available.md](datawarehouse/07_after_close_intraday_available.md) | 63 | +| 时间序列统计 | [datawarehouse/08_time_series_stats.md](datawarehouse/08_time_series_stats.md) | 40 | +| 成交明细数据函数 | [datawarehouse/09_transaction_detail_data.md](datawarehouse/09_transaction_detail_data.md) | 9 | +| 交易明细字段标识函数 | [datawarehouse/10_transaction_detail_fields.md](datawarehouse/10_transaction_detail_fields.md) | 28 | +| 查询和轮询函数 | [datawarehouse/11_query_polling.md](datawarehouse/11_query_polling.md) | 1 | +| 市场和板块函数 | [datawarehouse/12_market_sector.md](datawarehouse/12_market_sector.md) | 5 | +| 取行情数据序列函数 | [datawarehouse/13_quote_series.md](datawarehouse/13_quote_series.md) | 3 | +| 引用指定函数 | [datawarehouse/14_reference_functions.md](datawarehouse/14_reference_functions.md) | 4 | +| 系统参数设置和获取函数 | [datawarehouse/15_sys_param_access.md](datawarehouse/15_sys_param_access.md) | 4 | +| 复权类型函数 | [datawarehouse/16_reinstatement_types.md](datawarehouse/16_reinstatement_types.md) | 3 | +| 复权基准日函数 | [datawarehouse/17_reinstatement_base_date.md](datawarehouse/17_reinstatement_base_date.md) | 2 | +| 周期函数 | [datawarehouse/18_cycle.md](datawarehouse/18_cycle.md) | 34 | +| 财务函数 | [datawarehouse/19_financial.md](datawarehouse/19_financial.md) | 18 | +| 选股与取数 | [datawarehouse/20_selection_and_fetch.md](datawarehouse/20_selection_and_fetch.md) | 6 | +| 向导函数 | [datawarehouse/21_wizard.md](datawarehouse/21_wizard.md) | 22 | +| 向导函数 / N期 | [datawarehouse/22_wizard_n_periods.md](datawarehouse/22_wizard_n_periods.md) | 18 | +| 向导函数 / N日 | [datawarehouse/23_wizard_n_days.md](datawarehouse/23_wizard_n_days.md) | 38 | +| 向导函数 / N日 / 中间函数 | [datawarehouse/24_wizard_n_days_intermediate.md](datawarehouse/24_wizard_n_days_intermediate.md) | 2 | +| 向导函数 / 历史遗留 | [datawarehouse/25_wizard_legacy.md](datawarehouse/25_wizard_legacy.md) | 2 | +| 向导函数 / 区间 | [datawarehouse/26_wizard_range.md](datawarehouse/26_wizard_range.md) | 32 | +| 向导函数 / 中间函数 | [datawarehouse/27_wizard_intermediate.md](datawarehouse/27_wizard_intermediate.md) | 8 | +| 向导函数 / N季 | [datawarehouse/28_wizard_n_quarters.md](datawarehouse/28_wizard_n_quarters.md) | 6 | +| 向导函数 / 当日 | [datawarehouse/29_wizard_today.md](datawarehouse/29_wizard_today.md) | 16 | +| 向导函数 / 当日 / 中间函数 | [datawarehouse/30_wizard_today_intermediate.md](datawarehouse/30_wizard_today_intermediate.md) | 7 | +| 条件判定 | [datawarehouse/31_condition_predicates.md](datawarehouse/31_condition_predicates.md) | 1 | diff --git a/docs/tsl/reference/catalog/datawarehouse/01_system_param_keys.md b/docs/tsl/reference/catalog/datawarehouse/01_system_param_keys.md new file mode 100644 index 00000000..f46b6e83 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/01_system_param_keys.md @@ -0,0 +1,18 @@ +# 数据仓库金融函数 - 系统参数键 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 系统参数键 + +### `cyclefilter` + +用途：设置周期过滤器以及集合竞价分离器。它是系统参数键，不是函数调用。 + +参数个数：不适用 +返回值：不适用 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------------------------------------------------------------- | +| 1 | `value` | 是 | 整数 | 通过 `setSysParam("cyclefilter", value)` 设置；`0` 取消过滤，`1` 过滤期货放假期间夜盘，`3` 新增集合竞价周期点 | diff --git a/docs/tsl/reference/catalog/datawarehouse/02_system_param_names.md b/docs/tsl/reference/catalog/datawarehouse/02_system_param_names.md new file mode 100644 index 00000000..134c5103 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/02_system_param_names.md @@ -0,0 +1,177 @@ +# 数据仓库金融函数 - 系统参数名称函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 系统参数名称函数 + +### `pn_stock()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_date()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_rate()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_rateDay()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_nDay()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_cycle()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_precision()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_nilTrans()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_i64Trans()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_viewPoint()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_freeCycle()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_reportMode()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_emptymode()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_changedDateMode()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_reportType()` + +用途：返回数据仓库相关系统参数名。 + +参数个数：0 +返回值：系统参数名字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_noRaiseNoData()` + +用途：获取/设置“无数据不抛异常”的系统参数键。 + +参数个数：0 +返回值：系统参数名（用于 SetSysParam/GetSysParam）。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pn_calcCTRLWord()` + +用途：获取/设置 CalcCTRLWord 系统参数键，用于控制 nil 参与计算或浮点除 0 的提示/报错行为。 + +参数个数：0 +返回值：系统参数名（用于 SetSysParam/GetSysParam）。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/03_multi_market.md b/docs/tsl/reference/catalog/datawarehouse/03_multi_market.md new file mode 100644 index 00000000..3729da68 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/03_multi_market.md @@ -0,0 +1,64 @@ +# 数据仓库金融函数 - 多市场支撑函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 多市场支撑函数 + +### `marketId(stock_id)` + +用途：多市场支撑函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH600000"` | + +### `marketInfo(market_id)` + +用途：多市场支撑函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ----------------------------------------------------------- | +| 1 | `market_id` | 是 | 市场标识 | 按源文档示例顺序传入；示例参数形态为 `MarketID("SH600000")` | + +### `marketOpenCloseTime(market_id, date_value_2)` + +用途：多市场支撑函数相关函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ----------------------------------------------------------- | +| 1 | `market_id` | 是 | 市场标识 | 按源文档示例顺序传入；示例参数形态为 `MarketID("SH600000")` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230628T` | + +### `defaultTimeZone()` + +用途：多市场支撑函数相关函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tsPeriod(stock_id, cycle, dt)` + +用途：多市场支撑函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 整数或标识值 | 按源文档示例顺序传入；示例参数形态为 `"SH600000"` | +| 2 | `cycle` | 是 | 周期值 | 按源文档示例顺序传入；示例参数形态为 `cy_day()` | +| 3 | `dt` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230628T` | diff --git a/docs/tsl/reference/catalog/datawarehouse/04_time.md b/docs/tsl/reference/catalog/datawarehouse/04_time.md new file mode 100644 index 00000000..66fce38b --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/04_time.md @@ -0,0 +1,52 @@ +# 数据仓库金融函数 - 时间相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 时间相关函数 + +### `sp_time(arg1)` + +用途：时间相关函数相关函数。 + +参数个数：1 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `tradeDays(date_value, date_value_2)` + +用途：时间相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `date_value` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230601T` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230628T` | + +### `firstDay(stock_id)` + +用途：时间相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SH600086'` | + +### `lastDay(stock_id)` + +用途：时间相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SH600001'` | diff --git a/docs/tsl/reference/catalog/datawarehouse/05_predicates.md b/docs/tsl/reference/catalog/datawarehouse/05_predicates.md new file mode 100644 index 00000000..593c9d92 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/05_predicates.md @@ -0,0 +1,163 @@ +# 数据仓库金融函数 - 判定函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 判定函数 + +### `isStock(stock_id)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SZ000001'` | + +### `isTradeDay(date_value)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------ | ---------------------------------------------------------- | +| 1 | `date_value` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `inttodate(20110828)` | + +### `testStock(stock_id)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SZ000002'` | + +### `isValidCode(stock_id, i_d)` + +用途：判定函数相关函数。 + +参数个数：2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SZ000002'` | +| 2 | `i_d` | 是 | 整数或标识值 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `validFullCode(stock_id)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 整数或标识值 | 按源文档示例顺序传入；示例参数形态为 `"SZ000002"` | + +### `isCashFlowInfoId(arg1)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `48003` | + +### `isMainReportId(info_id)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | + +### `analyseStockArr(arg1, stock_id_2)` + +用途：判定函数相关函数。 + +参数个数：2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'上证50'` | +| 2 | `stock_id_2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'IF01;IF02'` | + +### `isBalanceInfoId(arg1)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `44003` | + +### `isInterestInfoId(arg1)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46003` | + +### `isFundBalanceSheetInfoId(arg1)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `312002` | + +### `isFundInterestInfoId(arg1)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `314002` | + +### `isStockFinancialItem(arg1)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `62003` | + +### `isFinancialInfoId(arg1)` + +用途：判定函数相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | diff --git a/docs/tsl/reference/catalog/datawarehouse/06_intraday.md b/docs/tsl/reference/catalog/datawarehouse/06_intraday.md new file mode 100644 index 00000000..bf550a43 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/06_intraday.md @@ -0,0 +1,18 @@ +# 数据仓库金融函数 - 盘中相关 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 盘中相关 + +### `rd(arg1)` + +用途：盘中相关相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | diff --git a/docs/tsl/reference/catalog/datawarehouse/07_after_close_intraday_available.md b/docs/tsl/reference/catalog/datawarehouse/07_after_close_intraday_available.md new file mode 100644 index 00000000..8a8308c1 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/07_after_close_intraday_available.md @@ -0,0 +1,637 @@ +# 数据仓库金融函数 - 盘后相关(在当日可用于盘中) + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 盘后相关(在当日可用于盘中) + +### `low()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sseSyl2()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sys_prevClose()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `open()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `close()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buyVol3()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `vol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buy2()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tradeCount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buyVol2()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buy1()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `amount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buyVol1()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `high()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sseSyl1()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buy3()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionOpen()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sale2()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `saleVol3()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sale5()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buy4()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `saleVol4()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionLow()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionHigh()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buyVol5()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionPrevClose()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `volRate()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sale3()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionAmount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buy5()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `saleVol1()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sale1()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionTradeCount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `saleVol5()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `buyVol4()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `saleVol2()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sale4()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `initialtiveBuyVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionalInitialtiveSaleVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `submitBuyVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionalInitialtiveBuyAmount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `advance()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `prev_settlement()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionTradeWay()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `submitSaleVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `decline()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionalSubmitBSR()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `initialtiveSaleAmount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `openInterest()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionalInitialtiveBuyVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionOpenInterest()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `initialtiveBuyAmount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionalSubmitBuyVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionalSubmitSaleVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `initialtiveSaleVol()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sectionalInitialtiveSaleAmount()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `submitBSR()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `settlement()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `isEqual()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flat()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `isDown()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `isUp()` + +用途：盘后相关(在当日可用于盘中)相关函数。 + +参数个数：0 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/08_time_series_stats.md b/docs/tsl/reference/catalog/datawarehouse/08_time_series_stats.md new file mode 100644 index 00000000..0b8d746f --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/08_time_series_stats.md @@ -0,0 +1,503 @@ +# 数据仓库金融函数 - 时间序列统计 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 时间序列统计 + +### `hhv(arg1, n)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `llv(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `14` | + +### `ma(arg1, n)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `ema(x, n)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `x` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `sma(x, n, m)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `x` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 3 | `m` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `3` | + +### `count(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `isup()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `sumN(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `VOL()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `sp_std(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | + +### `sp_stdp(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | + +### `sp_var(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | + +### `sp_varp(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | + +### `sp_avedev(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | + +### `sp_devsq(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | + +### `cross(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `ma(close(), 5)` | + +### `sp_large(arg1, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Vol()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `240` | + +### `sp_small(arg1, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `sp_percentile(arg1, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入；示例参数形态为 `0.8` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `240` | + +### `sp_percentrank(arg1, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `240` | + +### `sp_quartile(arg1, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_rank(arg1, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `240` | + +### `sp_trimmean(arg1, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入；示例参数形态为 `0.8` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_frequency(stock_id, arg2, arg3)` + +用途：时间序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------------------- | +| 1 | `stock_id` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Stockzf3()` | +| 2 | `arg2` | 是 | 数组 | 按源文档示例顺序传入；示例参数形态为 `array(-7, -3, 0, 3, 7)` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20` | + +### `sp_geomean(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4` | + +### `sp_harmean(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_median(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ------------ | ----------------------------------------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `tradedays(SP_time(), SP_time() + 14 / 24 + 57 / 24 / 60)` | + +### `sp_mode(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ------------ | ----------------------------------------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `tradedays(SP_time(), SP_time() + 14 / 24 + 57 / 24 / 60)` | + +### `sp_product(stock_id, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ----------------------------------------------------------- | +| 1 | `stock_id` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `1 + stockzf3() / 100` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `sp_totalvariance(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_norm(stock_id, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------ | ---------------------------------------------------------------------- | +| 1 | `stock_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `Close() - StockPJCJ4(SP_time())` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_skewness(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_kurtosis(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_skewness2(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_kurtosis2(arg1, arg2)` + +用途：时间序列统计相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_cov(arg1, arg2, arg3)` + +用途：双序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Spec(Close(), "SH000001")` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_correl(arg1, arg2, arg3)` + +用途：双序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Spec(Close(), "SH000001")` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_slope(arg1, arg2, arg3)` + +用途：双序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Spec(Close(), "SH000001")` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_intercept(arg1, arg2, arg3)` + +用途：双序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Spec(Close(), "SH000001")` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_rsq(arg1, arg2, arg3)` + +用途：双序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Spec(Close(), "SH000001")` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_steyx(arg1, arg2, arg3)` + +用途：双序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Spec(Close(), "SH000001")` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | + +### `sp_slopeandintercept(arg1, arg2, arg3)` + +用途：双序列统计相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `Spec(Close(), "SH000001")` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4800` | diff --git a/docs/tsl/reference/catalog/datawarehouse/09_transaction_detail_data.md b/docs/tsl/reference/catalog/datawarehouse/09_transaction_detail_data.md new file mode 100644 index 00000000..f9d98aa7 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/09_transaction_detail_data.md @@ -0,0 +1,135 @@ +# 数据仓库金融函数 - 成交明细数据函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 成交明细数据函数 + +### `toverData(date_value)` + +用途：成交明细数据函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------ | ---------------------------------------------------------- | +| 1 | `date_value` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `inttodate(20140115)` | + +### `toverDataEx(fields, d, trade_flag, beg_time, end_time, min_vol, min_amount, min_price, max_vol, max_amount, max_price)` + +用途：成交明细数据函数相关函数。 + +参数个数：11 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------ | ------------------------------------------------------------ | +| 1 | `fields` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 2 | `d` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `inttodate(20140115)` | +| 3 | `trade_flag` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 4 | `beg_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `strtotime("13:00:00")` | +| 5 | `end_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `strtotime("15:00:00")` | +| 6 | `min_vol` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `10000` | +| 7 | `min_amount` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 8 | `min_price` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `7.00` | +| 9 | `max_vol` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `90000` | +| 10 | `max_amount` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `9000000` | +| 11 | `max_price` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `8.00` | + +### `td(arg1)` + +用途：成交明细数据函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `tdByIndex(arg1, arg2)` + +用途：成交明细数据函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------ | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `tdCount()` + +用途：成交明细数据函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdCountEx(d, trade_flag, beg_time, end_time, min_vol, min_amount, min_price, max_vol, max_amount, max_price)` + +用途：成交明细数据函数相关函数。 + +参数个数：10 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------ | ------------------------------------------------------------ | +| 1 | `d` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `inttodate(20140115)` | +| 2 | `trade_flag` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 3 | `beg_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `strtotime("13:00:00")` | +| 4 | `end_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `strtotime("15:00:00")` | +| 5 | `min_vol` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `10000` | +| 6 | `min_amount` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 7 | `min_price` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `7.00` | +| 8 | `max_vol` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `90000` | +| 9 | `max_amount` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `9000000` | +| 10 | `max_price` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `8.00` | + +### `tdInfo()` + +用途：成交明细数据函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdInfoByIndex(arg1)` + +用途：成交明细数据函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `-1` | + +### `tdSum(sum_vol, sum_amount, d, trade_flag, beg_time, end_time, min_vol, min_amount, min_price, max_vol, max_amount, max_price)` + +用途：成交明细数据函数相关函数。 + +参数个数：12 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------ | ------------------------------------------------------------ | +| 1 | `sum_vol` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 2 | `sum_amount` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 3 | `d` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `inttodate(20140115)` | +| 4 | `trade_flag` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 5 | `beg_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `strtotime("13:00:00")` | +| 6 | `end_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `strtotime("15:00:00")` | +| 7 | `min_vol` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `10000` | +| 8 | `min_amount` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 9 | `min_price` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `7.00` | +| 10 | `max_vol` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `90000` | +| 11 | `max_amount` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `9000000` | +| 12 | `max_price` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `8.00` | diff --git a/docs/tsl/reference/catalog/datawarehouse/10_transaction_detail_fields.md b/docs/tsl/reference/catalog/datawarehouse/10_transaction_detail_fields.md new file mode 100644 index 00000000..b5fedb0c --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/10_transaction_detail_fields.md @@ -0,0 +1,287 @@ +# 数据仓库金融函数 - 交易明细字段标识函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 交易明细字段标识函数 + +### `tdf_buy2()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale3()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_vol()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy5()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_time()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_price()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy3()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_amount()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale1()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_lb()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale4()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy4()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale5()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy1()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale2()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy3count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_tradecount()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale2count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy5count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy2count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale3count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale5count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy1count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_buy4count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_syl2()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale1count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_sale4count()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tdf_syl1()` + +用途：交易明细字段标识函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/11_query_polling.md b/docs/tsl/reference/catalog/datawarehouse/11_query_polling.md new file mode 100644 index 00000000..04d518c9 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/11_query_polling.md @@ -0,0 +1,27 @@ +# 数据仓库金融函数 - 查询和轮询函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 查询和轮询函数 + +### `query(arg1, stock_id_2, arg3, arg4, arg5, stock_id_6, arg7, stock_id_8, arg9, arg10)` + +用途：查询和轮询函数相关函数。 + +参数个数：10 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ------------------------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'上证A股;创业板'` | +| 2 | `stock_id_2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SZ000001;SZ000002;SZ000997'` | +| 3 | `arg3` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close() > ma(close(), 10)` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `''` | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'证券代码'` | +| 6 | `stock_id_6` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `DefaultStockID()` | +| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'证券名称'` | +| 8 | `stock_id_8` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `CurrentStockName()` | +| 9 | `arg9` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'收盘价'` | +| 10 | `arg10` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | diff --git a/docs/tsl/reference/catalog/datawarehouse/12_market_sector.md b/docs/tsl/reference/catalog/datawarehouse/12_market_sector.md new file mode 100644 index 00000000..27845e1c --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/12_market_sector.md @@ -0,0 +1,62 @@ +# 数据仓库金融函数 - 市场和板块函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 市场和板块函数 + +### `getBk(arg1)` + +用途：市场和板块函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'上证A股;创业板'` | + +### `getUserBkList(arg1)` + +用途：市场和板块函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"申万行业\\申万金融业"` | + +### `getBkList(arg1)` + +用途：市场和板块函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'申万行业'` | + +### `getUserBkList2(arg1)` + +用途：市场和板块函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"申万行业"` | + +### `getBkList2(arg1)` + +用途：市场和板块函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'申万行业'` | diff --git a/docs/tsl/reference/catalog/datawarehouse/13_quote_series.md b/docs/tsl/reference/catalog/datawarehouse/13_quote_series.md new file mode 100644 index 00000000..3975a7f6 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/13_quote_series.md @@ -0,0 +1,56 @@ +# 数据仓库金融函数 - 取行情数据序列函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 取行情数据序列函数 + +### `nDay(arg1, arg2, date_value_3, arg4, arg5, arg6, arg7, arg8, arg9)` + +用途：取行情数据序列函数相关函数。 + +参数个数：9 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | --------------------------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'时间'` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `datetimetostr(sp_time())` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'收盘价'` | +| 5 | `arg5` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 6 | `arg6` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'当日高价'` | +| 7 | `arg7` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `high()` | +| 8 | `arg8` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'30日均线'` | +| 9 | `arg9` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `ma(close(), 30)` | + +### `nDay2(arg1, date_value_2, arg3, arg4, arg5, arg6, arg7, arg8)` + +用途：取行情数据序列函数相关函数。 + +参数个数：8 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | --------------------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'时间'` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `datetimetostr(sp_time())` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'收盘价'` | +| 4 | `arg4` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'当日高价'` | +| 6 | `arg6` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `high()` | +| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'30日均线'` | +| 8 | `arg8` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `ma(close(), 30)` | + +### `nDay3(arg1, arg2)` + +用途：取行情数据序列函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | diff --git a/docs/tsl/reference/catalog/datawarehouse/14_reference_functions.md b/docs/tsl/reference/catalog/datawarehouse/14_reference_functions.md new file mode 100644 index 00000000..fe9aaf6a --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/14_reference_functions.md @@ -0,0 +1,55 @@ +# 数据仓库金融函数 - 引用指定函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 引用指定函数 + +### `ref(arg1, arg2)` + +用途：引用指定函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `specDate(arg1, date_value_2)` + +用途：引用指定函数相关函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ---------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `inttodate(20110101)` | + +### `spec(arg1, stock_id_2)` + +用途：引用指定函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ---------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `ref(close(), N - 1)` | +| 2 | `stock_id_2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'SH000300'` | + +### `specAll(arg1, stock_id_2)` + +用途：引用指定函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `close()` | +| 2 | `sys_params` | 是 | 系统参数数组 | 按源文档示例顺序传入；示例参数形态为 `array(pn_stock():"SZ000001", pn_date():inttodate(20140117), pn_rate():1, pn_rateDay():-1)` | diff --git a/docs/tsl/reference/catalog/datawarehouse/15_sys_param_access.md b/docs/tsl/reference/catalog/datawarehouse/15_sys_param_access.md new file mode 100644 index 00000000..cf697bce --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/15_sys_param_access.md @@ -0,0 +1,53 @@ +# 数据仓库金融函数 - 系统参数设置和获取函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 系统参数设置和获取函数 + +### `getSysParam(stock_id)` + +用途：系统参数设置和获取函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `pn_stock()` | + +### `setSysParam(arg1, arg2)` + +用途：系统参数设置和获取函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'Abc'` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `123` | + +### `sp_s(arg1, arg2)` + +用途：系统参数设置和获取函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'Abc'` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `123` | + +### `sp_g(stock_id)` + +用途：系统参数设置和获取函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------- | +| 1 | `stock_id` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `pn_stock()` | diff --git a/docs/tsl/reference/catalog/datawarehouse/16_reinstatement_types.md b/docs/tsl/reference/catalog/datawarehouse/16_reinstatement_types.md new file mode 100644 index 00000000..c4922454 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/16_reinstatement_types.md @@ -0,0 +1,37 @@ +# 数据仓库金融函数 - 复权类型函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 复权类型函数 + +### `rt_none()` + +用途：复权类型函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rt_scale()` + +用途：复权类型函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rt_complex()` + +用途：复权类型函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/17_reinstatement_base_date.md b/docs/tsl/reference/catalog/datawarehouse/17_reinstatement_base_date.md new file mode 100644 index 00000000..f3795261 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/17_reinstatement_base_date.md @@ -0,0 +1,27 @@ +# 数据仓库金融函数 - 复权基准日函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 复权基准日函数 + +### `rd_lastday()` + +用途：复权基准日函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rd_firstday()` + +用途：复权基准日函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/18_cycle.md b/docs/tsl/reference/catalog/datawarehouse/18_cycle.md new file mode 100644 index 00000000..44fa1793 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/18_cycle.md @@ -0,0 +1,350 @@ +# 数据仓库金融函数 - 周期函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 周期函数 + +### `cy_month()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_20m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_1m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_halfYear()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_5m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_60m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_year()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_week()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_2m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_10m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_quarter()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_120m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_day()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_30m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_3m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_40m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_twoYear()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_15m()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_trailingseconds(arg1)` + +用途：周期函数相关函数。 + +参数个数：1 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `cy_6s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_trailingdays(arg1)` + +用途：周期函数相关函数。 + +参数个数：1 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `cy_15s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_detail()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_30s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_5s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_2s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_12s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_1s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_10s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_20s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_4s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_freeCycle(arg1)` + +用途：周期函数相关函数。 + +参数个数：1 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `cy_3s()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `cy_halfs()` + +用途：周期函数相关函数。 + +参数个数：0 +返回值：常量值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/19_financial.md b/docs/tsl/reference/catalog/datawarehouse/19_financial.md new file mode 100644 index 00000000..ccdd6ad7 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/19_financial.md @@ -0,0 +1,221 @@ +# 数据仓库金融函数 - 财务函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 财务函数 + +### `report(info_id, date_value_2)` + +用途：财务函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20170930` | + +### `reportOfAll(info_id, date_value_2)` + +用途：财务函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20170930` | + +### `reportOfDiy(info_id, date_value_2, arg3, arg4)` + +用途：财务函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8025001` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20091231` | +| 3 | `arg3` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `now()` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'刘研究员'` | + +### `reportExists(info_id, date_value_2)` + +用途：财务函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `18007` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20101231` | + +### `reportHist(info_id, date_value_2)` + +用途：财务函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数或标识值 | 按源文档示例顺序传入；示例参数形态为 `46002` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20140331` | + +### `reportHistExists(info_id)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `18007` | + +### `lastQuarterData(date_value, arg2, arg3)` + +用途：财务函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ----------------------------------------------- | +| 1 | `date_value` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20170930` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `last12MData(date_value, arg2)` + +用途：财务函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ----------------------------------------------- | +| 1 | `date_value` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20170930` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | + +### `base(info_id)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10002` | + +### `baseExists(info_id)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10002` | + +### `infoArray(info_id)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------ | -------------------------------------------- | +| 1 | `info_id` | 是 | 整数或标识值 | 按源文档示例顺序传入；示例参数形态为 `46002` | + +### `infoArrayExt(info_id, arg2, date_value_3, arg4, arg5, shares)` + +用途：财务函数相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `12` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'变动日'` | +| 3 | `date_value_3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `19970512` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"总股本"` | +| 6 | `shares` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `infoArrayExists(info_id)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | ----------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20` | + +### `bName(arg1)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `18007` | + +### `idtType(arg1)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10002` | + +### `idfType(arg1)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10002` | + +### `basicIdExists(info_id)` + +用途：财务函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------ | -------------------------------------------- | +| 1 | `info_id` | 是 | 整数或标识值 | 按源文档示例顺序传入；示例参数形态为 `46002` | + +### `baseArray(info_id, date_value_2)` + +用途：财务函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20151231` | diff --git a/docs/tsl/reference/catalog/datawarehouse/20_selection_and_fetch.md b/docs/tsl/reference/catalog/datawarehouse/20_selection_and_fetch.md new file mode 100644 index 00000000..9e5af3b5 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/20_selection_and_fetch.md @@ -0,0 +1,104 @@ +# 数据仓库金融函数 - 选股与取数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 选股与取数 + +### `queryBk(arg1, arg2, expression_3, arg4, arg5, expression_6, arg7, expression_8, arg9, expression_10, arg11, expression_12)` + +用途：选股与取数相关函数。 + +参数个数：12 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | ---------- | ------------------------------------------------------------------------------------------------------ | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"深证A股;上证A股;中小企业板"` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 3 | `expression_3` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@true` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"板块名"` | +| 6 | `expression_6` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@DefaultBKName()` | +| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"指定日流通市值和(万)(20120930,只考虑A股)"` | +| 8 | `expression_8` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Bk_MarketValue(41182, 1)` | +| 9 | `arg9` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"指定日总股本和(万)(20120930,只考虑A股)"` | +| 10 | `expression_10` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Bk_TotalShares(41182, 1)` | +| 11 | `arg11` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"每股主营收入(20111231,总股本加权,只考虑A股,全部,绩差股标准=0)"` | +| 12 | `expression_12` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Bk_MainincomePS(20111231, 0, 1, 0, 0)` | + +### `queryBkWithPeriod(arg1, arg2, expression_3, arg4, arg5, expression_6, arg7, expression_8, arg9, expression_10)` + +用途：选股与取数相关函数。 + +参数个数：10 +返回值：处理后的结果值 + +调用前置条件：调用前设置 `setSysParam(pn_begt(), inttodate(20120801))`、`setSysParam(pn_endt(), inttodate(20121001))` 和 `setSysParam("TimeIndex", 1)`。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | ---------- | ------------------------------------------------------------------ | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"深证A股"` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 3 | `expression_3` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@true` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"换手率(%)(加权,只考虑A股)"` | +| 6 | `expression_6` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Bk_HSL3(0, 1)` | +| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"成交量(万)(只考虑A股)"` | +| 8 | `expression_8` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Bk_VolSum3(1)` | +| 9 | `arg9` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"成交金额(万)(只考虑A股)"` | +| 10 | `expression_10` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Bk_AmountSum3(1)` | + +### `queryWithPeriod(arg1, stock_id_2, expression_3, arg4, arg5, expression_6, arg7, expression_8, arg9, expression_10)` + +用途：选股与取数相关函数。 + +参数个数：10 +返回值：处理后的结果值 + +调用前置条件：调用前设置 `setSysParam(pn_begt(), inttodate(20120801))`、`setSysParam(pn_endt(), inttodate(20121001))` 和 `setSysParam("TimeIndex", 1)`。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | ---------- | ---------------------------------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 2 | `stock_id_2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SZ000002;SZ000001;SH600000;SH600004"` | +| 3 | `expression_3` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@true` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"收盘价"` | +| 6 | `expression_6` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"成交量"` | +| 8 | `expression_8` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@vol()` | +| 9 | `arg9` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"成交金额"` | +| 10 | `expression_10` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@amount()` | + +### `defaultRepId()` + +用途：选股与取数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `qwpMaxCount()` + +用途：选股与取数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `evalstring(arg1)` + +用途：选股与取数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'1+3'` | diff --git a/docs/tsl/reference/catalog/datawarehouse/21_wizard.md b/docs/tsl/reference/catalog/datawarehouse/21_wizard.md new file mode 100644 index 00000000..66d99771 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/21_wizard.md @@ -0,0 +1,292 @@ +# 数据仓库金融函数 - 向导函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 + +### `relativeStrengthOfIndustry()` + +用途：向导函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `specSysParams(expression, date_value_2, cycle, arg4, arg5)` + +用途：向导函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `cycle` | 是 | 周期值 | 按源文档示例顺序传入；示例参数形态为 `cy_day()` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `relativeStrengthOfSector(expression, arg2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | -------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@stockzf3()` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'A股'` | + +### `reportOfListed(info_id, date_value_2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46002` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20160331` | + +### `reportPerShareOfListed(info_id, date_value_2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------- | +| 1 | `info_id` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `46033` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20160331` | + +### `derivative1(expression, arg2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `positionOfSector(expression, arg2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'A股'` | + +### `reduceWithHighestOfPeriod(expression, date_value_2, date_value_3, arg4)` + +用途：向导函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180803T` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `occuredRepIdOfRepPeriod(expression, date_value_2, arg3)` + +用途：向导函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(42002, GetSysParam('DefaultRepID')) > 1.5` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20101231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2018` | + +### `continuedMatchOfRepPeriod(expression, date_value_2, arg3)` + +用途：向导函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20140331` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2018` | + +### `growthOfRepPeriod(expression, date_value_2, arg3)` + +用途：向导函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20150331` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `relativeStrengthOfSectorDesc(expression, arg2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'A股'` | + +### `positionOfSectorDesc(expression, arg2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'A股'` | + +### `growthWithLowestOfPeriod(expression, date_value_2, date_value_3, arg4)` + +用途：向导函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180903T` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `sumOfSector(expression, date_value_2, date_value_3, arg4, arg5, arg6, arg7)` + +用途：向导函数相关函数。 + +参数个数：7 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `positionOfIndustry()` + +用途：向导函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `avgOfSector(expression, arg2, date_value_3, date_value_4, arg5, arg6, arg7, arg8)` + +用途：向导函数相关函数。 + +参数个数：8 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 4 | `date_value_4` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 8 | `arg8` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `occuredTimeOfPeriod(expression, date_value_2, date_value_3)` + +用途：向导函数相关函数。 + +参数个数：3 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180810T` | + +### `specDateValue(date_value, expression_2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `date_value` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 2 | `expression_2` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `derivative2(expression)` + +用途：向导函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `stockTrailingAvgByEndT(end_time, ref_type, expression_3, is_exclude_i_p_o, n)` + +用途：向导函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | ------------ | ------------------------------------------------- | +| 1 | `end_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20210714T` | +| 2 | `ref_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4` | +| 3 | `expression_3` | 是 | 表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `"Amount()"` | +| 4 | `is_exclude_i_p_o` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 5 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `3` | + +### `stockTrailingStdByEndT(end_time, ref_type, expression_3)` + +用途：向导函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | --------------------------------------------------- | +| 1 | `end_time` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20210714T` | +| 2 | `ref_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4` | +| 3 | `expression_3` | 是 | 表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `"stockzf3()"` | diff --git a/docs/tsl/reference/catalog/datawarehouse/22_wizard_n_periods.md b/docs/tsl/reference/catalog/datawarehouse/22_wizard_n_periods.md new file mode 100644 index 00000000..6b04a415 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/22_wizard_n_periods.md @@ -0,0 +1,255 @@ +# 数据仓库金融函数 - 向导函数 / N期 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / N期 + +### `occuredOfNReport(expression, date_value_2, arg3)` + +用途：N期相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20151231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `continuedMatchOfNReport(expression, date_value_2, arg3)` + +用途：N期相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20151231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | + +### `occuredRepIdOfNReport(expression, date_value_2, arg3)` + +用途：N期相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20001231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20` | + +### `sumOfNReport(expression, date_value_2, arg3)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20151231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | + +### `avgOfNReport(expression, date_value_2, arg3)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20151231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | + +### `refReportValue(expression, date_value_2, arg3)` + +用途：N期相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20161231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `growthOfNReport(expression, date_value_2, arg3, arg4)` + +用途：N期相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20151231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `accOfNReport(expression, date_value_2, arg3, arg4, arg5)` + +用途：N期相关函数。 + +参数个数：5 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | -------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Last12MData(DefaultRepID(), 46078)` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `robustGrowthOfNReport(expression, date_value_2, arg3, arg4)` + +用途：N期相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | ---------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Last12MData(DefaultRepID(), 9900604)` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `robustAccOfNReport(expression, date_value_2, arg3, arg4)` + +用途：N期相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | ---------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@Last12MData(DefaultRepID(), 9900604)` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `highestOfNReport(expression, date_value_2, arg3, arg4)` + +用途：N期相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | -------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@ReportOfAll(46080, DefaultRepID())` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `lowestOfNReport(expression, date_value_2, arg3, arg4)` + +用途：N期相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | -------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@ReportOfAll(46080, DefaultRepID())` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `standGrowthOfNReport(expression, report_id, n, report_type)` + +用途：N期相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `report_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `eAVOfNReport(expression, report_id, n, report_type, last_report_type)` + +用途：N期相关函数。 + +参数个数：5 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `report_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 5 | `last_report_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `eAAOfNReport(expression, report_id, last_report_type)` + +用途：N期相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `last_report_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `turnPositiveOfNReport(expression, report_id, n, report_type)` + +用途：N期相关函数。 + +参数个数：4 +返回值：整数。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `report_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `secondOrderGrowthOfNReport(expression, report_id, n, report_type)` + +用途：N期相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `report_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `highGrowthOfNReport(expression, report_id, n, report_type, range)` + +用途：N期相关函数。 + +参数个数：5 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | +| 4 | `report_type` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 5 | `range` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | diff --git a/docs/tsl/reference/catalog/datawarehouse/23_wizard_n_days.md b/docs/tsl/reference/catalog/datawarehouse/23_wizard_n_days.md new file mode 100644 index 00000000..14795ec6 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/23_wizard_n_days.md @@ -0,0 +1,487 @@ +# 数据仓库金融函数 - 向导函数 / N日 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / N日 + +### `highestOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `refValue(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | + +### `occuredOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | + +### `growthOfNDay(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `swingOfNDay(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `continuedMatchOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `3` | + +### `stdOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `sumOfNDay(expression, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | --------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@vol()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | + +### `lowestOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `occuredTimeOfNDay(expression, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | --------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@vol()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | + +### `avgOfNDay(expression, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `growthWithHighestOfNDay(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `growthWithLowestOfNDay(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `timeOfHighestOfNDay(expression, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `timeOfLowestOfNDay(expression, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `medianOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `kurtosisOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `skewnessOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | + +### `covOfNDay(expression, arg2, stock_id_3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `stock_id_3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `rSQOfNDay(expression, arg2, stock_id_3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `stock_id_3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `steyxOfNDay(expression, arg2, stock_id_3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `stock_id_3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `slopeOfNDay2(expression, arg2, stock_id_3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `stock_id_3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `correlOfNDay2(expression, arg2, stock_id_3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `stock_id_3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `interceptOfNDay2(expression, arg2, stock_id_3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `stock_id_3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `correlOfNDay(expression, expression_2, arg3, arg4)` + +用途：N日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | ------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@stockpjcj3()` | +| 2 | `expression_2` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@RefValue(@close(), 5)` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `decayAvgOfNDay(expression, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `deltaOfNDay(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `5` | + +### `hhvBarsOfNDay(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `interceptofNday(expression, expression_2, arg3, arg4)` + +用途：N日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `expression_2` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `100` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `llvBarsOfNDay()` + +用途：向导函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `percentRankOfNDay(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `signedPower(expression, arg2)` + +用途：N日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `3` | + +### `slopeofNday(expression, expression_2, arg3, arg4)` + +用途：N日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `expression_2` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `covarOfNDay(expression, expression_2, arg3, arg4)` + +用途：N日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `expression_2` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `productOfNDay(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `3` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `wmaofNday(expression, arg2, arg3)` + +用途：N日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ---------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `sumifofNday(expression, arg2, arg3, arg4)` + +用途：进行数值统计计算。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | --------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"@open()>@close()"` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `smaofNDay(expression, arg2, arg3, arg4)` + +用途：N日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ---------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `30` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | diff --git a/docs/tsl/reference/catalog/datawarehouse/24_wizard_n_days_intermediate.md b/docs/tsl/reference/catalog/datawarehouse/24_wizard_n_days_intermediate.md new file mode 100644 index 00000000..933e27ea --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/24_wizard_n_days_intermediate.md @@ -0,0 +1,29 @@ +# 数据仓库金融函数 - 向导函数 / N日 / 中间函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / N日 / 中间函数 + +### `getExpCaceStr(expression)` + +用途：向导函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `techCal_unit(expression)` + +用途：向导函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | diff --git a/docs/tsl/reference/catalog/datawarehouse/25_wizard_legacy.md b/docs/tsl/reference/catalog/datawarehouse/25_wizard_legacy.md new file mode 100644 index 00000000..4637fc6a --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/25_wizard_legacy.md @@ -0,0 +1,30 @@ +# 数据仓库金融函数 - 向导函数 / 历史遗留 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / 历史遗留 + +### `sumOfSectorExceptNoTrade(expression)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `avgOfSectorExceptNoTrade(expression, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | diff --git a/docs/tsl/reference/catalog/datawarehouse/26_wizard_range.md b/docs/tsl/reference/catalog/datawarehouse/26_wizard_range.md new file mode 100644 index 00000000..a65c6d24 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/26_wizard_range.md @@ -0,0 +1,437 @@ +# 数据仓库金融函数 - 向导函数 / 区间 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / 区间 + +### `sumOfPeriod(expression, date_value_2, date_value_3)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180802T` | + +### `swingOfPeriod(expression, date_value_2, date_value_3, arg4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180802T` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `highestOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180802T` | + +### `timeOfHighestOfPeriod(expression, date_value_2, date_value_3)` + +用途：日期时间处理函数。 + +参数个数：3 +返回值：日期或时间值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180802T` | + +### `occuredOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@IsUp()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `avgOfPeriod(expression, date_value_2, date_value_3)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180802T` | + +### `occuredOfRepPeriod(expression, date_value_2, arg3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20150331` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2018` | + +### `continuedMatchOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180803T` | + +### `lowestOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180803T` | + +### `avgOfRepPeriod(expression, date_value_2, arg3)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20150331` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2018` | + +### `sumOfRepPeriod(expression, date_value_2, arg3)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20150331` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2018` | + +### `growthOfPeriod(expression, date_value_2, date_value_3, arg4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180803T` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `timeOfLowestOfPeriod(expression, date_value_2, date_value_3)` + +用途：日期时间处理函数。 + +参数个数：3 +返回值：日期或时间值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180801T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20180802T` | + +### `hhvBarsOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `llvBarsOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `highestOfRepPeriod2(expression, date_value_2, date_value_3, arg4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `date_value_3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `lowestOfRepPeriod2(expression, date_value_2, date_value_3, arg4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `date_value_3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `medianOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `percentRankOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `skewnessOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `kurtosisOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `growthOfRepPeriod2(expression, date_value_2, date_value_3, arg4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `date_value_3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `sumOfRepPeriod2(expression, date_value_2, date_value_3, arg4)` + +用途：进行数值统计计算。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `date_value_3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `avgOfRepPeriod2(expression, date_value_2, date_value_3, arg4)` + +用途：进行数值统计计算。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `date_value_3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `stdOfPeriod(expression, date_value_2, date_value_3)` + +用途：区间相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | + +### `stdOfRepPeriod2(expression, date_value_2, date_value_3, arg4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | --------------------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@reportofall(46002, GetSysParam('DefaultRepID'))` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20201231` | +| 3 | `date_value_3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `correlOfPeriod(expression, date_value_2, date_value_3, stock_id_4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230901T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | +| 4 | `stock_id_4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `rSQOfPeriod(expression, date_value_2, date_value_3, stock_id_4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230901T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | +| 4 | `stock_id_4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `slopeOfPeriod(expression, date_value_2, date_value_3, stock_id_4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230901T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | +| 4 | `stock_id_4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `interceptOfPeriod(expression, date_value_2, date_value_3, stock_id_4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230901T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | +| 4 | `stock_id_4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `covOfPeriod(expression, date_value_2, date_value_3, stock_id_4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230901T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | +| 4 | `stock_id_4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | + +### `steyxOfPeriod(expression, date_value_2, date_value_3, stock_id_4)` + +用途：区间相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230901T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | +| 4 | `stock_id_4` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"SH000001"` | diff --git a/docs/tsl/reference/catalog/datawarehouse/27_wizard_intermediate.md b/docs/tsl/reference/catalog/datawarehouse/27_wizard_intermediate.md new file mode 100644 index 00000000..7db10388 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/27_wizard_intermediate.md @@ -0,0 +1,107 @@ +# 数据仓库金融函数 - 向导函数 / 中间函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / 中间函数 + +### `ratioValueByType(arg1, arg2, arg3, arg4)` + +用途：中间函数相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | + +### `isValidValue(arg1)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `10` | + +### `filterSampleByCriterion_wiz(stock_id, date_value_2, arg3, arg4, date_value_5)` + +用途：中间函数相关函数。 + +参数个数：5 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------------------------------------------------------------------- | +| 1 | `stock_id` | 是 | 数组 | 按源文档示例顺序传入；示例参数形态为 `array("SZ000001", "SZ000002")` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20150101` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 5 | `date_value_5` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20180801` | + +### `compositeRatioValue(arg1, arg2, arg3)` + +用途：中间函数相关函数。 + +参数个数：3 +返回值：整数。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `4` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | + +### `simplyRatioValue(arg1, arg2)` + +用途：中间函数相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | + +### `isNull(arg1)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `isValidPositiveValue(arg1)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `reportValueOfPeriod(expression, date_value_2, date_value_3)` + +用途：向导函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230110T` | diff --git a/docs/tsl/reference/catalog/datawarehouse/28_wizard_n_quarters.md b/docs/tsl/reference/catalog/datawarehouse/28_wizard_n_quarters.md new file mode 100644 index 00000000..1c08cc87 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/28_wizard_n_quarters.md @@ -0,0 +1,85 @@ +# 数据仓库金融函数 - 向导函数 / N季 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / N季 + +### `sumOfNReport2(expression, report_id, n)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `avgOfNReport2(expression, report_id, n)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `stdOfNReport2(expression, report_id, n)` + +用途：N季相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `accOfNReport2(expression, report_id, n)` + +用途：向导函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `robustGrowthOfNReport2(expression, report_id, n)` + +用途：N季相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | + +### `robustAccOfNReport2(expression, report_id, n)` + +用途：N季相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `report_id` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `n` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `8` | diff --git a/docs/tsl/reference/catalog/datawarehouse/29_wizard_today.md b/docs/tsl/reference/catalog/datawarehouse/29_wizard_today.md new file mode 100644 index 00000000..a22b3de5 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/29_wizard_today.md @@ -0,0 +1,211 @@ +# 数据仓库金融函数 - 向导函数 / 当日 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / 当日 + +### `percentRankOftheReport(expression, date_value_2)` + +用途：当日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | -------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@ReportOfAll(46002, DefaultRepID())` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | + +### `percentRankOftheDay3(expression, arg2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `rankOftheReport(expression, date_value_2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | -------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@ReportOfAll(46002, DefaultRepID())` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `rankOftheDay3(expression, arg2, arg3, arg4)` + +用途：当日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `scaleOfSeries3(expression, arg2, arg3, arg4)` + +用途：当日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `scaleOfSeriesOftheReport(expression, date_value_2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | -------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@ReportOfAll(46002, DefaultRepID())` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `indNeutralize4(expression, arg2, arg3, arg4)` + +用途：当日相关函数。 + +参数个数：4 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `indNeutralizeOftheReport(expression, date_value_2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ---------- | -------------------------------------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@ReportOfAll(46002, DefaultRepID())` | +| 2 | `date_value_2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `20221231` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `indNeutralize(expression, arg2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ---------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `indNeutralize2(expression, arg2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ---------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@open()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `percentRankOftheDay(expression)` + +用途：当日相关函数。 + +参数个数：1 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `percentRankOftheDay2(expression)` + +用途：当日相关函数。 + +参数个数：1 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | + +### `rankOftheDay(expression, arg2)` + +用途：当日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `rankOftheDay2(expression, arg2)` + +用途：当日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------------------ | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象或表达式字符串 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `0` | + +### `scaleOfSeries(expression, arg2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | + +### `scaleOfSeries2(expression, arg2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ---------- | ----------------------------------------------- | +| 1 | `expression` | 是 | 表达式对象 | 按源文档示例顺序传入；示例参数形态为 `@close()` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `""` | diff --git a/docs/tsl/reference/catalog/datawarehouse/30_wizard_today_intermediate.md b/docs/tsl/reference/catalog/datawarehouse/30_wizard_today_intermediate.md new file mode 100644 index 00000000..d929ac05 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/30_wizard_today_intermediate.md @@ -0,0 +1,88 @@ +# 数据仓库金融函数 - 向导函数 / 当日 / 中间函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 向导函数 / 当日 / 中间函数 + +### `cacheStrMerge(arg1, arg2, date_value_3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'1'` | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `2` | +| 3 | `date_value_3` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231020T` | + +### `pn_stockArrName()` + +用途：当日相关函数。 + +参数个数：0 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `getParm_stockArr_byEndt(arg1)` + +用途：当日相关函数。 + +参数个数：1 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ------------ | ------------------------------------------------- | +| 1 | `arg1` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `sp_time(1)` | + +### `getParm_groupIndustry_byEndt(date_value, date_value_2, arg3)` + +用途：当日相关函数。 + +参数个数：3 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------------------------------- | +| 1 | `date_value` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `GetBKByDate('SH000300', 20231010T)` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20231010T` | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `1` | + +### `getHBCacheStr(arg1, date_value_2)` + +用途：向导函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------ | ------------------------------------------------ | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `"A"` | +| 2 | `date_value_2` | 是 | 日期或时间值 | 按源文档示例顺序传入；示例参数形态为 `20230101T` | + +### `setParm_stockArrFunc(b, arg2)` + +用途：当日相关函数。 + +参数个数：2 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `b` | 是 | 任意值 | 按源文档示例顺序传入；示例参数形态为 `"A股"` | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入；示例参数形态为 `'ZZ500'` | + +### `pn_stockArrFunc()` + +用途：当日相关函数。 + +参数个数：0 +返回值：处理后的结果值。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/datawarehouse/31_condition_predicates.md b/docs/tsl/reference/catalog/datawarehouse/31_condition_predicates.md new file mode 100644 index 00000000..f2a22023 --- /dev/null +++ b/docs/tsl/reference/catalog/datawarehouse/31_condition_predicates.md @@ -0,0 +1,18 @@ +# 数据仓库金融函数 - 条件判定 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../datawarehouse.md](../datawarehouse.md)、[../../index.md](../../index.md) + +## 条件判定 + +### `isTimePeriodInfoId(arg1)` + +用途：条件判定相关函数。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入；示例参数形态为 `150003` | diff --git a/docs/tsl/reference/catalog/digest_encoding.md b/docs/tsl/reference/catalog/digest_encoding.md index 3697241d..11663d46 100644 --- a/docs/tsl/reference/catalog/digest_encoding.md +++ b/docs/tsl/reference/catalog/digest_encoding.md @@ -1,39 +1,160 @@ # 信息摘要及编码 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页描述哈希、摘要、编码与转换能力。生成函数调用时，只按函数条目中的参数表传参。 ## 模块范围 - 说明：哈希、摘要、编码与转换能力 -- 主题数：3 -- 函数数：7 +- 函数事实数：11 -## 主题目录 +## 信息摘要函数 -### 信息摘要函数 +### `getMsgDigest(...)` -- `GetMsgDigest` +用途：信息摘要函数相关函数。 -### BASE64编码 +参数个数：2 或 3 +返回值：处理后的摘要结果 -- `StrToBase64` -- `Base64ToStr` +调用形态：`getMsgDigest(value, digest_type)` -### 进制编码函数 +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------------------------------------------------------------------------------ | +| 1 | `value` | 是 | 字符串 | 要计算摘要的字符串 | +| 2 | `digest_type` | 是 | 整数 | 摘要算法编号：`0` CRC32，`1` MD5，`2` SHA1，`3` SHA224，`4` SHA256，`5` SHA384，`6` SHA512 | -- `EncodeRadixstr` -- `DecodeRadixstr` -- `Decoderadixwstr` -- `Encoderadixwstr` +调用形态：`getMsgDigest(alias, filename, digest_type)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------------------------------------------------------------------------------ | +| 1 | `alias` | 是 | 字符串 | 文件所在目录别名；不用别名时传空字符串 | +| 2 | `filename` | 是 | 字符串 | 要计算摘要的文件路径 | +| 3 | `digest_type` | 是 | 整数 | 摘要算法编号：`0` CRC32，`1` MD5，`2` SHA1，`3` SHA224，`4` SHA256，`5` SHA384，`6` SHA512 | + +## BASE64编码 + +### `strToBase64(value)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ---------- | +| 1 | `value` | 是 | 字符串 | 原始字符串 | + +### `base64ToStr(value)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ----------------- | +| 1 | `value` | 是 | 字符串 | Base64 编码字符串 | + +## 进制编码函数 + +### `encodeRadixstr(value, affix, radix_mode)` + +用途：进制编码函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------------------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 要编码的字符串 | +| 2 | `affix` | 是 | 字符串 | 前缀或后缀标记 | +| 3 | `radix_mode` | 是 | 整数 | 进制和格式控制；叠加 `0x80000000` 表示后缀，叠加 `0x40000000` 表示小写字母 | + +### `decodeRadixstr(value, affix_length, radix_mode)` + +用途：进制编码函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ---------------------------------------- | +| 1 | `value` | 是 | 字符串 | 要解码的编码字符串 | +| 2 | `affix_length` | 是 | 整数 | 前缀或后缀标记长度，不是标记字符串本身 | +| 3 | `radix_mode` | 是 | 整数 | 进制和格式控制；需与编码时使用的模式匹配 | + +### `encoderadixwstr(value, affix, radix_mode)` + +用途：进制编码函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------------------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 要编码的字符串 | +| 2 | `affix` | 是 | 字符串 | 前缀或后缀标记 | +| 3 | `radix_mode` | 是 | 整数 | 进制和格式控制；叠加 `0x80000000` 表示后缀，叠加 `0x40000000` 表示小写字母 | + +### `decoderadixwstr(value, affix_length, radix_mode)` + +用途：进制编码函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ---------------------------------------- | +| 1 | `value` | 是 | 字符串 | 要解码的宽字符编码字符串 | +| 2 | `affix_length` | 是 | 整数 | 前缀或后缀标记长度，不是标记字符串本身 | +| 3 | `radix_mode` | 是 | 整数 | 进制和格式控制；需与编码时使用的模式匹配 | + +## URI 编码函数 + +### `encodeURIComponent(value)` + +用途：按 URI component 规则编码字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `value` | 是 | 字符串 | 待编码字符串 | + +### `decodeURIComponent(value)` + +用途：按 URI component 规则解码字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `value` | 是 | 字符串 | 待解码字符串 | + +### `encodeURI(value)` + +用途：按 URI 规则编码字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `value` | 是 | 字符串 | 待编码字符串 | + +### `decodeURI(value)` + +用途：按 URI 规则解码字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `value` | 是 | 字符串 | 待解码字符串 | diff --git a/docs/tsl/reference/catalog/dotnet.md b/docs/tsl/reference/catalog/dotnet.md new file mode 100644 index 00000000..79b9f638 --- /dev/null +++ b/docs/tsl/reference/catalog/dotnet.md @@ -0,0 +1,169 @@ +# Windows/.NET 专属函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数只按 Windows/.NET/COM 环境生成调用 +遇到不确定时：先回到 [../index.md](../index.md) 重新确认平台；目标不是 Windows/.NET/COM 环境时再改查 [base.md](base.md)、[system.md](system.md) 或 [platform.md](platform.md) + +这一页只列出 Windows/.NET/COM 专属函数。非 Windows/.NET/COM 环境不要从本页生成调用。 + +## 模块范围 + +- 说明：Windows/.NET/COM 专属函数；包含 .NET 环境辅助函数和 Windows COM/OLE 函数 +- 函数事实数：12 + +## 基础函数 + +### `floatN(value, digits)` + +用途：将浮点数按指定小数位数四舍五入。 + +参数个数：2 +返回值：数值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------- | +| 1 | `value` | 是 | 实数 | 输入数值 | +| 2 | `digits` | 是 | 整数 | 保留的小数位数 | + +### `floatToStrEx(value, digits)` + +用途：将浮点数格式化为字符串，保留指定小数位数。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------- | +| 1 | `value` | 是 | 实数 | 输入数值 | +| 2 | `digits` | 是 | 整数 | 保留的小数位数 | + +### `formatFloatExt(value[, format])` + +用途：按扩展格式输出数值字符串，支持千分位与空值处理。 + +参数个数：1 到 2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | ----------- | -------------------------------- | +| 1 | `value` | 是 | 数值/字符串 | 输入数值；源文档示例也传入字符串 | +| 2 | `format` | 否 | 整数 | 格式参数（可选） | + +### `webZero(value)` + +用途：当数值为 0 时返回空字符串，否则返回数值字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 数值 | 输入数值 | + +### `roundTo5(value)` + +用途：将数值按 0.5 的步长进行四舍五入。 + +参数个数：1 +返回值：数值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 数值 | 输入数值 | + +### `simpleRoundTo2(value, digits)` + +用途：按指定小数位数进行四舍五入（对负数同样生效）。 + +参数个数：2 +返回值：数值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------- | +| 1 | `value` | 是 | 数值 | 输入数值 | +| 2 | `digits` | 是 | 整数 | 保留的小数位数 | + +### `divValue(v1, v2)` + +用途：当除数不为 0 时返回 `v1 / v2`，否则返回 `0`。 + +参数个数：2 +返回值：数值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------ | +| 1 | `v1` | 是 | 数值 | 被除数 | +| 2 | `v2` | 是 | 数值 | 除数 | + +### `dataisequal(a, b)` + +用途：判断两个数据是否相等。 + +参数个数：2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------- | +| 1 | `a` | 是 | 任意值 | 待比较数据 | +| 2 | `b` | 是 | 任意值 | 待比较数据 | + +## 系统相关函数 + +### `getOleObject(prog_id, flags, out_obj)` + +用途：获取已注册的 OLE/COM 对象实例（仅 Windows）。 + +参数个数：3 +返回值：是否获取成功（1/0） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | ----------------------------------- | +| 1 | `prog_id` | 是 | 字符串 | COM ProgID（如 `Word.Application`） | +| 2 | `flags` | 是 | 整数 | 选项标记（可选，通常为 `0`） | +| 3 | `out_obj` | 是 | 任意值 | 输出对象变量 | + +### `createComObject(guid_or_prog_id, out_obj)` + +用途：创建 Windows COM 对象实例（仅 Windows COM 环境）。 + +参数个数：2 +返回值：是否创建成功（1/0） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | -------------------------------------------------------------------------------------------------- | +| 1 | `guid_or_prog_id` | 是 | 字符串 | COM ProgID 或带花括号的 CLSID；例如 `Word.Application` 或 `{000209FF-0000-0000-C000-000000000046}` | +| 2 | `out_obj` | 是 | 任意值 | 输出对象变量；调用前通常先设为 `nil` | + +生成规则： + +- 函数名使用 `CreateComObject`；不要写成 `CreateComObj`。 +- 必须使用双参数形式，把 COM 对象写入第二个输出变量；不要生成单参调用。 +- 仅在 Windows COM 环境生成；目标机器必须安装并注册对应 COM 组件，位数、权限和 Office 自动化环境必须匹配。 +- 如果创建的是 Word COM 对象，用完后按对象能力调用 `obj.Quit()`，避免留下隐藏的 `WINWORD.EXE`。 +- `guid_or_prog_id` 可传 ProgID，也可传带花括号 CLSID；不要传不带花括号的裸 CLSID 字符串。 + +### `ifThen3(left, right, greater_value, equal_value, less_value)` + +用途：比较两个值，返回大/等/小对应结果。 + +参数个数：5 +返回值：对应比较结果的值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | --------------------- | +| 1 | `left` | 是 | 任意值 | 左值 | +| 2 | `right` | 是 | 任意值 | 右值 | +| 3 | `greater_value` | 是 | 任意值 | `left > right` 时返回 | +| 4 | `equal_value` | 是 | 任意值 | `left = right` 时返回 | +| 5 | `less_value` | 是 | 任意值 | `left < right` 时返回 | + +### `safeEval(expr)` + +用途：安全执行表达式或表达式字符串，执行失败返回 nil。 + +参数个数：1 +返回值：表达式结果或 nil + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------ | +| 1 | `expr` | 是 | 字符串 | 表达式（@）或表达式字符串（&） | diff --git a/docs/tsl/reference/catalog/graphics.md b/docs/tsl/reference/catalog/graphics.md index b710aa55..98897f9b 100644 --- a/docs/tsl/reference/catalog/graphics.md +++ b/docs/tsl/reference/catalog/graphics.md @@ -1,59 +1,31 @@ # 图形函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实路由页 +是否可直接用于生成代码：是；进入分类详情页后按函数事实条目生成调用 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页是图形函数的轻量入口，不直接承载全部函数事实。生成函数调用时，先按分类目录进入详情页，再只读取命中的函数条目和参数表。 ## 模块范围 - 说明：图表、绘图与可视化相关函数 -- 主题数：3 -- 函数数：27 +- 函数事实数：87 -## 主题目录 +## 智能体检索规则 -### 作图函数 +1. 用户只描述能力时，先按“分类目录”选择候选详情页。 +2. 用户给出函数名时，优先在 `graphics/` 子目录中搜索三级函数标题。 +3. 只读取命中的函数条目、相邻分类标题和必要参数表；不要把同页其它函数混进当前调用。 +4. 没有命中函数事实条目时，不要发明函数名；回到 [../index.md](../index.md) 或项目实际代码确认。 -- `Graph` -- `GraphGroup` -- `MergeGraph` -- `EncodeGraphGroup` -- `DecodeGraphGroup` -- `DecodeGraph` -- `EncodeGraph` -- `FastLine_Web` -- `GetColorByIndex` +## 分类目录 -### 图形字段函数 - -- `gfColor` -- `gfFill` -- `gfFlag` -- `gfZero` -- `gfMaxValue` -- `gfMinValue` -- `gfLTP` -- `gfTitleCaption` -- `gfLeftTitleCaption` -- `gfCoordinate` - -### 图形填充设置函数 - -- `flSolid` -- `flClear` -- `flHorizontal` -- `flVertical` -- `flFDiagonal` -- `flBDiagonal` -- `flCross` -- `flDiagCross` +| 分类 | 详情页 | 函数事实数 | +| ---------------- | ---------------------------------------------------------------- | ---------: | +| 作图函数 | [graphics/01_drawing.md](graphics/01_drawing.md) | 7 | +| 图形字段函数 | [graphics/02_graph_fields.md](graphics/02_graph_fields.md) | 22 | +| 图形填充设置函数 | [graphics/03_graph_fill.md](graphics/03_graph_fill.md) | 8 | +| 图形类型函数 | [graphics/04_graph_types.md](graphics/04_graph_types.md) | 7 | +| 图形标示函数 | [graphics/05_graph_markers.md](graphics/05_graph_markers.md) | 9 | +| 颜色函数 | [graphics/06_color.md](graphics/06_color.md) | 22 | +| 颜色变换函数 | [graphics/07_color_transform.md](graphics/07_color_transform.md) | 12 | diff --git a/docs/tsl/reference/catalog/graphics/01_drawing.md b/docs/tsl/reference/catalog/graphics/01_drawing.md new file mode 100644 index 00000000..1add48f7 --- /dev/null +++ b/docs/tsl/reference/catalog/graphics/01_drawing.md @@ -0,0 +1,100 @@ +# 图形函数 - 作图函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../graphics.md](../graphics.md)、[../../index.md](../../index.md) + +## 作图函数 + +### `mergeGraph(graph1, graph2, graph3, graph4)` + +用途：合并多个图形对象。 + +参数个数：4 +返回值：处理后的图形结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------- | +| 1 | `graph1` | 是 | 图形对象 | 第一个图形 | +| 2 | `graph2` | 是 | 图形对象 | 第二个图形 | +| 3 | `graph3` | 是 | 图形对象 | 第三个图形 | +| 4 | `graph4` | 是 | 图形对象 | 第四个图形 | + +### `encodeGraphGroup(graphs, options)` + +用途：编码图形组合。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | ------------ | +| 1 | `graphs` | 是 | 数组 | 图形对象数组 | +| 2 | `options` | 是 | 数组 | 编码选项 | + +### `decodeGraphGroup(data, out_graph, out_data)` + +用途：分解图形组合。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------- | -------------------- | +| 1 | `data` | 是 | 图形组合/数组 | 待分解的图形组合数据 | +| 2 | `out_graph` | 是 | 变量引用 | 输出分解后的图形 | +| 3 | `out_data` | 是 | 变量引用 | 输出分解后的数据 | + +### `decodeGraph(graph, out_type, out_name, out_data, out_property)` + +用途：分解图形对象。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------ | +| 1 | `graph` | 是 | 图形对象 | 待分解的图形 | +| 2 | `out_type` | 是 | 变量引用 | 输出图形类型 | +| 3 | `out_name` | 是 | 变量引用 | 输出图形名称 | +| 4 | `out_data` | 是 | 变量引用 | 输出图形数据 | +| 5 | `out_property` | 是 | 变量引用 | 输出图形属性 | + +### `encodeGraph(graph_type, name, data, options)` + +用途：编码图形对象。 + +参数个数：4 +返回值：处理后的图形结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | ------------- | -------- | +| 1 | `graph_type` | 是 | 整数/图形类型 | 图形类型 | +| 2 | `name` | 是 | 字符串 | 图形名称 | +| 3 | `data` | 是 | 数组 | 图形数据 | +| 4 | `options` | 是 | 数组 | 图形选项 | + +### `graphGroup(arg1, arg2, arg3, arg4)` + +用途：作图函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `getColorByIndex(index)` + +用途：按颜色索引获取颜色值。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `index` | 是 | 整数 | 颜色索引 | diff --git a/docs/tsl/reference/catalog/graphics/02_graph_fields.md b/docs/tsl/reference/catalog/graphics/02_graph_fields.md new file mode 100644 index 00000000..a9ece27c --- /dev/null +++ b/docs/tsl/reference/catalog/graphics/02_graph_fields.md @@ -0,0 +1,227 @@ +# 图形函数 - 图形字段函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../graphics.md](../graphics.md)、[../../index.md](../../index.md) + +## 图形字段函数 + +### `gfColor()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfFill()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfFlag()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfZero()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfMaxValue()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfMinValue()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfLTP()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfTitleCaption()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfLeftTitleCaption()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfCoordinate()` + +用途：图形字段函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfValue()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfClose()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfOpen()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfHigh()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfLow()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfTowerLow()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfTowerHigh()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfTowerMid()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfVol()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfAmount()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfTime()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gfRateFlag()` + +用途：返回图形字段常量。 + +参数个数：0 +返回值：图形字段常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/graphics/03_graph_fill.md b/docs/tsl/reference/catalog/graphics/03_graph_fill.md new file mode 100644 index 00000000..f550aa3b --- /dev/null +++ b/docs/tsl/reference/catalog/graphics/03_graph_fill.md @@ -0,0 +1,87 @@ +# 图形函数 - 图形填充设置函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../graphics.md](../graphics.md)、[../../index.md](../../index.md) + +## 图形填充设置函数 + +### `flSolid()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flClear()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flHorizontal()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flVertical()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flFDiagonal()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flBDiagonal()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flCross()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `flDiagCross()` + +用途：图形填充设置函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/graphics/04_graph_types.md b/docs/tsl/reference/catalog/graphics/04_graph_types.md new file mode 100644 index 00000000..2ce16635 --- /dev/null +++ b/docs/tsl/reference/catalog/graphics/04_graph_types.md @@ -0,0 +1,77 @@ +# 图形函数 - 图形类型函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../graphics.md](../graphics.md)、[../../index.md](../../index.md) + +## 图形类型函数 + +### `gtLine()` + +用途：返回图形类型常量。 + +参数个数：0 +返回值：图形类型常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gtKLine()` + +用途：返回图形类型常量。 + +参数个数：0 +返回值：图形类型常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gtTower()` + +用途：返回图形类型常量。 + +参数个数：0 +返回值：图形类型常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gtAmerican()` + +用途：返回图形类型常量。 + +参数个数：0 +返回值：图形类型常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gtBar()` + +用途：返回图形类型常量。 + +参数个数：0 +返回值：图形类型常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gtSingleBar()` + +用途：返回图形类型常量。 + +参数个数：0 +返回值：图形类型常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `gtCircle()` + +用途：返回图形类型常量。 + +参数个数：0 +返回值：图形类型常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/graphics/05_graph_markers.md b/docs/tsl/reference/catalog/graphics/05_graph_markers.md new file mode 100644 index 00000000..650a2e66 --- /dev/null +++ b/docs/tsl/reference/catalog/graphics/05_graph_markers.md @@ -0,0 +1,97 @@ +# 图形函数 - 图形标示函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../graphics.md](../graphics.md)、[../../index.md](../../index.md) + +## 图形标示函数 + +### `fgNone()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgUp()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgDown()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgLeft()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgRight()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgLeftUp()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgLeftDown()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgRightUp()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fgRightDown()` + +用途：返回图形标示常量。 + +参数个数：0 +返回值：图形标示常量 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/graphics/06_color.md b/docs/tsl/reference/catalog/graphics/06_color.md new file mode 100644 index 00000000..07c34a83 --- /dev/null +++ b/docs/tsl/reference/catalog/graphics/06_color.md @@ -0,0 +1,227 @@ +# 图形函数 - 颜色函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../graphics.md](../graphics.md)、[../../index.md](../../index.md) + +## 颜色函数 + +### `clBlack()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clMaroon()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clGreen()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clOlive()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clNavy()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clPurple()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clTeal()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clGray()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clSilver()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clRed()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clLime()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clYellow()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clBlue()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clFuchsia()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clAqua()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clLtGray()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clDkGray()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clWhite()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clMoneyGreen()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clSkyBlue()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clCream()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `clMedGray()` + +用途：返回颜色常量。 + +参数个数：0 +返回值：颜色值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/graphics/07_color_transform.md b/docs/tsl/reference/catalog/graphics/07_color_transform.md new file mode 100644 index 00000000..e7ee7034 --- /dev/null +++ b/docs/tsl/reference/catalog/graphics/07_color_transform.md @@ -0,0 +1,146 @@ +# 图形函数 - 颜色变换函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../graphics.md](../graphics.md)、[../../index.md](../../index.md) + +## 颜色变换函数 + +### `getCValue(color)` + +用途：从颜色值中取 C 分量。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | + +### `getMValue(color)` + +用途：从颜色值中取 M 分量。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | + +### `getYValue(color)` + +用途：从颜色值中取 Y 分量。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | + +### `getKValue(color)` + +用途：从颜色值中取 K 分量。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | + +### `cmyk(c, m, y, k)` + +用途：按 C、M、Y、K 分量生成颜色值。 + +参数个数：4 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------ | +| 1 | `c` | 是 | 整数 | C 分量 | +| 2 | `m` | 是 | 整数 | M 分量 | +| 3 | `y` | 是 | 整数 | Y 分量 | +| 4 | `k` | 是 | 整数 | K 分量 | + +### `rgb(r, g, b)` + +用途：按 R、G、B 分量生成颜色值。 + +参数个数：3 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------ | +| 1 | `r` | 是 | 整数 | R 分量 | +| 2 | `g` | 是 | 整数 | G 分量 | +| 3 | `b` | 是 | 整数 | B 分量 | + +### `rgbbgr(color)` + +用途：转换 RGB/BGR 颜色值。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | + +### `paletteRGB(r, g, b)` + +用途：按 R、G、B 分量生成调色板颜色值。 + +参数个数：3 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------ | +| 1 | `r` | 是 | 整数 | R 分量 | +| 2 | `g` | 是 | 整数 | G 分量 | +| 3 | `b` | 是 | 整数 | B 分量 | + +### `paletteIndex(index)` + +用途：按调色板索引生成颜色值。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ---------- | +| 1 | `index` | 是 | 整数 | 调色板索引 | + +### `getRValue(color)` + +用途：从颜色值中取 R 分量。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | + +### `getGValue(color)` + +用途：从颜色值中取 G 分量。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | + +### `getBValue(color)` + +用途：从颜色值中取 B 分量。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `color` | 是 | 整数 | 颜色值 | diff --git a/docs/tsl/reference/catalog/index.md b/docs/tsl/reference/catalog/index.md deleted file mode 100644 index f24a0923..00000000 --- a/docs/tsl/reference/catalog/index.md +++ /dev/null @@ -1,41 +0,0 @@ -# Function Catalog - -这里是候选函数索引。它只回答“函数名可能在哪个模块里”，不承担基础语法教学，也不证明函数在当前环境可用。 - -候选名没有进入 verified 函数页前不能当成可调用事实。agent 真正生成代码前，只从 verified 函数页读取参数类型。 - -## 使用顺序 - -1. 不知道函数在哪个模块，先看下面的模块目录。 -2. 进入模块页后，在页内搜索具体候选函数名。 -3. 如果要生成代码，先看 [../verified/index.md](../verified/index.md)，再进入具体函数页；当前核心函数页是 [../verified/core.md](../verified/core.md)。 -4. 如果候选函数没有进入 verified 函数页，不要生成调用代码。 -5. 如果问题是语法怎么写，回到 [../../syntax/index.md](../../syntax/index.md)。 -6. 如果问题是金融场景如何组织，回到 [../../finance/index.md](../../finance/index.md)。 - -## 模块目录 - -| 模块 | 分类页 | 范围 | 函数数 | -| -------------- | ---------------------------------------- | ---------------------------------------------- | ------ | -| 基础函数 | [base.md](base.md) | 字符串、数组、日期时间、类型转换与常用基础能力 | 574 | -| 数学函数 | [math.md](math.md) | 数值计算、统计分析、矩阵处理与数学算法 | 518 | -| 系统相关函数 | [system.md](system.md) | 数据类型、表达式调用、性能与运行时能力 | 57 | -| 资源访问函数 | [resource.md](resource.md) | 文件、数据库、网络与外部资源访问 | 136 | -| 平台函数 | [platform.md](platform.md) | 平台相关功能与系统接口 | 19 | -| 客户端函数 | [client.md](client.md) | 客户端交互、界面控制与前端协作能力 | 19 | -| 图形函数 | [graphics.md](graphics.md) | 图表、绘图与可视化相关函数 | 27 | -| 压缩和解压函数 | [compression.md](compression.md) | 压缩、解压与归档能力 | 5 | -| 信息摘要及编码 | [digest_encoding.md](digest_encoding.md) | 哈希、摘要、编码与转换能力 | 7 | -| 第三方交互函数 | [third_party.md](third_party.md) | 第三方库与外部程序交互能力 | 8 | - -## 说明 - -- 这套目录页由仓库内的函数语料自动整理生成。 -- catalog 只保留候选函数索引，不写参数矩阵，不写可调用结论。 -- 当前目标是先提供稳定检索层，再逐步补全 agent 可直接读取的参数事实。 - -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 diff --git a/docs/tsl/reference/catalog/math.md b/docs/tsl/reference/catalog/math.md index 253d84e4..cf357d7e 100644 --- a/docs/tsl/reference/catalog/math.md +++ b/docs/tsl/reference/catalog/math.md @@ -1,661 +1,37 @@ # 数学函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实路由页 +是否可直接用于生成代码：是；进入分类详情页后按函数事实条目生成调用 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页是数学函数的轻量入口，不直接承载全部函数事实。生成函数调用时，先按分类目录进入详情页，再只读取命中的函数条目和参数表。 ## 模块范围 - 说明：数值计算、统计分析、矩阵处理与数学算法 -- 主题数：40 -- 函数数：518 - -## 主题目录 - -### 数值计算 / 数值微积分 - -- `ig_Romberg` -- `integral` -- `ig_Trapezoid_1` -- `ig_Trapezoid_2` -- `ig_Simpson_1` -- `ig_Gauss` -- `ig_Chebyshev` -- `ig_Simpson_2` -- `sf_SinX` -- `sf_CosX` -- `sf_eX` -- `sf_EllipseX_1` -- `sf_EllipseX_2` -- `Conv` -- `Hessian` - -### 数值计算 / 线性方程组的求解 - -- `se_Gauss` -- `se_Gauss_Jordan` -- `se_Ldl` -- `se_Cholesky` -- `se_Gauss_Seidel` - -### 数值计算 / 插值 - -- `interp` -- `interp_unit` -- `ip_Lagrangian_A` -- `ip_Lagrangian_B` -- `ip_Parabola_A` -- `ip_Parabola_B` -- `ip_Hermite_A` -- `ip_Hermite_B` -- `ip_Aitken_A` -- `ip_Aitken_B` -- `ip_Spline_A` -- `ip_Spline_B` -- `ip_Spline_C` -- `ip_SLQ` -- `ip_SLG` - -### 数值计算 / 矩阵运算及分解 - -- `mt_Transposition` -- `mt_Multiplication` -- `mt_Addition` -- `mt_iv_Gauss_Jordan` -- `mt_iv_Ldl` -- `mt_Subtraction` -- `Mt_decompose_lu` -- `mt_decompose_qr` -- `mt_decompose_chol` -- `chol` -- `mt_va_Gauss_Jordan` -- `mt_decompose_svd` -- `mt_decompose_ldl` -- `mt_decompose_eig` -- `Standarize_II` -- `ReIndex2` -- `Det` -- `isSymmetry` -- `Orth` -- `roots` -- `Eigen` -- `pinv` -- `norm2` -- `Cond` -- `diag` -- `isDefinite` - -### 数值计算 / 数组扩展 - -- `Any` -- `ALL` - -### 数值计算 / 其他 - -- `perms` -- `nchoosek` -- `MaxDrawDown` -- `MinRecoveryTime` -- `Betainc` -- `PercentileOfScore` -- `GenerateCombinations` -- `Percentage` - -### 常用数学函数 - -- `Pi` -- `Odd` -- `Abs` -- `Sqr` -- `Sqrt` -- `DivMod` -- `Frexp` -- `Ldexp` -- `Poly` - -### 三角函数 - -- `Sin` -- `Cos` -- `SinCos` -- `Tan` -- `Cot` -- `CoTan` -- `Sec` -- `Csc` -- `Secant` -- `Cosecant` -- `ArcSin` -- `ArcCos` -- `ArcTan` -- `ArcTan2` -- `ArcCot` -- `ArcSec` -- `ArcCsc` -- `Hypot` - -### 角度量转换 - -- `RadToDeg` -- `RadToGrad` -- `RadToCycle` -- `DegToRad` -- `DegToGrad` -- `DegToCycle` -- `GradToRad` -- `GradToDeg` -- `GradToCycle` -- `CycleToRad` -- `CycleToDeg` -- `CycleToGrad` - -### 双曲线函数 - -- `Sinh` -- `Cosh` -- `Tanh` -- `CotH` -- `SecH` -- `CscH` -- `ArcCosh` -- `ArcSinh` -- `ArcTanh` -- `ArcCotH` -- `ArcSecH` -- `ArcCscH` - -### 指数对数函数 - -- `Ln` -- `LnXP1` -- `Log10` -- `Log2` -- `LogN` -- `Exp` -- `IntPower` -- `Power` - -### 精度设置及取整运算 - -- `Int` -- `Ceil` -- `Ceil32` -- `Ceil64` -- `Floor` -- `Floor32` -- `Floor64` -- `Trunc` -- `Trunc32` -- `Trunc64` -- `Frac` -- `Round` -- `Round32` -- `Round64` -- `SimpleRound` -- `SimpleRound32` -- `SimpleRound64` -- `RoundTo` -- `SimpleRoundTo` - -### 比较判断函数 - -- `IsNan` -- `IsInfinite` -- `Sign` -- `IsZero` -- `Min` -- `Max` -- `CompareValue` -- `SameValue` -- `RandomRange` -- `InRange` -- `EnsureRange` - -### 一般统计量 - -- `MinIntValue` -- `SumOfSquares` -- `StdDev` -- `Mean` -- `Sum` -- `MaxValue` -- `MinValue` -- `Norm` -- `SumsAndSquares` -- `MaxIntValue` -- `SumInt` -- `Harmean` -- `Variance` -- `MeanAndStdDev` -- `AveDev` -- `Skewness` -- `TotalVariance` -- `Product` -- `PopnStdDev` -- `kurtosis2` -- `Median` -- `skewness2` -- `Kurtosis` -- `Mode` -- `RandG` -- `Geomean` -- `PopnVariance` -- `MomentSkewKurtosis` -- `DevSq` -- `randomfrom` - -### 次序统计量 - -- `Large` -- `Small` -- `Percentile` -- `Percentrank` -- `Quartile` -- `Rank` -- `Trimmean` -- `Frequency` - -### 统计函数 - -- `Cov` -- `Correl` -- `Slope` -- `Intercept` -- `Rsq` -- `Steyx` -- `Slopeandintercept` -- `VariationCoefficient` -- `Skew` -- `SelfStddev` -- `RegressionChannel` -- `Kurt` -- `MeanAndPopnStdDevWithRate` -- `BetaAndAlpha` -- `correlpaired` -- `correlpaired_side` - -### 统计函数 / 扩充统计 - -- `Expanding_Unit` - -### 统计函数 / 含NAN统计 - -- `NanMean` -- `NanSum` -- `NanStd` -- `NanVariance` -- `NanPopnStd` -- `NanPopnVariance` -- `NanRankArr` -- `NanPercentRankArr` - -### 统计分布 - -- `Gammaln` -- `Hist` -- `sf_Error` -- `erfc` -- `sf_Gamma` -- `erf` -- `erfcinv` -- `sf_Beta` -- `sf_IntegerBessel_1` -- `sf_IncompleteGamma` -- `Gamma` -- `erfinv` -- `Randnorm` -- `sf_F` -- `sf_geopdf` -- `sf_RealBessel_1` -- `sf_unidcdf` -- `sf_normpdf` -- `sf_geoinv` -- `sf_unidpdf` -- `sf_IncompleteBeta` -- `sf_normalinv2` -- `sf_norminv` -- `Randunid` -- `sf_Normal` -- `sf_unidinv` -- `sf_X2` -- `sf_IntegerBessel_2` -- `sf_normcdf` -- `sf_t` -- `sf_geocdf` -- `Randgeo` -- `sf_normalinv` -- `Normfit` -- `sf_RealBessel_2` -- `sf_hygeinv` -- `poissfit` -- `sf_binocdf` -- `Randhyge` -- `sf_poissinv` -- `sf_poisscdf` -- `sf_nbininv` -- `binofit` -- `sf_hygepdf` -- `sf_unifcdf` -- `sf_exppdf` -- `sf_binoinv` -- `uniffit` -- `sf_nbinpdf` -- `Randnbin` -- `Randpoiss` -- `sf_hygecdf` -- `sf_poisspdf` -- `Randbino` -- `Randunif` -- `sf_unifinv` -- `sf_binopdf` -- `sf_nbincdf` -- `sf_unifpdf` -- `sf_tcdf` -- `sf_fpdf` -- `sf_tinv` -- `expfit` -- `Randgam` -- `sf_ch2inv` -- `sf_ch2cdf` -- `sf_finv1` -- `Randt` -- `sf_expcdf` -- `sf_finv` -- `sf_gamcdf` -- `sf_tpdf` -- `sf_x2inv` -- `sf_gampdf` -- `sf_gammainv` -- `sf_fcdf` -- `sf_ch2pdf` -- `Randf` -- `Randexp` -- `Randch2` -- `sf_gaminv` -- `sf_expinv` -- `sf_betapdf` -- `sf_tinv1` -- `RandCauchy` -- `sf_Laplacecdf` -- `Randbeta` -- `sf_Cauchypdf` -- `sf_logninv` -- `sf_Laplaceinv` -- `sf_betacdf` -- `sf_raylinv` -- `sf_wblcdf` -- `sf_lognpdf` -- `sf_Cauchycdf` -- `Randlogn` -- `Randrayl` -- `sf_Laplacepdf` -- `sf_raylpdf` -- `sf_wblinv` -- `sf_logncdf` -- `sf_Cauchyinv` -- `sf_raylcdf` -- `Randwbl` -- `sf_betainv` -- `RandLaplace` -- `sf_wblpdf` -- `sf_betainv1` -- `sf_mvtcdf` -- `Mvtcdfqmc` -- `sf_mvncdf` -- `sf_copulacdf` -- `sf_copulafit` -- `RandCopula` -- `sf_exp` -- `Norminv` - -### 统计推断 - -- `Estimate_SNU` -- `Estimate_TNU` -- `Estimate_TND` -- `Estimate_SP` -- `Estimate_TP` -- `Hypoth_TailRes` -- `NormPlot` -- `Hypoth_Kstest` -- `Hypoth_lillietest` -- `Hypoth_IndepTest` -- `Hypoth_KruskalWallis` -- `Hypoth_SNUTest` -- `Hypoth_TNUTest` -- `Hypoth_SNDTest` -- `Hypoth_TNDTest` -- `Hypoth_LSUTest` -- `Anova_Single` -- `Anova_Twice` -- `Anova_Bartlett` -- `Anova_Levene` - -### 统计推断 / 假设检验 - -- `Hypoth_SignTest` -- `Hypoth_WilcoxonTest` -- `Hypoth_McNemarTest` - -### 统计推断 / 配对检验 - -- `Hypoth_PNUTest` - -### 多元统计分析 - -- `Corr` -- `CorrelationMatrix` -- `Covariance` -- `Corrcoef` -- `Corr_partial` -- `Distance` -- `Cluster_Kmeans` -- `Cluster_System` -- `Cluster_ward` -- `Discrim` -- `princomp` -- `Factor` -- `corr_canonical` -- `corr_Spearman` -- `Cov2CorrMatrix` -- `CorrMatrixAdjust` -- `corr_Kendall` -- `HISTC` - -### 多元统计分析 / 相对重要性 - -- `Regress_domin_formula` -- `Regress_domin_marginal` - -### 回归 / 回归检验 - -- `Regress_Ridge` -- `Regress_AdjustedR2` -- `Regress_Logistic` -- `Regression` -- `Regress_DWTest` -- `Regress_Stepwise` -- `Regress_Constraint` -- `Regress_White` -- `Regress_MLS` -- `Regress_CMLS` -- `Regress_JBTest` -- `Regress_pri` -- `Regress_FTest` -- `Regression_WLS` -- `Regress_Binary` -- `Regress_TTest` -- `Regress_NLM` -- `Regress_WLS` -- `Regress_AicAndSbic` -- `Regress_RSquare` -- `Regress_QRlsq` -- `boxcox` -- `Regress_HettestSpearman` -- `Regress_VIF` -- `Regress_TTest_RWLS` -- `Regress_TTest_White` -- `Regress_TTest_NW` -- `Regression_OLS_White` -- `Regression_OLS_NW` -- `NW_Adjustment_Simplification` -- `Robustfit_M` -- `Regress_GRStest` - -### 回归 / 回归公用函数 - -- `LeastSquares_CurveFitting` - -### 灰色系统 - -- `GM_Initial` -- `GM_Corr` -- `GM_AGO` -- `GM_Icorr` -- `GM_Scorr` - -### 主成分分析 - -- `PrincaipalComponentAnalysis` - -### 主成分分析 / 中间函数 - -- `Mbbub` -- `ComponentScoreMatrix` -- `FactorScoreMatrix` -- `ComponentMatrix` -- `RotatedComponentMatrix` -- `Eigen_Jacobi` -- `GetEigenValue` -- `FScoreResult` - -### 时间序列分析 - -- `Time_Diff` -- `Time_AutoCov` -- `Time_ACF` -- `Time_PACF` -- `Time_RandomTest` -- `Time_DanielTest` -- `AR` -- `ARMA` -- `Time_ARCH` -- `Time_GARCH` -- `Times_ADFTest` -- `Times_Cointergration_test` -- `Times_ECM` -- `Times_Granger` -- `Time_ARp` -- `Time_MAq` -- `Time_ARMA` -- `Time_GreenFun` -- `Time_InvFun` -- `Time_Analyse` -- `Time_ChoseP` -- `Times_Cointergration` -- `GM_Estimate` -- `Time_ARCHTest` -- `GarchFit` -- `Times_johansen` -- `Times_GrangerCausality` - -### 时间序列分析 / 因果推断 - -- `Time_VolatilitySpillover` - -### 优化 - -- `NonLP_Hooke_Jeeves` -- `Prog_L` -- `NonLP_minPS` -- `NonLP_Fibonacci` -- `NonLP_Range` -- `Fmin` -- `NonLP_BSearch` -- `Prog_M` -- `NonLP_minFactor` -- `NonLP_GP` -- `NonLP_Fminsearch` -- `NonLP_Fmincon` -- `NonLP_minSUMT` -- `Prog_Q` -- `Prog_N` -- `NonLP_Nelder` -- `NonLP_Fminbnd` -- `NonLP_Golden` -- `TSOptimizer` -- `Quadprog` -- `LinearProgramming` -- `NonLP_Rosenbrock` -- `QuadLagR` -- `OZProg` -- `QuadTrackRoute` -- `IntLinProg` - -### 优化 / 有约束优化算法 - -- `SUMT_Method` - -### 优化 / 无约束优化算法 - -- `Hooke_Jeeves_Method` - -### 优化 / 测试 - -- `H_J_Method_Pgm` -- `Sumt_Method_CallBack` - -### 小波分析 - -- `Wavedec` -- `wrcoef` -- `wavelet` - -### 财务函数 - -- `DoubleDecliningBalance` -- `FutureValue` -- `InterestPayment` -- `InterestRate` -- `InternalRateOfReturn` -- `NumberOfPeriods` -- `NetPresentValue` -- `Payment` -- `PeriodPayment` -- `PresentValue` -- `SLNDepreciation` -- `SYDDepreciation` - -### 增长率与比率 - -- `AccumulativeYTMtoYTM` -- `YTMToAccumulativeYTM` -- `RatioValue` -- `OutPutValueByUnit` -- `OutPutLnGrowRatio` -- `OutPutGrowValue` -- `OutPutGrowValue2` -- `OutPutGrowRatio` -- `OutPutGrowRatio2` -- `MultyValue` -- `OutPutGrowValue3` -- `OutPutGrowRatio3` -- `RatioValue_Math` - -### 概率分布 / 线性变换 - -- `Norm_LinearTransform` - -### 信号处理 - -- `filter_hp` +- 函数事实数：472 + +## 智能体检索规则 + +1. 用户只描述能力时，先按“分类目录”选择候选详情页。 +2. 用户给出函数名时，优先在 `math/` 子目录中搜索三级函数标题。 +3. 只读取命中的函数条目、相邻分类标题和必要参数表；不要把同页其它函数混进当前调用。 +4. 没有命中函数事实条目时，不要发明函数名；回到 [../index.md](../index.md) 或项目实际代码确认。 + +## 分类目录 + +| 分类 | 详情页 | 函数事实数 | +| ------------------ | ------------------------------------------------------------------ | ---------: | +| 矩阵与数组 | [math/matrix_and_arrays.md](math/matrix_and_arrays.md) | 14 | +| 数值方法 | [math/numerical_methods.md](math/numerical_methods.md) | 39 | +| 初等数学与判断 | [math/elementary_math.md](math/elementary_math.md) | 55 | +| 三角、角度与双曲线 | [math/trig_angle_hyperbolic.md](math/trig_angle_hyperbolic.md) | 42 | +| 描述统计 | [math/statistics_descriptive.md](math/statistics_descriptive.md) | 67 | +| 统计分布 | [math/distribution.md](math/distribution.md) | 116 | +| 财务数学 | [math/financial_math.md](math/financial_math.md) | 12 | +| 统计推断 | [math/statistical_inference.md](math/statistical_inference.md) | 25 | +| 多元统计分析 | [math/multivariate_statistics.md](math/multivariate_statistics.md) | 26 | +| 回归分析 | [math/regression.md](math/regression.md) | 34 | +| 灰色系统与小波分析 | [math/gray_and_wavelet.md](math/gray_and_wavelet.md) | 9 | +| 时间序列分析 | [math/time_series.md](math/time_series.md) | 25 | +| 优化与规划 | [math/optimization.md](math/optimization.md) | 8 | diff --git a/docs/tsl/reference/catalog/math/distribution.md b/docs/tsl/reference/catalog/math/distribution.md new file mode 100644 index 00000000..acb79d2f --- /dev/null +++ b/docs/tsl/reference/catalog/math/distribution.md @@ -0,0 +1,1509 @@ +# 数学函数 - 统计分布 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录统计分布函数。 + +## 统计分布 + +### `gammaln(arg1)` + +用途：统计分布相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 数组 | 按源文档示例顺序传入 | + +### `sf_Error(arg1, v)` + +用途：统计分布相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `erfc(arg1)` + +用途：统计分布相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `sf_Gamma(arg1, v)` + +用途：统计分布相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `erf(arg1)` + +用途：统计分布相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `erfcinv(arg1)` + +用途：统计分布相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `sf_Beta(arg1, arg2, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_IntegerBessel_1(n, x, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `n` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `x` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_IncompleteGamma(a, x, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `x` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `gamma(arg1)` + +用途：统计分布相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 数组 | 按源文档示例顺序传入 | + +### `erfinv(arg1)` + +用途：统计分布相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `sf_F(f, n1, n2, v)` + +用途：统计分布相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `f` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `n1` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `n2` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_RealBessel_1(n, x, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `n` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `x` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_IncompleteBeta(a, b, x, v)` + +用途：统计分布相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `x` | 是 | 实数 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_normalinv2(arg1, v)` + +用途：统计分布相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_Normal(x, a, d, v)` + +用途：统计分布相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `x` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `d` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_X2(x, n, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `x` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `n` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_IntegerBessel_2(n, x, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `n` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `x` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_t(t, n, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `t` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `n` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_normalinv(arg1, arg2, arg3, v)` + +用途：统计分布相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_RealBessel_2(n, x, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `n` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `x` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_tinv(arg1, arg2, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_finv(arg1, arg2, arg3, v)` + +用途：统计分布相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_x2inv(arg1, arg2, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_gammainv(arg1, arg2, v)` + +用途：统计分布相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_betainv(y, arg2, arg3, x)` + +用途：统计分布相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `x` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `x` | + +## 服务器统计分布函数 + +### `hist(values, bin_count, center)` + +用途：按指定组数统计数值序列的直方图频数。 + +参数个数：3 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------------------ | +| 1 | `values` | 是 | 数值数组 | 待统计的数值序列 | +| 2 | `bin_count` | 是 | 整数 | 分组数量 | +| 3 | `center` | 是 | 变量引用 | 接收或参与分组中心值计算 | + +### `randnorm(mean, std_dev, row_count, columns)` + +用途：生成正态分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `mean` | 是 | 数值 | 均值 | +| 2 | `std_dev` | 是 | 数值 | 标准差 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_geopdf(x, probability)` + +用途：计算几何分布概率密度。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `probability` | 是 | 数值 | 成功概率 | + +### `sf_geocdf(x, probability)` + +用途：计算几何分布累计分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `probability` | 是 | 数值 | 成功概率 | + +### `sf_geoinv(probability_value, probability)` + +用途：计算几何分布逆分布值。 + +参数个数：2 +返回值：整数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `probability` | 是 | 数值 | 成功概率 | + +### `randgeo(probability[, row_count][, columns])` + +用途：生成几何分布随机数。 + +参数个数：1 到 3 +返回值：实数/数组/数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------ | +| 1 | `probability` | 是 | 数值 | 成功概率 | +| 2 | `row_count` | 否 | 整数 | 生成行数 | +| 3 | `columns` | 否 | 数组 | 生成列名数组 | + +### `sf_unidpdf(x, max_value)` + +用途：计算离散均匀分布概率密度。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------- | ---------------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `max_value` | 是 | 整数 | 离散均匀分布上界 | + +### `sf_unidcdf(x, max_value)` + +用途：计算离散均匀分布累计分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------- | ---------------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `max_value` | 是 | 整数 | 离散均匀分布上界 | + +### `sf_unidinv(probability_value, max_value)` + +用途：计算离散均匀分布逆分布值。 + +参数个数：2 +返回值：整数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `max_value` | 是 | 整数 | 离散均匀分布上界 | + +### `randunid(max_value, row_count, columns)` + +用途：生成离散均匀分布随机数数组。 + +参数个数：3 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ---------------- | +| 1 | `max_value` | 是 | 整数 | 离散均匀分布上界 | +| 2 | `row_count` | 是 | 整数 | 生成行数 | +| 3 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_normpdf(x, mean, std_dev)` + +用途：计算正态分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `mean` | 是 | 数值 | 均值 | +| 3 | `std_dev` | 是 | 数值 | 标准差 | + +### `sf_normcdf(x, mean, std_dev)` + +用途：计算正态分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `mean` | 是 | 数值 | 均值 | +| 3 | `std_dev` | 是 | 数值 | 标准差 | + +### `sf_norminv(probability_value, mean, std_dev)` + +用途：计算正态分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `mean` | 是 | 数值 | 均值 | +| 3 | `std_dev` | 是 | 数值 | 标准差 | + +### `normfit(values, alpha)` + +用途：估计正态分布参数及置信区间。 + +参数个数：2 +返回值：数组表；包含 `muhat`、`sigmahat`、`muci`、`sigmaci` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | ----------------- | ---------- | +| 1 | `values` | 是 | 数值数组/数值矩阵 | 样本数据 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `sf_hygeinv(probability_value, population_size, success_count, draw_count)` + +用途：计算超几何分布逆分布值。 + +参数个数：4 +返回值：整数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `population_size` | 是 | 整数 | 总体数量 | +| 3 | `success_count` | 是 | 整数 | 总体中的成功数量 | +| 4 | `draw_count` | 是 | 整数 | 抽取数量 | + +### `poissfit(values, alpha)` + +用途：估计泊松分布 lambda 参数及置信区间。 + +参数个数：2 +返回值：数组表；包含 `lambdahat`、`lambdaci` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `sf_binocdf(x, trial_count, probability)` + +用途：计算二项分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `trial_count` | 是 | 整数 | 试验次数 | +| 3 | `probability` | 是 | 数值 | 成功概率 | + +### `randhyge(population_size, success_count, draw_count, row_count, columns)` + +用途：生成超几何分布随机数数组。 + +参数个数：5 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | ---------------- | +| 1 | `population_size` | 是 | 整数 | 总体数量 | +| 2 | `success_count` | 是 | 整数 | 总体中的成功数量 | +| 3 | `draw_count` | 是 | 整数 | 抽取数量 | +| 4 | `row_count` | 是 | 整数 | 生成行数 | +| 5 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_hygepdf(x, population_size, success_count, draw_count)` + +用途：计算超几何分布概率密度。 + +参数个数：4 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ------------- | ---------------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `population_size` | 是 | 整数 | 总体数量 | +| 3 | `success_count` | 是 | 整数 | 总体中的成功数量 | +| 4 | `draw_count` | 是 | 整数 | 抽取数量 | + +### `sf_hygecdf(x, population_size, success_count, draw_count)` + +用途：计算超几何分布累计分布值。 + +参数个数：4 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ------------- | ---------------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `population_size` | 是 | 整数 | 总体数量 | +| 3 | `success_count` | 是 | 整数 | 总体中的成功数量 | +| 4 | `draw_count` | 是 | 整数 | 抽取数量 | + +### `sf_poisspdf(x, lambda_value)` + +用途：计算泊松分布概率密度。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------- | ----------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `lambda_value` | 是 | 数值 | lambda 参数 | + +### `sf_poisscdf(x, lambda_value)` + +用途：计算泊松分布累计分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ------------- | ----------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `lambda_value` | 是 | 数值 | lambda 参数 | + +### `sf_poissinv(probability_value, lambda_value)` + +用途：计算泊松分布逆分布值。 + +参数个数：2 +返回值：整数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ----------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `lambda_value` | 是 | 数值 | lambda 参数 | + +### `randpoiss(lambda_value, row_count, columns)` + +用途：生成泊松分布随机数数组。 + +参数个数：3 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------ | +| 1 | `lambda_value` | 是 | 数值 | lambda 参数 | +| 2 | `row_count` | 是 | 整数 | 生成行数 | +| 3 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_nbinpdf(x, success_count, probability)` + +用途：计算负二项分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | ------------- | ------------ | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `success_count` | 是 | 整数 | 成功次数参数 | +| 3 | `probability` | 是 | 数值 | 成功概率 | + +### `sf_nbincdf(x, success_count, probability)` + +用途：计算负二项分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | ------------- | ------------ | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `success_count` | 是 | 整数 | 成功次数参数 | +| 3 | `probability` | 是 | 数值 | 成功概率 | + +### `sf_nbininv(probability_value, success_count, probability)` + +用途：计算负二项分布逆分布值。 + +参数个数：3 +返回值：整数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ------------ | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `success_count` | 是 | 整数 | 成功次数参数 | +| 3 | `probability` | 是 | 数值 | 成功概率 | + +### `randnbin(success_count, probability, row_count, columns)` + +用途：生成负二项分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | ------------ | +| 1 | `success_count` | 是 | 整数 | 成功次数参数 | +| 2 | `probability` | 是 | 数值 | 成功概率 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_binopdf(x, trial_count, probability)` + +用途：计算二项分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `trial_count` | 是 | 整数 | 试验次数 | +| 3 | `probability` | 是 | 数值 | 成功概率 | + +### `sf_binoinv(probability_value, trial_count, probability)` + +用途：计算二项分布逆分布值。 + +参数个数：3 +返回值：整数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `trial_count` | 是 | 整数 | 试验次数 | +| 3 | `probability` | 是 | 数值 | 成功概率 | + +### `randbino(trial_count, probability, row_count, columns)` + +用途：生成二项分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------ | +| 1 | `trial_count` | 是 | 整数 | 试验次数 | +| 2 | `probability` | 是 | 数值 | 成功概率 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `binofit(values, trial_count, alpha)` + +用途：估计二项分布成功概率及置信区间。 + +参数个数：3 +返回值：数组表；包含 `phat`、`pci` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------ | +| 1 | `values` | 是 | 数值数组 | 样本成功次数序列 | +| 2 | `trial_count` | 是 | 整数 | 每个样本的试验次数 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | + +### `sf_unifcdf(x, min_value, max_value)` + +用途：计算连续均匀分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `min_value` | 是 | 数值 | 分布下界 | +| 3 | `max_value` | 是 | 数值 | 分布上界 | + +### `sf_unifinv(probability_value, min_value, max_value)` + +用途：计算连续均匀分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `min_value` | 是 | 数值 | 分布下界 | +| 3 | `max_value` | 是 | 数值 | 分布上界 | + +### `randunif(min_value, max_value, row_count, columns)` + +用途：生成连续均匀分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `min_value` | 是 | 数值 | 分布下界 | +| 2 | `max_value` | 是 | 数值 | 分布上界 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `uniffit(values, alpha)` + +用途：估计连续均匀分布上下界及置信区间。 + +参数个数：2 +返回值：数组表；包含 `ahat`、`bhat`、`aci`、`bci` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `sf_exppdf(values, lambda_value)` + +用途：计算指数分布概率密度。 + +参数个数：2 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ---------------------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 随机变量序列；标量输入会返回 `nil`，生成代码时使用数组输入 | +| 2 | `lambda_value` | 是 | 数值 | lambda 参数 | + +### `sf_unifpdf(x, min_value, max_value)` + +用途：计算连续均匀分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `min_value` | 是 | 数值 | 分布下界 | +| 3 | `max_value` | 是 | 数值 | 分布上界 | + +### `sf_tcdf(x, degrees_freedom)` + +用途：计算 t 分布累计分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `degrees_freedom` | 是 | 数值 | 自由度 | + +### `sf_fpdf(x, numerator_degrees_freedom, denominator_degrees_freedom)` + +用途：计算 F 分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `numerator_degrees_freedom` | 是 | 数值 | 分子自由度 | +| 3 | `denominator_degrees_freedom` | 是 | 数值 | 分母自由度 | + +### `expfit(values, alpha)` + +用途：估计指数分布参数及置信区间。 + +参数个数：2 +返回值：数组表；包含 `parmhat`、`parmci` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据；生成代码时直接传数值数组 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `randgam(shape, scale, row_count, columns)` + +用途：生成 Gamma 分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `shape` | 是 | 数值 | 形状参数 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_ch2inv(probability_value, degrees_freedom)` + +用途：计算卡方分布逆分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `degrees_freedom` | 是 | 数值 | 自由度 | + +### `sf_ch2cdf(x, degrees_freedom)` + +用途：计算卡方分布累计分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `degrees_freedom` | 是 | 数值 | 自由度 | + +### `sf_finv1(probability_value, numerator_degrees_freedom, denominator_degrees_freedom)` + +用途：计算 F 分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `numerator_degrees_freedom` | 是 | 数值 | 分子自由度 | +| 3 | `denominator_degrees_freedom` | 是 | 数值 | 分母自由度 | + +### `randt(degrees_freedom, row_count, columns)` + +用途：生成 t 分布随机数数组。 + +参数个数：3 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | ------------ | +| 1 | `degrees_freedom` | 是 | 数值 | 自由度 | +| 2 | `row_count` | 是 | 整数 | 生成行数 | +| 3 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_expcdf(values, lambda_value)` + +用途：计算指数分布累计分布值。 + +参数个数：2 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ---------------------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 随机变量序列；标量输入会返回 `nil`，生成代码时使用数组输入 | +| 2 | `lambda_value` | 是 | 数值 | lambda 参数 | + +### `sf_gamcdf(x, shape, scale)` + +用途：计算 Gamma 分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `shape` | 是 | 数值 | 形状参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_tpdf(x, degrees_freedom)` + +用途：计算 t 分布概率密度。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `degrees_freedom` | 是 | 数值 | 自由度 | + +### `sf_gampdf(x, shape, scale)` + +用途：计算 Gamma 分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `shape` | 是 | 数值 | 形状参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_fcdf(x, numerator_degrees_freedom, denominator_degrees_freedom)` + +用途：计算 F 分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `numerator_degrees_freedom` | 是 | 数值 | 分子自由度 | +| 3 | `denominator_degrees_freedom` | 是 | 数值 | 分母自由度 | + +### `sf_ch2pdf(x, degrees_freedom)` + +用途：计算卡方分布概率密度。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `degrees_freedom` | 是 | 数值 | 自由度 | + +### `randf(numerator_degrees_freedom, denominator_degrees_freedom, row_count, columns)` + +用途：生成 F 分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------------------- | ---- | -------- | ------------ | +| 1 | `numerator_degrees_freedom` | 是 | 数值 | 分子自由度 | +| 2 | `denominator_degrees_freedom` | 是 | 数值 | 分母自由度 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `randexp(lambda_value, row_count, columns)` + +用途：生成指数分布随机数数组。 + +参数个数：3 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------ | +| 1 | `lambda_value` | 是 | 数值 | lambda 参数 | +| 2 | `row_count` | 是 | 整数 | 生成行数 | +| 3 | `columns` | 是 | 数组 | 生成列名数组 | + +### `randch2(degrees_freedom, row_count, columns)` + +用途：生成卡方分布随机数数组。 + +参数个数：3 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | ------------ | +| 1 | `degrees_freedom` | 是 | 数值 | 自由度 | +| 2 | `row_count` | 是 | 整数 | 生成行数 | +| 3 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_gaminv(probability_value, shape, scale)` + +用途：计算 Gamma 分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `shape` | 是 | 数值 | 形状参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_expinv(probability_value, lambda_value)` + +用途：计算指数分布逆分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ----------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `lambda_value` | 是 | 数值 | lambda 参数 | + +### `sf_betapdf(x, shape_alpha, shape_beta)` + +用途：计算 Beta 分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------- | -------------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `shape_alpha` | 是 | 数值 | alpha 形状参数 | +| 3 | `shape_beta` | 是 | 数值 | beta 形状参数 | + +### `sf_tinv1(probability_value, degrees_freedom)` + +用途：计算 t 分布逆分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `degrees_freedom` | 是 | 数值 | 自由度 | + +### `randCauchy(location, scale, row_count, columns)` + +用途：生成 Cauchy 分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `location` | 是 | 数值 | 位置参数 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_laplacecdf(x, location, scale)` + +用途：计算 Laplace 分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `location` | 是 | 数值 | 位置参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `randbeta(shape_alpha, shape_beta, row_count, columns)` + +用途：生成 Beta 分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------- | +| 1 | `shape_alpha` | 是 | 数值 | alpha 形状参数 | +| 2 | `shape_beta` | 是 | 数值 | beta 形状参数 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_cauchypdf(x, location, scale)` + +用途：计算 Cauchy 分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `location` | 是 | 数值 | 位置参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_logninv(probability_value, mean, std_dev)` + +用途：计算对数正态分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ------------------ | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `mean` | 是 | 数值 | 底层正态分布均值 | +| 3 | `std_dev` | 是 | 数值 | 底层正态分布标准差 | + +### `sf_laplaceinv(probability_value, location, scale)` + +用途：计算 Laplace 分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `location` | 是 | 数值 | 位置参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_betacdf(x, shape_alpha, shape_beta)` + +用途：计算 Beta 分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------- | -------------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `shape_alpha` | 是 | 数值 | alpha 形状参数 | +| 3 | `shape_beta` | 是 | 数值 | beta 形状参数 | + +### `sf_raylinv(probability_value, scale)` + +用途：计算 Rayleigh 分布逆分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_wblcdf(x, scale, shape)` + +用途：计算 Weibull 分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | +| 3 | `shape` | 是 | 数值 | 形状参数 | + +### `sf_lognpdf(x, mean, std_dev)` + +用途：计算对数正态分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------- | ------------------ | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `mean` | 是 | 数值 | 底层正态分布均值 | +| 3 | `std_dev` | 是 | 数值 | 底层正态分布标准差 | + +### `sf_cauchycdf(x, location, scale)` + +用途：计算 Cauchy 分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `location` | 是 | 数值 | 位置参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `randlogn(mean, std_dev, row_count, columns)` + +用途：生成对数正态分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------------ | +| 1 | `mean` | 是 | 数值 | 底层正态分布均值 | +| 2 | `std_dev` | 是 | 数值 | 底层正态分布标准差 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `randrayl(scale, row_count, columns)` + +用途：生成 Rayleigh 分布随机数数组。 + +参数个数：3 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `scale` | 是 | 数值 | 尺度参数 | +| 2 | `row_count` | 是 | 整数 | 生成行数 | +| 3 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_laplacepdf(x, location, scale)` + +用途：计算 Laplace 分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `location` | 是 | 数值 | 位置参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_raylpdf(x, scale)` + +用途：计算 Rayleigh 分布概率密度。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_wblinv(probability_value, scale, shape)` + +用途：计算 Weibull 分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | +| 3 | `shape` | 是 | 数值 | 形状参数 | + +### `sf_logncdf(x, mean, std_dev)` + +用途：计算对数正态分布累计分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------- | ------------------ | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `mean` | 是 | 数值 | 底层正态分布均值 | +| 3 | `std_dev` | 是 | 数值 | 底层正态分布标准差 | + +### `sf_cauchyinv(probability_value, location, scale)` + +用途：计算 Cauchy 分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `location` | 是 | 数值 | 位置参数 | +| 3 | `scale` | 是 | 数值 | 尺度参数 | + +### `sf_raylcdf(x, scale)` + +用途：计算 Rayleigh 分布累计分布值。 + +参数个数：2 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | + +### `randwbl(scale, shape, row_count, columns)` + +用途：生成 Weibull 分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `scale` | 是 | 数值 | 尺度参数 | +| 2 | `shape` | 是 | 数值 | 形状参数 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `randLaplace(location, scale, row_count, columns)` + +用途：生成 Laplace 分布随机数数组。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `location` | 是 | 数值 | 位置参数 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | +| 3 | `row_count` | 是 | 整数 | 生成行数 | +| 4 | `columns` | 是 | 数组 | 生成列名数组 | + +### `sf_wblpdf(x, scale, shape)` + +用途：计算 Weibull 分布概率密度。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ------------- | ---------- | +| 1 | `x` | 是 | 数值/数值数组 | 随机变量值 | +| 2 | `scale` | 是 | 数值 | 尺度参数 | +| 3 | `shape` | 是 | 数值 | 形状参数 | + +### `sf_betainv1(probability_value, shape_alpha, shape_beta)` + +用途：计算 Beta 分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | -------------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `shape_alpha` | 是 | 数值 | alpha 形状参数 | +| 3 | `shape_beta` | 是 | 数值 | beta 形状参数 | + +### `sf_mvtcdf(lower_bounds, upper_bounds, correlation_matrix, degrees_freedom)` + +用途：计算多变量 t 分布累计分布值。 + +参数个数：4 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------------- | ---- | -------------- | ------------------------------- | +| 1 | `lower_bounds` | 是 | `nil`/数值矩阵 | 下界；传 `nil` 表示使用默认下界 | +| 2 | `upper_bounds` | 是 | 数值矩阵 | 上界矩阵 | +| 3 | `correlation_matrix` | 是 | 数值矩阵 | 相关系数矩阵 | +| 4 | `degrees_freedom` | 是 | 数值 | 自由度 | + +### `mvtcdfqmc(lower_bounds, upper_bounds, correlation_matrix, degrees_freedom, options)` + +用途：用 QMC 方式计算多变量 t 分布累计分布值。 + +参数个数：5 +返回值：数组；通常包含计算值和误差估计 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------------- | ---- | ----------------- | ------------------------------ | +| 1 | `lower_bounds` | 是 | 数值数组/数值矩阵 | 下界 | +| 2 | `upper_bounds` | 是 | 数值数组/数值矩阵 | 上界 | +| 3 | `correlation_matrix` | 是 | 数值矩阵 | 相关系数矩阵 | +| 4 | `degrees_freedom` | 是 | 数值 | 自由度 | +| 5 | `options` | 是 | 数组 | QMC 选项；无选项时传 `array()` | + +### `sf_mvncdf(lower_bounds, upper_bounds, mean_values, correlation_matrix)` + +用途：计算多变量正态分布累计分布值。 + +参数个数：4 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------------- | ---- | ----------------------- | ------------------------------- | +| 1 | `lower_bounds` | 是 | `nil`/数值矩阵 | 下界；传 `nil` 表示使用默认下界 | +| 2 | `upper_bounds` | 是 | 数值矩阵 | 上界矩阵 | +| 3 | `mean_values` | 是 | `nil`/数值数组/数值矩阵 | 均值；传 `nil` 表示使用默认均值 | +| 4 | `correlation_matrix` | 是 | 数值矩阵 | 相关系数矩阵 | + +### `sf_copulacdf(values, family, dependency[, parameter])` + +用途：计算 copula 分布累计分布值。 + +参数个数：3 到 4 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------------- | -------------------------------------------------------------------- | +| 1 | `values` | 是 | 数值矩阵 | 每行一组 copula 输入值 | +| 2 | `family` | 是 | 字符串 | 分布族；支持 `"gaussian"`、`"t"`、`"clayton"`、`"frank"`、`"gumbel"` | +| 3 | `dependency` | 是 | `nil`/数值矩阵 | 相关矩阵或依赖参数容器；阿基米德族可传 `nil` | +| 4 | `parameter` | 否 | 数值 | t 分布自由度或阿基米德族参数 | + +### `sf_copulafit(values, family[, method])` + +用途：估计 copula 分布参数。 + +参数个数：2 到 3 +返回值：矩阵/实数/数组；随 `family` 改变 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------------------------------------------------------------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | +| 2 | `family` | 是 | 字符串 | 分布族；支持 `"gaussian"`、`"t"`、`"clayton"`、`"frank"`、`"gumbel"` | +| 3 | `method` | 否 | 字符串 | 估计方法；gaussian/t 常用 `"AML"` | + +### `randCopula(family, dependency, parameter, row_count)` + +用途：生成 copula 分布随机数矩阵。 + +参数个数：4 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------------- | -------------------------------------------------------------------- | +| 1 | `family` | 是 | 字符串 | 分布族；支持 `"gaussian"`、`"t"`、`"clayton"`、`"frank"`、`"gumbel"` | +| 2 | `dependency` | 是 | `nil`/数值矩阵 | 相关矩阵或依赖参数容器；阿基米德族可传 `nil` | +| 3 | `parameter` | 是 | 数值/数值矩阵 | t 分布自由度、阿基米德族参数，或 gaussian 族所需参数矩阵 | +| 4 | `row_count` | 是 | 整数 | 生成行数 | + +### `sf_exp(probability_value, lambda_value, out_value)` + +用途：计算指数分布逆分布值，并把结果写入输出变量。 + +参数个数：3 +返回值：实数/数组；同时写入 `out_value` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ------------ | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `lambda_value` | 是 | 数值 | lambda 参数 | +| 3 | `out_value` | 是 | 变量引用 | 接收计算结果 | + +### `norminv(probability_value, mean, std_dev)` + +用途：计算正态分布逆分布值。 + +参数个数：3 +返回值：实数/数组 + +使用选择：生成新代码默认使用 `sf_norminv`；只有用户或项目代码明确使用 `norminv` 命名时，才使用本函数。 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | ------------- | ---------- | +| 1 | `probability_value` | 是 | 数值/数值数组 | 分布概率值 | +| 2 | `mean` | 是 | 数值 | 均值 | +| 3 | `std_dev` | 是 | 数值 | 标准差 | diff --git a/docs/tsl/reference/catalog/math/elementary_math.md b/docs/tsl/reference/catalog/math/elementary_math.md new file mode 100644 index 00000000..8236c5ef --- /dev/null +++ b/docs/tsl/reference/catalog/math/elementary_math.md @@ -0,0 +1,652 @@ +# 数学函数 - 初等数学与判断 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录常用数学、指数对数、精度取整、比较判断和位运算函数。 + +## 常用数学函数 + +### `pi()` + +用途：常用数学函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `odd(arg1)` + +用途：常用数学函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `abs(arg1)` + +用途：常用数学函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sqr(x)` + +用途：常用数学函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `x` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sqrt(x)` + +用途：常用数学函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | + +### `divMod(arg1, arg2, a, b)` + +用途：常用数学函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `a` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `a` | +| 4 | `b` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `b` | + +### `frexp(x, base, exponent)` + +用途：常用数学函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | --------------------------------------------------- | +| 1 | `x` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `base` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Base` | +| 3 | `exponent` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Exponent` | + +### `ldexp(arg1, arg2)` + +用途：常用数学函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `poly(x, a)` + +用途：常用数学函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `x` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `a` | 是 | 数组 | 按源文档示例顺序传入 | + +## 指数对数函数 + +### `ln(arg1)` + +用途：指数对数函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `lnXP1(arg1)` + +用途：指数对数函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `log10(arg1)` + +用途：指数对数函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `log2(arg1)` + +用途：指数对数函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `logN(arg1, arg2)` + +用途：指数对数函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `exp(arg1)` + +用途：指数对数函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `intPower(arg1, arg2)` + +用途：指数对数函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | + +### `power(arg1, arg2)` + +用途：指数对数函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | + +## 精度设置及取整运算 + +### `int(x)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `x` | 是 | 实数 | 按源文档示例顺序传入 | + +### `ceil(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `ceil32(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `ceil64(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `floor(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `floor32(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `floor64(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `trunc(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `trunc32(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `trunc64(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `frac(x)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `x` | 是 | 实数 | 按源文档示例顺序传入 | + +### `round(x)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `x` | 是 | 实数 | 按源文档示例顺序传入 | + +### `round32(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `round64(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `simpleRound(x)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `x` | 是 | 实数 | 按源文档示例顺序传入 | + +### `simpleRound32(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `simpleRound64(arg1)` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `roundTo(arg1, arg2)` + +用途：精度设置及取整运算相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `simpleRoundTo(arg1[, arg2])` + +用途：精度设置及取整运算相关函数。 + +参数个数：1 到 2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | + +## 比较判断函数 + +### `isNan(v)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `v` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `isInfinite(inf)` + +用途：判断条件是否成立。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `inf` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sign(arg1)` + +用途：比较判断函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `isZero(arg1, arg2)` + +用途：判断条件是否成立。 + +参数个数：2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | + +### `min(arg1, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | + +### `max(arg1, arg2)` + +用途：进行数值统计计算。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------- | -------------------- | +| 1 | `arg1` | 是 | 整数/数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数/数组 | 按源文档示例顺序传入 | + +### `compareValue(arg1, arg2, arg3)` + +用途：比较判断函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 实数 | 按源文档示例顺序传入 | + +### `sameValue(arg1, arg2, arg3)` + +用途：比较判断函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 实数 | 按源文档示例顺序传入 | + +### `randomRange(arg1, arg2)` + +用途：比较判断函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | + +### `inRange(arg1, arg2, arg3)` + +用途：比较判断函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `ensureRange(arg1, arg2, arg3)` + +用途：比较判断函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +## 位运算函数 + +### `_and(left, right)` + +用途：对两个整数做按位与运算。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `left` | 是 | 整数 | 左操作数 | +| 2 | `right` | 是 | 整数 | 右操作数 | + +### `_or(left, right)` + +用途：对两个整数做按位或运算。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `left` | 是 | 整数 | 左操作数 | +| 2 | `right` | 是 | 整数 | 右操作数 | + +### `_not(value)` + +用途：对整数做按位取反运算。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 整数 | 输入整数 | + +### `_xor(left, right)` + +用途：对两个整数做按位异或运算。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `left` | 是 | 整数 | 左操作数 | +| 2 | `right` | 是 | 整数 | 右操作数 | + +### `_shl(value, bits)` + +用途：将整数按位左移。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 整数 | 输入整数 | +| 2 | `bits` | 是 | 整数 | 左移位数 | + +### `_shr(value, bits)` + +用途：将整数按位右移。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 整数 | 输入整数 | +| 2 | `bits` | 是 | 整数 | 右移位数 | + +### `_rol(value, bits)` + +用途：将整数按位循环左移。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `value` | 是 | 整数 | 输入整数 | +| 2 | `bits` | 是 | 整数 | 循环左移位数 | + +### `_ror(value, bits)` + +用途：将整数按位循环右移。 + +参数个数：2 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `value` | 是 | 整数 | 输入整数 | +| 2 | `bits` | 是 | 整数 | 循环右移位数 | diff --git a/docs/tsl/reference/catalog/math/financial_math.md b/docs/tsl/reference/catalog/math/financial_math.md new file mode 100644 index 00000000..c6ab293a --- /dev/null +++ b/docs/tsl/reference/catalog/math/financial_math.md @@ -0,0 +1,182 @@ +# 数学函数 - 财务数学 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录财务数学函数。 + +## 财务函数 + +### `doubleDecliningBalance(cost, salvage, life, period)` + +用途：财务函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------- | +| 1 | `cost` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `salvage` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `life` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `period` | 是 | 整数 | 按源文档示例顺序传入 | + +### `futureValue(rate, nperiods, payment, present_value, payment_time)` + +用途：财务函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `rate` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `nperiods` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `payment` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `present_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `interestPayment(rate, period, nperiods, present_value, future_value, payment_time)` + +用途：财务函数相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `rate` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `period` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `nperiods` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `present_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `future_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `interestRate(nperiod, payment, present_value, future_value, payment_time)` + +用途：财务函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `nperiod` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `payment` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `present_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `future_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `internalRateOfReturn(guess, data)` + +用途：财务函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `guess` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `data` | 是 | 数组 | 按源文档示例顺序传入 | + +### `numberOfPeriods(rate, payment, present_value, future_value, payment_time)` + +用途：财务函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `rate` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `payment` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `present_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `future_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `netPresentValue(rate, cash_flows, payment_time)` + +用途：财务函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------------------- | +| 1 | `rate` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `cash_flows` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `payment(rate, nperiods, present_value, future_value, payment_time)` + +用途：财务函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `rate` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `nperiods` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `present_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `future_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `periodPayment(rate, period, nperiods, present_value, future_value, payment_time)` + +用途：财务函数相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `rate` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `period` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `nperiods` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `present_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `future_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `presentValue(rate, nperiods, payment, future_value, payment_time)` + +用途：财务函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------------------------------------------------- | +| 1 | `rate` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `nperiods` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `payment` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Payment` | +| 4 | `future_value` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `payment_time` | 是 | 整数 | 按源文档示例顺序传入 | + +### `slnDepreciation(arg1, arg2, arg3)` + +用途：财务函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sydDepreciation(arg1, arg2, arg3, arg4)` + +用途：财务函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/math/gray_and_wavelet.md b/docs/tsl/reference/catalog/math/gray_and_wavelet.md new file mode 100644 index 00000000..a0c18dcf --- /dev/null +++ b/docs/tsl/reference/catalog/math/gray_and_wavelet.md @@ -0,0 +1,127 @@ +# 数学函数 - 灰色系统与小波分析 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录灰色系统初始化、灰色关联分析、累加生成和灰色预测函数。 + +## 服务器灰色系统函数 + +### `gm_Initial(values, method, unit_values)` + +用途：对灰色系统输入矩阵做初始化转换。 + +参数个数：3 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ----------------------------------------------------------- | +| 1 | `values` | 是 | 数值矩阵 | 原始序列矩阵 | +| 2 | `method` | 是 | 字符串 | 初始化方式；可用 `"ini"`、`"mean"`、`"rrange"`、`"norm"` | +| 3 | `unit_values` | 是 | 数值数组 | `method` 为 `"norm"` 时传归一化基准；其它方式可传 `array()` | + +### `gm_Corr(values, target_index)` + +用途：计算灰色关联分析结果。 + +参数个数：2 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------------- | +| 1 | `values` | 是 | 数值矩阵 | 待分析序列矩阵 | +| 2 | `target_index` | 是 | 整数 | 参考序列下标 | + +### `gm_AGO(values, method, order)` + +用途：执行灰色系统累加生成或还原运算。 + +参数个数：3 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------------------------- | +| 1 | `values` | 是 | 数值数组 | 原始序列 | +| 2 | `method` | 是 | 字符串 | 运算方式；可用 `"add"`、`"sub"` | +| 3 | `order` | 是 | 整数 | 生成或还原阶数 | + +### `gm_Icorr(values, target_index)` + +用途：计算灰色关联分析结果。 + +参数个数：2 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------------- | +| 1 | `values` | 是 | 数值矩阵 | 待分析序列矩阵 | +| 2 | `target_index` | 是 | 整数 | 参考序列下标 | + +### `gm_Scorr(values, method)` + +用途：计算灰色绝对、相对或综合关联度矩阵。 + +参数个数：2 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------------------------------------ | +| 1 | `values` | 是 | 数值矩阵 | 待分析序列矩阵 | +| 2 | `method` | 是 | 字符串 | 关联度类型；可用 `"abs"`、`"ret"`、`"com"` | + +### `gm_Estimate(values, step_count)` + +用途：按灰色模型估计后续序列值。 + +参数个数：2 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ------------------ | +| 1 | `values` | 是 | 数值数组 | 原始序列 | +| 2 | `step_count` | 是 | 整数 | 需要估计的后续步数 | + +## 小波分析 + +### `wavedec(data, level, wname)` + +用途：对序列进行小波分解，返回系数向量与长度向量。 + +参数个数：3 +返回值：数组；`result[0]` 为分解向量 C，`result[1]` 为记录向量 L + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `data` | 是 | 数组 | 输入序列 | +| 2 | `level` | 是 | 整数 | 分解层数 | +| 3 | `wname` | 是 | 字符串 | 小波名称 | + +### `wrcoef(mode, c, l, wname, level)` + +用途：基于 `wavedec` 的结果重构近似或细节信号。 + +参数个数：5 +返回值：重构后的序列 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------- | +| 1 | `mode` | 是 | 字符串 | 指定近似或细节 | +| 2 | `c` | 是 | 数组 | 分解系数 | +| 3 | `l` | 是 | 数组 | 长度向量 | +| 4 | `wname` | 是 | 字符串 | 小波名称 | +| 5 | `level` | 是 | 整数 | 分解层数 | + +### `wavelet(data, wname, n, options)` + +用途：对序列进行小波变换或去噪，常与 `wavedec`、`wrcoef` 配合使用。 + +参数个数：4 +返回值：处理后的序列 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------- | +| 1 | `data` | 是 | 数组 | 输入序列 | +| 2 | `wname` | 是 | 字符串 | 小波名称 | +| 3 | `n` | 是 | 整数 | 层数 | +| 4 | `options` | 是 | 数组 | 去噪选项 | diff --git a/docs/tsl/reference/catalog/math/matrix_and_arrays.md b/docs/tsl/reference/catalog/math/matrix_and_arrays.md new file mode 100644 index 00000000..e4788283 --- /dev/null +++ b/docs/tsl/reference/catalog/math/matrix_and_arrays.md @@ -0,0 +1,184 @@ +# 数学函数 - 矩阵与数组 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录矩阵、数组、FMArray、矩阵初始化、矩阵运算及数组扩展函数。 + +## 矩阵初始化函数 + +### `zeros(size_or_rows[, cols_or_fields])` + +用途：生成元素为 `0` 的一维或二维矩阵样结果。 + +参数个数：1 到 2 +返回值：数组或矩阵样数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | --------- | -------------------- | +| 1 | `size_or_rows` | 是 | 整数 | 一维长度或二维行数 | +| 2 | `cols_or_fields` | 否 | 整数/数组 | 二维列数，或列名数组 | + +### `ones(length)` + +用途：生成元素为 `1` 的一维结果。 + +参数个数：1 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `length` | 是 | 整数 | 一维长度 | + +### `nils(length)` + +用途：生成元素为 `nil` 的一维结果。 + +参数个数：1 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `length` | 是 | 整数 | 一维长度 | + +### `eye(size)` + +用途：生成单位矩阵。 + +参数个数：1 +返回值：矩阵样数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------ | +| 1 | `size` | 是 | 整数 | 行数和列数；`eye(3)` 生成 `3 x 3` 单位矩阵 | + +### `rand(rows, cols)` + +用途：生成随机矩阵样结果。 + +参数个数：2 +返回值：矩阵样数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | +| 1 | `rows` | 是 | 整数 | 行数 | +| 2 | `cols` | 是 | 整数 | 列数 | + +## FMArray 函数 + +### `mInit(size_or_shape, value)` + +用途：生成指定尺寸并填充指定值的 FMArray。 + +参数个数：2 +返回值：FMArray + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | --------- | ----------------------------------------------- | +| 1 | `size_or_shape` | 是 | 整数/数组 | 一维长度，或形如 `array(rows, cols)` 的尺寸数组 | +| 2 | `value` | 是 | 数值 | 填充值；值的类型决定 FMArray 单元格类型 | + +### `mInitDiag(rows, cols, value)` + +用途：生成对角线填充值的 FMArray。 + +参数个数：3 +返回值：FMArray + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `rows` | 是 | 整数 | 行数 | +| 2 | `cols` | 是 | 整数 | 列数 | +| 3 | `value` | 是 | 数值 | 对角线填充值 | + +### `mRand(rows, cols)` + +用途：生成随机 FMArray。 + +参数个数：2 +返回值：FMArray + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | +| 1 | `rows` | 是 | 整数 | 行数 | +| 2 | `cols` | 是 | 整数 | 列数 | + +### `mswap(value, dim1, dim2)` + +用途：交换多维 FMArray 的两个维度。 + +参数个数：3 +返回值：FMArray + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------- | +| 1 | `value` | 是 | FMArray | 输入 FMArray | +| 2 | `dim1` | 是 | 整数 | 第一个维度下标 | +| 3 | `dim2` | 是 | 整数 | 第二个维度下标 | + +## 矩阵运算及分解 + +### `mt_va_Gauss_Jordan(a, v)` + +用途：数值计算相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `mt_decompose_svd(a, u, s, d)` + +用途：矩阵运算及分解相关函数。 + +参数个数：4 +返回值：矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `u` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `U` | +| 3 | `s` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `S` | +| 4 | `d` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `D` | + +### `mt_va_Cholesky(a, v)` + +用途：用 Cholesky 方法处理矩阵和向量输入。 + +参数个数：2 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------- | ------------------ | +| 1 | `a` | 是 | 数组/矩阵 | 矩阵数据 | +| 2 | `v` | 是 | 变量引用 | 接收处理结果的变量 | + +## 数组扩展 + +### `any(arg1, arg2)` + +用途：数值计算相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ----------- | -------------------- | +| 1 | `arg1` | 是 | 字符串/数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `all(arg1[, arg2])` + +用途：数值计算相关函数。 + +参数个数：1 到 2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/math/multivariate_statistics.md b/docs/tsl/reference/catalog/math/multivariate_statistics.md new file mode 100644 index 00000000..d4a206c6 --- /dev/null +++ b/docs/tsl/reference/catalog/math/multivariate_statistics.md @@ -0,0 +1,329 @@ +# 数学函数 - 多元统计分析 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录相关矩阵、协方差矩阵、距离、聚类、判别分析、主成分分析、因子分析和秩相关函数。 + +## 服务器多元统计函数 + +### `corr(values, method[, tail])` + +用途：计算相关系数矩阵；带 `tail` 时同时返回相关性检验 P 值矩阵。 + +参数个数：2 到 3 +返回值：数值矩阵/数组；带 `tail` 时返回 `[相关系数矩阵, P值矩阵]` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | +| 2 | `method` | 是 | 整数 | 相关系数计算方式 | +| 3 | `tail` | 否 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | + +### `correlationMatrix(values, method)` + +用途：计算相关系数矩阵。 + +参数个数：2 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | +| 2 | `method` | 是 | 整数 | 相关系数计算方式 | + +### `covariance(values)` + +用途：计算协方差矩阵。 + +参数个数：1 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | + +### `corrcoef(values)` + +用途：执行相关系数分析。 + +参数个数：1 +返回值：数组表；包含 `r`、`p`、`rlo`、`rup` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | + +### `corr_partial(x_values, y_values, z_values, method[, tail])` + +用途：计算偏相关系数；带 `tail` 时同时返回检验结果。 + +参数个数：4 到 5 +返回值：数值矩阵/数组表；带 `tail` 时包含 `coef`、`pval`、`df` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------------------------------- | +| 1 | `x_values` | 是 | 数值矩阵 | 第一组变量 | +| 2 | `y_values` | 是 | 数值矩阵 | 第二组变量 | +| 3 | `z_values` | 是 | 数值矩阵 | 控制变量 | +| 4 | `method` | 是 | 整数 | 相关系数计算方式 | +| 5 | `tail` | 否 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | + +### `distance(values, right_or_method[, method])` + +用途：计算向量距离，或计算矩阵样本两两距离。 + +参数个数：2 到 3 +返回值：实数/数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ----------------- | ------------------------------------------ | +| 1 | `values` | 是 | 数值数组/数值矩阵 | 左向量，或样本矩阵 | +| 2 | `right_or_method` | 是 | 数值数组/字符串 | 三参形式下为右向量；二参形式下为距离方法名 | +| 3 | `method` | 否 | 字符串 | 三参形式下的距离方法名；常用 `"euclidean"` | + +### `cluster_Kmeans(samples, class_count, options)` + +用途：执行 K-means 聚类。 + +参数个数：3 +返回值：数组；每个元素是一类样本下标数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------------------------------------------ | +| 1 | `samples` | 是 | 数值矩阵 | 样本矩阵 | +| 2 | `class_count` | 是 | 整数 | 聚类数量 | +| 3 | `options` | 是 | 数组表 | 参数表；常见键包括 `maxiter`、`tol`、`distance`、`out` | + +### `cluster_System(samples, distance_method, cluster_method[, output])` + +用途：执行系统聚类。 + +参数个数：3 到 4 +返回值：数组；三参返回谱系合并过程，四参且 `output` 包含 `best` 时返回最佳分类 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | ------------------------------- | +| 1 | `samples` | 是 | 数值矩阵 | 样本矩阵 | +| 2 | `distance_method` | 是 | 整数 | 距离方法 | +| 3 | `cluster_method` | 是 | 整数 | 聚类方法 | +| 4 | `output` | 否 | 数组表 | 输出选项；如 `array("best": 1)` | + +### `cluster_ward(samples)` + +用途：执行 Ward 聚类。 + +参数个数：1 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------- | +| 1 | `samples` | 是 | 数值矩阵 | 样本矩阵 | + +### `discrim(training_data, sample_data, method)` + +用途：执行判别分析并返回待判别样本分类。 + +参数个数：3 +返回值：数组；每个元素是对应待判别样本的分类编号 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | ---------------------------------------- | +| 1 | `training_data` | 是 | 数值矩阵 | 训练数据；第一列为分类编号，其余列为特征 | +| 2 | `sample_data` | 是 | 数值矩阵 | 待判别样本特征矩阵 | +| 3 | `method` | 是 | 整数 | 判别方法参数 | + +### `princomp(values, contribution_rate, standardize, residual)` + +用途：执行主成分分析。 + +参数个数：4 +返回值：数组表 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | -------------- | -------------------------------------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | +| 2 | `contribution_rate` | 是 | 数值 | 累计贡献率阈值 | +| 3 | `standardize` | 是 | 整数 | 是否标准化的模式参数 | +| 4 | `residual` | 是 | 变量引用/`nil` | 接收残差或相关输出；不需要时可传 `nil` | + +### `factor(values, contribution_rate)` + +用途：执行因子分析。 + +参数个数：2 +返回值：数组表；包含 `Correlation Matrix`、`kmo`、`Total Variance Explained` 等结果项 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | -------- | -------------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | +| 2 | `contribution_rate` | 是 | 数值 | 累计贡献率阈值 | + +### `corr_canonical(x_values, y_values, alpha, standardize)` + +用途：执行典型相关分析。 + +参数个数：4 +返回值：数组表；包含 `Cor`、`XCoef`、`YCoef` 等结果项 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------- | +| 1 | `x_values` | 是 | 数值矩阵 | 第一组变量 | +| 2 | `y_values` | 是 | 数值矩阵 | 第二组变量 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | +| 4 | `standardize` | 是 | 整数 | 是否标准化的模式参数 | + +### `corr_Spearman(x_values, y_values)` + +用途：计算 Spearman 秩相关系数。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ---------- | +| 1 | `x_values` | 是 | 数值数组 | 第一组数据 | +| 2 | `y_values` | 是 | 数值数组 | 第二组数据 | + +### `cov2CorrMatrix(covariance_matrix)` + +用途：把协方差矩阵转换为相关系数矩阵。 + +参数个数：1 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | -------- | ---------- | +| 1 | `covariance_matrix` | 是 | 数值矩阵 | 协方差矩阵 | + +### `corrMatrixAdjust(correlation_matrix)` + +用途：修正相关系数矩阵。 + +参数个数：1 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------------- | ---- | -------- | -------------------- | +| 1 | `correlation_matrix` | 是 | 数值矩阵 | 待修正的相关系数矩阵 | + +### `corr_Kendall(x_values, y_values)` + +用途：计算 Kendall 秩相关系数。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ---------- | +| 1 | `x_values` | 是 | 数值数组 | 第一组数据 | +| 2 | `y_values` | 是 | 数值数组 | 第二组数据 | + +### `histc(values, bins)` + +用途：按边界数组统计直方图计数。 + +参数个数：2 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------- | +| 1 | `values` | 是 | 数值数组 | 待统计数据 | +| 2 | `bins` | 是 | 数值数组 | 分箱边界 | + +### `princaipalComponentAnalysis(values)` + +用途：执行主成分分析并返回主因子得分结果。 + +参数个数：1 +返回值：数组表；包含 `F`、`F1`、`F2` 等得分字段 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `values` | 是 | 数值矩阵 | 样本矩阵 | + +### `mbbub(values, index_output)` + +用途：按数值排序并返回排序后的原始下标。 + +参数个数：2 +返回值：数组；同时写入 `index_output` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------ | +| 1 | `values` | 是 | 数值数组 | 待排序数组 | +| 2 | `index_output` | 是 | 变量引用 | 接收排序后的原始下标数组 | + +### `eigen_Jacobi(matrix, eigen_values, eigen_vectors)` + +用途：用 Jacobi 方法计算矩阵特征值和特征向量。 + +参数个数：3 +返回值：无直接返回值；写入 `eigen_values` 和 `eigen_vectors` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | ---------------- | +| 1 | `matrix` | 是 | 数值矩阵 | 待分解矩阵 | +| 2 | `eigen_values` | 是 | 变量引用 | 接收特征值数组 | +| 3 | `eigen_vectors` | 是 | 变量引用 | 接收特征向量矩阵 | + +### `componentMatrix(eigen_values, eigen_vectors, max_eigen_values)` + +用途：根据特征值和特征向量生成主成分载荷矩阵。 + +参数个数：3 +返回值：数值矩阵；同时写入 `max_eigen_values` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | -------- | ---------------------- | +| 1 | `eigen_values` | 是 | 数值数组 | 特征值数组 | +| 2 | `eigen_vectors` | 是 | 数值矩阵 | 特征向量矩阵 | +| 3 | `max_eigen_values` | 是 | 变量引用 | 接收主因子对应的特征根 | + +### `componentScoreMatrix(component_matrix, correlation_matrix)` + +用途：根据载荷矩阵和相关系数矩阵生成因子得分系数矩阵。 + +参数个数：2 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------------- | ---- | -------- | -------------- | +| 1 | `component_matrix` | 是 | 数值矩阵 | 主成分载荷矩阵 | +| 2 | `correlation_matrix` | 是 | 数值矩阵 | 相关系数矩阵 | + +### `factorScoreMatrix(score_matrix, standardized_values)` + +用途：根据因子得分系数矩阵和标准化样本矩阵生成样本公共因子得分。 + +参数个数：2 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------------- | ---- | -------- | ------------------ | +| 1 | `score_matrix` | 是 | 数值矩阵 | 因子得分系数矩阵 | +| 2 | `standardized_values` | 是 | 数值矩阵 | 标准化后的样本矩阵 | + +### `rotatedComponentMatrix(component_matrix)` + +用途：对主成分载荷矩阵做旋转处理。 + +参数个数：1 +返回值：数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | -------- | -------------- | +| 1 | `component_matrix` | 是 | 数值矩阵 | 主成分载荷矩阵 | + +### `fScoreResult(factor_scores, max_eigen_values)` + +用途：根据样本公共因子得分和主因子特征根生成综合得分结果。 + +参数个数：2 +返回值：数组表；包含 `F`、`F1`、`F2` 等得分字段 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | ----------------- | -------------------- | +| 1 | `factor_scores` | 是 | 数值矩阵 | 样本公共因子得分矩阵 | +| 2 | `max_eigen_values` | 是 | 数值数组/数值矩阵 | 主因子对应的特征根 | diff --git a/docs/tsl/reference/catalog/math/numerical_methods.md b/docs/tsl/reference/catalog/math/numerical_methods.md new file mode 100644 index 00000000..5f80d608 --- /dev/null +++ b/docs/tsl/reference/catalog/math/numerical_methods.md @@ -0,0 +1,549 @@ +# 数学函数 - 数值方法 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录数值微积分、线性方程组、插值和其他数值计算函数。 + +## 数值微积分 + +### `ig_Romberg(a, b, call_back, v)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `call_back` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `ig_Trapezoid_1(a, b, call_back, v)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `call_back` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `ig_Trapezoid_2(a, b, call_back, v)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `call_back` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `ig_Simpson_1(a, b, call_back, v)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `call_back` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `ig_Gauss(a, b, call_back, v)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `call_back` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `ig_Chebyshev(a, b, call_back, v)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `call_back` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `ig_Simpson_2(a, b, call_back1, call_back2, call_back3, v)` + +用途：数值计算相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `call_back1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `call_back2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 5 | `call_back3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 6 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_SinX(arg1, v)` + +用途：数值微积分相关函数。 + +参数个数：2 +返回值：数值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_CosX(arg1, v)` + +用途：数值计算相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_eX(arg1, v)` + +用途：数值计算相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_EllipseX_1(k, f, v)` + +用途：数值计算相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `k` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `f` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `sf_EllipseX_2(k, f, v)` + +用途：数值计算相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `k` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `f` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `v` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `v` | + +### `conv(a, b)` + +用途：数值计算相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 数组 | 按源文档示例顺序传入 | + +## 线性方程组的求解 + +### `se_Gauss(a, b, x)` + +用途：线性方程组的求解相关函数。 + +参数个数：3 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `x` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `X` | + +### `se_Gauss_Jordan(a, b, x)` + +用途：数值计算相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `x` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `X` | + +### `se_Ldl(a, b, x)` + +用途：数值计算相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `x` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `X` | + +### `se_Cholesky(a, b, x)` + +用途：数值计算相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `x` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `X` | + +### `se_Gauss_Seidel()` + +用途：线性方程组的求解相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +## 插值 + +### `ip_Lagrangian_A(x, y, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `xv` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Lagrangian_B(x0, h, y, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x0` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `h` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 4 | `xv` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Parabola_A(x, y, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `xv` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Parabola_B(x0, h, y, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x0` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `h` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 4 | `xv` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Hermite_A(x, y, dy, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `dy` | 是 | 任意值 | 按源文档示例顺序传入 | +| 4 | `xv` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Hermite_B(x0, h, y, dy, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x0` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `h` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 4 | `dy` | 是 | 数组 | 按源文档示例顺序传入 | +| 5 | `xv` | 是 | 实数 | 按源文档示例顺序传入 | +| 6 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Aitken_A(x, y, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `xv` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Aitken_B(x0, h, y, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x0` | 是 | 实数 | 按源文档示例顺序传入 | +| 2 | `h` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 4 | `xv` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Spline_A(x, y, dy0, dyn_1, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `dy0` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `dyn_1` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `xv` | 是 | 实数 | 按源文档示例顺序传入 | +| 6 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Spline_B(x, y, ddy0, ddyn_1, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `ddy0` | 是 | 整数 | 按源文档示例顺序传入 | +| 4 | `ddyn_1` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `xv` | 是 | 实数 | 按源文档示例顺序传入 | +| 6 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_Spline_C(x, y, xv, yv)` + +用途：数值计算相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `xv` | 是 | 实数 | 按源文档示例顺序传入 | +| 4 | `yv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `yv` | + +### `ip_SLQ(x, y, z, xv, yv, zv)` + +用途：数值计算相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `z` | 是 | 数组 | 按源文档示例顺序传入 | +| 4 | `xv` | 是 | 实数 | 按源文档示例顺序传入 | +| 5 | `yv` | 是 | 实数 | 按源文档示例顺序传入 | +| 6 | `zv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `zv` | + +### `ip_SLG(x, y, z, xv, yv, zv)` + +用途：数值计算相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------------------------- | +| 1 | `x` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `y` | 是 | 数组 | 按源文档示例顺序传入 | +| 3 | `z` | 是 | 数组 | 按源文档示例顺序传入 | +| 4 | `xv` | 是 | 实数 | 按源文档示例顺序传入 | +| 5 | `yv` | 是 | 实数 | 按源文档示例顺序传入 | +| 6 | `zv` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `zv` | + +## 其他数值计算 + +### `perms(value[, pick_count][, callback_object])` + +用途：计算阶乘、全排列或指定长度排列。 + +参数个数：1 到 3 +返回值：整数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | --------- | -------------------------------------------- | +| 1 | `value` | 是 | 整数/数组 | 传整数时计算阶乘；传数组时生成排列 | +| 2 | `pick_count` | 否 | 整数 | 指定每个排列选取的元素个数 | +| 3 | `callback_object` | 否 | 对象 | 可传带 `exe(dat)` 方法的对象接收排列过程数据 | + +### `nchoosek(values, choose_count)` + +用途：从数组中生成指定长度的组合。 + +参数个数：2 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ---------------------- | +| 1 | `values` | 是 | 数组 | 候选元素数组 | +| 2 | `choose_count` | 是 | 整数 | 每个组合选取的元素个数 | + +### `maxDrawDown(values[, direction])` + +用途：计算数值序列的最大涨跌幅区间。 + +参数个数：1 到 2 +返回值：数组；依次包含入点下标、出点下标、差值、比例 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 待计算的数值序列 | +| 2 | `direction` | 否 | 整数 | 方向参数；传 `1` 时按最大涨幅计算，省略时按最大跌幅计算 | + +### `minRecoveryTime(values, buy_index, sell_index)` + +用途：计算买入卖出后恢复到目标状态所需的最小时间位置。 + +参数个数：3 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------- | +| 1 | `values` | 是 | 数值数组 | 价格或数值序列 | +| 2 | `buy_index` | 是 | 整数 | 买入位置下标 | +| 3 | `sell_index` | 是 | 整数 | 卖出位置下标 | + +### `betainc(x, alpha, beta[, tail])` + +用途：计算不完全 beta 函数值。 + +参数个数：3 到 4 +返回值：实数/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ------------- | --------------------------------------------------------- | +| 1 | `x` | 是 | 实数/数值数组 | 输入值或输入序列 | +| 2 | `alpha` | 是 | 数值 | alpha 参数 | +| 3 | `beta` | 是 | 数值 | beta 参数 | +| 4 | `tail` | 否 | 字符串 | 尾部类型；省略时计算下尾，标量输入可传 `"upper"` 计算上尾 | + +### `percentileOfScore(data, score, kind)` + +用途：计算指定分数在数组中的百分位位置。 + +参数个数：3 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `data` | 是 | 数值数组 | 待计算的数值序列 | +| 2 | `score` | 是 | 数值 | 要定位的分数 | +| 3 | `kind` | 是 | 字符串 | 计算方式；可用 `"rank"`、`"strict"`、`"weak"`、`"mean"` | + +### `generateCombinations(values, out_combinations)` + +用途：生成数组元素的组合集合。 + +参数个数：2 +返回值：通过 `out_combinations` 接收结果数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------ | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数组 | 候选元素数组 | +| 2 | `out_combinations` | 是 | 变量引用 | 接收组合结果数组 | + +### `percentage(data, percent, style)` + +用途：按百分比参数和样式处理数值数组。 + +参数个数：3 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ----------------- | ------------ | +| 1 | `data` | 是 | 数值数组/数值矩阵 | 待处理的数据 | +| 2 | `percent` | 是 | 数值 | 百分比参数 | +| 3 | `style` | 是 | 整数 | 计算样式参数 | diff --git a/docs/tsl/reference/catalog/math/optimization.md b/docs/tsl/reference/catalog/math/optimization.md new file mode 100644 index 00000000..fa7c9b3c --- /dev/null +++ b/docs/tsl/reference/catalog/math/optimization.md @@ -0,0 +1,139 @@ +# 数学函数 - 优化与规划 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录线性规划、二次规划、整数规划、0/1 规划和二次规划辅助求解函数。 + +## 服务器优化函数 + +### `prog_L(f, a, b, aeq, beq, lower_bounds, upper_bounds, x0, options, binary_indices, integer_indices)` + +用途：求解带线性约束、边界约束、0/1 约束或整数约束的线性规划问题。 + +参数个数：11 +返回值：数组表；包含 `X`、`Fval`、`Error_M`、`Iter` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | --------------- | -------------------------------- | +| 1 | `f` | 是 | 数值数组 | 目标函数线性系数 | +| 2 | `a` | 是 | 数值矩阵/空数组 | 线性不等式约束左侧矩阵 | +| 3 | `b` | 是 | 数值数组/空数组 | 线性不等式约束右侧向量 | +| 4 | `aeq` | 是 | 数值矩阵/空数组 | 线性等式约束左侧矩阵 | +| 5 | `beq` | 是 | 数值数组/空数组 | 线性等式约束右侧向量 | +| 6 | `lower_bounds` | 是 | 数值数组/空数组 | 变量下界 | +| 7 | `upper_bounds` | 是 | 数值数组/空数组 | 变量上界 | +| 8 | `x0` | 是 | 数值数组 | 初始解 | +| 9 | `options` | 是 | 数组表/空数组 | 算法选项；使用默认设置时传空数组 | +| 10 | `binary_indices` | 是 | 整数数组/空数组 | 按 0/1 约束处理的变量下标 | +| 11 | `integer_indices` | 是 | 整数数组/空数组 | 按整数约束处理的变量下标 | + +### `prog_Q(h, f, a, b, aeq, beq, lower_bounds, upper_bounds)` + +用途：求解带线性约束和边界约束的二次规划问题。 + +参数个数：8 +返回值：数组表；包含 `X`、`Fval`、`Error_M`、`Iter` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | --------------- | ---------------------- | +| 1 | `h` | 是 | 数值矩阵 | 二次项系数矩阵 | +| 2 | `f` | 是 | 数值数组 | 一次项系数 | +| 3 | `a` | 是 | 数值矩阵/空数组 | 线性不等式约束左侧矩阵 | +| 4 | `b` | 是 | 数值数组/空数组 | 线性不等式约束右侧向量 | +| 5 | `aeq` | 是 | 数值矩阵/空数组 | 线性等式约束左侧矩阵 | +| 6 | `beq` | 是 | 数值数组/空数组 | 线性等式约束右侧向量 | +| 7 | `lower_bounds` | 是 | 数值数组/空数组 | 变量下界 | +| 8 | `upper_bounds` | 是 | 数值数组/空数组 | 变量上界 | + +### `quadprog(h, f, a, b, aeq, beq)` + +用途：求解标准二次规划问题。 + +参数个数：6 +返回值：数组表；包含 `最优值`，并用整数键返回各变量解 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------------- | ---------------------- | +| 1 | `h` | 是 | 数值矩阵 | 二次项系数矩阵 | +| 2 | `f` | 是 | 数值数组 | 一次项系数 | +| 3 | `a` | 是 | 数值矩阵/空数组 | 线性不等式约束左侧矩阵 | +| 4 | `b` | 是 | 数值数组/空数组 | 线性不等式约束右侧向量 | +| 5 | `aeq` | 是 | 数值矩阵/空数组 | 线性等式约束左侧矩阵 | +| 6 | `beq` | 是 | 数值数组/空数组 | 线性等式约束右侧向量 | + +### `linearProgramming(f, a, b, aeq, beq)` + +用途：求解标准线性规划问题。 + +参数个数：5 +返回值：数组表；包含 `最优值`，并用整数键返回各变量解 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------------- | ---------------------- | +| 1 | `f` | 是 | 数值数组 | 目标函数线性系数 | +| 2 | `a` | 是 | 数值矩阵/空数组 | 线性不等式约束左侧矩阵 | +| 3 | `b` | 是 | 数值数组/空数组 | 线性不等式约束右侧向量 | +| 4 | `aeq` | 是 | 数值矩阵/空数组 | 线性等式约束左侧矩阵 | +| 5 | `beq` | 是 | 数值数组/空数组 | 线性等式约束右侧向量 | + +### `quadLagR(h, f, aeq, beq)` + +用途：用拉格朗日方法求解带等式约束的二次规划问题。 + +参数个数：4 +返回值：数组表；包含 `最优值`，并用整数键返回各变量解 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `h` | 是 | 数值矩阵 | 二次项系数矩阵 | +| 2 | `f` | 是 | 数值数组 | 一次项系数 | +| 3 | `aeq` | 是 | 数值矩阵 | 线性等式约束左侧矩阵 | +| 4 | `beq` | 是 | 数值数组 | 线性等式约束右侧向量 | + +### `ozProg(f, a, b)` + +用途：求解 0/1 规划问题。 + +参数个数：3 +返回值：数组表；包含 `最优值`，并用整数键返回各变量解 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------- | +| 1 | `f` | 是 | 数值数组 | 目标函数线性系数 | +| 2 | `a` | 是 | 数值矩阵 | 线性不等式约束左侧矩阵 | +| 3 | `b` | 是 | 数值数组 | 线性不等式约束右侧向量 | + +### `quadTrackRoute(h, f, a, b, aeq, beq, x0)` + +用途：用路径跟踪法求解二次规划问题。 + +参数个数：7 +返回值：数组表；包含 `最优值`，并用整数键返回各变量解 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------------- | ---------------------- | +| 1 | `h` | 是 | 数值矩阵 | 二次项系数矩阵 | +| 2 | `f` | 是 | 数值数组 | 一次项系数 | +| 3 | `a` | 是 | 数值矩阵/空数组 | 线性不等式约束左侧矩阵 | +| 4 | `b` | 是 | 数值数组/空数组 | 线性不等式约束右侧向量 | +| 5 | `aeq` | 是 | 数值矩阵/空数组 | 线性等式约束左侧矩阵 | +| 6 | `beq` | 是 | 数值数组/空数组 | 线性等式约束右侧向量 | +| 7 | `x0` | 是 | 数值数组 | 初始解 | + +### `intLinProg(f, a, b, aeq, beq, integer_indices)` + +用途：求解整数线性规划问题。 + +参数个数：6 +返回值：数组表；包含 `最优值`，并用整数键返回各变量解 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | --------------- | ------------------------------------------------------ | +| 1 | `f` | 是 | 数值数组 | 目标函数线性系数 | +| 2 | `a` | 是 | 数值矩阵/空数组 | 线性不等式约束左侧矩阵 | +| 3 | `b` | 是 | 数值数组/空数组 | 线性不等式约束右侧向量 | +| 4 | `aeq` | 是 | 数值矩阵/空数组 | 线性等式约束左侧矩阵 | +| 5 | `beq` | 是 | 数值数组/空数组 | 线性等式约束右侧向量 | +| 6 | `integer_indices` | 是 | 整数数组/空数组 | 按整数约束处理的变量下标；传空数组时按函数默认规则处理 | diff --git a/docs/tsl/reference/catalog/math/regression.md b/docs/tsl/reference/catalog/math/regression.md new file mode 100644 index 00000000..86991eeb --- /dev/null +++ b/docs/tsl/reference/catalog/math/regression.md @@ -0,0 +1,482 @@ +# 数学函数 - 回归分析 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录回归建模、回归诊断、回归检验、加权回归、岭回归、Logistic/Binary 回归和回归辅助统计函数。 + +## 服务器回归函数 + +### `regress_domin_formula(y_values, x_values)` + +用途：计算回归解释变量的相对重要性。 + +参数个数：2 +返回值：数组表；包含 `变量名`、`贡献度`、`贡献率(%)`、`排名` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | + +### `regress_domin_marginal(y_values, x_values, variable_names, method)` + +用途：用边际效用法计算回归解释变量的相对重要性。 + +参数个数：4 +返回值：数组表；包含 `变量名`、`贡献度`、`贡献率(%)`、`排名` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | ---------- | ------------------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `variable_names` | 是 | `nil`/数组 | 变量名；不指定时传 `nil` | +| 4 | `method` | 是 | 整数 | 边际效用计算方式 | + +### `regress_Ridge(y_values, x_values[, k_values][, trace_mode])` + +用途：执行岭回归，或按 `k_values` 输出岭迹。 + +参数个数：2 或 4 +返回值：数组表/数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `k_values` | 否 | 数值数组 | 岭参数序列；省略时自动选择 | +| 4 | `trace_mode` | 否 | 布尔值 | 是否按岭迹模式输出 | + +### `regress_AdjustedR2(r_square, sample_count, variable_count)` + +用途：根据 R2、样本数和变量数计算调整后 R2。 + +参数个数：3 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ---------- | +| 1 | `r_square` | 是 | 数值 | R2 | +| 2 | `sample_count` | 是 | 整数 | 样本数量 | +| 3 | `variable_count` | 是 | 整数 | 自变量数量 | + +### `regress_Logistic(y_values, x_values, constant, alpha)` + +用途：执行 Logistic 回归。 + +参数个数：4 +返回值：数组表；包含 `Coefficient`、`-2LogLikeHood`、`Wald Test` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 0/1 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `constant` | 是 | 布尔值 | 是否包含常数项 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | + +### `regression(y_values, x_values, alpha, constant)` + +用途：执行普通最小二乘回归。 + +参数个数：4 +返回值：数组表；包含 `Coefficient`、`Resid`、`Residual Test`、`R-Squared` 等结果项 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ----------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | +| 4 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | + +### `regress_DWTest(residuals)` + +用途：计算 Durbin-Watson 统计量。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `residuals` | 是 | 数值数组 | 回归残差序列 | + +### `regress_White(y_values, x_values, constant, alpha)` + +用途：执行 White 异方差检验。 + +参数个数：4 +返回值：数组表；包含 `F`、`NR2` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ----------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | + +### `regress_MLS(y_values, x_values, residuals)` + +用途：执行最小二乘回归并输出残差。 + +参数个数：3 +返回值：数组；返回回归系数，同时写入 `residuals` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `residuals` | 是 | 变量引用 | 接收残差序列 | + +### `regress_CMLS(y_values, x_values, residuals, constant)` + +用途：执行带常数项控制的最小二乘回归并输出残差。 + +参数个数：4 +返回值：数组；返回回归系数，同时写入 `residuals` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ----------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `residuals` | 是 | 变量引用 | 接收残差序列 | +| 4 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | + +### `regress_JBTest(values, alpha)` + +用途：执行 Jarque-Bera 正态性检验。 + +参数个数：2 +返回值：数组表；包含 `JB-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------- | +| 1 | `values` | 是 | 数值数组 | 待检验序列 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `regress_FTest(y_values, residuals, variable_count, alpha)` + +用途：执行回归 F 检验。 + +参数个数：4 +返回值：数组表；包含 `F-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `residuals` | 是 | 数值数组 | 回归残差序列 | +| 3 | `variable_count` | 是 | 整数 | 自变量数量 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | + +### `regression_WLS(y_values, x_values, alpha, constant, mode, restrictiveness, x0, y0, weights)` + +用途：执行加权最小二乘回归。 + +参数个数：9 +返回值：数组表；包含 `Coefficient`、`Resid`、`Residual Test` 等结果项 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------------- | ---------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | +| 4 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | +| 5 | `mode` | 是 | 整数 | 回归模式参数 | +| 6 | `restrictiveness` | 是 | `nil`/数组 | 约束参数；无约束时传 `nil` | +| 7 | `x0` | 是 | `nil`/数值矩阵 | 预测自变量；不需要时传 `nil` | +| 8 | `y0` | 是 | `nil`/数值数组 | 预测因变量；不需要时传 `nil` | +| 9 | `weights` | 是 | 数值数组 | 权重序列 | + +### `regress_Binary(y_values, x_values, link_name, iteration_count, constant, alpha)` + +用途：执行二元响应回归。 + +参数个数：6 +返回值：数组表；包含 `Coefficient`、`-2LogLikeHood`、`Wald Test` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | -------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 0/1 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `link_name` | 是 | 字符串 | 链接函数名；常用 `"logit"` | +| 4 | `iteration_count` | 是 | 整数 | 迭代或模型参数 | +| 5 | `constant` | 是 | 布尔值 | 是否包含常数项 | +| 6 | `alpha` | 是 | 数值 | 显著性水平 | + +### `regress_TTest(x_values, coefficients, residuals, variable_count, alpha, constant)` + +用途：执行回归系数 T 检验。 + +参数个数：6 +返回值：数组表；包含 `T-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | ----------------- | -------------------------- | +| 1 | `x_values` | 是 | 数值数组/数值矩阵 | 自变量样本 | +| 2 | `coefficients` | 是 | 数值数组 | 回归系数 | +| 3 | `residuals` | 是 | 数值数组 | 回归残差序列 | +| 4 | `variable_count` | 是 | 整数 | 自变量数量或自由度相关参数 | +| 5 | `alpha` | 是 | 数值 | 显著性水平 | +| 6 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | + +### `regress_WLS(y_values, x_values, weights, residuals)` + +用途：执行加权最小二乘回归并输出残差。 + +参数个数：4 +返回值：数组表；同时写入 `residuals` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ----------------- | ------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值数组/数值矩阵 | 自变量样本 | +| 3 | `weights` | 是 | 数值数组 | 权重序列 | +| 4 | `residuals` | 是 | 变量引用 | 接收残差序列 | + +### `regress_AicAndSbic(residuals, variable_count, sample_count)` + +用途：计算 AIC 和 SBIC。 + +参数个数：3 +返回值：数组表；包含 `Akaike Info Criterion`、`Schwarz Info Criterion` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ------------ | +| 1 | `residuals` | 是 | 数值数组 | 回归残差序列 | +| 2 | `variable_count` | 是 | 整数 | 自变量数量 | +| 3 | `sample_count` | 是 | 整数 | 样本数量 | + +### `regress_RSquare(y_values, residuals)` + +用途：根据因变量序列和残差序列计算 R2。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `residuals` | 是 | 数值数组 | 回归残差序列 | + +### `regress_QRlsq(y_values, x_values, residuals, constant)` + +用途：用 QR 分解执行最小二乘回归并输出残差。 + +参数个数：4 +返回值：数组；返回回归系数，同时写入 `residuals` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ----------------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值数组/数值矩阵 | 自变量样本 | +| 3 | `residuals` | 是 | 变量引用 | 接收残差序列 | +| 4 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | + +### `boxcox(values)` + +用途：执行 Box-Cox 变换。 + +参数个数：1 +返回值：数组表；包含 `data`、`lambda` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------- | +| 1 | `values` | 是 | 数值数组 | 待变换数据 | + +### `regress_VIF(x_values)` + +用途：计算方差膨胀因子和条件数。 + +参数个数：1 +返回值：数组表；包含 `VIF`、`Cond` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------- | +| 1 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | + +### `regress_Constraint(y_values, x_values, constant, a, b, aeq, beq, alpha, option, lower_bounds, upper_bounds)` + +用途：执行带线性约束和边界约束的回归。 + +参数个数：11 +返回值：数组表；包含 `Coefficient`、`Fval`、`R-Squared`、`Adjusted R-Squared`、`Residual Series`、`Residual Test`、`F Test`、`T Test` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | --------------- | ------------------------------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | +| 4 | `a` | 是 | 数值矩阵/空数组 | 不等式约束左侧矩阵；无约束时传空数组 | +| 5 | `b` | 是 | 数值数组/空数组 | 不等式约束右侧向量；无约束时传空数组 | +| 6 | `aeq` | 是 | 数值矩阵/空数组 | 等式约束左侧矩阵；无约束时传空数组 | +| 7 | `beq` | 是 | 数值数组/空数组 | 等式约束右侧向量；无约束时传空数组 | +| 8 | `alpha` | 是 | 数值 | 显著性水平 | +| 9 | `option` | 是 | 整数 | 优化目标或约束回归模式参数 | +| 10 | `lower_bounds` | 是 | 数值数组/空数组 | 系数下界；无下界时传空数组 | +| 11 | `upper_bounds` | 是 | 数值数组/空数组 | 系数上界；无上界时传空数组 | + +### `regress_HettestSpearman(y_values, x_values, alpha, constant)` + +用途：执行 Spearman 等级相关异方差检验。 + +参数个数：4 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | ----------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | +| 4 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | + +### `regression_OLS_White(y_values, x_values)` + +用途：执行普通最小二乘回归，并输出 White 稳健标准误相关结果。 + +参数个数：2 +返回值：数组表；包含 `Coefficient`、`Resid`、`R-Squared`、`Adjusted R-Squared`、稳健 `T Test` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | + +### `regression_OLS_NW(y_values, x_values)` + +用途：执行普通最小二乘回归，并输出 Newey-West 稳健标准误相关结果。 + +参数个数：2 +返回值：数组表；包含 `Coefficient`、`Resid`、`R-Squared`、`Adjusted R-Squared`、稳健 `T Test` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | + +### `nw_Adjustment_Simplification(values)` + +用途：对序列执行 Newey-West 调整的简化计算。 + +参数个数：1 +返回值：数组表；包含 `stderr`、`T-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 待调整的样本序列 | + +### `regress_TTest_RWLS(x_values, coefficients, residuals, variable_count, alpha, constant)` + +用途：执行线性约束加权最小二乘回归的系数 T 检验。 + +参数个数：6 +返回值：数组表；包含 `T-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | ----------------- | -------------------------- | +| 1 | `x_values` | 是 | 数值数组/数值矩阵 | 自变量样本 | +| 2 | `coefficients` | 是 | 数值数组 | 回归系数 | +| 3 | `residuals` | 是 | 数值数组 | 回归残差序列 | +| 4 | `variable_count` | 是 | 整数 | 自变量数量或自由度相关参数 | +| 5 | `alpha` | 是 | 数值 | 显著性水平 | +| 6 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | + +### `regress_TTest_White(x_values, coefficients, residuals, alpha, constant, white_result)` + +用途：基于 White 稳健结果执行回归系数 T 检验。 + +参数个数：6 +返回值：数组表；包含 `stderr`、`T-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ----------------- | -------------------------------- | +| 1 | `x_values` | 是 | 数值数组/数值矩阵 | 自变量样本 | +| 2 | `coefficients` | 是 | 数值数组 | 回归系数 | +| 3 | `residuals` | 是 | 数值数组 | 回归残差序列 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | +| 5 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | +| 6 | `white_result` | 是 | 数组表/矩阵 | White 稳健方差结果或对应回归结果 | + +### `regress_TTest_NW(x_values, coefficients, residuals, alpha, constant, lag_order, robust_result)` + +用途：基于 Newey-West 稳健结果执行回归系数 T 检验。 + +参数个数：7 +返回值：数组表；包含 `stderr`、`T-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | ----------------- | -------------------------- | +| 1 | `x_values` | 是 | 数值数组/数值矩阵 | 自变量样本 | +| 2 | `coefficients` | 是 | 数值数组 | 回归系数 | +| 3 | `residuals` | 是 | 数值数组 | 回归残差序列 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | +| 5 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | +| 6 | `lag_order` | 是 | 整数 | Newey-West 滞后阶数 | +| 7 | `robust_result` | 是 | 数组表/矩阵 | 稳健方差结果或对应回归结果 | + +### `robustfit_M(y_values, x_values, alpha, constant, weight_name, tune)` + +用途：执行 M 估计稳健回归。 + +参数个数：6 +返回值：数组表；包含 `Coefficient`、`Resid` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ----------------- | ------------------------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值数组/数值矩阵 | 自变量样本 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | +| 4 | `constant` | 是 | 整数/布尔值 | 是否包含常数项 | +| 5 | `weight_name` | 是 | 字符串 | 稳健权重函数名；如 `"andrews"` | +| 6 | `tune` | 是 | 数值 | 权重函数调节常数 | + +### `regress_GRStest(alpha_values, residual_matrix, factor_matrix)` + +用途：执行 GRS 检验。 + +参数个数：3 +返回值：数组表；包含 `FGRS`、`pGRS` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ----------------- | ---------------------- | +| 1 | `alpha_values` | 是 | 数值数组/数值矩阵 | 截距项或 alpha 向量 | +| 2 | `residual_matrix` | 是 | 数值矩阵 | 回归残差矩阵 | +| 3 | `factor_matrix` | 是 | 数值矩阵 | 因子收益或因子暴露矩阵 | + +### `leastSquares_CurveFitting(factors, y_values)` + +用途：执行最小二乘曲线拟合；当 `y_values` 中存在 `nil` 或 `nan` 时，跳过对应位置后计算。 + +参数个数：2 +返回值：数值矩阵/数组；拟合系数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------ | +| 1 | `factors` | 是 | 数值矩阵 | 拟合因子矩阵 | +| 2 | `y_values` | 是 | 数值数组 | 目标值序列 | + +### `regress_Stepwise(y_values, x_values, enter_alpha, remove_alpha)` + +用途：执行逐步回归。 + +参数个数：4 +返回值：数组表；包含 `x`、`regress` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `enter_alpha` | 是 | 数值 | 变量进入模型的显著性阈值 | +| 4 | `remove_alpha` | 是 | 数值 | 变量移出模型的显著性阈值 | + +### `regress_pri(y_values, x_values, contribution_rate, alpha)` + +用途：执行按累计贡献率选择主成分的回归。 + +参数个数：4 +返回值：数组表；包含 `Coefficient`、`Resid`、`R-Squared`、`Adjusted R-Squared`、`SSR`、`HelpRegress` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | -------- | -------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量样本 | +| 2 | `x_values` | 是 | 数值矩阵 | 自变量样本矩阵 | +| 3 | `contribution_rate` | 是 | 数值 | 主成分累计贡献率阈值 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | diff --git a/docs/tsl/reference/catalog/math/statistical_inference.md b/docs/tsl/reference/catalog/math/statistical_inference.md new file mode 100644 index 00000000..77807da3 --- /dev/null +++ b/docs/tsl/reference/catalog/math/statistical_inference.md @@ -0,0 +1,345 @@ +# 数学函数 - 统计推断 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录置信区间估计、假设检验、方差分析和正态 QQ 分析函数。 + +## 服务器统计推断函数 + +### `estimate_SNU(values, known_variance, alpha, tail)` + +用途：估计单个正态总体均值的置信区间。 + +参数个数：4 +返回值：数组表；包含 `Lower`、`Upper` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | ---------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `known_variance` | 是 | `nil`/数值 | 已知方差；未知时传 `nil` | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | +| 4 | `tail` | 是 | 字符串 | 区间方向；常用 `"both"`、`"left"`、`"right"` | + +### `estimate_TNU(samples, known_variances, alpha, tail, mode)` + +用途：估计两个正态总体均值差的置信区间。 + +参数个数：5 +返回值：数组表；包含 `Lower`、`Upper` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | ------------- | -------------------------------------------- | +| 1 | `samples` | 是 | 数值矩阵/数组 | 两组样本数据 | +| 2 | `known_variances` | 是 | 数组 | 两组已知方差；未知项可用 `nil` | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | +| 4 | `tail` | 是 | 字符串 | 区间方向；常用 `"both"`、`"left"`、`"right"` | +| 5 | `mode` | 是 | 整数 | 检验或估计模式参数 | + +### `estimate_SND(values, alpha, tail)` + +用途：估计单个正态总体方差的置信区间。 + +参数个数：3 +返回值：数组表；包含 `Lower`、`Upper` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | +| 3 | `tail` | 是 | 字符串 | 区间方向；常用 `"both"`、`"left"`、`"right"` | + +### `estimate_TND(samples, alpha)` + +用途：估计两个正态总体方差比的置信区间。 + +参数个数：2 +返回值：数组表；包含 `Lower`、`Upper` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------- | ------------ | +| 1 | `samples` | 是 | 数值矩阵/数组 | 两组样本数据 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `estimate_SP(sample_ratio, sample_count, alpha)` + +用途：估计单个总体比例的置信区间。 + +参数个数：3 +返回值：数组表；包含 `Lower`、`upper` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ---------- | +| 1 | `sample_ratio` | 是 | 数值 | 样本比例 | +| 2 | `sample_count` | 是 | 整数 | 样本数量 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | + +### `estimate_TP(sample_ratios, sample_counts, alpha)` + +用途：估计两个总体比例差的置信区间。 + +参数个数：3 +返回值：数组表；包含 `Lower`、`upper` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | ------------ | +| 1 | `sample_ratios` | 是 | 数值数组 | 两个样本比例 | +| 2 | `sample_counts` | 是 | 数值数组 | 两个样本数量 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_TailRes(statistic, p_value, tail, alpha)` + +用途：根据统计量、P 值、检验方向和显著性水平生成假设检验结果。 + +参数个数：4 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------------------------- | +| 1 | `statistic` | 是 | 数值 | 检验统计量 | +| 2 | `p_value` | 是 | 数值 | P 值 | +| 3 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | + +### `normPlot(values[, mode])` + +用途：生成正态 QQ 图数据，或返回正态性评分。 + +参数个数：1 到 2 +返回值：数组表/实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | --------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `mode` | 否 | 整数 | 省略时返回 QQ 图数组表；传 `1` 时返回评分实数 | + +### `hypoth_Kstest(values, tail, alpha, cdf)` + +用途：执行 Kolmogorov-Smirnov 检验。 + +参数个数：4 +返回值：数组表；包含 `statistical`、`criticalValue`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | --------------------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 3 | `alpha` | 是 | 数值/变量引用/`nil` | 显著性水平；传变量或 `nil` 时使用默认值 | +| 4 | `cdf` | 是 | 表达式对象/函数/`nil` | 理论分布 CDF；默认检验可传 `nil` | + +### `hypoth_lillietest(values, alpha, distribution_name)` + +用途：执行 Lilliefors 正态性检验。 + +参数个数：3 +返回值：数组表；包含 `kstat`、`cv`、`P-value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------------- | ---- | -------- | ----------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | +| 3 | `distribution_name` | 是 | 字符串 | 分布名；正态性检验传 `"norm"` | + +### `hypoth_IndepTest(observed_table, alpha)` + +用途：执行列联表独立性检验。 + +参数个数：2 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | -------------- | +| 1 | `observed_table` | 是 | 数值矩阵 | 列联表观测频数 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_KruskalWallis(observed_table, alpha)` + +用途：执行 Kruskal-Wallis 检验。 + +参数个数：2 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ------------ | +| 1 | `observed_table` | 是 | 数值矩阵 | 检验数据矩阵 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_SNUTest(values, mean_value, std_dev, tail, alpha)` + +用途：执行单个正态总体均值 U 检验。 + +参数个数：5 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis`，可包含 `(T1,T2)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `mean_value` | 是 | 数值 | 原假设均值 | +| 3 | `std_dev` | 是 | 数值 | 总体标准差 | +| 4 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 5 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_TNUTest(samples, mean_diff, std_devs, tail, alpha, mode)` + +用途：执行两个正态总体均值差 U 检验。 + +参数个数：6 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis`，可包含 `(T1,T2)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------- | -------------------------------------------- | +| 1 | `samples` | 是 | 数值矩阵/数组 | 两组样本数据 | +| 2 | `mean_diff` | 是 | 数值 | 原假设均值差 | +| 3 | `std_devs` | 是 | 数值数组 | 两组标准差参数 | +| 4 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 5 | `alpha` | 是 | 数值 | 显著性水平 | +| 6 | `mode` | 是 | 整数 | 检验模式参数 | + +### `hypoth_SNDTest(values, variance_value, tail, alpha)` + +用途：执行单个正态总体方差检验。 + +参数个数：4 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis`，可包含 `(T1,T2)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `variance_value` | 是 | 数值 | 原假设方差 | +| 3 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_TNDTest(samples, tail, alpha)` + +用途：执行两个正态总体方差检验。 + +参数个数：3 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | ------------- | -------------------------------------------- | +| 1 | `samples` | 是 | 数值矩阵/数组 | 两组样本数据 | +| 2 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_LSUTest(sample_mean, sample_variance, sample_count, mean_value, tail, alpha)` + +用途：用样本均值、样本方差和样本数量执行单总体均值检验。 + +参数个数：6 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis`，可包含 `(T1,T2)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | -------------------------------------------- | +| 1 | `sample_mean` | 是 | 数值 | 样本均值 | +| 2 | `sample_variance` | 是 | 数值 | 样本方差 | +| 3 | `sample_count` | 是 | 整数 | 样本数量 | +| 4 | `mean_value` | 是 | 数值 | 原假设均值 | +| 5 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 6 | `alpha` | 是 | 数值 | 显著性水平 | + +### `anova_Single(groups, alpha)` + +用途：执行单因素方差分析。 + +参数个数：2 +返回值：数组表；包含 `A-Factor`、`Error`、`Total` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | ------------- | ---------- | +| 1 | `groups` | 是 | 数值矩阵/数组 | 各组观测值 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `anova_Twice(values, alpha, repeat_count)` + +用途：执行双因素方差分析。 + +参数个数：3 +返回值：数组表；包含 `A-Factor(Rows)`、`B-Factor(Columns)`、`AB-interaction` 等结果项 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------------ | +| 1 | `values` | 是 | 数值矩阵 | 观测值矩阵 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | +| 3 | `repeat_count` | 是 | 整数 | 每个因素水平组合的重复试验次数 | + +### `anova_Bartlett(groups, alpha)` + +用途：执行 Bartlett 方差齐性检验。 + +参数个数：2 +返回值：数组表；包含 `B-Stat`、`P-Value`、`df`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | ------------- | ---------- | +| 1 | `groups` | 是 | 数值矩阵/数组 | 各组观测值 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `anova_Levene(groups, alpha)` + +用途：执行 Levene 方差齐性检验。 + +参数个数：2 +返回值：数组表；包含 `F-Stat`、`P-Value`、`df1`、`df2`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | ------------- | ---------- | +| 1 | `groups` | 是 | 数值矩阵/数组 | 各组观测值 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_SignTest(values, probability, median_value, tail, alpha)` + +用途：执行符号检验。 + +参数个数：5 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `probability` | 是 | 数值 | 原假设成功概率 | +| 3 | `median_value` | 是 | 数值 | 原假设中位数 | +| 4 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 5 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_WilcoxonTest(values, median_value, tail, alpha)` + +用途：执行 Wilcoxon 符号秩检验。 + +参数个数：4 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 样本数据 | +| 2 | `median_value` | 是 | 数值 | 原假设中位数 | +| 3 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_McNemarTest(observed_table, alpha)` + +用途：执行 McNemar 检验。 + +参数个数：2 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ---------------------- | +| 1 | `observed_table` | 是 | 数值矩阵 | 2x2 配对分类资料列联表 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `hypoth_PNUTest(samples, mean_diff, std_dev, tail, alpha)` + +用途：执行配对样本均值差 U 检验。 + +参数个数：5 +返回值：数组表；包含 `Statistic`、`P-Value`、`Hypothesis`，可包含 `(T1,T2)` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | ------------- | -------------------------------------------- | +| 1 | `samples` | 是 | 数值矩阵/数组 | 两组配对样本数据 | +| 2 | `mean_diff` | 是 | 数值 | 原假设均值差 | +| 3 | `std_dev` | 是 | `nil`/数值 | 差值标准差；未知时传 `nil` | +| 4 | `tail` | 是 | 字符串 | 检验方向；常用 `"both"`、`"left"`、`"right"` | +| 5 | `alpha` | 是 | 数值 | 显著性水平 | diff --git a/docs/tsl/reference/catalog/math/statistics_descriptive.md b/docs/tsl/reference/catalog/math/statistics_descriptive.md new file mode 100644 index 00000000..319b0d4a --- /dev/null +++ b/docs/tsl/reference/catalog/math/statistics_descriptive.md @@ -0,0 +1,854 @@ +# 数学函数 - 描述统计 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录一般统计量、次序统计量和含 NAN 统计函数。 + +## 一般统计量 + +### `minIntValue(a)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | + +### `sumOfSquares(a)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | + +### `stdDev(a[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `mean(a[, arg2][, arg3][, arg4])` + +用途：进行数值统计计算。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `sum(a[, arg2][, arg3][, arg4])` + +用途：进行数值统计计算。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `maxValue(a[, arg2][, arg3][, arg4])` + +用途：进行数值统计计算。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `minValue(a[, arg2][, arg3][, arg4])` + +用途：进行数值统计计算。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `norm(a[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `sumsAndSquares(a, b, c)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `b` | +| 3 | `c` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `c` | + +### `maxIntValue(a)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | + +### `sumInt(a)` + +用途：进行数值统计计算。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | + +### `harmean(data[, arg2][, arg3][, arg4])` + +用途：进行数值统计计算。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `variance(a[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `meanAndStdDev(a, b, c)` + +用途：进行数值统计计算。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `b` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `b` | +| 3 | `c` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `c` | + +### `aveDev(data)` + +用途：一般统计量相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | + +### `skewness(data[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `totalVariance(a)` + +用途：一般统计量相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | + +### `product(data[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `popnStdDev(a[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `kurtosis2(data[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `median(data)` + +用途：一般统计量相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | + +### `skewness2(data[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `kurtosis(data[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `mode(data)` + +用途：一般统计量相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | + +### `randG(arg1, arg2)` + +用途：一般统计量相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `geomean(data[, arg2][, arg3][, arg4])` + +用途：进行数值统计计算。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `popnVariance(a[, arg2][, arg3][, arg4])` + +用途：一般统计量相关函数。 + +参数个数：1 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `a` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `momentSkewKurtosis(data, m1, m2, m3, m4, skew, kurtosis)` + +用途：一般统计量相关函数。 + +参数个数：7 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | --------------------------------------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `m1` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `M1` | +| 3 | `m2` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `M2` | +| 4 | `m3` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `M3` | +| 5 | `m4` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `M4` | +| 6 | `skew` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Skew` | +| 7 | `kurtosis` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `Kurtosis` | + +### `devSq(data)` + +用途：一般统计量相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | + +## 服务器统计函数 + +### `cov(left_values, right_values)` + +用途：计算两个数值序列的协方差。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------------------------------ | +| 1 | `left_values` | 是 | 数值数组 | 第一个数值序列 | +| 2 | `right_values` | 是 | 数值数组 | 第二个数值序列；长度应与第一个序列一致且不少于 2 | + +### `correl(left_values, right_values)` + +用途：计算两个数值序列的相关系数。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ------------------------------------------------ | +| 1 | `left_values` | 是 | 数值数组 | 第一个数值序列 | +| 2 | `right_values` | 是 | 数值数组 | 第二个数值序列；长度应与第一个序列一致且不少于 2 | + +### `slope(y_values, x_values)` + +用途：计算 `y_values` 对 `x_values` 做线性回归时的斜率。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量序列 | +| 2 | `x_values` | 是 | 数值数组 | 自变量序列；长度应与因变量序列一致且不少于 2 | + +### `intercept(y_values, x_values)` + +用途：计算 `y_values` 对 `x_values` 做线性回归时的截距。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量序列 | +| 2 | `x_values` | 是 | 数值数组 | 自变量序列；长度应与因变量序列一致且不少于 2 | + +### `rsq(y_values, x_values)` + +用途：计算 `y_values` 与 `x_values` 的回归判定系数。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量序列 | +| 2 | `x_values` | 是 | 数值数组 | 自变量序列；长度应与因变量序列一致且不少于 2 | + +### `steyx(y_values, x_values)` + +用途：计算 `y_values` 对 `x_values` 做线性回归时的估计标准误差。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------ | +| 1 | `y_values` | 是 | 数值数组 | 因变量序列 | +| 2 | `x_values` | 是 | 数值数组 | 自变量序列；长度应与因变量序列一致且大于 2 | + +### `slopeAndIntercept(y_values, x_values)` + +用途：计算 `y_values` 对 `x_values` 做线性回归时的斜率和截距。 + +参数个数：2 +返回值：数组；第 1 个元素为斜率，第 2 个元素为截距 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量序列 | +| 2 | `x_values` | 是 | 数值数组 | 自变量序列；长度应与因变量序列一致且不少于 2 | + +### `variationCoefficient(values)` + +用途：计算数值序列的变异系数。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 要计算的数值序列 | + +### `selfStdDev(values, threshold)` + +用途：按给定阈值计算数值序列的下行标准差。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ----------------------------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 要计算的数值序列 | +| 2 | `threshold` | 是 | 数值 | 阈值；按 `value - threshold` 处理后，将大于 0 的部分按 0 参与计算 | + +### `skew(values, out_skew)` + +用途：计算数值序列的偏度。 + +参数个数：2 +返回值：整数状态码；成功返回 `1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ---------------------------- | +| 1 | `values` | 是 | 数值数组 | 要计算的数值序列 | +| 2 | `out_skew` | 是 | 变量引用 | 接收偏度结果，结果类型为实数 | + +### `kurt(values, out_kurt)` + +用途：计算数值序列的峰度。 + +参数个数：2 +返回值：整数状态码；成功返回 `1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ---------------------------- | +| 1 | `values` | 是 | 数值数组 | 要计算的数值序列 | +| 2 | `out_kurt` | 是 | 变量引用 | 接收峰度结果，结果类型为实数 | + +### `meanAndPopnStdDevWithRate(values, rates, out_mean, out_std_dev)` + +用途：按权重序列计算均值和总体标准差。 + +参数个数：4 +返回值：整数状态码；成功返回 `0` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------------------- | +| 1 | `values` | 是 | 数值数组 | 要计算的数值序列 | +| 2 | `rates` | 是 | 数值数组 | 权重序列；长度应与 `values` 一致 | +| 3 | `out_mean` | 是 | 变量引用 | 接收均值，结果类型为实数 | +| 4 | `out_std_dev` | 是 | 变量引用 | 接收总体标准差，结果类型为实数 | + +### `betaAndAlpha(y_values, x_values, out_beta, out_alpha)` + +用途：计算 `y_values` 对 `x_values` 做线性回归时的 beta 和 alpha。 + +参数个数：4 +返回值：整数状态码；成功返回 `0` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ---------------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量序列 | +| 2 | `x_values` | 是 | 数值数组 | 自变量序列；长度应与因变量序列一致 | +| 3 | `out_beta` | 是 | 变量引用 | 接收 beta，结果类型为实数 | +| 4 | `out_alpha` | 是 | 变量引用 | 接收 alpha，结果类型为实数 | + +### `regressionChannel(y_values, x_values, now_y, now_x, out_beta, out_alpha, out_upper_alpha, out_lower_alpha, out_upper_y, out_lower_y, out_position_percent, out_expected_y)` + +用途：按线性回归结果计算上下轨道、当前点所在轨道百分比和当前 `x` 的预期回归值。 + +参数个数：12 +返回值：整数状态码；成功返回 `0` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------------- | ---- | -------- | ------------------------------------------------------------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 因变量序列 | +| 2 | `x_values` | 是 | 数值数组 | 自变量序列；长度应与因变量序列一致 | +| 3 | `now_y` | 是 | 数值 | 当前点的 y 值 | +| 4 | `now_x` | 是 | 数值 | 当前点的 x 值 | +| 5 | `out_beta` | 是 | 变量引用 | 接收 beta，结果类型为实数 | +| 6 | `out_alpha` | 是 | 变量引用 | 接收 alpha，结果类型为实数 | +| 7 | `out_upper_alpha` | 是 | 变量引用 | 接收上轨 alpha，结果类型为实数 | +| 8 | `out_lower_alpha` | 是 | 变量引用 | 接收下轨 alpha，结果类型为实数 | +| 9 | `out_upper_y` | 是 | 变量引用 | 接收 `now_x` 对应的上轨 y 值，结果类型为实数 | +| 10 | `out_lower_y` | 是 | 变量引用 | 接收 `now_x` 对应的下轨 y 值，结果类型为实数 | +| 11 | `out_position_percent` | 是 | 变量引用 | 接收 `now_y` 在上下轨之间的位置百分比，低于下轨可小于 `0`，高于上轨可大于 `100` | +| 12 | `out_expected_y` | 是 | 变量引用 | 接收 `now_x` 对应的预期回归 y 值，结果类型为实数 | + +### `correlpaired(left_values, right_values)` + +用途：按配对方式计算一个序列与另一个序列或矩阵的相关系数。 + +参数个数：2 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | ----------------- | -------------- | +| 1 | `left_values` | 是 | 数值数组/数值矩阵 | 左侧序列或矩阵 | +| 2 | `right_values` | 是 | 数值数组/数值矩阵 | 右侧序列或矩阵 | + +### `correlpairedSide(values, filter_type)` + +用途：按指定过滤方向计算配对相关系数矩阵。 + +参数个数：2 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------ | +| 1 | `values` | 是 | 数值矩阵 | 待计算的数值矩阵 | +| 2 | `filter_type` | 是 | 整数 | 过滤方向或样式参数 | + +## 扩充统计函数 + +### `expdMax(values)` + +用途：计算数值序列的扩展最大值序列。 + +参数个数：1 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 待计算的数值序列 | + +### `expdMin(values)` + +用途：计算数值序列的扩展最小值序列。 + +参数个数：1 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 待计算的数值序列 | + +### `expdSum(values)` + +用途：计算数值序列的扩展求和序列。 + +参数个数：1 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 待计算的数值序列 | + +### `expdProduct(values)` + +用途：计算数值序列的扩展乘积序列。 + +参数个数：1 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 待计算的数值序列 | + +### `expdVar(values, mode)` + +用途：计算数值序列的扩展方差序列。 + +参数个数：2 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------------------- | +| 1 | `values` | 是 | 数值数组 | 待计算的数值序列 | +| 2 | `mode` | 是 | 整数 | 方差计算方式参数；常用 `0` | + +### `expdStd(values, mode)` + +用途：计算数值序列的扩展标准差序列。 + +参数个数：2 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------------------- | +| 1 | `values` | 是 | 数值数组 | 待计算的数值序列 | +| 2 | `mode` | 是 | 整数 | 标准差计算方式参数；常用 `0` | + +## 次序统计量 + +### `large(data, arg2)` + +用途：次序统计量相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `small(data, arg2)` + +用途：次序统计量相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `percentile(data, arg2[, arg3][, arg4][, arg5])` + +用途：次序统计量相关函数。 + +参数个数：2 到 5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 整数 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 否 | 数组 | 按源文档示例顺序传入 | + +### `percentrank(data, arg2)` + +用途：次序统计量相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `quartile(data, arg2)` + +用途：次序统计量相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `rank(data, arg2)` + +用途：次序统计量相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `trimmean(data, arg2)` + +用途：对字符串进行裁剪处理。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 实数 | 按源文档示例顺序传入 | + +### `frequency(data, freq_data)` + +用途：次序统计量相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------- | +| 1 | `data` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `freq_data` | 是 | 数组 | 按源文档示例顺序传入 | + +## 含NAN统计 + +### `nanPopnVariance()` + +用途：含NAN统计相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `nanMean(values)` + +用途：忽略 `nan` 计算数值序列均值。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------------------- | +| 1 | `values` | 是 | 数值数组 | 可包含 `nan` 的数值序列 | + +### `nanSum(values)` + +用途：忽略 `nan` 计算数值序列总和。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------------------- | +| 1 | `values` | 是 | 数值数组 | 可包含 `nan` 的数值序列 | + +### `nanStd(values)` + +用途：忽略 `nan` 计算数值序列样本标准差。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------------------- | +| 1 | `values` | 是 | 数值数组 | 可包含 `nan` 的数值序列 | + +### `nanVariance(values)` + +用途：忽略 `nan` 计算数值序列样本方差。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------------------- | +| 1 | `values` | 是 | 数值数组 | 可包含 `nan` 的数值序列 | + +### `nanPopnStd(values)` + +用途：忽略 `nan` 计算数值序列总体标准差。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------------------- | +| 1 | `values` | 是 | 数值数组 | 可包含 `nan` 的数值序列 | + +### `nanRankArr(values)` + +用途：忽略 `nan` 计算数值序列的秩数组。 + +参数个数：1 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 可包含 `nan` 的数值序列；`nan` 位置在结果中保持为 `nan` | + +### `nanPercentRankArr(values)` + +用途：忽略 `nan` 计算数值序列的百分位秩数组。 + +参数个数：1 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 可包含 `nan` 的数值序列；`nan` 位置在结果中保持为 `nan` | diff --git a/docs/tsl/reference/catalog/math/time_series.md b/docs/tsl/reference/catalog/math/time_series.md new file mode 100644 index 00000000..eb44a2d4 --- /dev/null +++ b/docs/tsl/reference/catalog/math/time_series.md @@ -0,0 +1,335 @@ +# 数学函数 - 时间序列分析 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录时间序列差分、自相关、偏自相关、随机性检验、AR/MA/ARMA、ARCH/GARCH、单位根、协整、ECM 和 Granger 因果检验函数。 + +## 服务器时间序列函数 + +### `time_Diff(values, order)` + +用途：计算序列、数组或矩阵的指定阶差分。 + +参数个数：2 +返回值：数值数组/数值矩阵 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | ----------------- | -------------- | +| 1 | `values` | 是 | 数值数组/数值矩阵 | 原始序列或矩阵 | +| 2 | `order` | 是 | 整数 | 差分阶数 | + +### `time_AutoCov(values, lag)` + +用途：计算时间序列在指定滞后阶数下的自协方差。 + +参数个数：2 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `lag` | 是 | 整数 | 滞后阶数 | + +### `time_ACF(values)` + +用途：计算时间序列自相关系数。 + +参数个数：1 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | + +### `time_PACF(values)` + +用途：计算时间序列偏自相关系数。 + +参数个数：1 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | + +### `time_RandomTest(values, lag_count, alpha)` + +用途：执行时间序列纯随机性检验。 + +参数个数：3 +返回值：数组表；包含 `Qm-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `lag_count` | 是 | 整数 | 检验滞后阶数 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | + +### `ar(values, order, method)` + +用途：拟合 AR 模型。 + +参数个数：3 +返回值：数组表；包含 `AR`、`T-test`、`e` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | --------------------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `order` | 是 | 整数 | AR 阶数 | +| 3 | `method` | 是 | 字符串 | 拟合方法；常用 `"ls"` | + +### `arma(values, ar_order, ma_order)` + +用途：拟合 ARMA 模型。 + +参数个数：3 +返回值：数组表；数据不满足建模条件时可能返回诊断文本 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `ar_order` | 是 | 整数 | AR 阶数 | +| 3 | `ma_order` | 是 | 整数 | MA 阶数 | + +### `time_ARp(values, order, mode)` + +用途：估计 AR 模型参数。 + +参数个数：3 +返回值：数组表；包含 `AR-Coefficient`、`Variance` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------ | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `order` | 是 | 整数 | AR 阶数 | +| 3 | `mode` | 是 | 整数 | 估计模式参数 | + +### `time_MAq(values, order, mode)` + +用途：估计 MA 模型参数。 + +参数个数：3 +返回值：数组表；包含 `MA-Coefficient`、`Variance` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ------------ | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `order` | 是 | 整数 | MA 阶数 | +| 3 | `mode` | 是 | 整数 | 估计模式参数 | + +### `time_ARMA(values, ar_order, ma_order, mode)` + +用途：估计 ARMA 模型参数。 + +参数个数：4 +返回值：数组表；包含 `Constant`、`AR-Coefficient`、`MA-Coefficient`、`Variance` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------ | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `ar_order` | 是 | 整数 | AR 阶数 | +| 3 | `ma_order` | 是 | 整数 | MA 阶数 | +| 4 | `mode` | 是 | 整数 | 估计模式参数 | + +### `time_GreenFun(ar_coefficients, ma_coefficients)` + +用途：根据 AR、MA 系数计算 Green 函数序列。 + +参数个数：2 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------------- | ---- | -------- | ----------- | +| 1 | `ar_coefficients` | 是 | 数值数组 | AR 系数数组 | +| 2 | `ma_coefficients` | 是 | 数值数组 | MA 系数数组 | + +### `time_InvFun(left_values, right_values)` + +用途：根据两个输入序列计算逆函数序列。 + +参数个数：2 +返回值：数值数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | -------- | +| 1 | `left_values` | 是 | 数值数组 | 左侧序列 | +| 2 | `right_values` | 是 | 数值数组 | 右侧序列 | + +### `time_ChoseP(values, model_name, criterion)` + +用途：按准则选择 AR、MA 或 ARMA 模型阶数。 + +参数个数：3 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `model_name` | 是 | 字符串 | 模型名；可用 `"AR"`、`"MA"`、`"ARMA"` | +| 3 | `criterion` | 是 | 字符串 | 信息准则；常用 `"AIC"`、`"SBIC"` | + +### `times_Granger(y_values, x_values, lag_order, alpha)` + +用途：检验 `x_values` 是否为 `y_values` 的 Granger 原因。 + +参数个数：4 +返回值：数组表；包含 `F-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------ | +| 1 | `y_values` | 是 | 数值数组 | 被解释序列 | +| 2 | `x_values` | 是 | 数值数组 | 候选原因序列 | +| 3 | `lag_order` | 是 | 整数 | 滞后阶数 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | + +### `time_DanielTest(values, alpha)` + +用途：执行 Daniel 平稳性检验。 + +参数个数：2 +返回值：数组表；包含 `Q-Value`、`T-Stat`、`P-Value`、`Hypothesis` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `alpha` | 是 | 数值 | 显著性水平 | + +### `times_ADFTest(values, diff_order, model_style, criterion, lag_order, alpha)` + +用途：执行 ADF 单位根检验。 + +参数个数：6 +返回值：数组表；包含 `ADF-Stat` 和显著性水平临界值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | -------------------------------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `diff_order` | 是 | 整数 | 差分阶数 | +| 3 | `model_style` | 是 | 整数 | 检验模型类型 | +| 4 | `criterion` | 是 | 字符串 | 信息准则；常用 `"AIC"`、`"SBIC"` | +| 5 | `lag_order` | 是 | 整数 | 滞后阶数 | +| 6 | `alpha` | 是 | 数值 | 显著性水平 | + +### `times_Cointergration_test(y_values, x_values, diff_order, alpha, lag_order, criterion)` + +用途：执行两个序列的协整检验。 + +参数个数：6 +返回值：数组表；包含 `Diff_y`、`Diff_x`、`E_Stat`，并可提供 ECM 所需残差项 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------------- | +| 1 | `y_values` | 是 | 数值数组 | 第一条时间序列 | +| 2 | `x_values` | 是 | 数值数组 | 第二条时间序列 | +| 3 | `diff_order` | 是 | 整数 | 差分阶数 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | +| 5 | `lag_order` | 是 | 整数 | 滞后阶数 | +| 6 | `criterion` | 是 | 字符串 | 信息准则；常用 `"AIC"`、`"SBIC"` | + +### `times_Cointergration(y_values, x_values, alpha)` + +用途：判断两个序列是否存在协整关系。 + +参数个数：3 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------- | +| 1 | `y_values` | 是 | 数值数组 | 第一条时间序列 | +| 2 | `x_values` | 是 | 数值数组 | 第二条时间序列 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | + +### `times_ECM(y_values, x_values, residuals, alpha, p_order, q_order)` + +用途：建立误差修正模型。 + +参数个数：6 +返回值：数组表；包含 `Coefficient`、`ECM`、`regression` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------------- | +| 1 | `y_values` | 是 | 数值数组 | 第一条时间序列 | +| 2 | `x_values` | 是 | 数值数组 | 第二条时间序列 | +| 3 | `residuals` | 是 | 数值数组 | 协整检验残差项 | +| 4 | `alpha` | 是 | 数值 | 显著性水平 | +| 5 | `p_order` | 是 | 整数 | `y_values` 滞后阶数 | +| 6 | `q_order` | 是 | 整数 | `x_values` 滞后阶数 | + +### `time_ARCHTest(values, lag_order, alpha)` + +用途：执行 ARCH 效应检验。 + +参数个数：3 +返回值：数组表；包含 `F` 和 `TR2` 检验结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 残差或收益率序列 | +| 2 | `lag_order` | 是 | 整数 | 滞后阶数 | +| 3 | `alpha` | 是 | 数值 | 显著性水平 | + +### `time_ARCH(values, q_order, forecast_count)` + +用途：建立 ARCH 模型并输出均值、方差和预测结果。 + +参数个数：3 +返回值：数组表；包含 `Mean-Coefficient`、`Variance-Coefficient`、`Log LikeHood`、`MeanForecast`、`SigmaForecast` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ---------------- | +| 1 | `values` | 是 | 数值数组 | 残差或收益率序列 | +| 2 | `q_order` | 是 | 整数 | ARCH 阶数 | +| 3 | `forecast_count` | 是 | 整数 | 预测步数 | + +### `time_GARCH(values, model_name)` + +用途：建立 GARCH 类模型并输出均值、方差和预测结果。 + +参数个数：2 +返回值：数组表；包含 `Model Type`、`Mean-Coefficient`、`Variance-Coefficient`、`Log LikeHood`、`MeanForecast`、`SigmaForecast` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ---------------------- | +| 1 | `values` | 是 | 数值数组 | 残差或收益率序列 | +| 2 | `model_name` | 是 | 字符串 | 模型名；常用 `"GARCH"` | + +### `garchFit(model_spec, values)` + +用途：按模型规格拟合 GARCH 类波动率模型。 + +参数个数：2 +返回值：数组表；包含 `C`、`K`、`GARCH`、`ARCH`、`LLF`、`Errors`、`e`、`h` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ----------------------------------------------------------------------------------------------------------------- | +| 1 | `model_spec` | 是 | 数组表 | 模型规格；常用键包括 `R`、`M`、`AR`、`MA`、`Regress`、`VarianceModel`、`C`、`P`、`Q`、`GARCH`、`ARCH`、`Leverage` | +| 2 | `values` | 是 | 数值数组 | 待拟合的收益率、残差或平稳时间序列 | + +### `time_Analyse(values, model_name, ar_order, ma_order, forecast_count)` + +用途：按 AR、MA 或 ARMA 模型分析序列并输出预测结果。 + +参数个数：5 +返回值：数组表；包含 `Forecast`、`Volatility` 以及模型系数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ------------------------------------- | +| 1 | `values` | 是 | 数值数组 | 时间序列 | +| 2 | `model_name` | 是 | 字符串 | 模型名；可用 `"AR"`、`"MA"`、`"ARMA"` | +| 3 | `ar_order` | 是 | 整数 | AR 阶数 | +| 4 | `ma_order` | 是 | 整数 | MA 阶数 | +| 5 | `forecast_count` | 是 | 整数 | 预测步数 | + +### `times_GrangerCausality(series_matrix, lag_order)` + +用途：对矩阵中的多个序列执行两两 Granger 因果检验。 + +参数个数：2 +返回值：数组表；每行包含 `result`、`cause`、`F-Stat`、`P-Value` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | --------------------------------------------------- | ------------------ | +| 1 | `series_matrix` | 是 | 数值矩阵 | 多个时间序列组成的矩阵；可由两条序列用 `left_series | right_series` 组成 | +| 2 | `lag_order` | 是 | 整数 | 滞后阶数 | diff --git a/docs/tsl/reference/catalog/math/trig_angle_hyperbolic.md b/docs/tsl/reference/catalog/math/trig_angle_hyperbolic.md new file mode 100644 index 00000000..eafd2270 --- /dev/null +++ b/docs/tsl/reference/catalog/math/trig_angle_hyperbolic.md @@ -0,0 +1,479 @@ +# 数学函数 - 三角、角度与双曲线 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../math.md](../math.md)、[../../index.md](../../index.md) + +本页收录三角函数、角度量转换和双曲线函数。 + +## 三角函数 + +### `sin(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `cos(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sinCos(arg1, sin, cos)` + +用途：三角函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `sin` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `sin` | +| 3 | `cos` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `cos` | + +### `tan(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `cot(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `coTan(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sec(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `csc(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `secant(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `cosecant(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `arcSin(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcCos(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcTan(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcTan2(arg1, arg2)` + +用途：三角函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcCot(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcSec(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcCsc(arg1)` + +用途：三角函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `hypot(arg1, arg2)` + +用途：三角函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +## 角度量转换 + +### `radToDeg(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `radToGrad(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `radToCycle(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `degToRad(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `degToGrad(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `degToCycle(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `gradToRad(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `gradToDeg(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `gradToCycle(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `cycleToRad(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `cycleToDeg(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `cycleToGrad(arg1)` + +用途：角度量转换相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 任意值 | 按源文档示例顺序传入 | + +## 双曲线函数 + +### `sinh(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `cosh(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `tanh(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `cotH(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `secH(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `cscH(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcCosh(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcSinh(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcTanh(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 实数 | 按源文档示例顺序传入 | + +### `arcCotH(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `arcSecH(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | --------- | -------------------- | +| 1 | `arg1` | 是 | 整数/实数 | 按源文档示例顺序传入 | + +### `arcCscH(arg1)` + +用途：双曲线函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/platform.md b/docs/tsl/reference/catalog/platform.md index 57331050..57f68042 100644 --- a/docs/tsl/reference/catalog/platform.md +++ b/docs/tsl/reference/catalog/platform.md @@ -1,54 +1,238 @@ -# 平台函数 +# 天软平台服务函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页描述天软平台服务、用户数据维护、自定义板块、平台执行信息和授权用户共享函数入口。生成函数调用时，只按函数条目中的参数表传参。 ## 模块范围 -- 说明：平台相关功能与系统接口 -- 主题数：4 -- 函数数：19 +- 说明：天软平台服务函数；包含用户数据、板块维护、平台执行信息和授权用户共享函数入口 +- 函数事实数：17 -## 主题目录 +## 自有数据维护函数 -### 自有数据维护函数 +运行边界：这些函数依赖平台用户数据维护能力；目标环境没有用户数据服务时，不要生成这些调用。 -- `LoadTableEx` -- `LoadTable` -- `SaveTable` -- `TestTable` -- `SaveBk` -- `DeleteBk` -- `ListTable` -- `DeleteTable` +### `saveTable(table_name, data, stream_mode)` -### 自有数据维护函数 / UserDB +用途：把用户数据保存为平台用户数据表。 -- `UserDataUpLoad` -- `HexToString` -- `TransFileName` +参数个数：2 或 3 +返回值：整数；源文档示例中成功返回 `-1` -### 平台执行信息 +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | ------------------ | ---------------------------------------------------------------- | +| 1 | `table_name` | 是 | 字符串 | 用户数据名称；可用 `目录\\表名` 保存到指定目录 | +| 2 | `data` | 是 | 任意值，通常为数组 | 要保存的用户数据 | +| 3 | `stream_mode` | 否 | 整数 | 流格式；`0` 表示原始流格式，`1` 表示新流格式；省略时使用默认格式 | -- `tsAppServer` -- `TsAppServerName` -- `SendToClient` -- `TS_ModuleInfo` +### `loadTable(table_name)` -### 用户和函数相关函数 +用途：读取已保存的平台用户数据表。 -- `User` -- `FunctionType` -- `FunctionName` -- `FunctionVer` +参数个数：1 +返回值：已保存的数据值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ----------------------------------------------- | +| 1 | `table_name` | 是 | 字符串 | 用户数据名称；读取目录下数据时使用 `目录\\表名` | + +### `loadTableEx(table_name)` + +用途：读取已保存的平台用户数据表。 + +参数个数：1 +返回值：已保存的数据值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ----------------------------------------------- | +| 1 | `table_name` | 是 | 字符串 | 用户数据名称；读取目录下数据时使用 `目录\\表名` | + +生成规则：默认使用 `loadTable`；只有用户明确要求 `loadTableEx`，或项目已有代码使用 `loadTableEx` 时，才生成 `loadTableEx`。 + +### `testTable(table_name)` + +用途：检查指定平台用户数据表是否存在。 + +参数个数：1 +返回值：整数；存在返回 `1`，不存在返回 `0` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ------------------------------------------------------- | +| 1 | `table_name` | 是 | 字符串 | 要检查的用户数据名称；检查目录下数据时使用 `目录\\表名` | + +### `listTable()` + +用途：取得当前用户可见的平台用户数据表列表。 + +参数个数：0 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `deleteTable(table_name)` + +用途：删除已保存的平台用户数据表。 + +参数个数：1 +返回值：整数；源文档示例中成功返回 `-1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ------------------------------------------------------- | +| 1 | `table_name` | 是 | 字符串 | 要删除的用户数据名称；删除目录下数据时使用 `目录\\表名` | + +## 自定义板块维护函数 + +运行边界：这些函数会写入或删除当前用户的自定义板块。只有用户明确要求维护板块时才生成调用。 + +### `saveBk(sector_name, category_path, stocks)` + +用途：保存自定义板块。 + +参数个数：3 +返回值：整数；成功返回 `-1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | ---------------------------------------------------------- | +| 1 | `sector_name` | 是 | 字符串 | 板块名称 | +| 2 | `category_path` | 是 | 字符串 | 板块分类路径；多级分类用 `\\` 分隔 | +| 3 | `stocks` | 是 | 数组 | 板块成分证券代码数组，例如 `array("SZ000001", "SZ000002")` | + +### `deleteBk(sector_name)` + +用途：删除自定义板块。 + +参数个数：1 +返回值：整数；成功返回 `-1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ---------------- | +| 1 | `sector_name` | 是 | 字符串 | 要删除的板块名称 | + +## 用户数据辅助函数 + +### `hexToString(value)` + +用途：把用户数据文件名中的十六进制名称转换为可读字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ----------------------------------------------------------------------- | +| 1 | `value` | 是 | 字符串 | 用户数据文件名或十六进制名称字符串，例如 `hex_74657374646174613031.stm` | + +## 平台执行信息 + +### `tsAppServer()` + +用途：取得当前平台执行服务器信息。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `tsAppServerName()` + +用途：取得当前平台执行程序信息。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ts_ModuleInfo()` + +用途：平台执行信息相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +## 用户和函数相关函数 + +### `userName()` + +用途：获取当前用户名。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `user(name)` + +用途：取得指定授权用户的共享函数调用入口，并通过链式成员调用执行该用户共享的函数。 + +参数个数：1 +返回值：用户共享函数调用代理；链式调用后的返回值由目标共享函数决定 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------ | +| 1 | `name` | 是 | 字符串 | 已授权用户的用户名 | + +生成规则： + +- 只在用户明确要求调用其它用户共享函数，且已经说明授权关系和目标函数名时生成。 +- 生成形态是 `user("user1").sample(...)`，不要只生成裸 `user("user1")` 当成最终业务结果。 +- 目标用户必须已经授权当前用户调用对应共享函数；目标函数名和参数按该共享函数事实或项目代码确定。 +- 示例形态：`user("jrtzsupport").Show_DSXG_211(begt, endt, 0)`。 + +### `functionType()` + +用途：取得当前运行函数的类型。 + +参数个数：0 +返回值：整数；`1` 表示用户函数，`2` 表示公用函数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +生成规则： + +- 只在需要判断当前函数来源类型时生成。 +- 该函数读取当前运行函数上下文；不要把顶层空返回泛化成函数不存在。 +- 相关函数：`functionName()`、`functionVer()`。 + +### `functionName()` + +用途：取得当前运行函数的名称。 + +参数个数：0 +返回值：字符串；当前运行函数的名称 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +生成规则： + +- 只在需要读取当前运行函数名称时生成。 +- 该函数读取当前运行函数上下文；不要把顶层空返回泛化成函数不存在。 +- 相关函数：`functionType()`、`functionVer()`。 + +### `functionVer(function_type, name)` + +用途：返回指定函数的版本号；函数版本号是函数保存在 SERVER 的版本标识，可用于判断函数是否被修改过。 + +参数个数：2 +返回值：整数；函数版本号 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------- | +| 1 | `function_type` | 是 | 整数 | 函数类型 | +| 2 | `name` | 是 | 字符串 | 函数名称 | + +生成规则： + +- 只在需要比较或记录函数版本号时生成。 +- 可与 `saveTable(...)`、`loadTable(...)` 配合保存和读取版本标识。 +- 相关函数：`functionType()`、`functionName()`。 diff --git a/docs/tsl/reference/catalog/resource.md b/docs/tsl/reference/catalog/resource.md index 8e00eafd..0af715cc 100644 --- a/docs/tsl/reference/catalog/resource.md +++ b/docs/tsl/reference/catalog/resource.md @@ -1,189 +1,33 @@ # 资源访问函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实路由页 +是否可直接用于生成代码：是；进入分类详情页后按函数事实条目生成调用 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页是资源访问函数的轻量入口，不直接承载全部函数事实。生成函数调用时，先按分类目录进入详情页，再只读取命中的函数条目和参数表。 ## 模块范围 - 说明：文件、数据库、网络与外部资源访问 -- 主题数：10 -- 函数数：136 +- 函数事实数：132 -## 主题目录 +## 智能体检索规则 -### 数据库访问函数 +1. 用户只描述能力时，先按“分类目录”选择候选详情页。 +2. 用户给出函数名时，优先在 `resource/` 子目录中搜索三级函数标题。 +3. 只读取命中的函数条目、相邻分类标题和必要参数表；不要把同页其它函数混进当前调用。 +4. 没有命中函数事实条目时，不要发明函数名；回到 [../index.md](../index.md) 或项目实际代码确认。 -- `ExecSQL` +## 分类目录 -### 文件访问函数 - -- `FileList` -- `FileAge` -- `RemoveDir` -- `FileSize` -- `SetFileAttr` -- `FileDelete` -- `Sysdbfwrite` -- `FileTime` -- `SetFileAge` -- `WriteFile` -- `WriteToLog` -- `FileExists` -- `FileCopy` -- `SetFileTime` -- `ReadExcelSheets` -- `CreateDir` -- `FileAttr` -- `ReadFile` -- `Sysdbfread` -- `FileRename` -- `ImportFile` -- `ExportFile` -- `ExportFile2` -- `ImportFile2` -- `FileMode` -- `SetFileMode` -- `FileAttrToStr` -- `FileModeToStr` -- `StrToFileAttr` -- `StrToFileMode` -- `Filemove` - -### 文件访问函数 / 导入导出类型函数 - -- `ftCSV` -- `ftXLS` -- `ftXls2` -- `ftXls3` -- `ftStream` -- `ftString` -- `ftXML` -- `ftdbf` - -### 文件访问函数 / 文件读写类型函数 - -- `rwByte` -- `rwInt` -- `rwReal` -- `rwStr` -- `rwObj` -- `rwRaw` -- `rwBinary` - -### 网络访问以及相关函数 - -- `GetHttp` -- `PostHttp` -- `GetURL` -- `CreateHttpSession` -- `SetHttpMode` -- `SetHttpCallBack` -- `GetHttpContent` -- `GetHttpResponseHeader` -- `SysSendMail` - -### INI文件处理函数 - -- `IniReadBool` -- `IniReadDate` -- `IniReadDateTime` -- `IniReadFloat` -- `IniReadInteger` -- `IniReadTime` -- `IniReadString` -- `IniReadBinaryStream` -- `IniReadSection` -- `IniReadSections` -- `IniReadSectionValues` -- `IniSectionExists` -- `IniValueExists` -- `IniWriteBool` -- `IniWriteDate` -- `IniWriteDateTime` -- `IniWriteFloat` -- `IniWriteInteger` -- `IniWriteTime` -- `IniWriteString` -- `IniWriteBinaryStream` -- `IniDeleteKey` -- `IniEraseSection` - -### INI文件处理函数 / 宽字节处理函数 - -- `IniReadSectionsw` - -### 进程相关函数 - -- `SysPutenv` -- `SysExec` -- `SysParamStr` -- `SysErrorMessage` -- `Sysgetenv` -- `SysWaitForMultipleObjects` -- `SysTerminate` -- `SysCreateMutex` -- `SysCloseHandle` -- `SysReleaseMutex` -- `SysProcessID` -- `SysParamcount` -- `SysThreadID` -- `Sleep` -- `SysWaitForSingleObject` -- `SysGetenvs` -- `SysexecReadpipe` -- `SysexecGetenvs` -- `SysexecDeletepipe` -- `SysexecSetenvs` -- `SysexecNewpipe` -- `SysExecWritepipe` -- `dbglocalrunning` -- `dbglocalcancel` -- `SysThreadSelf` -- `syslinuxkrnlclosemutex` -- `SysSetThreadPriority` -- `SysGetThreadPriority` -- `SysSetProcessPriority` -- `SysGetProcessPriority` -- `SysGetProcessList` -- `SysGetProcessListw` -- `SysGetProcessNamePath` -- `SysGetProcessNamePathw` -- `SysGetProcessCmdLine` -- `SysGetProcessCmdLinew` -- `SysSetThreadName` -- `SysGetThreadName` -- `SysGetThreads` -- `SysPPid` -- `SysGetSubProcesses` -- `SysKill` -- `SysPidOfTid` -- `SysPidOfHandle` -- `SysHandleOfPid` - -### 进程相关函数 / 获取COM进程 - -- `SysGetPidOfCom` -- `SysGetWndOfCaption` -- `SysGetPidtidOfWnd` - -### 本地资源相关函数 - -- `SysExecName` -- `PluginPath` -- `FileInfo` -- `Getlogicdrive` -- `GetDeviceFree` -- `Getdeviceinfo` -- `Createlink` -- `Realpath` +| 分类 | 详情页 | 函数事实数 | +| -------------------- | ------------------------------------------------------------------------ | ---------: | +| 数据库访问函数 | [resource/01_database_access.md](resource/01_database_access.md) | 3 | +| 文件访问函数 | [resource/02_file_access.md](resource/02_file_access.md) | 29 | +| 导入导出类型函数 | [resource/03_import_export_types.md](resource/03_import_export_types.md) | 8 | +| 文件读写类型函数 | [resource/04_file_rw_types.md](resource/04_file_rw_types.md) | 7 | +| 网络访问以及相关函数 | [resource/05_network.md](resource/05_network.md) | 9 | +| INI文件处理函数 | [resource/06_ini.md](resource/06_ini.md) | 23 | +| 宽字节处理函数 | [resource/07_wide_byte.md](resource/07_wide_byte.md) | 1 | +| 进程相关函数 | [resource/08_process.md](resource/08_process.md) | 44 | +| 本地资源相关函数 | [resource/09_local_resource.md](resource/09_local_resource.md) | 8 | diff --git a/docs/tsl/reference/catalog/resource/01_database_access.md b/docs/tsl/reference/catalog/resource/01_database_access.md new file mode 100644 index 00000000..88a7e4e1 --- /dev/null +++ b/docs/tsl/reference/catalog/resource/01_database_access.md @@ -0,0 +1,41 @@ +# 资源访问函数 - 数据库访问函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 数据库访问函数 + +### `execSQL(arg1, arg2, arg3, arg4)` + +用途：数据库访问函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 变量引用 | 按源文档示例顺序传入；源文档示例传入变量 `result` | + +### `sqlErrorMsg()` + +用途：获取最近一次 SQL 错误信息。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sqlCloseConn()` + +用途：关闭 SQL 连接。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/02_file_access.md b/docs/tsl/reference/catalog/resource/02_file_access.md new file mode 100644 index 00000000..7a283c78 --- /dev/null +++ b/docs/tsl/reference/catalog/resource/02_file_access.md @@ -0,0 +1,388 @@ +# 资源访问函数 - 文件访问函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 文件访问函数 + +### `fileList(filename, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `fileAge(filename, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `removeDir(arg1, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `fileSize(filename, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `setFileAttr(filename, arg2, arg3)` + +用途：文件访问函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `fileDelete(filename, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sysdbfwrite(arg1, arg2, t[, arg4])` + +用途：文件访问函数相关函数。 + +参数个数：3 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `t` | 是 | 任意值 | 按源文档示例顺序传入 | +| 4 | `arg4` | 否 | 数组 | 按源文档示例顺序传入 | + +### `fileTime(filename, arg2)` + +用途：日期时间处理函数。 + +参数个数：2 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `setFileAge()` + +用途：文件访问函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `writeFile(filename, arg2, arg3, arg4, arg5, a)` + +用途：文件访问函数相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `a` | 是 | 数组 | 按源文档示例顺序传入 | + +### `fileExists(filename, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `fileCopy(filename, arg2, arg3, arg4, arg5)` + +用途：文件访问函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | + +### `setFileTime(filename, arg2, arg3)` + +用途：日期时间处理函数。 + +参数个数：3 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `readExcelSheets(arg1, arg2, r, arg4)` + +用途：文件访问函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `r` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `r` | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | + +### `createDir(arg1, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `fileAttr(filename, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `readFile(filename, arg2, arg3, arg4, size, data)` + +用途：文件访问函数相关函数。 + +参数个数：6 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ----------------------------------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 整数 | 按源文档示例顺序传入 | +| 5 | `size` | 是 | 任意值 | 按源文档示例顺序传入 | +| 6 | `data` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `data` | + +### `fileRename(filename, arg2, arg3)` + +用途：文件访问函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `importFile(filename, arg2, arg3, data2)` + +用途：文件访问函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ------------------------------------------------ | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `data2` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `data2` | + +### `exportFile(filename, arg2, arg3, data)` + +用途：文件访问函数相关函数。 + +参数个数：4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `data` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `exportFile2(filename, arg2, arg3, data, arg5, arg6, arg7, arg8)` + +用途：文件访问函数相关函数。 + +参数个数：8 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | --------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `data` | 是 | 数组/矩阵 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 是 | 字符串 | 按源文档示例顺序传入 | +| 8 | `arg8` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `importFile2(filename, arg2, arg3, data, arg5, arg6, arg7, arg8, arg9)` + +用途：文件访问函数相关函数。 + +参数个数：9 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | ----------------------------------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `data` | 是 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `data` | +| 5 | `arg5` | 是 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 是 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 是 | 整数 | 按源文档示例顺序传入 | +| 8 | `arg8` | 是 | 字符串 | 按源文档示例顺序传入 | +| 9 | `arg9` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `fileMode(filename, arg2)` + +用途：文件访问函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `setFileMode(filename, arg2, arg3)` + +用途：文件访问函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `fileAttrToStr(attr)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `attr` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `fileModeToStr(attr)` + +用途：将输入值转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `attr` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `strToFileAttr(str1)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `str1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `strToFileMode(str1)` + +用途：将字符串转换为对应类型。 + +参数个数：1 +返回值：转换后的数值或日期 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `str1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `filemove(filename, lj0, arg3, lj1[, arg5])` + +用途：移动文件，支持跨卷移动（相比 FileRename 可跨盘）。 + +参数个数：4 到 5 +返回值：成功返回 1，失败返回 0 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `lj0` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `lj1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 5 | `arg5` | 否 | 整数 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/resource/03_import_export_types.md b/docs/tsl/reference/catalog/resource/03_import_export_types.md new file mode 100644 index 00000000..a17b10e1 --- /dev/null +++ b/docs/tsl/reference/catalog/resource/03_import_export_types.md @@ -0,0 +1,87 @@ +# 资源访问函数 - 导入导出类型函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 导入导出类型函数 + +### `ftCSV()` + +用途：导入导出类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ftXLS()` + +用途：导入导出类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ftXls2()` + +用途：导入导出类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ftXls3()` + +用途：导入导出类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ftStream()` + +用途：文件访问函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ftString()` + +用途：导入导出类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ftXML()` + +用途：导入导出类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `ftdbf()` + +用途：导入导出类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/04_file_rw_types.md b/docs/tsl/reference/catalog/resource/04_file_rw_types.md new file mode 100644 index 00000000..5952063e --- /dev/null +++ b/docs/tsl/reference/catalog/resource/04_file_rw_types.md @@ -0,0 +1,77 @@ +# 资源访问函数 - 文件读写类型函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 文件读写类型函数 + +### `rwByte()` + +用途：文件访问函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rwInt()` + +用途：文件读写类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rwReal()` + +用途：文件读写类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rwStr()` + +用途：文件读写类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rwObj()` + +用途：文件读写类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rwRaw()` + +用途：文件访问函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `rwBinary()` + +用途：文件读写类型函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/05_network.md b/docs/tsl/reference/catalog/resource/05_network.md new file mode 100644 index 00000000..bcc292f7 --- /dev/null +++ b/docs/tsl/reference/catalog/resource/05_network.md @@ -0,0 +1,128 @@ +# 资源访问函数 - 网络访问以及相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 网络访问以及相关函数 + +### `getHttp(arg1, arg2, data, code[, arg5])` + +用途：网络访问以及相关函数相关函数。 + +参数个数：4 到 5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ----------- | ----------------------------------------------- | +| 1 | `arg1` | 是 | 字符串/整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数/字符串 | 按源文档示例顺序传入 | +| 3 | `data` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `data` | +| 4 | `code` | 是 | 字符串 | 按源文档示例顺序传入；源文档示例传入变量 `code` | +| 5 | `arg5` | 否 | 字符串 | 按源文档示例顺序传入；源文档示例传入变量 `code` | + +### `postHttp(arg1, arg2, arg3, data, code[, arg6])` + +用途：网络访问以及相关函数相关函数。 + +参数个数：5 到 6 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ----------- | ----------------------------------------------- | +| 1 | `arg1` | 是 | 字符串/整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数/字符串 | 按源文档示例顺序传入 | +| 4 | `data` | 是 | 整数 | 按源文档示例顺序传入；源文档示例传入变量 `data` | +| 5 | `code` | 是 | 字符串 | 按源文档示例顺序传入；源文档示例传入变量 `code` | +| 6 | `arg6` | 否 | 字符串 | 按源文档示例顺序传入；源文档示例传入变量 `code` | + +### `getURL(url, arg2)` + +用途：网络访问以及相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `url` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `createHttpSession()` + +用途：网络访问以及相关函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `setHttpMode(sid, arg2)` + +用途：网络访问以及相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `sid` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `setHttpCallBack(sid, arg2[, arg3])` + +用途：网络访问以及相关函数相关函数。 + +参数个数：2 到 3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `sid` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | +| 3 | `arg3` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `getHttpContent(sid)` + +用途：网络访问以及相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `sid` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `getHttpResponseHeader()` + +用途：网络访问以及相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysSendMail(arg1, arg2, arg3, arg4, arg5, msg[, arg7][, arg8][, arg9][, arg10][, arg11][, arg12])` + +用途：通过 SMTP 服务器发送邮件。 + +参数个数：6 到 12 +返回值：发送成功返回 true，失败返回 false；可通过 Msg 获取错误信息 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 见下方定义与参数说明 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入 | +| 5 | `arg5` | 是 | 字符串 | 按源文档示例顺序传入 | +| 6 | `msg` | 是 | 字符串 | 按源文档示例顺序传入 | +| 7 | `arg7` | 否 | 字符串 | 按源文档示例顺序传入 | +| 8 | `arg8` | 否 | 字符串 | 按源文档示例顺序传入 | +| 9 | `arg9` | 否 | 整数 | 按源文档示例顺序传入 | +| 10 | `arg10` | 否 | 字符串 | 按源文档示例顺序传入 | +| 11 | `arg11` | 否 | 字符串 | 按源文档示例顺序传入 | +| 12 | `arg12` | 否 | 任意值 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/resource/06_ini.md b/docs/tsl/reference/catalog/resource/06_ini.md new file mode 100644 index 00000000..767efc20 --- /dev/null +++ b/docs/tsl/reference/catalog/resource/06_ini.md @@ -0,0 +1,247 @@ +# 资源访问函数 - INI文件处理函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## INI文件处理函数 + +### `iniReadBool()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadDate()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadDateTime()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadFloat()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadInteger()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadTime()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadString()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadBinaryStream(value, ini_file_path, arg3, arg4[, arg5])` + +用途：INI文件处理函数相关函数。 + +参数个数：4 到 5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `ini_file_path` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入 | +| 5 | `arg5` | 否 | 整数 | 按源文档示例顺序传入 | + +### `iniReadSection()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadSections()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniReadSectionValues()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniSectionExists()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniValueExists()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteBool()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteDate()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteDateTime()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteFloat()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteInteger()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteTime()` + +用途：日期时间处理函数。 + +参数个数：0 +返回值：日期或时间值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteString()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniWriteBinaryStream(value, ini_file_path, arg3, arg4, data)` + +用途：INI文件处理函数相关函数。 + +参数个数：5 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `ini_file_path` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 字符串 | 按源文档示例顺序传入 | +| 4 | `arg4` | 是 | 字符串 | 按源文档示例顺序传入 | +| 5 | `data` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `iniDeleteKey()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `iniEraseSection()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/07_wide_byte.md b/docs/tsl/reference/catalog/resource/07_wide_byte.md new file mode 100644 index 00000000..8a609cf7 --- /dev/null +++ b/docs/tsl/reference/catalog/resource/07_wide_byte.md @@ -0,0 +1,17 @@ +# 资源访问函数 - 宽字节处理函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 宽字节处理函数 + +### `iniReadSectionsw()` + +用途：INI文件处理函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/08_process.md b/docs/tsl/reference/catalog/resource/08_process.md new file mode 100644 index 00000000..60b27be6 --- /dev/null +++ b/docs/tsl/reference/catalog/resource/08_process.md @@ -0,0 +1,485 @@ +# 资源访问函数 - 进程相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 进程相关函数 + +### `sysPutenv(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sysParamStr(i)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `i` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sysErrorMessage(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysgetenv(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sysWaitForMultipleObjects(arg1, arg2, arg3)` + +用途：进程相关函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sysTerminate()` + +用途：进程相关函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysCreateMutex(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sysReleaseMutex(ret)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `ret` | 是 | 变量引用 | 按源文档示例顺序传入 | + +### `sysProcessID()` + +用途：获取当前进程 ID（PID）。 + +参数个数：0 +返回值：进程 ID（整数） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysParamcount()` + +用途：获取命令行传入参数的个数。 + +参数个数：0 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysThreadID()` + +用途：获取当前线程 ID。 + +参数个数：0 +返回值：线程 ID（整数） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sleep(arg1)` + +用途：让当前线程休眠指定毫秒数。 + +参数个数：1 +返回值：无 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysWaitForSingleObject(hand1, arg2)` + +用途：进程相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `hand1` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sysGetenvs()` + +用途：进程相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysexecGetenvs()` + +用途：进程相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysexecDeletepipe(hand)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `hand` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sysexecSetenvs(arg1, arg2)` + +用途：进程相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 数组 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysexecNewpipe(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `dbglocalrunning()` + +用途：返回本地解释器正在运行的任务列表与调用栈信息。 + +参数个数：0 +返回值：任务信息数组（包含 StartInfo/CallStack） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `dbglocalcancel(task_id)` + +用途：根据任务 ID 终止本地运行中的任务。 + +参数个数：1 +返回值：成功返回 1，失败返回 0 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------- | ---- | -------- | -------------------- | +| 1 | `task_id` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sysThreadSelf()` + +用途：获取当前线程 ID（Linux 下为 pthread_t）。 + +参数个数：0 +返回值：线程 ID（整数） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `syslinuxkrnlclosemutex(arg1, arg2)` + +用途：关闭并清理指定互斥量（Linux），用于移除互斥相关的系统信号量与临时文件。 + +参数个数：2 +返回值：成功返回 1，失败返回 0 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysSetThreadPriority(arg1[, arg2])` + +用途：进程相关函数相关函数。 + +参数个数：1 到 2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `tid` | + +### `sysGetThreadPriority(pri[, arg2])` + +用途：进程相关函数相关函数。 + +参数个数：1 到 2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `pri` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 任意值 | 按源文档示例顺序传入 | + +### `sysSetProcessPriority(arg1[, arg2])` + +用途：进程相关函数相关函数。 + +参数个数：1 到 2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | + +### `sysGetProcessPriority(pri[, arg2])` + +用途：进程相关函数相关函数。 + +参数个数：1 到 2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `pri` | 是 | 任意值 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 整数 | 按源文档示例顺序传入 | + +### `sysGetProcessList()` + +用途：进程相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysGetProcessListw()` + +用途：进程相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysGetProcessNamePath(path)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sysGetProcessNamePathw(path)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `sysGetProcessCmdLine(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysGetProcessCmdLinew(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysSetThreadName(arg1[, arg2])` + +用途：设置线程名称（Linux 仅支持当前线程）。 + +参数个数：1 到 2 +返回值：成功返回 0，失败返回非 0 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------------------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 否 | 任意值 | 按源文档示例顺序传入；源文档示例传入变量 `tid` | + +### `sysGetThreadName([arg1])` + +用途：获取线程名称。 + +参数个数：0 到 1 +返回值：线程名称字符串；失败返回 nil 或空串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 否 | 任意值 | 按源文档示例顺序传入 | + +### `sysGetThreads()` + +用途：进程相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysPPid()` + +用途：进程相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysGetSubProcesses()` + +用途：进行字符串提取或替换处理。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysKill(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysPidOfTid(tid)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `tid` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sysPidOfHandle(handle)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------------------- | +| 1 | `handle` | 是 | 任意值 | 按源文档示例顺序传入 | + +### `sysHandleOfPid(arg1)` + +用途：进程相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 整数 | 按源文档示例顺序传入 | + +### `sysGetLastError()` + +用途：获取最近一次系统错误码。 + +参数个数：0 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysCmdLine()` + +用途：获取当前进程命令行。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysClientInfo()` + +用途：获取客户端信息。 + +参数个数：0 +返回值：客户端信息或 nil + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | diff --git a/docs/tsl/reference/catalog/resource/09_local_resource.md b/docs/tsl/reference/catalog/resource/09_local_resource.md new file mode 100644 index 00000000..9be9170a --- /dev/null +++ b/docs/tsl/reference/catalog/resource/09_local_resource.md @@ -0,0 +1,97 @@ +# 资源访问函数 - 本地资源相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../resource.md](../resource.md)、[../../index.md](../../index.md) + +## 本地资源相关函数 + +### `sysExecName()` + +用途：获取当前执行程序的完整路径。 + +参数个数：0 +返回值：程序路径字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `pluginPath()` + +用途：获取插件目录路径。 + +参数个数：0 +返回值：插件路径字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `fileInfo(filename, path)` + +用途：本地资源相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------- | ---- | -------- | -------------------- | +| 1 | `filename` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `getlogicdrive()` + +用途：本地资源相关函数相关函数。 + +参数个数：0 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `getDeviceFree(arg1, arg2)` + +用途：本地资源相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `getdeviceinfo(arg1, arg2)` + +用途：本地资源相关函数相关函数。 + +参数个数：2 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `arg2` | 是 | 字符串 | 按源文档示例顺序传入 | + +### `createlink(arg1, path, arg3)` + +用途：本地资源相关函数相关函数。 + +参数个数：3 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `arg1` | 是 | 字符串 | 按源文档示例顺序传入 | +| 2 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | +| 3 | `arg3` | 是 | 整数 | 按源文档示例顺序传入 | + +### `realpath(path)` + +用途：本地资源相关函数相关函数。 + +参数个数：1 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------------------- | +| 1 | `path` | 是 | 字符串 | 按源文档示例顺序传入 | diff --git a/docs/tsl/reference/catalog/system.md b/docs/tsl/reference/catalog/system.md index cba84210..3d59a7dd 100644 --- a/docs/tsl/reference/catalog/system.md +++ b/docs/tsl/reference/catalog/system.md @@ -1,107 +1,34 @@ # 系统相关函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实路由页 +是否可直接用于生成代码：是；进入分类详情页后按函数事实条目生成调用 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页是系统相关函数的轻量入口，不直接承载全部函数事实。生成函数调用时，先按分类目录进入详情页，再只读取命中的函数条目和参数表。 ## 模块范围 - 说明：数据类型、表达式调用、性能与运行时能力 -- 主题数：9 -- 函数数：57 +- 函数事实数：60 -## 主题目录 +## 智能体检索规则 -### 数据类型函数 +1. 用户只描述能力时，先按“分类目录”选择候选详情页。 +2. 用户给出函数名时，优先在 `system/` 子目录中搜索三级函数标题。 +3. 只读取命中的函数条目、相邻分类标题和必要参数表；不要把同页其它函数混进当前调用。 +4. 没有命中函数事实条目时，不要发明函数名；回到 [../index.md](../index.md) 或项目实际代码确认。 -- `DataType` -- `ifInt` -- `ifInt64` -- `ifReal` -- `ifNumber` -- `ifString` -- `ifArray` -- `ifNil` -- `ifExp` -- `ifGraph` -- `ifGraphGroup` -- `ifBinary` -- `ifMatrix` -- `ifObj` -- `GetOleObject` -- `CreateComObject` -- `CreateMatrix` -- `MatrixToArray` -- `GetMatrixFields` -- `CreateBinary` -- `ConvertDataToBuf` -- `ConvertBufToData` +## 分类目录 -### 数据类型函数 / None类型 - -- `ifNone` -- `GetNone` - -### 数据类型转换函数 - -- `Integer` -- `Int64` -- `Real` -- `String` -- `WideString` -- `Binary` -- `SetPrecision` -- `ToSTM` -- `ToSTN` -- `ToXML` -- `XML` -- `ExportCsv` -- `ImportCsv` - -### 复制函数 - -- `dupValue` - -### 随机函数 - -- `randomize` -- `random` -- `RandomFrom` - -### 条件选择函数 - -- `IfThen` -- `IfThen3` - -### 表达式相关函数 - -- `Eval` -- `Call` -- `CallInArray` -- `Invoke` -- `Invokeinarray` -- `SafeEval` -- `DoubleVariableExecute` -- `MultipleExecute` -- `SingleVariableExecute` -- `SafeSetSysParam` - -### 性能优化相关函数 - -- `SetProfiler` -- `GetProfilerInfo` - -### 函数库路径 - -- `sysgettsllibpath` -- `syssettsllibpath` +| 分类 | 详情页 | 函数事实数 | +| ---------------- | ------------------------------------------------------------ | ---------: | +| 数据类型函数 | [system/01_data_type.md](system/01_data_type.md) | 27 | +| 数据类型转换函数 | [system/02_type_conversion.md](system/02_type_conversion.md) | 13 | +| 复制函数 | [system/03_copy.md](system/03_copy.md) | 1 | +| 全局缓存函数 | [system/04_global_cache.md](system/04_global_cache.md) | 4 | +| 随机函数 | [system/05_random.md](system/05_random.md) | 3 | +| 条件选择函数 | [system/06_conditional.md](system/06_conditional.md) | 1 | +| 表达式相关函数 | [system/07_expression.md](system/07_expression.md) | 5 | +| 性能优化相关函数 | [system/08_profiler.md](system/08_profiler.md) | 2 | +| 函数库路径 | [system/09_tsl_lib_path.md](system/09_tsl_lib_path.md) | 3 | +| 错误与断言函数 | [system/10_error_assertion.md](system/10_error_assertion.md) | 1 | diff --git a/docs/tsl/reference/catalog/system/01_data_type.md b/docs/tsl/reference/catalog/system/01_data_type.md new file mode 100644 index 00000000..62e5f48d --- /dev/null +++ b/docs/tsl/reference/catalog/system/01_data_type.md @@ -0,0 +1,335 @@ +# 系统相关函数 - 数据类型函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 数据类型函数 + +### `dataType(value, mode)` + +用途：返回数据类型编号，支持数组遍历模式。 + +参数个数：2 +返回值：类型编号或类型数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifInt(value, mode)` + +用途：判断是否为 32 位整数类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | --------------------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 整数/实数/字符串/数组 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifInt64(value, mode)` + +用途：判断是否为 64 位整数类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifReal(value, mode)` + +用途：判断是否为 实数类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 数组 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifNumber(value, mode)` + +用途：判断是否为 数字（整数或实数）类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 数组 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifString(value, mode)` + +用途：判断是否为 字符串类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 数组 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifArray(value, mode)` + +用途：判断是否为 数组类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifNil(value, mode)` + +用途：判断是否为 Nil类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | nil | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifNone(value[, tag])` + +用途：判断对象 `operator[1]` 多级下标写入时传入的 None 标记值。 + +参数个数：1 到 2 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------ | +| 1 | `value` | 是 | None | `operator[1]` 中间层或回滚层传入的 None 值 | +| 2 | `tag` | 否 | 整数 | None 标记值；中间层第一层为 `0`，回滚标记为 `-1` | + +### `getNone(value)` + +用途：读取 None 值携带的整数标记。 + +参数个数：1 +返回值：整数标记 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------ | +| 1 | `value` | 是 | None | `operator[1]` 中间层或回滚层传入的 None 值 | + +### `ifExp(value, mode)` + +用途：判断是否为 表达式类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifGraph(value)` + +用途：判断是否为 图形类型。 + +参数个数：1 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | + +### `ifGraphGroup(value)` + +用途：判断是否为 图形组类型。 + +参数个数：1 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | + +### `ifBinary(value, mode)` + +用途：判断是否为 二进制/Buffer类型。 + +参数个数：2 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------------------------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 遍历模式（可选；-1 对第一维逐项判断；1 对每个元素判断） | + +### `ifMatrix(value)` + +用途：判断是否为 Matrix类型。 + +参数个数：1 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | + +### `ifFmarray(value)` + +用途：判断是否为 FMArray 类型。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | + +### `ifObj(value)` + +用途：判断是否为对象类型。 + +参数个数：1 +返回值：布尔值或布尔数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | + +### `createMatrix(rows, cols, cols_value, values[, arg5][, arg6][, arg7][, arg8][, arg9][, arg10][, arg11][, arg12][, arg13][, arg14][, arg15])` + +用途：创建 Matrix 类型数据，可指定列索引与初始值。 + +参数个数：4 到 15 +返回值：Matrix 对象 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | -------------------------------- | +| 1 | `rows` | 是 | 整数 | 行数 | +| 2 | `cols` | 是 | 整数 | 列数 | +| 3 | `cols_value` | 是 | 整数 | 列序列（可选） | +| 4 | `values` | 是 | 整数 | 初始化值序列（可选，按行列顺序） | +| 5 | `arg5` | 否 | 整数 | 按源文档示例顺序传入 | +| 6 | `arg6` | 否 | 整数 | 按源文档示例顺序传入 | +| 7 | `arg7` | 否 | 整数 | 按源文档示例顺序传入 | +| 8 | `arg8` | 否 | 整数 | 按源文档示例顺序传入 | +| 9 | `arg9` | 否 | 整数 | 按源文档示例顺序传入 | +| 10 | `arg10` | 否 | 整数 | 按源文档示例顺序传入 | +| 11 | `arg11` | 否 | 整数 | 按源文档示例顺序传入 | +| 12 | `arg12` | 否 | 整数 | 按源文档示例顺序传入 | +| 13 | `arg13` | 否 | 整数 | 按源文档示例顺序传入 | +| 14 | `arg14` | 否 | 整数 | 按源文档示例顺序传入 | +| 15 | `arg15` | 否 | 整数 | 按源文档示例顺序传入 | + +### `matrixToArray(matrix)` + +用途：将 Matrix 转换为数组。 + +参数个数：1 +返回值：数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------- | +| 1 | `matrix` | 是 | 矩阵 | Matrix 数据 | + +### `arrayToFm(value, sample_value)` + +用途：将数组转换为 FMArray，并按样例值确定单元格类型。 + +参数个数：2 +返回值：FMArray + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------- | ---- | -------- | ----------------------------------------------------------- | +| 1 | `value` | 是 | 数组 | 输入数组 | +| 2 | `sample_value` | 是 | 数值 | 单元格类型样例；如 `0` 生成整型单元格，`0.0` 生成浮点单元格 | + +### `msize(value[, mode])` + +用途：读取矩阵样数据或 FMArray 的尺寸信息。 + +参数个数：1 到 2 +返回值：尺寸数组或索引数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | --------------------------------- | ----------------------------------------- | +| 1 | `value` | 是 | 矩阵样数据/FMArray/支持重载的对象 | 输入数据 | +| 2 | `mode` | 否 | 整数 | 省略时返回各维长度；传 `1` 时返回索引数组 | + +### `mrows(value[, mode])` + +用途：读取矩阵样数据或 FMArray 的行数或行索引。 + +参数个数：1 到 2 +返回值：行数或行索引数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | --------------------------------- | --------------------------------------- | +| 1 | `value` | 是 | 矩阵样数据/FMArray/支持重载的对象 | 输入数据 | +| 2 | `mode` | 否 | 整数 | 省略时返回行数；传 `1` 时返回行索引数组 | + +### `mcols(value[, mode])` + +用途：读取矩阵样数据或 FMArray 的列数或列索引。 + +参数个数：1 到 2 +返回值：列数或列索引数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | --------------------------------- | --------------------------------------- | +| 1 | `value` | 是 | 矩阵样数据/FMArray/支持重载的对象 | 输入数据 | +| 2 | `mode` | 否 | 整数 | 省略时返回列数；传 `1` 时返回列索引数组 | + +### `getMatrixFields(matrix)` + +用途：获取 Matrix 的字段（列名）列表。 + +参数个数：1 +返回值：字段名数组 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ----------- | +| 1 | `matrix` | 是 | 矩阵 | Matrix 数据 | + +### `createBinary(size)` + +用途：创建 Binary 缓冲区。 + +参数个数：1 +返回值：Binary 数据 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | -------- | +| 1 | `size` | 是 | 整数 | 字节长度 | + +### `convertDataToBuf(value, type_name)` + +用途：按指定类型将数据编码为内存 Buffer。 + +参数个数：2 +返回值：Binary Buffer + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 实数 | 输入数据 | +| 2 | `type_name` | 是 | 字符串 | 类型名称 | + +### `convertBufToData(buffer, type_name)` + +用途：按指定类型将 Buffer 解码为数据。 + +参数个数：2 +返回值：解析后的数据 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | ------------- | +| 1 | `buffer` | 是 | 任意值 | Binary Buffer | +| 2 | `type_name` | 是 | 字符串 | 类型名称 | diff --git a/docs/tsl/reference/catalog/system/02_type_conversion.md b/docs/tsl/reference/catalog/system/02_type_conversion.md new file mode 100644 index 00000000..aae91972 --- /dev/null +++ b/docs/tsl/reference/catalog/system/02_type_conversion.md @@ -0,0 +1,160 @@ +# 系统相关函数 - 数据类型转换函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 数据类型转换函数 + +### `integer(value)` + +用途：将数值转换为整数。 + +参数个数：1 +返回值：整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 数值 | 输入数值 | + +### `int64(value)` + +用途：将数值转换为 64 位整数。 + +参数个数：1 +返回值：64 位整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 数值 | 输入数值 | + +### `real(value)` + +用途：将数值转换为实数。 + +参数个数：1 +返回值：实数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 数值 | 输入数值 | + +### `string(value)` + +用途：将数据转换为字符串。 + +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 任意值 | 输入数据 | + +### `wideString(value)` + +用途：将数据转换为 Unicode 字符串。 + +参数个数：1 +返回值：Unicode 字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 字符串 | 输入数据 | + +### `binary(value)` + +用途：将数据转换为二进制流。 + +参数个数：1 +返回值：Binary 数据 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 字符串 | 输入数据 | + +### `setPrecision(value, digits)` + +用途：设置数值的小数精度。 + +参数个数：2 +返回值：按精度处理后的数值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | -------- | +| 1 | `value` | 是 | 数值 | 输入数值 | +| 2 | `digits` | 是 | 整数 | 小数位数 | + +### `toSTM(value, mode, precision[, arg4])` + +用途：将数据序列化为 STM 二进制流。 + +参数个数：3 到 4 +返回值：STM 二进制流 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------- | +| 1 | `value` | 是 | 数组 | 输入数据 | +| 2 | `mode` | 是 | 整数 | 序列化模式（可选） | +| 3 | `precision` | 是 | 整数 | 小数位数（可选） | +| 4 | `arg4` | 否 | 整数 | 按源文档示例顺序传入 | + +### `toSTN(value, digits)` + +用途：将数值格式化为 STN 字符串。 + +参数个数：2 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------- | ---- | -------- | ---------------- | +| 1 | `value` | 是 | 数值 | 输入数值 | +| 2 | `digits` | 是 | 整数 | 小数位数（可选） | + +### `exportCsv(data, out_text, include_index, include_header)` + +用途：将数组导出为 CSV 格式字符串。 + +参数个数：4 +返回值：是否成功（1/0） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ---------------- | ---- | -------- | ------------------------- | +| 1 | `data` | 是 | 数组 | 数组数据 | +| 2 | `out_text` | 是 | 字符串 | 输出字符串（引用返回） | +| 3 | `include_index` | 是 | 整数 | 是否包含下标（可选，1/0） | +| 4 | `include_header` | 是 | 整数 | 是否包含表头（可选，1/0） | + +### `importCsv(csv_text, out_data, has_header)` + +用途：将 CSV 字符串解析为数组。 + +参数个数：3 +返回值：是否成功（1/0） + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------ | ---- | -------- | ------------------------- | +| 1 | `csv_text` | 是 | 字符串 | CSV 字符串 | +| 2 | `out_data` | 是 | 数组 | 输出数组（引用返回） | +| 3 | `has_header` | 是 | 整数 | 是否包含表头（可选，1/0） | + +### `stm(value)` + +用途：解析 STM 序列化数据。 + +参数个数：1 +返回值：解析后的数据 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | ----------------- | -------- | +| 1 | `value` | 是 | 二进制数据/字符串 | STM 数据 | + +### `stn(value)` + +用途：解析 STN 数值字符串。 + +参数个数：1 +返回值：数值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ---------- | +| 1 | `value` | 是 | 字符串 | STN 字符串 | diff --git a/docs/tsl/reference/catalog/system/03_copy.md b/docs/tsl/reference/catalog/system/03_copy.md new file mode 100644 index 00000000..687b427c --- /dev/null +++ b/docs/tsl/reference/catalog/system/03_copy.md @@ -0,0 +1,18 @@ +# 系统相关函数 - 复制函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 复制函数 + +### `dupValue(value)` + +用途：复制值，避免被调用函数修改原变量。 + +参数个数：1 +返回值：复制后的值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------ | +| 1 | `value` | 是 | 整数 | 输入值 | diff --git a/docs/tsl/reference/catalog/system/04_global_cache.md b/docs/tsl/reference/catalog/system/04_global_cache.md new file mode 100644 index 00000000..09f60142 --- /dev/null +++ b/docs/tsl/reference/catalog/system/04_global_cache.md @@ -0,0 +1,53 @@ +# 系统相关函数 - 全局缓存函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 全局缓存函数 + +### `setGlobalCache(name, value)` + +用途：写入全局缓存。 + +参数个数：2 +返回值：成功标记；成功时返回 `1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------ | +| 1 | `name` | 是 | 字符串 | 缓存键 | +| 2 | `value` | 是 | 任意值 | 写入缓存的值 | + +### `getGlobalCache(name, out_value)` + +用途：按键读取全局缓存。 + +参数个数：2 +返回值：成功标记；成功时返回 `1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------- | +| 1 | `name` | 是 | 字符串 | 缓存键 | +| 2 | `out_value` | 是 | 变量 | 输出变量，接收缓存值 | + +### `ifCache(value)` + +用途：判断值是否仍是全局缓存引用。 + +参数个数：1 +返回值：布尔值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ---------- | +| 1 | `value` | 是 | 任意值 | 待判断的值 | + +### `checkGlobalCacheExpired(value)` + +用途：判断全局缓存引用是否已经过期。 + +参数个数：1 +返回值：布尔值；未过期返回 `0`，过期返回 `1` + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | ------------------------------------ | +| 1 | `value` | 是 | 缓存引用 | `getGlobalCache(...)` 取出的缓存引用 | diff --git a/docs/tsl/reference/catalog/system/05_random.md b/docs/tsl/reference/catalog/system/05_random.md new file mode 100644 index 00000000..4d7b75a1 --- /dev/null +++ b/docs/tsl/reference/catalog/system/05_random.md @@ -0,0 +1,39 @@ +# 系统相关函数 - 随机函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 随机函数 + +### `randomize()` + +用途：随机函数相关函数。 + +参数个数：0 +返回值：处理结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `random([value])` + +用途：生成随机数。 + +参数个数：0 到 1 +返回值：随机实数或随机整数 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------------- | +| 1 | `value` | 否 | 整数 | value 为上限（可选） | + +### `randomFrom(items)` + +用途：从数组中随机取一个元素。 + +参数个数：1 +返回值：随机元素 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------- | +| 1 | `items` | 是 | 数组 | 候选数组 | diff --git a/docs/tsl/reference/catalog/system/06_conditional.md b/docs/tsl/reference/catalog/system/06_conditional.md new file mode 100644 index 00000000..b2fe2727 --- /dev/null +++ b/docs/tsl/reference/catalog/system/06_conditional.md @@ -0,0 +1,20 @@ +# 系统相关函数 - 条件选择函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 条件选择函数 + +### `ifThen(condition, true_value, false_value)` + +用途：条件成立返回 true_value，否则返回 false_value。 + +参数个数：3 +返回值：true_value 或 false_value + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------------- | ---- | -------- | ------------------ | +| 1 | `condition` | 是 | 整数 | 判断条件 | +| 2 | `true_value` | 是 | 整数 | 条件成立时返回值 | +| 3 | `false_value` | 是 | 整数 | 条件不成立时返回值 | diff --git a/docs/tsl/reference/catalog/system/07_expression.md b/docs/tsl/reference/catalog/system/07_expression.md new file mode 100644 index 00000000..3595eca6 --- /dev/null +++ b/docs/tsl/reference/catalog/system/07_expression.md @@ -0,0 +1,72 @@ +# 系统相关函数 - 表达式相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 表达式相关函数 + +### `eval(expr)` + +用途：计算表达式或表达式字符串并返回结果。 + +参数个数：1 +返回值：表达式计算结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ------------------------------ | +| 1 | `expr` | 是 | 字符串 | 表达式（@）或表达式字符串（&） | + +### `call(func, args)` + +用途：按函数名字符串或函数指针调用函数。 + +参数个数：2 +返回值：函数返回值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------- | +| 1 | `func` | 是 | 字符串 | 函数名字符串或函数指针 | +| 2 | `args` | 是 | 整数 | 调用参数列表 | + +### `callInArray(func, args)` + +用途：以参数数组调用指定函数（含函数名或函数变量）。 + +参数个数：2 +返回值：函数调用结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------- | +| 1 | `func` | 是 | 字符串 | 函数名字符串或函数指针 | +| 2 | `args` | 是 | 数组 | 参数数组 | + +### `invoke(obj, name, mode, args[, arg5][, arg6])` + +用途：调用对象成员方法或设置成员属性。 + +参数个数：4 到 6 +返回值：调用结果或设置结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | ----------- | ---------------------- | +| 1 | `obj` | 是 | 任意值 | 目标对象 | +| 2 | `name` | 是 | 字符串 | 成员名 | +| 3 | `mode` | 是 | 整数 | 0 调用方法；1 设置成员 | +| 4 | `args` | 是 | 字符串/整数 | 方法参数或设置值 | +| 5 | `arg5` | 否 | 字符串 | 按源文档示例顺序传入 | +| 6 | `arg6` | 否 | 字符串 | 按源文档示例顺序传入 | + +### `invokeinarray(obj, name, mode, args)` + +用途：以参数数组调用对象成员方法或设置成员属性。 + +参数个数：4 +返回值：调用结果或设置结果 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------------- | +| 1 | `obj` | 是 | 任意值 | 目标对象 | +| 2 | `name` | 是 | 字符串 | 成员名 | +| 3 | `mode` | 是 | 整数 | 0 调用方法；1 设置成员 | +| 4 | `args` | 是 | 数组 | 参数数组 | diff --git a/docs/tsl/reference/catalog/system/08_profiler.md b/docs/tsl/reference/catalog/system/08_profiler.md new file mode 100644 index 00000000..91869ca3 --- /dev/null +++ b/docs/tsl/reference/catalog/system/08_profiler.md @@ -0,0 +1,29 @@ +# 系统相关函数 - 性能优化相关函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 性能优化相关函数 + +### `setProfiler(flags)` + +用途：设置性能分析开关与统计范围。 + +参数个数：1 +返回值：无 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------- | ---- | -------- | -------------- | +| 1 | `flags` | 是 | 整数 | 统计选项位掩码 | + +### `getProfilerInfo(mode)` + +用途：获取性能分析信息。 + +参数个数：1 +返回值：性能分析信息 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------------- | +| 1 | `mode` | 是 | 整数 | 可选；传 1 仅返回信息不弹窗 | diff --git a/docs/tsl/reference/catalog/system/09_tsl_lib_path.md b/docs/tsl/reference/catalog/system/09_tsl_lib_path.md new file mode 100644 index 00000000..dd5d311f --- /dev/null +++ b/docs/tsl/reference/catalog/system/09_tsl_lib_path.md @@ -0,0 +1,38 @@ +# 系统相关函数 - 函数库路径 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 函数库路径 + +### `tslfilename()` + +用途：获取正在执行的 `.tsl` 主脚本完整路径。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `sysgettsllibpath()` + +用途：获取当前函数库查找路径。 + +参数个数：0 +返回值：当前查找路径字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +### `syssettsllibpath(path_list)` + +用途：设置函数库查找路径（支持分号分隔的多个目录）。 + +参数个数：1 +返回值：设置前的查找路径字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ----------- | ---- | -------- | -------------------------- | +| 1 | `path_list` | 是 | 字符串 | 路径列表字符串（分号分隔） | diff --git a/docs/tsl/reference/catalog/system/10_error_assertion.md b/docs/tsl/reference/catalog/system/10_error_assertion.md new file mode 100644 index 00000000..feb11e09 --- /dev/null +++ b/docs/tsl/reference/catalog/system/10_error_assertion.md @@ -0,0 +1,27 @@ +# 系统相关函数 - 错误与断言函数 + +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../system.md](../system.md)、[../../index.md](../../index.md) + +## 错误与断言函数 + +### `assert(check, error_message)` + +用途：断言 `check` 是否为真值；为真时返回 `0` 并继续执行，为假时抛出 `error_message` 指定的运行时错误。 + +参数个数：2 +返回值：整数；断言通过时返回 `0`，断言失败时不返回而是抛出错误 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | --------------- | ---- | ------------- | --------------------------------------- | +| 1 | `check` | 是 | 任意值/表达式 | 按 TSL 真值规则判断；真值通过，假值失败 | +| 2 | `error_message` | 是 | 字符串 | 断言失败时抛出的错误信息 | + +生成规则： + +- 只在需要主动校验前置条件、输入约束或不可继续执行的状态时生成。 +- `check` 可以是逻辑判断表达式，例如 `1 = 1`、`3 > 2`、`(3 > 2) and (2 < 4)`。 +- 真值示例：`1`、`true`、`-1`、`0.5`、`"abc"`、`array(1)`；通过时返回 `0`。 +- 假值示例：`0`、`false`、`nil`、`""`、`array()`；失败时直接抛出 `error_message`。 +- 断言失败不会把错误信息作为普通返回值交给调用方继续执行。 diff --git a/docs/tsl/reference/catalog/third_party.md b/docs/tsl/reference/catalog/third_party.md index ece7b2c9..81f08631 100644 --- a/docs/tsl/reference/catalog/third_party.md +++ b/docs/tsl/reference/catalog/third_party.md @@ -1,40 +1,99 @@ # 第三方交互函数 -这一页只负责函数定位：先按主题找到模块，再在页内搜索函数名。 +文档类型：函数事实页 +是否可直接用于生成代码：是；本页函数条目均包含参数表 +遇到不确定时：回到 [../index.md](../index.md)、[../../syntax/index.md](../../syntax/index.md) -## 候选函数索引说明 - -- 本页是候选函数索引，只说明函数名被归入当前模块。 -- 候选名没有进入 verified 函数页前不能当成可调用事实。 -- 生成代码前必须先查 [../verified/index.md](../verified/index.md)；只从 verified 函数页读取参数类型。 - -## 使用方式 - -- 返回总目录：[catalog/index.md](index.md) -- 需要基础语法时回到 [../../syntax/index.md](../../syntax/index.md) -- 需要金融任务组织方式时回到 [../../finance/index.md](../../finance/index.md) +这一页描述第三方库与外部程序交互能力。生成函数调用时，只按函数条目中的参数表传参。 ## 模块范围 - 说明：第三方库与外部程序交互能力 -- 主题数：3 -- 函数数：8 +- 函数事实数：7 -## 主题目录 +## Python支持函数 -### Python支持函数 +### `pyRun(code)` -- `PyRun` -- `PyCall` -- `PyError` +用途：执行 Python 代码片段。 -### R支持函数 +参数个数：1 +返回值：处理后的结果值 -- `RRelease` +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------------- | +| 1 | `code` | 是 | 字符串 | Python 代码字符串 | -### Html +### `pyCall(module_or_mode, function_or_module[, function_or_arg][, arg_values])` -- `TextToHtml` -- `TextToURL` -- `HtmlToText` -- `URLToText` +用途：Python支持函数相关函数。 + +参数个数：2 到 4 +返回值：处理后的结果值 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | -------------------- | ---- | -------------------- | ---------------------------------------------------------------------------------------- | +| 1 | `module_or_mode` | 是 | 字符串/整数 | Python 模块名；也可传整数模式，例如源文档示例中的 `2` | +| 2 | `function_or_module` | 是 | 字符串 | 当第 1 参数是模块名时为 Python 函数名；当第 1 参数是模式时为 Python 模块名 | +| 3 | `function_or_arg` | 否 | 字符串/任意值 | 当第 1 参数是模块名时为传给 Python 函数的第一个参数；当第 1 参数是模式时为 Python 函数名 | +| 4 | `arg_values` | 否 | 任意值/数组/命名参数 | 继续传给 Python 函数的位置参数、数组参数或命名参数 | + +### `pyError()` + +用途：获取最近一次 Python 调用错误信息。 + +参数个数：0 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---- | + +## Html 和 URL 文本转换函数 + +### `textToHtml(text)` + +用途：将普通文本转换为 HTML 文本；空格会转换为 ` `。 + +适用环境：Windows TSL 解释器。 +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------- | +| 1 | `text` | 是 | 字符串 | 待转换的普通文本 | + +### `textToURL(text)` + +用途：将普通文本转换为 URL 编码文本。 + +适用环境：Windows TSL 解释器。 +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ---------------- | +| 1 | `text` | 是 | 字符串 | 待转换的普通文本 | + +### `htmlToText(text)` + +用途：将 HTML 文本转换为普通文本；` ` 会转换为空格。 + +适用环境：Windows TSL 解释器。 +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | ----------------------------------------- | +| 1 | `text` | 是 | 字符串 | 待转换的 HTML 文本；` ` 不按空格转换 | + +### `urlToText(text)` + +用途：将 URL 编码文本转换为普通文本。 + +适用环境：Windows TSL 解释器。 +参数个数：1 +返回值：字符串 + +| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 | +| -------- | ------ | ---- | -------- | --------------------- | +| 1 | `text` | 是 | 字符串 | 待转换的 URL 编码文本 | diff --git a/docs/tsl/reference/index.md b/docs/tsl/reference/index.md index 5b26c763..b7c7137e 100644 --- a/docs/tsl/reference/index.md +++ b/docs/tsl/reference/index.md @@ -1,38 +1,54 @@ -# Reference Index +# 函数查阅入口 -文档类型：检索页 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[catalog/index.md](catalog/index.md)、[../syntax/index.md](../syntax/index.md)、[../finance/index.md](../finance/index.md) +文档类型：函数事实路由页 +是否可直接用于生成代码：是；进入 catalog 分类页后按函数事实条目生成调用 +遇到不确定时：先按本页“按任务跳转”和“模块目录”分流；语法问题看 [../syntax/index.md](../syntax/index.md)，模块集成看 [../modules/index.md](../modules/index.md)，项目业务接口看项目实际文档 -这里是函数查阅层，不是默认通读入口。现在这一页本身就是函数总入口，不再要求先跳到额外的中转页。 +这里是函数查阅层，不是默认通读入口。它只回答两类问题：函数名属于哪个模块、带参数表的函数事实条目应该怎样传参。 -reference 的目标是确认每个方法的参数类型，让 agent 写代码时知道该传什么。文档只保留 agent 生成代码需要的函数事实。 +语法写法回语法层，模块集成回模块层；真实业务字段、账户和项目接口回项目实际文档。 -## Agent 函数使用规则 +## 智能体函数使用规则 -- 只从 verified 函数页读取参数类型、返回值和调用约束。 -- catalog 只是候选函数索引，不能把 catalog 里的函数名直接当成可调用事实。 -- 函数没有进入 verified 函数页时，不要根据函数名猜参数，也不要生成调用代码。 +- 生成函数调用前，只从带完整参数表的函数事实条目读取签名、接收类型、返回值和调用约束。 +- catalog 使用推荐大小写展示函数名；函数名里的下划线和数字结构按条目标题保留。生成代码时以函数事实条目的函数名拼写为准。 - 函数参数必须按正确类型传入；TSL 本身弱类型，不等于函数参数无类型。 -- 如果函数被记录为当前测试环境不支持，不要使用该函数生成代码。 +- 没在 catalog 正式条目里的函数，不要根据函数名猜调用；先回到对应业务文档、模块文档或项目代码确认来源。 -## 检索策略 +## 智能体检索策略 -1. 先看 [catalog/index.md](catalog/index.md) 的模块目录，确定候选大类。 -2. 进入对应模块页，在页内搜索具体候选函数名。 -3. 先看 [verified/index.md](verified/index.md)，再进入具体 verified 函数页读取参数类型、返回值和调用约束；当前核心函数页是 [verified/core.md](verified/core.md)。 -4. 如果候选函数没有进入 verified 函数页，不要生成调用代码。 -5. 当前测试环境不支持的方法见 [unavailable_methods.md](unavailable_methods.md)。 -6. 如果目录和定向检索都找不到函数，不要发明函数名，也不要默认它是 TSL 内建函数；回 [../syntax/index.md](../syntax/index.md)、[../finance/index.md](../finance/index.md)、[../modules/index.md](../modules/index.md) 或项目文档确认来源。 +1. 用户只描述能力时，先看本页“模块目录”，确定候选大类。 +2. catalog 分类页通常很大；进入分类页后先搜索函数名或能力关键词，不要默认通读整页。 +3. 只读取命中的函数条目、相邻分类标题和必要参数表；不要把同页其它函数混进当前调用。 +4. 函数名下方有完整参数表时，按该条目生成调用。 +5. 如果目录和定向检索都找不到函数，不要发明函数名，也不要默认它是 TSL 内建函数；回 [../syntax/index.md](../syntax/index.md)、[../modules/index.md](../modules/index.md) 或项目文档确认来源。 ## 按任务跳转 -| 当前任务 | 先读哪里 | -| ------------------------ | ------------------------------------------------ | -| 查函数库入口 | [catalog/index.md](catalog/index.md) | -| 直接按模块查函数 | [catalog/index.md](catalog/index.md) | -| 查可调用函数参数类型 | [verified/index.md](verified/index.md) | -| 查当前测试环境不支持方法 | [unavailable_methods.md](unavailable_methods.md) | -| 回到语法层 | [../syntax/index.md](../syntax/index.md) | -| 回到金融层 | [../finance/index.md](../finance/index.md) | -| 回到模块层 | [../modules/index.md](../modules/index.md) | +| 任务 | 先读哪里 | +| -------------------- | ---------------------------------------------------- | +| 查函数库入口 | 本页“模块目录” | +| 直接按模块查函数 | 本页“模块目录” | +| 查可调用函数参数类型 | 带完整参数表的函数事实条目 | +| 回到语法层 | [../syntax/index.md](../syntax/index.md) | +| 查数据仓库金融函数 | [catalog/datawarehouse.md](catalog/datawarehouse.md) | +| 回到模块层 | [../modules/index.md](../modules/index.md) | + +## 模块目录 + +这里是函数模块目录。进入分类页后，按函数事实条目的参数表生成调用。 + +| 模块 | 分类页 | 范围 | 函数事实数 | +| --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- | ---------- | +| 基础函数 | [catalog/base.md](catalog/base.md) | 轻量入口；字符串、数组、日期时间、类型转换与常用基础能力详情在分类页 | 365 | +| 数学函数 | [catalog/math.md](catalog/math.md) | 轻量入口；数值计算、统计分析、矩阵处理与数学算法详情在分类页 | 221 | +| 数据仓库金融函数 | [catalog/datawarehouse.md](catalog/datawarehouse.md) | 轻量入口；行情、财务、板块、选股、时序统计和向导函数详情在分类页 | 414 | +| 系统相关函数 | [catalog/system.md](catalog/system.md) | 轻量入口；数据类型、表达式调用、性能与运行时能力详情在分类页 | 60 | +| Windows/.NET 专属函数 | [catalog/dotnet.md](catalog/dotnet.md) | Windows/.NET/COM 环境辅助函数和 COM/OLE 函数 | 12 | +| 资源访问函数 | [catalog/resource.md](catalog/resource.md) | 轻量入口；文件、数据库、网络与外部资源访问详情在分类页 | 132 | +| 天软平台服务函数 | [catalog/platform.md](catalog/platform.md) | 用户数据、板块维护、平台执行信息和授权用户共享函数入口 | 17 | +| 客户端函数 | [catalog/client.md](catalog/client.md) | 客户端交互、界面控制与前端协作能力 | 2 | +| 图形函数 | [catalog/graphics.md](catalog/graphics.md) | 轻量入口；图表、绘图与可视化相关函数详情在分类页 | 87 | +| 压缩和解压函数 | [catalog/compression.md](catalog/compression.md) | 压缩、解压与归档能力 | 5 | +| 信息摘要及编码 | [catalog/digest_encoding.md](catalog/digest_encoding.md) | 哈希、摘要、编码与转换能力 | 11 | +| 第三方交互函数 | [catalog/third_party.md](catalog/third_party.md) | 第三方库与外部程序交互能力 | 7 | diff --git a/docs/tsl/reference/unavailable_methods.md b/docs/tsl/reference/unavailable_methods.md deleted file mode 100644 index de2305e8..00000000 --- a/docs/tsl/reference/unavailable_methods.md +++ /dev/null @@ -1,11 +0,0 @@ -# Reference Unavailable Methods - -文档类型：当前测试环境不支持的方法清单 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[verified/core.md](verified/core.md)、[catalog/index.md](catalog/index.md) - -这里只记录方法不存在，或当前测试环境暂不支持的方法。参数类型事实写在 verified 函数页。 - -## 当前测试环境不支持的方法 - -暂无已入档记录。 diff --git a/docs/tsl/reference/verified/core.md b/docs/tsl/reference/verified/core.md deleted file mode 100644 index 69641f20..00000000 --- a/docs/tsl/reference/verified/core.md +++ /dev/null @@ -1,49 +0,0 @@ -# Verified Core Reference Functions - -文档类型：agent 参数事实表 -是否可直接用于生成代码：是 -遇到不确定时跳转到：[../catalog/index.md](../catalog/index.md)、[../../syntax/index.md](../../syntax/index.md) - -本页只保留 agent 生成代码需要的函数事实：签名、接收类型、返回值和调用约束。 - -## 使用规则 - -- 只按“接收类型”传参。 -- TSL 是弱类型语言，但函数参数不是任意类型。 -- catalog 同名函数没有出现在 verified 页时，不要当作可调用事实。 - -## 函数参数 - -### `Abs(value)` - -用途：返回数值绝对值。 - -| 参数 | 接收类型 | 返回 | 说明 | -| ------- | -------- | ---- | ---------- | -| `value` | 整数 | 数值 | 返回绝对值 | -| `value` | 实数 | 数值 | 返回绝对值 | - -### `ifInt(value)` - -用途：判断值当前是否按整数处理，返回 `1` 或 `0`。 - -| 参数 | 接收类型 | 返回 | 说明 | -| ------- | --------------------------------------- | ---- | ---------------------- | -| `value` | 任意值；已记录整数、实数、字符串、`nil` | 整数 | 整数返回 `1`，否则 `0` | - -### `DateToStr(value)` - -用途：把日期时间值转成日期字符串。 - -| 参数 | 接收类型 | 返回 | 说明 | -| ------- | -------- | ------ | ------------------------------ | -| `value` | 日期时间 | 字符串 | 日期时间字面量可写 `20111231T` | - -### `Length(value)` - -用途：返回字符串或数组长度。 - -| 参数 | 接收类型 | 返回 | 说明 | -| ------- | -------- | ---- | ------------ | -| `value` | 字符串 | 整数 | 返回字符长度 | -| `value` | 数组 | 整数 | 返回元素个数 | diff --git a/docs/tsl/reference/verified/index.md b/docs/tsl/reference/verified/index.md deleted file mode 100644 index 35a655f8..00000000 --- a/docs/tsl/reference/verified/index.md +++ /dev/null @@ -1,19 +0,0 @@ -# Verified Reference Functions - -文档类型：agent 参数事实索引 -是否可直接用于生成代码：否 -遇到不确定时跳转到：[../catalog/index.md](../catalog/index.md)、[../../syntax/index.md](../../syntax/index.md) - -本页只负责定位已经整理成参数事实表的函数页。生成调用代码时，进入具体函数页读取签名、接收类型、返回值和调用约束。 - -## 使用规则 - -- 只从具体函数页读取接收类型和返回值。 -- catalog 里的候选名没有出现在具体函数页时，不要当作可调用事实。 -- 不根据函数名猜参数。 - -## 参数事实页 - -| 范围 | 页面 | 当前函数 | -| -------- | ------------------ | ------------------------------------- | -| 核心函数 | [core.md](core.md) | `Abs`、`ifInt`、`DateToStr`、`Length` | diff --git a/docs/tsl/syntax/01_introduction.md b/docs/tsl/syntax/01_introduction.md deleted file mode 100644 index 30645c58..00000000 --- a/docs/tsl/syntax/01_introduction.md +++ /dev/null @@ -1,94 +0,0 @@ -# Introduction - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：否 -遇到不确定时跳转到：[02_quickstart.md](02_quickstart.md)、[03_core_model.md](03_core_model.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 1 篇，共 32 篇。上一篇：手册入口 [index.md](index.md)。下一篇：[02_quickstart.md](02_quickstart.md)。 - -这一篇只做一件事：给 agent 建立 TSL 的第一判断模型。它不是人类教程，不负责展开所有语法细节；它只告诉 agent 第一次看到 TSL 任务时先判断什么、按什么证据生成代码、哪些直觉不能继承。 - -## 这一篇解决什么问题 - -回答“agent 第一次读到 TSL 需求时，怎样先识别交付形态，再选择最小可靠代码结构”。 - -涉及赋值、命名参数、类外形、`unit` 骨架、数组 / 字符串下标这类高频硬规则时，统一以 [02_quickstart.md](02_quickstart.md) 的“语言核心事实速查”为准；这一页只负责建立第一判断模型。 - -## Agent 第一判断流程 - -1. 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。 -2. 用户未给后缀时，先看交付目标：可执行代码对应 `.tsl`，通用模块对应 `.tsf`。 -3. 交付目标仍不明确时，向用户确认；不要替用户发明文件形态。 -4. 写 `.tsl` 时，先生成会顺序执行的语句区；如果需要函数或类，把声明区放在语句区之后。 -5. 写 `.tsf` 时，只生成模块 / 函数扩展代码；部署后的顶层函数可被 `.tsl` 脚本直接调用。 -6. 没有文档证据时不要发明语法；只能回到对应专题页、反例页、项目规则，或记录文档缺口。 - -## 先用什么方式理解 TSL - -- TSL 可以借 Pascal 风格外形理解：`function ... begin ... end;`、`unit ... interface ... implementation ... end.`、`type Name = class ... end;` 都很接近。 -- 这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。 -- `.tsl` / `.tsf` 首先是用户交付形态：`.tsl` 是可执行脚本，`.tsf` 是通用模块 / 函数扩展。 -- 日常赋值先记 `:=`，不要把 `=` 当成普通赋值。 - -## 已验证的第一印象 - -`.tsl` 可执行脚本第一印象： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -test(); - -function test(); -begin - echo "test"; -end; -``` - -代码块说明：`.tsl` 的语句区在前，按顺序执行；函数声明区在后，供前面的脚本语句调用。 - -`.tsf` 通用模块第一印象： - -代码块身份：已验证可执行示例 - -```tsl -function Test1(); -begin - echo "test1"; -end; -``` - -代码块说明：这个 `.tsf` 部署到解释器 `funcext` 后，`.tsl` 脚本可以直接调用 `Test1();`。文件部署方式属于项目执行层，不写进通用语法页。 - -赋值、数组、字符串下标的第一印象： - -代码块身份：已验证可执行示例 - -```tsl -items := array(10, 20, 30); -table_data := array("Code": "000001", "Name": "Demo"); -echo items[0]; -echo table_data["Code"]; -echo "ABC"[1]; -``` - -代码块说明：数组下标从 `0` 开始，字符串下标从 `1` 开始；更完整规则见 [04_values_and_literals.md](04_values_and_literals.md)。 - -## 第一次写时最容易混淆的边界 - -- 不要把 `.tsl` / `.tsf` 当成 agent 自行选择的纯语法分支；后缀和用户交付目标优先。 -- 不要把 Pascal 外形直接泛化成 Pascal 文件模型。 -- 不要在 `.tsl` 的函数/类声明区之后继续追加脚本语句。 -- 不要把未验证写法写成语法事实；agent 生成代码时只模仿带证据标签的代码块。 - -## 下一步怎么读 - -- 需要立刻开始写代码：看 [02_quickstart.md](02_quickstart.md) -- 需要判断当前文件组织方式：看 [03_core_model.md](03_core_model.md) -- 需要先写值、数组、字符串：看 [04_values_and_literals.md](04_values_and_literals.md) -- 需要先写变量、常量：看 [05_variables_and_constants.md](05_variables_and_constants.md) -- 需要先写函数和调用：看 [06_functions_and_calls.md](06_functions_and_calls.md) -- 需要先避开高频误写：看 [12_pitfalls.md](12_pitfalls.md) diff --git a/docs/tsl/syntax/01_quickstart.md b/docs/tsl/syntax/01_quickstart.md new file mode 100644 index 00000000..f8fc9161 --- /dev/null +++ b/docs/tsl/syntax/01_quickstart.md @@ -0,0 +1,218 @@ +# TSL 快速落代码规则 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本文“下一步路由”继续判断；文件模型看 [02_core_model.md](02_core_model.md)，函数 / 调用看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +本篇只回答两个落代码前问题：用户已给出 `.tsl` / `.tsf` 后缀时，智能体如何按后缀组织代码；以及生成代码前必须先核对哪些语言硬规则。 + +## 本篇职责 + +快速回答“任务已经给出后缀或交付目标时，应该选择哪一种可直接照写骨架”，并提供一份单点的语言核心事实速查。 + +## 智能体快速落代码流程 + +1. 先看用户有没有指定 `.tsl` / `.tsf` 后缀；指定后缀时，后缀就是文件形态判断依据。 +2. 用户未指定后缀时，再根据交付目标判断 `.tsl` 或 `.tsf`：入口流程、脚本任务或一次性执行逻辑用 `.tsl`；可复用交付物（函数、过程、类、模块或扩展文件）用 `.tsf`；如果只是脚本内部封装函数或类，仍按 `.tsl` 处理。 +3. 只从 `代码块身份：可直接照写示例` 的骨架起手；遇到 `反例 / 不可照写` 必须避开。 +4. 写 `.tsl` 时，先写会执行的语句区；需要函数或类时，把声明区放在语句区之后。 +5. 写 `.tsf` 时，只写可复用顶层声明，不写入口脚本流程；部署、查找路径和解释器环境属于项目执行层。 +6. 本页和对应专题页没有覆盖的写法，不要发明语法；按“下一步路由”切到对应专题页判断；仍无文档事实时向用户确认或记录文档缺口。 + +## 语言核心事实速查 + +这一节是本语法手册默认的语言硬规则收口点。涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、命名参数、类写法、`unit` 骨架和下标规则时，统一先看这里。 + +- 赋值：普通赋值用 `:=`，不要把 `=` 当成普通赋值。 +- 后缀：用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；用户未给后缀时，再按交付目标判断。 +- 无后缀：入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用交付物（函数、过程、类、模块或扩展文件）对应 `.tsf`；只是脚本内部封装函数或类时，仍按 `.tsl` 处理；仍不明确时向用户确认。 +- `.tsl`：可执行脚本，语句区在前并按顺序执行；函数 / 类声明区在后，供前面的语句调用或运行时解析。 +- `.tsf`：可复用模块 / 函数扩展文件；非 `unit` 顶层函数 / 过程部署到解释器 `funcext` 后，脚本可以直接调用；顶层类声明只按可复用声明理解；`unit` 按模块组织理解。 +- `.tsl` 声明区：如果需要函数或类，先写会执行的语句区，再写函数 / 类声明区；不要在声明区后面继续追加脚本语句。 +- `function` / `procedure`：用户只说“写一个函数”时默认用 `function`；只有用户明确要求 `procedure` / 过程时才用 `procedure Name(...); begin ... end;`；`procedure` 头后不允许写返回类型。 +- 类：顶层类定义统一写成 `type Name = class ... end;`，不要写裸 `class Name`；创建对象有两种方式，`new ClassName()` 最常用，`createObject(...)` 作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`。 +- `unit`：涉及多文件组织时，先按 `unit Name; interface ... implementation ... end.` 骨架理解；不要把 `unit` 当默认最小起手。 +- 命名参数：写法是 `Func(a:1, b:2)`，不要写成 `Func(a = 1, b = 2)`。 +- 下标：`array(...)` 既可以写顺序数组，也可以写字符串键表；数组下标从 `0` 开始，字符串下标从 `1` 开始。 + +## 术语对照 + +- “脚本语句区”：`.tsl` 文件开头会按顺序执行的语句。 +- “声明区”：`.tsl` 语句区之后的 `function / procedure` 或 `type Name = class` 声明。 +- “顶层 `function / procedure`”：在 `.tsf` 中指模块暴露的顶层函数 / 过程，在 `.tsl` 中指脚本声明区里的函数 / 过程。 +- “顶层函数骨架”“顶层函数定义体”：只指 `function` 骨架；不要因为任务没有返回值就自动改成 `procedure`。 +- `class function` / “类方法”：同一件事；前者是代码关键字写法，后者是中文描述。 + +## 起手骨架选择规则 + +| 任务 | 起手骨架 | +| ------------------------------------ | ------------------------------ | +| 写入口流程、脚本任务或一次性执行逻辑 | `.tsl` 脚本语句区 | +| 脚本逻辑需要调用本文件内函数 | `.tsl` 语句区 + 后置函数声明区 | +| 脚本逻辑需要对象状态、字段、方法 | `.tsl` 语句区 + 后置类声明区 | +| 沉淀可复用函数、过程或类 | `.tsf` 可复用顶层声明 | +| 需要把接口和实现组织进一个模块 | `.tsf` `unit` | + +默认建议： + +- 用户只要求写一段代码、脚本或示例，且没有明确复用、模块或 `.tsf` 交付需求时，优先从 `.tsl` 脚本语句区开始。 +- 不要因为代码里需要函数或类就自动升级成 `.tsf`；`.tsl` 也可以在语句区后放声明区。 +- 不要把 `unit` 当成最小起手骨架；只有用户明确要模块接口 / 实现组织，或项目已有 `unit` 边界时，才进入 `unit` 写法。 +- `uses` 往往天然进入多文件查找路径问题，所以不放进这篇的最小起手骨架里。 + +## 最小骨架 + +使用这些骨架时遵守： + +- 可以模仿已经出现的代码外形、语句顺序和块级结构。 +- 不要从骨架推断未出现的语法、内置函数、部署方式、文件名规则或模块查找规则。 +- 需要扩展写法时，先进入对应专题页读取规则。 + +本页只列最短高频骨架；`procedure`、参数、返回类型和调用细节见 [05_functions_and_calls.md](05_functions_and_calls.md)。 + +### `.tsl` 脚本骨架 + +`.tsl` 脚本语句区骨架： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +``` + +代码块说明：这是 `.tsl` 语句区最小形态，只证明脚本语句可以从文件开头顺序执行。 + +`.tsl` 语句区调用后置函数声明： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +test(); + +function test(); +begin + echo "test"; +end; +``` + +代码块身份：输出片段 + +```text +test +``` + +代码块说明：这个骨架证明 `.tsl` 语句区可以调用后置函数声明；不要在函数声明区之后继续追加脚本语句。 + +`.tsl` 语句区调用后置类声明： + +代码块身份：可直接照写示例 + +```tsl +obj := new MyClass(); +obj.value := 5; +echo obj.value; + +type MyClass = class + value; +end; +``` + +代码块身份：输出片段 + +```text +5 +``` + +代码块说明：这个骨架证明 `.tsl` 语句区可以通过 `new MyClass()` 使用后置类声明；普通对象创建默认优先 `new ClassName()`。`createObject(...)` 也是对象创建方式，但作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`，细节见 [08_objects_and_classes.md](08_objects_and_classes.md)。 + +### `.tsf` 可复用骨架 + +`.tsf` 顶层函数骨架： + +代码块身份：可直接照写示例 + +```tsl +function Test1(); +begin + echo "test1"; +end; +``` + +代码块说明：这个 `.tsf` 部署到解释器 `funcext` 后，`.tsl` 脚本可以直接调用 `Test1();`。部署方式属于项目执行层，不写进通用语法页。 + +代码块身份：输出片段 + +```text +test1 +``` + +`.tsf` `unit` 骨架： + +代码块身份：可直接照写示例 + +```tsl +unit DemoUnit; + +interface + +function Ping(); + +implementation + +function Ping(); +begin + return 1; +end; + +end. +``` + +代码块说明：这个 `.tsf` 骨架用于模块接口 / 实现组织；`.tsl` 脚本 `uses DemoUnit` 后可调用 `Ping()`，返回值为 `1`。调用脚本和查找路径边界见 [09_units_and_scope.md](09_units_and_scope.md)。 + +## 默认起手骨架 + +如果用户只要求写一段代码、脚本或示例，且没有明确 `.tsf`、`unit`、模块复用或对象建模需求，直接从 `.tsl` 脚本版本开始： + +代码块身份：可直接照写示例 + +```tsl +echo "hello"; +``` + +代码块身份：输出片段 + +```text +hello +``` + +代码块说明：这是默认可执行脚本骨架；没有复用或模块需求时，不要主动改成 `.tsf`。 + +## 最高频禁止项 + +- `.tsl` 可以同时有语句区和声明区；真正要避免的是在声明区后面继续追加脚本语句。 + +代码块身份：反例 / 不可照写 + +```text +a := 1; +test(); + +function test(); +begin + echo "test"; +end; + +echo "after declaration"; +``` + +代码块说明：这是不可照写的错误形态；最后一行属于“声明区之后继续写脚本语句”。正确做法是把所有会执行的脚本语句放在声明区之前。 + +代码块身份：输出片段 + +```text +Execute script error at Line:9 +function:__main__:line 9: invalid statement +``` diff --git a/docs/tsl/syntax/02_core_model.md b/docs/tsl/syntax/02_core_model.md new file mode 100644 index 00000000..206ca891 --- /dev/null +++ b/docs/tsl/syntax/02_core_model.md @@ -0,0 +1,190 @@ +# TSL 文件模型规则 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本文“下一步路由”继续判断；最短骨架和高频硬规则看 [01_quickstart.md](01_quickstart.md)，函数 / 过程看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +本篇说明 TSL 的文件模型判断规则：智能体如何区分 `.tsl` 可执行脚本与 `.tsf` 可复用声明文件，如何识别脚本语句区和声明区，以及为什么很多错误其实是“文件模型选错了”。 + +## 本篇职责 + +回答“目标文件到底是 `.tsl` 脚本还是 `.tsf` 可复用声明文件，以及 `.tsl` 里的哪些内容会顺序执行、哪些内容只是后置声明”。 + +如果问题已经变成具体语法外形，先用本页完成文件模型判断，再跳到对应专题页：函数 / 过程看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，赋值和表达式看 [06_expressions_and_operators.md](06_expressions_and_operators.md)。[01_quickstart.md](01_quickstart.md) 只作为最短骨架和高频硬规则速查。 + +## 智能体文件模型判断流程 + +1. 后缀是第一证据：用户明确要求 `.tsl` 时，按可执行脚本写；用户明确要求 `.tsf` 时，按可复用声明文件写。 +2. 没有后缀时看交付目标：入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用交付物（函数、过程、类、模块或扩展文件）对应 `.tsf`；如果只是脚本内部封装函数或类，仍按 `.tsl` 处理。 +3. 目标仍不明确时先问用户；不要把脚本入口和可复用模块替用户合并成一个猜测文件。 +4. 写 `.tsl` 时，先生成脚本语句区；需要函数、过程或类时，把声明区放在语句区之后。 +5. 写 `.tsf` 时，生成顶层函数 / 过程 / 类声明，或 `unit`；不要写成会直接顺序执行的脚本入口。 +6. 没有文档证据时不要发明文件模型；只能回到对应专题页、项目自身文档或项目专属规则，或记录文档缺口。 + +## 文件模型核心规则 + +- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，再按交付目标判断。 +- 未给后缀时，入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用交付物（函数、过程、类、模块或扩展文件）对应 `.tsf`；只是脚本内部封装函数或类时，仍按 `.tsl` 处理；仍不明确时向用户确认。 +- `.tsl` 脚本按两段理解：语句区在前并按顺序执行；声明区在后，可放 `function / procedure` 或 `type Name = class`。 +- `.tsf` 里的非 `unit` 顶层函数 / 过程可按函数扩展理解：部署到解释器 `funcext` 后，`.tsl` 可以直接调用；顶层类声明只按可复用声明理解；`unit` 按模块组织理解。 +- `uses` 可以出现在顶层，但这里只把它当成辅助语句，不把它当成主体声明；函数体和类定义体里的位置限制见 [09_units_and_scope.md](09_units_and_scope.md)。 +- 裸 `class Name` 不作为类定义写法使用。 +- 在 `.tsl` 中，不要在声明区之后继续追加脚本语句。 +- `unit` 默认先按完整形态理解；它也可以省略 `interface` / `implementation` 写成简写形态，见 [09_units_and_scope.md](09_units_and_scope.md)。 +- 不要把 `.tsl` 写成只有顶层函数的模块；如果用户要通用可复用函数，优先写 `.tsf`。 +- 不要把 `.tsf` 写成会直接执行脚本语句的入口；如果用户要顺序执行入口，优先写 `.tsl`。 + +## 文件模型示例 + +使用这些示例时遵守： + +- 可以模仿已经出现的文件模型、语句顺序和块级结构。 +- 不要从示例推断未出现的部署方式、文件名规则或模块查找规则。 +- `.tsf` 示例后的输出片段只证明部署后可由 `.tsl` 调用取得结果；不要理解为 `.tsf` 会独立顺序执行。 +- 需要扩展写法时，先进入对应专题页读取规则。 + +### `.tsl` 文件模型 + +`.tsl` 脚本语句区的最小形态： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +``` + +代码块说明：这是 `.tsl` 语句区最小形态，只证明脚本语句可以从文件开头顺序执行。 + +`.tsl` 语句区后接函数声明区： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +test(); + +function test(); +begin + echo "test"; +end; +``` + +代码块身份：输出片段 + +```text +test +``` + +代码块说明：这个骨架证明 `.tsl` 语句区可以调用后置函数声明；不要在函数声明区之后继续追加脚本语句。 + +`.tsl` 语句区后接类声明区： + +代码块身份：可直接照写示例 + +```tsl +obj := new MyClass(); +obj.value := 5; +echo obj.value; + +type MyClass = class + value; +end; +``` + +代码块身份：输出片段 + +```text +5 +``` + +代码块说明：这个骨架证明 `.tsl` 语句区可以通过 `new MyClass()` 使用后置类声明；普通对象创建默认优先 `new ClassName()`。`createObject(...)` 也是对象创建方式，但作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`，细节见 [08_objects_and_classes.md](08_objects_and_classes.md)。 + +### `.tsf` 文件模型 + +`.tsf` 顶层函数的最小形态： + +代码块身份：可直接照写示例 + +```tsl +function Demo(); +begin + return 1; +end; +``` + +代码块说明：这个 `.tsf` 部署为函数扩展后，可由 `.tsl` 脚本调用 `Demo()` 并取得返回值；部署方式属于项目执行层，不写进通用语法页。 + +代码块身份：输出片段 + +```text +1 +``` + +`.tsf` `unit` 的最小形态： + +代码块身份：可直接照写示例 + +```tsl +unit DemoUnit; + +interface + +function Ping(); + +implementation + +function Ping(); +begin + return 1; +end; + +end. +``` + +代码块说明：这个 `.tsf` `unit` 可由 `.tsl` 脚本 `uses DemoUnit` 后调用 `Ping()`，返回值为 `1`；调用脚本和查找路径边界见 [09_units_and_scope.md](09_units_and_scope.md)。 + +代码块身份：输出片段 + +```text +1 +``` + +### 文件模型反例 + +不可照写形态： + +代码块身份：反例 / 不可照写 + +```text +class DemoType +end; +``` + +上面这种裸 `class` 顶层写法会编译失败。 + +代码块身份：输出片段 + +```text +invalid statement +``` + +## 文件模型归类速查 + +任务目标是判断文件属于哪一种模型时，使用下面这组归类： + +- `.tsl` 脚本语句区：直接写会顺序执行的语句。 +- `.tsl` 声明区：在语句区之后写 `function ... begin ... end;`、`procedure ... begin ... end;` 或 `type Name = class ... end;`。 +- `.tsf` 顶层函数 / 过程：写可部署到 `funcext` 的 `function` / `procedure` 文件。 +- `.tsf` 顶层类声明：写 `type Name = class ... end;`，只按可复用声明理解；类细节见 [08_objects_and_classes.md](08_objects_and_classes.md)。 +- `.tsf` 顶层单元：默认先写 `unit ... interface ... implementation ... end.`；简写形态见 [09_units_and_scope.md](09_units_and_scope.md)。 + +## 文件模型禁止项 + +- 把 `.tsl` 当成 `.tsf` 来写，只给一个顶层函数，不写任何会执行的脚本语句。 +- 因为 `.tsl` 脚本内部需要函数或类，就自动改成 `.tsf`。 +- 把 `.tsf` 当成 `.tsl` 来写，在模块文件里直接堆顺序执行的脚本语句。 +- 把 `.tsf` 顶层类声明写成裸 `class Name ... end;`；类声明必须使用 `type Name = class ... end;`。 +- 把 `uses` 当成主体声明，而不是辅助组织语句。 +- 在 `.tsl` 声明区之后继续追加脚本语句。 diff --git a/docs/tsl/syntax/02_quickstart.md b/docs/tsl/syntax/02_quickstart.md deleted file mode 100644 index 1cf72858..00000000 --- a/docs/tsl/syntax/02_quickstart.md +++ /dev/null @@ -1,202 +0,0 @@ -# Syntax Quickstart - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[03_core_model.md](03_core_model.md)、[06_functions_and_calls.md](06_functions_and_calls.md)、[10_units_and_scope.md](10_units_and_scope.md) - -手册位置：第 2 篇，共 32 篇。上一篇：[01_introduction.md](01_introduction.md)。下一篇：[03_core_model.md](03_core_model.md)。 - -这一篇集中回答两个紧邻问题：用户已给出 `.tsl` / `.tsf` 后缀时，agent 应该如何按后缀组织代码；以及落代码前必须先核对哪些语言硬规则。 - -## 这一篇解决什么问题 - -快速回答“当前任务已经给出后缀或交付目标时，应该使用哪一种骨架”，并提供一份单点的语言核心事实速查。 - -## Agent 快速落代码流程 - -1. 先看用户有没有指定 `.tsl` / `.tsf` 后缀；指定后缀时，后缀就是文件形态判断依据。 -2. 用户未指定后缀时，再根据交付目标判断 `.tsl` 或 `.tsf`：可执行脚本用 `.tsl`，通用模块 / 函数扩展用 `.tsf`。 -3. 只从 `代码块身份：已验证可执行示例` 的骨架起手；遇到 `反例 / 不可照写` 必须避开。 -4. 写 `.tsl` 时，先写会执行的语句区；需要函数或类时，把声明区放在语句区之后。 -5. 写 `.tsf` 时，只写模块 / 函数扩展内容；部署、查找路径和解释器环境属于项目执行层。 -6. 当前页和对应专题页没有覆盖的写法，不要发明语法；改为跳转补证、向用户确认，或记录文档缺口。 - -## 语言核心事实速查 - -这一节是当前语法手册默认的语言硬规则收口点。涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、命名参数、类写法、`unit` 骨架和下标规则时，统一先看这里。 - -- 普通赋值用 `:=`，不要把 `=` 当成普通赋值。 -- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；用户未给后缀时，再按交付目标判断。 -- 未给后缀时，可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。 -- `.tsl` 是可执行脚本：语句区在前并按顺序执行；函数/类声明区在后，供前面的语句调用或运行时解析。 -- `.tsf` 是模块/函数扩展文件：部署到解释器 `funcext` 后，脚本可以直接调用其中暴露的顶层函数。 -- 在 `.tsl` 中，如果需要函数或类，先写会执行的语句区，再写函数/类声明区；不要在声明区后面继续追加脚本语句。 -- 无返回值时用 `procedure Name(...); begin ... end;`，不要勉强用 `function`。 -- 顶层类定义统一写成 `type Name = class ... end;`，不要写裸 `class Name`。 -- 多文件组织默认先按 `unit Name; interface ... implementation ... end.` 理解。 -- 命名参数写法是 `Func(a:1, b:2)`。 -- `array(...)` 既可以写顺序数组，也可以写字符串键表；数组下标从 `0` 开始，字符串下标从 `1` 开始。 - -## 术语对照 - -- 文档里出现的“脚本语句区”，指 `.tsl` 文件开头会按顺序执行的语句。 -- 文档里出现的“声明区”，指 `.tsl` 语句区之后的 `function / procedure` 或 `type Name = class` 声明。 -- 文档里出现的“顶层 `function / procedure`”“顶层函数骨架”“顶层函数定义体”，在 `.tsf` 中指模块暴露的顶层函数，在 `.tsl` 中指脚本声明区里的函数。 -- 文档里出现的 `class function` 和“类方法”，指的是同一件事：前者是代码关键字写法，后者是中文描述。 - -## 先选哪一种骨架 - -| 当前任务 | 起手骨架 | -| -------------------------------- | --------------------------------- | -| 写一次性可执行逻辑 | `.tsl` 脚本语句区 | -| 脚本逻辑需要调用本文件内函数 | `.tsl` 语句区 + 后置函数声明区 | -| 脚本逻辑需要对象状态、字段、方法 | `.tsl` 语句区 + 后置类声明区 | -| 沉淀可复用函数并给脚本直接调用 | `.tsf` 顶层函数，部署到 `funcext` | -| 需要把接口和实现组织进一个模块 | `.tsf` `unit` | - -默认建议： - -- 如果你只是要让 agent 先写出一段最稳、最容易续写的可执行代码，优先从 `.tsl` 脚本语句区开始。 -- 不要把 `unit` 当成最小起手骨架；只有用户明确要模块接口 / 实现组织，或项目已有 `unit` 边界时，才进入 `unit` 写法。 -- `uses` 往往天然进入多文件查找路径问题，所以不放进这篇的最小起手骨架里。 - -## 已验证最小骨架 - -`.tsl` 脚本语句区骨架： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -``` - -`.tsl` 语句区调用后置函数声明： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -test(); - -function test(); -begin - echo "test"; -end; -``` - -代码块身份：已验证输出片段 - -```text -test -``` - -`.tsl` 语句区调用后置类声明： - -代码块身份：已验证可执行示例 - -```tsl -obj := CreateObject("MyClass"); -obj.value := 5; -echo obj.value; - -type MyClass = class - value; -end; -``` - -代码块身份：已验证输出片段 - -```text -5 -``` - -`.tsf` 顶层函数骨架： - -代码块身份：已验证可执行示例 - -```tsl -function Test1(); -begin - echo "test1"; -end; -``` - -代码块说明：这个 `.tsf` 部署到解释器 `funcext` 后，`.tsl` 脚本可以直接调用 `Test1();`。部署方式属于项目执行层，不写进通用语法页。 - -代码块身份：已验证输出片段 - -```text -test1 -``` - -`.tsf` `unit` 骨架： - -代码块身份：已验证可执行示例 - -```tsl -unit DemoUnit; -interface - function Ping(); - -implementation - function Ping(); - begin - return 1; - end; -end. -``` - -代码块说明：这个 `.tsf` 骨架用于模块接口 / 实现组织；已通过 `.tsl` 脚本 `uses DemoUnit` 调用 `Ping()` 验证返回值为 `1`。调用脚本和查找路径边界见 [10_units_and_scope.md](10_units_and_scope.md)。 - -## 最常用起手版本 - -如果你现在没有明确的模块复用或对象建模需求，直接从 `.tsl` 脚本版本开始： - -代码块身份：已验证可执行示例 - -```tsl -echo "hello"; -``` - -代码块身份：已验证输出片段 - -```text -hello -``` - -## 最容易写错的一件事 - -- `.tsl` 可以同时有语句区和声明区；真正要避免的是在声明区后面继续追加脚本语句。 - -代码块身份：反例 / 不可照写 - -```text -a := 1; -test(); - -function test(); -begin - echo "test"; -end; - -echo "after declaration"; -``` - -上面最后一行属于“声明区之后继续写脚本语句”。写 `.tsl` 时先把会执行的语句放在前面，再把函数/类声明放在后面。 - -代码块身份：已验证输出片段 - -```text -Execute script error at Line:9 -function:__main__:line 9: invalid statement -``` - -## 跳转指引 - -- 先建立整体读法：见 [01_introduction.md](01_introduction.md) -- 继续判断顶层模型：见 [03_core_model.md](03_core_model.md) -- 继续写函数：见 [06_functions_and_calls.md](06_functions_and_calls.md) -- 继续写 `unit` / `uses`：见 [10_units_and_scope.md](10_units_and_scope.md) -- 继续写类：见 [09_objects_and_classes.md](09_objects_and_classes.md) diff --git a/docs/tsl/syntax/03_core_model.md b/docs/tsl/syntax/03_core_model.md deleted file mode 100644 index fecefce1..00000000 --- a/docs/tsl/syntax/03_core_model.md +++ /dev/null @@ -1,180 +0,0 @@ -# Core Model - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[06_functions_and_calls.md](06_functions_and_calls.md)、[10_units_and_scope.md](10_units_and_scope.md)、[09_objects_and_classes.md](09_objects_and_classes.md) - -手册位置：第 3 篇，共 32 篇。上一篇：[02_quickstart.md](02_quickstart.md)。下一篇：[04_values_and_literals.md](04_values_and_literals.md)。 - -这一篇说明 TSL 的文件模型判断规则：agent 如何区分 `.tsl` 可执行脚本与 `.tsf` 模块，如何识别脚本语句区和声明区，以及为什么很多错误其实是“文件模型选错了”。 - -## 这一篇解决什么问题 - -回答“当前文件到底是 `.tsl` 脚本还是 `.tsf` 模块，以及 `.tsl` 里的哪些内容会顺序执行、哪些内容只是后置声明”。 - -如果问题已经变成赋值、命名参数、类外形、`unit` 骨架或下标规则这类通用硬规则，统一回 [02_quickstart.md](02_quickstart.md) 的“语言核心事实速查”；这一页只处理文件模型判断。 - -## Agent 文件模型判断流程 - -1. 后缀是第一证据：用户明确要求 `.tsl` 时，按可执行脚本写；用户明确要求 `.tsf` 时，按模块 / 函数扩展写。 -2. 没有后缀时看交付目标：可执行交付对应 `.tsl`，可复用扩展交付对应 `.tsf`。 -3. 目标仍不明确时先问用户；不要把脚本入口和通用模块替用户合并成一个猜测文件。 -4. 写 `.tsl` 时，先生成脚本语句区；需要函数、过程或类时，把声明区放在语句区之后。 -5. 写 `.tsf` 时，生成顶层函数 / 过程或 `unit`；不要写成会直接顺序执行的脚本入口。 -6. 没有文档证据时不要发明文件模型；只能回到对应专题页、项目规则，或记录文档缺口。 - -## 必须记住的规则 - -- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，再按交付目标判断。 -- 未给后缀时，可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。 -- `.tsl` 脚本按两段理解：语句区在前并按顺序执行；声明区在后，可放 `function / procedure` 或 `type Name = class`。 -- `.tsf` 模块按可部署扩展理解：顶层函数部署到解释器 `funcext` 后，`.tsl` 可以直接调用；`unit` 仍按模块组织理解。 -- `uses` 可以出现在顶层，但这里只把它当成辅助语句，不把它当成主体声明；函数体和类定义体里的位置限制见 [10_units_and_scope.md](10_units_and_scope.md)。 -- 裸 `class Name` 不作为类定义写法使用。 -- 在 `.tsl` 中，不要在声明区之后继续追加脚本语句。 -- `unit` 默认先按完整形态理解；它也可以省略 `interface` / `implementation` 写成简写形态，见 [10_units_and_scope.md](10_units_and_scope.md)。 -- 不要把 `.tsl` 写成只有顶层函数的模块；如果用户要通用可复用函数，优先写 `.tsf`。 -- 不要把 `.tsf` 写成会直接执行脚本语句的入口；如果用户要顺序执行入口，优先写 `.tsl`。 - -## 已验证语法 - -`.tsl` 脚本语句区的最小形态： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -``` - -`.tsl` 语句区后接函数声明区： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -test(); - -function test(); -begin - echo "test"; -end; -``` - -代码块身份：已验证输出片段 - -```text -test -``` - -`.tsl` 语句区后接类声明区： - -代码块身份：已验证可执行示例 - -```tsl -obj := CreateObject("MyClass"); -obj.value := 5; -echo obj.value; - -type MyClass = class - value; -end; -``` - -代码块身份：已验证输出片段 - -```text -5 -``` - -`.tsf` 顶层函数的最小形态： - -代码块身份：已验证可执行示例 - -```tsl -function Demo(); -begin - return 1; -end; -``` - -代码块说明：这个 `.tsf` 部署为函数扩展后，可由 `.tsl` 脚本调用 `Demo()` 并取得返回值。 - -代码块身份：已验证输出片段 - -```text -1 -``` - -`.tsf` `unit` 的最小形态： - -代码块身份：已验证可执行示例 - -```tsl -unit DemoUnit; -interface - function Ping(); - -implementation - function Ping(); - begin - return 1; - end; -end. -``` - -代码块说明：这个 `.tsf` `unit` 已通过 `.tsl` 脚本 `uses DemoUnit` 调用 `Ping()` 验证返回值为 `1`；调用脚本和查找路径边界见 [10_units_and_scope.md](10_units_and_scope.md)。 - -代码块身份：已验证输出片段 - -```text -1 -``` - -已验证失败的形态： - -代码块身份：反例 / 不可照写 - -```text -class DemoType -end; -``` - -上面这种裸 `class` 顶层写法会编译失败。 - -代码块身份：已验证输出片段 - -```text -invalid statement -``` - -## 最小可编译示例 - -如果当前任务只是“先让 agent 判断当前文件属于哪一种模型”，先记住下面这组归类： - -- `.tsl` 脚本语句区：直接写会顺序执行的语句。 -- `.tsl` 声明区：在语句区之后写 `function ... begin ... end;`、`procedure ... begin ... end;` 或 `type Name = class ... end;`。 -- `.tsf` 顶层函数 / 过程：写可部署到 `funcext` 的 `function` / `procedure` 文件。 -- `.tsf` 顶层单元：默认先写 `unit ... interface ... implementation ... end.`；简写形态见 [10_units_and_scope.md](10_units_and_scope.md)。 - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -``` - -## 常见误写 - -- 把 `.tsl` 当成 `.tsf` 来写，只给一个顶层函数，不写任何会执行的脚本语句。 -- 把 `.tsf` 当成 `.tsl` 来写，在模块文件里直接堆顺序执行的脚本语句。 -- 把 `uses` 当成主体声明，而不是辅助组织语句。 -- 在 `.tsl` 声明区之后继续追加脚本语句。 - -## 跳转指引 - -- 先看整体读法：见 [01_introduction.md](01_introduction.md) -- 写最短骨架：见 [02_quickstart.md](02_quickstart.md) -- 写函数 / 过程：见 [06_functions_and_calls.md](06_functions_and_calls.md) -- 写 unit / uses：见 [10_units_and_scope.md](10_units_and_scope.md) -- 写类：见 [09_objects_and_classes.md](09_objects_and_classes.md) diff --git a/docs/tsl/syntax/03_values_and_literals.md b/docs/tsl/syntax/03_values_and_literals.md new file mode 100644 index 00000000..12577d48 --- /dev/null +++ b/docs/tsl/syntax/03_values_and_literals.md @@ -0,0 +1,434 @@ +# TSL 值与字面量 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[04_variables_and_constants.md](04_variables_and_constants.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[17_types_and_conversions.md](17_types_and_conversions.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇整理基本类型、字面量、数组、字符串、字符串编码边界与基础值模型，避免把值规则分散在函数或金融示例里。 + +## 本篇职责 + +回答“基本类型怎么写、数组和字符串怎么索引、字符串编码边界怎么写、哪些值规则属于语言级事实”。矩阵、集合扩展和复杂容器不在本页展开；命中这些任务时跳到 [12_matrix_and_collections.md](12_matrix_and_collections.md) 或对应深水专题。 + +## 智能体值写法判断流程 + +1. 普通值优先从整数、实数、普通字符串、布尔和 `array(...)` 起手。 +2. 字符串默认用普通字符串；只有编码、宽串、UTF8、原始字符串、字符码或 ASCII `0` 需求明确时，才使用本页字符串边界规则里的文档明确形态。 +3. 看到 `array(...)` 时，先判断要顺序数组还是字符串键表：顺序数组用位置元素，字符串键表用 `"Key": value`。 +4. 写下标前先判断对象类别：顺序数组和二进制缓冲区下标从 `0` 开始，字符串下标从 `1` 开始。 +5. 写字符串区间前先确认 `s[start:end]` 的 `end` 会被包含；不要按半开区间推断。 +6. 如果任务已经变成矩阵、集合扩展、结果集过滤或 TS-SQL 数据形态，不要留在值页硬拼写法；先跳到 [12_matrix_and_collections.md](12_matrix_and_collections.md)、[13_resultset_and_filters.md](13_resultset_and_filters.md) 或 [14_ts_sql.md](14_ts_sql.md)。 +7. 没有对应代码块时不要发明值写法；尤其不要从 JSON、JavaScript、Pascal 或 C 字符串规则直接迁移。 + +## 核心规则 + +- 最先掌握的几类值是：整数、实数、普通字符串、布尔和 `array(...)`。 +- 普通字符串既可以用双引号，也可以用单引号。 +- 同类引号本身可以通过连续写两个同类引号放进字符串里。 +- `\\`、`\"`、`\n` 这类基础转义可用。 +- `\t` 和 `\xNN` 这类转义也可用。 +- `\r`、`\r\n`、`\a`、`\b`、`\f`、`\v` 这些经典转义也可用。 +- `array(...)` 既可以写顺序数组，也可以写字符串键表。 +- 顺序数组下标从 `0` 开始。 +- `binary(...)` 创建的二进制缓冲区也用 `[]` 访问，并且下标从 `0` 开始。 +- 字符串下标从 `1` 开始。 +- `s[0]` 在运行时会越界，不要把字符串当成 0 基下标。 +- 字符串取子串用 `s[start:end]`，并且 `end` 是包含在结果里的。 +- 字符串替换子串用 `s[start:end] := "..."`。 +- 字符串删除子串，本质上就是 `s[start:end] := ""`。 +- 字符串插入子串用 `s[index:0] := "..."`。 +- 普通字符串、`L""` 宽串、`U""` UTF8 前缀串，以及 `%%` 原始字符串都属于文档明确写法。 +- `%%` 原始字符串开头后必须先跟一个空白分隔符；可以带标识符，也支持多行。 +- `L%% ...%%` 与 `U%% ...%%` 这两种带前缀的原始字符串也属于文档明确写法。 +- 普通字符串里的 `\uXXXX` 不要直接按“单字符宽串”理解；`length("\u0041") = 2`，而 `length(L"\u0041") = 1`、`length(U"\u0041") = 1`。 +- `U""` 不是宽串；需要在 UTF8、宽串、普通串之间显式转换时，继续用 `utf8ToUnicode(...)`、`utf8ToAnsi(...)`、`ansiToUtf8(...)`、`unicodeToUtf8(...)`、`string(...)`、`wideString(...)`。 +- `#number` 可以直接把字符码拼进字符串。 +- `\0` 和 `#0` 都能把 ASCII `0` 放进字符串，并且不会把字符串截断。 + +## 可直接照写示例 + +使用这些示例时遵守： + +- 只复制任务需要的值、字面量、下标或字符串片段，不要把多个示例拼成未写入文档的新语法。 +- 普通示例默认按 `.tsl` 脚本语句区书写；需要函数或类型时，放在后置声明区。 +- 字符串编码、宽串和原始字符串边界不清楚时，优先看本页“字符串边界规则”。 + +最基础的值写法： + +代码块身份：可直接照写示例 + +```tsl +count := 1; +price := 12.5; +name := "ABC"; +flag1 := true; +flag2 := false; +items := array(1, 2, 3); +writeLn(count); +writeLn(price); +writeLn(name); +writeLn(flag1); +writeLn(flag2); +writeLn(items[1]); +``` + +代码块身份：输出片段 + +```text +1 +12.5 +ABC +1 +0 +2 +``` + +代码块说明：`true` / `false` 可以直接写成布尔值；运行输出里分别表现为 `1` / `0`。 + +普通字符串字面量： + +代码块身份：可直接照写示例 + +```tsl +writeLn("ABC"); +writeLn('XYZ'); +``` + +结果说明： + +- 依次输出 `ABC`、`XYZ` + +字符串内引号与基础转义： + +代码块身份：可直接照写示例 + +```tsl +writeLn("A""B"); +writeLn('A''B'); +writeLn("A\\B"); +writeLn("A\"B"); +writeLn("A\nB"); +``` + +结果说明： + +- 依次输出 `A"B`、`A'B`、`A\B` +- `"A\nB"` 会分成两行输出 `A` 和 `B` + +更多基础转义： + +代码块身份：可直接照写示例 + +```tsl +writeLn("A\tB" = "A"#9"B"); +writeLn("A\x30B" = "A0B"); +``` + +结果说明： + +- 两行都输出 `1` +- 说明 `\t` 可以表示制表符，`\x30` 这类写法可以按 ANSI 字节值插入字符 + +经典控制字符转义： + +代码块身份：可直接照写示例 + +```tsl +writeLn("\r" = #13); +writeLn("\r\n" = #13#10); +writeLn(length("\r\n")); +writeLn("\a" = #7); +writeLn("\b" = #8); +writeLn("\f" = #12); +writeLn("\v" = #11); +``` + +结果说明： + +- 依次输出 `1`、`1`、`2`、`1`、`1`、`1`、`1` +- 说明 `\r` / `\r\n` 可以直接表示回车和回车换行 +- 说明 `\a`、`\b`、`\f`、`\v` 也属于可用的经典转义 + +代码块身份：可直接照写示例 + +```tsl +items := array(10, 20, 30); +row := array("Code": "0001", "Price": 12.3); +s := "ABC"; +writeLn(items[0]); +writeLn(items[1]); +writeLn(row["Code"]); +writeLn(s[1]); +writeLn(s[2]); +writeLn(s[3]); +``` + +代码块身份：输出片段 + +```text +10 +20 +0001 +A +B +C +``` + +代码块说明：顺序数组 `items` 从 `0` 开始，字符串键表 `row` 用字符串键访问，字符串 `s` 从 `1` 开始。 + +### 字符串边界规则 + +原始字符串 `%%` 的空白分隔、标识符和多行： + +代码块身份：可直接照写示例 + +```tsl +s1 := %% ABC%%; +s2 := %%tag A"B'C%%tag; +s3 := %%m +A +B%%m; +writeLn(s1); +writeLn(s2); +writeLn(s3); +``` + +结果说明： + +- `s1` 输出 `ABC` +- `s2` 输出 `A"B'C` +- `s3` 输出两行 `A`、`B` +- 说明 `%%` 开头后的第一个空白只是分隔符，不属于正文 +- 说明 `%%tag ...%%tag` 可以用标识符配对 +- 也说明 `%%` 原始字符串支持直接跨行 + +代码块身份：输出片段 + +```text +ABC +A"B'C +A +B +``` + +带前缀的原始字符串： + +代码块身份：可直接照写示例 + +```tsl +writeLn(L%% ABC%% = L"ABC"); +writeLn(U%% ABC%% = "ABC"); +``` + +结果说明： + +- 依次输出 `1`、`1` +- 说明 `L%% ...%%` 和 `U%% ...%%` 都属于文档明确写法 + +`\uXXXX` 在普通串、宽串和 `U` 串里的边界： + +代码块身份：可直接照写示例 + +```tsl +writeLn(length("\u0041")); +writeLn(length(L"\u0041")); +writeLn(length(U"\u0041")); +``` + +结果说明： + +- 依次输出 `2`、`1`、`1` +- 因此不要把普通字符串里的 `"\u0041"` 直接理解成和 `L"\u0041"` 一样的“单字符”写法 + +字符串显式编码转换： + +代码块身份：可直接照写示例 + +```tsl +utf8_s := U"\u5929\u8F6F"; +utf8_s2 := unicodeToUtf8(L"\u5929\u8F6F"); +wide_s := utf8ToUnicode(utf8_s); +ansi_s := utf8ToAnsi(utf8_s); +writeLn(ifWString(utf8_s)); +writeLn(utf8_s = utf8_s2); +writeLn(wide_s = L"\u5929\u8F6F"); +writeLn(ansi_s = string(L"\u5929\u8F6F")); +``` + +结果说明： + +- 依次输出 `0`、`1`、`1`、`1` +- 说明 `U""` 不是宽串 +- 说明 UTF8、宽串、普通串之间可以按示例显式转换 + +ASCII `0` 字符不会截断字符串： + +代码块身份：可直接照写示例 + +```tsl +s1 := "A\0B"; +s2 := "A"#0"B"; +writeLn(length(s1)); +writeLn(length(s2)); +writeLn(s1 = s2); +writeLn(s1[2] = #0); +``` + +结果说明： + +- 依次输出 `3`、`3`、`1`、`1` +- 说明 `\0` 和 `#0` 都可以把 ASCII `0` 放进字符串 +- 也说明 TSL 字符串不是遇到 `#0` 就自动截断的 C 风格零结尾串 + +字符码拼接： + +代码块身份：可直接照写示例 + +```tsl +writeLn("A"#48"B"); +writeLn("A"#13#10"B"); +``` + +结果说明： + +- 第一行输出 `A0B` +- 第二组输出会分成两行 `A`、`B` +- 说明 `#48` 这类写法会按字符码直接参与字符串拼接，`#13#10` 可以直接表示换行 + +二进制缓冲区： + +代码块身份：可直接照写示例 + +```tsl +b := binary("30"); +writeLn(ifBinary(b)); +writeLn(b[0] = "3"); +writeLn(b[1] = "0"); +b[1] := 0x31; +writeLn(b[1] = "1"); +``` + +结果说明： + +- 依次输出 `1`、`1`、`1`、`1` +- 说明 `binary(...)` 会得到二进制缓冲区 +- 说明二进制缓冲区的 `[]` 下标从 `0` 开始 +- 也说明二进制缓冲区项可以直接按单字节读写 + +字符串子串读取： + +代码块身份：可直接照写示例 + +```tsl +s := "ABCDE"; +writeLn(s[2:4]); +``` + +代码块身份：输出片段 + +```text +BCD +``` + +代码块说明：字符串区间 `2:4` 会包含结束位 `4`。 + +字符串替换子串： + +代码块身份：可直接照写示例 + +```tsl +s := "ABCDE"; +s[2:4] := "XYZ"; +writeLn(s); +``` + +结果说明： + +- 输出 `AXYZE` + +字符串删除子串： + +代码块身份：可直接照写示例 + +```tsl +s := "ABCDE"; +s[2:4] := ""; +writeLn(s); +``` + +结果说明： + +- 输出 `AE` + +字符串插入子串： + +代码块身份：可直接照写示例 + +```tsl +s := "AAABBB"; +s[4:0] := "111"; +writeLn(s); +``` + +结果说明： + +- 输出 `AAA111BBB` +- 这说明 `s[index:0] := ...` 是在指定位置插入，而不是删除或替换区间 + +## 默认生成模板 + +如果你只是要抓住“基本类型 + array”的第一层，用这个最短例子： + +代码块身份：可直接照写示例 + +```tsl +count := 1; +price := 12.5; +name := "ABC"; +flag := true; +items := array(1, 2, 3); +``` + +## 禁止项 + +- 用 `s[0]` 访问字符串首字符。 +- 误以为 `array(...)` 只能写顺序数组，不能写字符串键表。 +- 误以为字符串区间和数组一样从 `0` 开始。 +- 把 `s[index:0] := ...` 误解成“替换到第 0 位”。 +- 把二进制缓冲区也按字符串的 `1` 基下标去理解。 +- 在普通字符串示例里默认切到原始字符串、宽串 / UTF8 前缀、字符码或编码转换，却没有按本页字符串边界规则确认。 +- 把普通字符串里的 `\uXXXX` 直接当成宽串单字符。 +- 把 `U""` 当成宽串；需要宽串时按本页转换链处理。 +- 把 `#0` / `\0` 当成 C 风格字符串终止符。 + +代码块身份：反例 / 不可照写 + +```text +s := "ABC"; +writeLn(s[0]); +``` + +上面这类写法在运行时会报字符串下标越界。 + +代码块身份：输出片段 + +```text +String index out of bounds +``` + +代码块身份：可直接照写示例 + +```tsl +s := "ABCDE"; +writeLn(s[1:3]); +``` + +不要把上面这个区间访问类比成数组切片的半开区间。按文档输出，它返回 `ABC`，不是 `AB`；字符串区间的结束位会被包含进结果。 + +代码块身份：输出片段 + +```text +ABC +``` diff --git a/docs/tsl/syntax/04_values_and_literals.md b/docs/tsl/syntax/04_values_and_literals.md deleted file mode 100644 index 67424549..00000000 --- a/docs/tsl/syntax/04_values_and_literals.md +++ /dev/null @@ -1,628 +0,0 @@ -# Basic Types And Values - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[05_variables_and_constants.md](05_variables_and_constants.md)、[07_expressions_and_operators.md](07_expressions_and_operators.md)、[20_strings_and_text.md](20_strings_and_text.md) - -手册位置：第 4 篇，共 32 篇。上一篇：[03_core_model.md](03_core_model.md)。下一篇：[05_variables_and_constants.md](05_variables_and_constants.md)。 - -这一篇整理基本类型、字面量、数组、字符串与基础值模型，避免把值规则分散在函数或金融示例里。 - -## 这一篇解决什么问题 - -回答“基本类型怎么写、数组和字符串怎么索引、哪些值规则属于语言级事实”。 - -## Agent 值写法判断流程 - -1. 普通值优先从整数、实数、普通字符串、布尔和 `array(...)` 起手。 -2. 字符串默认用普通字符串；`L""` / `U""` 只在编码或宽串场景，并且必须按本页已验证边界写。 -3. 看到 `array(...)` 时，先判断要顺序数组还是字符串键表：顺序数组用位置元素，字符串键表用 `"Key": value`。 -4. 写下标前先判断对象类别：顺序数组和二进制缓冲区下标从 `0` 开始，字符串下标从 `1` 开始。 -5. 写字符串区间前先记住 `s[start:end]` 的 `end` 会被包含；不要按半开区间推断。 -6. 没有已验证代码块时不要发明值写法；尤其不要从 JSON、JavaScript、Pascal 或 C 字符串规则直接迁移。 - -## 必须记住的规则 - -- 最先掌握的几类值是：整数、实数、普通字符串、布尔和 `array(...)`。 -- 普通字符串既可以用双引号，也可以用单引号。 -- 同类引号本身可以通过连续写两个同类引号放进字符串里。 -- `\\`、`\"`、`\n` 这类基础转义已验证可用。 -- `\t` 和 `\xNN` 这类转义也已验证可用。 -- `\r`、`\r\n`、`\a`、`\b`、`\f`、`\v` 这些经典转义也已验证可用。 -- 当前解释器接受 `%%` 原始字符串；开头的 `%%` 或 `%%tag` 后面必须先跟一个空白分隔符，正文才开始。 -- `%%` 原始字符串里的反斜杠不做转义处理，并且支持多行内容。 -- `array(...)` 既可以写顺序数组，也可以写字符串键表。 -- 顺序数组下标从 `0` 开始。 -- `Binary(...)` 创建的二进制缓冲区，当前也用 `[]` 访问，并且下标从 `0` 开始。 -- 字符串下标从 `1` 开始。 -- `s[0]` 在运行时会越界，不要把字符串当成 0 基下标。 -- 字符串取子串用 `s[start:end]`，并且 `end` 是包含在结果里的。 -- 字符串替换子串用 `s[start:end] := "..."`。 -- 字符串删除子串，本质上就是 `s[start:end] := ""`。 -- 字符串插入子串用 `s[index:0] := "..."`。 -- 当前解释器接受 `L""` 与 `U""` 前缀字符串，但当前手册默认仍优先普通字符串。 -- 当前解释器也接受 `L%% ...%%` 与 `U%% ...%%` 前缀原始字符串。 -- 当前最小验证表明：从 `IfWString(...)` 观察，混合拼接时结果是否为宽串，取决于左操作数是否为宽串；`U""` 在这里仍按非宽串处理。 -- 当前最小验证表明：可以用 `String(...)` 把宽串显式转回普通串，也可以用 `WideString(...)` 把普通串显式转成宽串。 -- 当前最小验证表明：`U""` 可以和 `UnicodetoUTF8(...)`、`UTF8ToUnicode(...)`、`UTF8ToAnsi(...)`、`AnsiToUTF8(...)` 组成一条清晰的 UTF8 转换链；`U""` 本身不等同于宽串。 -- 当前最小验证表明：`\uXXXX` 在普通字符串里不要直接当成“单个字符宽串”；例如 `Length("\u0041")` 为 `2`，而 `Length(L"\u0041")` 和 `Length(U"\u0041")` 都为 `1`。 -- 当前最小验证表明：字符串可以包含 ASCII `0` 字符；`\0` 和 `#0` 都能构造这个字符，并且不会把字符串截断。 -- `#number` 可以按字符码直接拼进字符串里；`#13#10` 这类写法可直接形成换行。 - -## 已验证语法 - -最基础的值写法： - -代码块身份：已验证可执行示例 - -```tsl -count := 1; -price := 12.5; -name := "ABC"; -flag1 := true; -flag2 := false; -items := array(1, 2, 3); -WriteLn(count); -WriteLn(price); -WriteLn(name); -WriteLn(flag1); -WriteLn(flag2); -WriteLn(items[1]); -``` - -代码块身份：已验证输出片段 - -```text -1 -12.5 -ABC -1 -0 -2 -``` - -代码块说明：`true` / `false` 可以直接写成布尔值；运行输出里分别表现为 `1` / `0`。 - -普通字符串字面量： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("ABC"); -WriteLn('XYZ'); -``` - -已验证运行结果： - -- 依次输出 `ABC`、`XYZ` - -字符串内引号与基础转义： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("A""B"); -WriteLn('A''B'); -WriteLn("A\\B"); -WriteLn("A\"B"); -WriteLn("A\nB"); -``` - -已验证运行结果： - -- 依次输出 `A"B`、`A'B`、`A\B` -- `"A\nB"` 会分成两行输出 `A` 和 `B` - -更多基础转义： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("A\tB" = "A"#9"B"); -WriteLn("A\x30B" = "A0B"); -``` - -已验证运行结果： - -- 两行都输出 `1` -- 说明 `\t` 可以表示制表符，`\x30` 这类写法可以按 ANSI 字节值插入字符 - -经典控制字符转义： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn("\r" = #13); - WriteLn("\r\n" = #13#10); - WriteLn(Length("\r\n")); - WriteLn("\a" = #7); - WriteLn("\b" = #8); - WriteLn("\f" = #12); - WriteLn("\v" = #11); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1`、`2`、`1`、`1`、`1`、`1` -- 说明 `\r` / `\r\n` 可以直接表示回车和回车换行 -- 说明 `\a`、`\b`、`\f`、`\v` 也已经在当前解释器里拿到正向最小结果 - -`L""` / `U""` 前缀的最小已验证事实： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn(L"A" = L"\u0041"); -WriteLn(U"Hello" = "Hello"); -``` - -已验证运行结果： - -- 依次输出 `1`、`1` -- 说明当前解释器接受 `L""`、`U""` 和 ASCII 范围的 `\u` 表达 -- 但在当前控制台里直接 `WriteLn(L"Hello")` 会显示成带空字节的宽串输出，因此当前手册不把 `L""` 作为默认示例写法 - -非 ASCII 宽串的最小已验证事实： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn(L"\u5929\u8F6F" = L""#0x5929#0x8F6F); -``` - -已验证运行结果： - -- 输出 `1` -- 说明当前解释器接受非 ASCII 宽串的 `\uXXXX` 与 `#0xXXXX` 这两种构造方式 -- 但当前手册仍优先把它们当作边界写法，而不是默认入门写法 - -原始字符串 `%%`： - -代码块身份：已验证可执行示例 - -```tsl -s := %% ABC%%; -WriteLn(s); -``` - -已验证运行结果： - -- 输出 `ABC` -- 说明 `%%` 开头后面的第一个空白只是分隔符，不计入最终字符串内容 - -原始字符串不会处理转义： - -代码块身份：已验证可执行示例 - -```tsl -s := %% a\r\nb%%; -WriteLn(s = "a\\r\\nb"); -``` - -已验证运行结果： - -- 输出 `1` -- 说明 `%%` 原始字符串里的 `\r`、`\n` 只是普通字符，不会变成回车换行 - -带标识符的原始字符串： - -代码块身份：已验证可执行示例 - -```tsl -s := %%tag A"B'C%%tag; -WriteLn(s); -``` - -已验证运行结果： - -- 输出 `A"B'C` -- 说明 `%%tag ...%%tag` 的首尾标识符可以配对使用，正文里可直接放单双引号 - -多行原始字符串： - -代码块身份：已验证可执行示例 - -```tsl -s := %%m -A -B%%m; -WriteLn(s); -``` - -已验证运行结果： - -- 输出两行 `A`、`B` -- 说明 `%%` 原始字符串支持直接跨行 - -带前缀的原始字符串： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn(L%% ABC%% = L"ABC"); -WriteLn(U%% ABC%% = "ABC"); -``` - -已验证运行结果： - -- 依次输出 `1`、`1` -- 说明 `L%% ...%%` 和 `U%% ...%%` 在当前解释器里都可用 - -前缀字符串与混合拼接的最小类型观察： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(IfWString("A" + L"B")); - WriteLn(IfWString(L"A" + "B")); - WriteLn(IfWString(U"A")); - WriteLn(IfWString(U"A" + L"B")); - WriteLn(IfWString(L"A" + U"B")); -end. -``` - -已验证运行结果： - -- 依次输出 `0`、`1`、`0`、`0`、`1` -- 说明从 `IfWString(...)` 的观察角度看，混合拼接是否得到宽串，取决于左操作数是否为宽串 -- 也说明 `U""` 前缀字符串在这里仍按非宽串处理，不等同于 `L""` - -显式字符串类型转换： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a := String(L"abcd"); - b := WideString("abcd"); - WriteLn(a = "abcd"); - WriteLn(IfWString(a)); - WriteLn(b = L"abcd"); - WriteLn(IfWString(b)); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`0`、`1`、`1` -- 说明 `String(...)` 可以把宽串显式转回普通串 -- 说明 `WideString(...)` 可以把普通串显式转成宽串 - -`U""` 与 UTF8 显式转换： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - utf8_s := U"\u5929\u8F6F"; - utf8_s2 := UnicodetoUTF8(L"\u5929\u8F6F"); - wide_s := UTF8ToUnicode(utf8_s); - ansi_s := UTF8ToAnsi(utf8_s); - WriteLn(IfWString(utf8_s)); - WriteLn(utf8_s = utf8_s2); - WriteLn(wide_s = L"\u5929\u8F6F"); - WriteLn(ansi_s = String(L"\u5929\u8F6F")); -end. -``` - -已验证运行结果： - -- 依次输出 `0`、`1`、`1`、`1` -- 说明 `U""` 在当前解释器里不是宽串 -- 说明 `U"\u5929\u8F6F"` 和 `UnicodetoUTF8(L"\u5929\u8F6F")` 可以对应到同一个 UTF8 串 -- 说明 `UTF8ToUnicode(...)` 可以把 UTF8 串转回宽串，`UTF8ToAnsi(...)` 可以把 UTF8 串转回普通串 - -ANSI / UTF8 / 宽串的最小往返： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - ansi_s := String(L"\u5929\u8F6F"); - utf8_s := AnsiToUTF8(ansi_s); - ansi_back := UTF8ToAnsi(utf8_s); - wide_s := UTF8ToUnicode(utf8_s); - WriteLn(IfWString(ansi_s)); - WriteLn(IfWString(utf8_s)); - WriteLn(IfWString(wide_s)); - WriteLn(ansi_back = ansi_s); - WriteLn(wide_s = L"\u5929\u8F6F"); -end. -``` - -已验证运行结果： - -- 依次输出 `0`、`0`、`1`、`1`、`1` -- 说明 `AnsiToUTF8(...)` 产物在这里仍按非宽串处理 -- 说明 `UTF8ToAnsi(...)` 和 `UTF8ToUnicode(...)` 都已经在当前解释器里拿到了正向最小结果 - -`\uXXXX` 在普通字符串、宽串和 `U` 串里的最小边界： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(Length("\u0041")); - WriteLn(Length(L"\u0041")); - WriteLn(Length(U"\u0041")); -end. -``` - -已验证运行结果： - -- 依次输出 `2`、`1`、`1` -- 因此不要把普通字符串里的 `"\u0041"` 直接理解成和 `L"\u0041"` 一样的“单字符宽串”语义 - -ASCII `0` 字符不会截断字符串： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - s1 := "A\0B"; - s2 := "A"#0"B"; - WriteLn(Length(s1)); - WriteLn(Length(s2)); - WriteLn(s1 = s2); - WriteLn(s1[2] = #0); -end. -``` - -已验证运行结果： - -- 依次输出 `3`、`3`、`1`、`1` -- 说明 `\0` 和 `#0` 都可以把 ASCII `0` 放进字符串 -- 也说明当前字符串不是遇到 `#0` 就自动截断的 C 风格零结尾串 - -带 ASCII `0` 的字符串切片仍然保留该字符： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - s := "A"#0"B"; - t := s[1:3]; - WriteLn(Length(t)); - WriteLn(t = s); - u := s[2:2]; - WriteLn(Length(u)); - WriteLn(u = #0); -end. -``` - -已验证运行结果： - -- 依次输出 `3`、`1`、`1`、`1` -- 说明字符串切片和单字符读取对 ASCII `0` 仍然稳定，不会在中间被截断 - -字符码拼接： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("A"#48"B"); -WriteLn("A"#13#10"B"); -``` - -已验证运行结果： - -- 第一行输出 `A0B` -- 第二组输出会分成两行 `A`、`B` -- 说明 `#48` 这类写法会按字符码直接参与字符串拼接，`#13#10` 可直接表示换行 - -代码块身份：已验证可执行示例 - -```tsl -items := array(10, 20, 30); -row := array("Code": "0001", "Price": 12.3); -s := "ABC"; -WriteLn(items[0]); -WriteLn(items[1]); -WriteLn(row["Code"]); -WriteLn(s[1]); -WriteLn(s[2]); -WriteLn(s[3]); -``` - -代码块身份：已验证输出片段 - -```text -10 -20 -0001 -A -B -C -``` - -代码块说明：顺序数组 `items` 从 `0` 开始，字符串键表 `row` 用字符串键访问，字符串 `s` 从 `1` 开始。 - -二进制缓冲区： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - b := Binary("30"); - WriteLn(IfBinary(b)); - WriteLn(b[0] = "3"); - WriteLn(b[1] = "0"); - b[1] := 0x31; - WriteLn(b[1] = "1"); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1`、`1`、`1` -- 说明 `Binary(...)` 当前确实得到二进制缓冲区 -- 说明二进制缓冲区的 `[]` 下标从 `0` 开始 -- 也说明二进制缓冲区项可以直接按单字节读写 - -字符串子串读取： - -代码块身份：已验证可执行示例 - -```tsl -s := "ABCDE"; -WriteLn(s[2:4]); -``` - -代码块身份：已验证输出片段 - -```text -BCD -``` - -代码块说明：字符串区间 `2:4` 会包含结束位 `4`。 - -字符串替换子串： - -代码块身份：已验证可执行示例 - -```tsl -s := "ABCDE"; -s[2:4] := "XYZ"; -WriteLn(s); -``` - -已验证运行结果： - -- 输出 `AXYZE` - -字符串删除子串： - -代码块身份：已验证可执行示例 - -```tsl -s := "ABCDE"; -s[2:4] := ""; -WriteLn(s); -``` - -已验证运行结果： - -- 输出 `AE` - -字符串插入子串： - -代码块身份：已验证可执行示例 - -```tsl -s := "AAABBB"; -s[4:0] := "111"; -WriteLn(s); -``` - -已验证运行结果： - -- 输出 `AAA111BBB` -- 这说明 `s[index:0] := ...` 是在指定位置插入，而不是删除或替换区间 - -## 最小可编译示例 - -如果你只是要抓住“基本类型 + array”的第一层，用这个最短例子： - -代码块身份：已验证可执行示例 - -```tsl -count := 1; -price := 12.5; -name := "ABC"; -flag := true; -items := array(1, 2, 3); -``` - -## 常见误写 - -- 用 `s[0]` 访问字符串首字符。 -- 误以为 `array(...)` 只能写顺序数组，不能写字符串键表。 -- 误以为字符串区间和数组一样从 `0` 开始。 -- 把 `s[index:0] := ...` 误解成“替换到第 0 位”。 -- 把二进制缓冲区也按字符串的 `1` 基下标去理解。 -- 在普通字符串示例里默认切到 `L""`，却没有先确认下游场景真的需要宽串。 -- 把 `U""` 误解成和 `L""` 一样的宽串。 -- 把普通字符串里的 `"\uXXXX"` 直接当成和 `L"\uXXXX"` 一样的单字符写法。 -- 把带 `#0` / `\0` 的字符串当成会自动截断的 C 风格零结尾串。 -- 把 `%%ABC%%` 当成合法的原始字符串起手式。 - -代码块身份：反例 / 不可照写 - -```text -s := "ABC"; -WriteLn(s[0]); -``` - -上面这类写法在运行时会报字符串下标越界。 - -代码块身份：已验证输出片段 - -```text -String index out of bounds -``` - -代码块身份：反例 / 不可照写 - -```text -s := "ABCDE"; -WriteLn(s[1:3]); -``` - -不要把上面这个区间访问类比成数组切片的半开区间。当前解释器里它输出的是 `ABC`，不是 `AB`；字符串区间的结束位会被包含进结果。 - -代码块身份：反例 / 不可照写 - -```text -s := %%ABC%%; -``` - -上面这种写法在当前解释器里会报 `missing or invalid characters`。`%%` -原始字符串开头后面必须先跟一个空白分隔符，或者写成 `%%tag` -这种“标识符 + 空白”形式。 - -代码块身份：反例 / 不可照写 - -```text -WriteLn(Length("\u0041")); -WriteLn(Length(L"\u0041")); -``` - -不要把上面这两行想成同一件事。当前解释器里前者输出 `2`，后者输出 `1`；普通字符串里的 `\uXXXX` 不能直接按宽串单字符去理解。 - -代码块身份：反例 / 不可照写 - -```text -WriteLn(IfWString(U"\u5929\u8F6F")); -WriteLn(IfWString(L"\u5929\u8F6F")); -``` - -不要把 `U""` 和 `L""` 当成同一种“宽串前缀”。当前解释器里前者输出 `0`，后者输出 `1`。 - -代码块身份：反例 / 不可照写 - -```text -s := "A"#0"B"; -WriteLn(Length(s)); -``` - -不要把上面这类字符串想成遇到 `#0` 就结束。当前解释器里这里输出 `3`，说明 ASCII `0` 是字符串内容的一部分。 - -## 跳转指引 - -- 值有了名字以后怎么看：见 [05_variables_and_constants.md](05_variables_and_constants.md) -- 值怎样组成表达式：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 看字符串与编码深水专题：见 [20_strings_and_text.md](20_strings_and_text.md) diff --git a/docs/tsl/syntax/04_variables_and_constants.md b/docs/tsl/syntax/04_variables_and_constants.md new file mode 100644 index 00000000..dc65df67 --- /dev/null +++ b/docs/tsl/syntax/04_variables_and_constants.md @@ -0,0 +1,376 @@ +# TSL 变量与常量 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇收拢变量与常量初始化规则。 + +## 本篇职责 + +回答“普通变量怎样直接使用、`var` 在什么位置出现、常量必须怎样初始化、哪些名字一旦绑定就不能再赋值”。 + +## 智能体变量/常量判断流程 + +1. 普通变量默认直接用 `:=` 首次赋值，不要先补一个没有需求证据的 `var` 段。 +2. 只有用户要求显式声明或遇到 `{$explicit+}` 时才优先写 `var`。 +3. 常量声明必须同时初始化；默认只生成 `const name = value;`，顶层脚本常量需要后续脚本语句时，仍按 `.tsl` 语句区规则组织。 +4. 多参数赋值按 `[a, b] := array(...)` 写；单变量拆包必须写成 `[name, ] := array(...)`。 +5. 如果问题已经变成表达式求值、函数参数、运行时类型 / 转换、或 `{$explicit+}` 之外的编译选项，不要留在变量页硬推断；分别跳到 [06_expressions_and_operators.md](06_expressions_and_operators.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[17_types_and_conversions.md](17_types_and_conversions.md) 或 [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)。 +6. 没有对应代码块时不要发明变量/常量写法；尤其不要从 Pascal 的声明习惯反推 TSL 必须先声明变量。 + +## 核心规则 + +- 默认变量模型是“直接赋值即得到变量”，不要求先写 `var`。 +- 例如：`a := 1; b := array(1, 2, 3);` 这种写法可直接编译。 +- `var name;` 只作为显式声明写法，不能当成默认必需步骤。 +- `const name = value;` 是常量初始化的默认生成写法；`const` 不能只声明名字而不初始化。 +- 文档规则： + - `const name = value;` 适合顶层脚本常量、函数内部 `const` 段、`unit` 接口常量、类成员常量。 + - 顶层脚本里的 `const name = value;` 可以放在后续脚本语句之前；单独只写一行 `const name = value;` 不作为可运行脚本骨架。 +- 函数内部 `const = expr`、以及松散脚本顶层的 `const = expr`，都可以把右侧写成常量表达式。 +- 用 `const =` 初始化的这些常量不能再次赋值。 +- 多参数赋值文档明确写法是 `[a, b] := array(...)`。 +- 左侧只有一个变量时，末尾逗号不能省略，必须写成 `[a, ] := array(...)`。 +- 当左侧变量数大于右侧数组长度时，多出的变量会得到 `nil`。 +- 右侧数组元素也可以是数组；拆出来的变量会直接得到对应子数组。 +- 多参数赋值也可以出现在函数调用参数里。 +- `{$explicit+}` 开启后，后续变量必须先用 `var` 声明；未声明变量会报 `variable not defined`。 + +## 可直接照写示例 + +使用这些示例时遵守： + +- 默认生成普通变量时直接用 `:=`；只有用户明确要求或 `{$explicit+}` 场景才复制 `var`。 +- 普通示例默认按 `.tsl` 脚本语句区书写；需要函数或类型时，放在后置声明区。 +- 复制常量示例时只使用 `const name = value;`。 + +### 普通变量与显式声明 + +默认变量模型： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +b := array(1, 2, 3); +writeLn(a); +writeLn(b[1]); +``` + +代码块身份：输出片段 + +```text +1 +2 +``` + +显式 `var` 写法： + +代码块身份：可直接照写示例 + +```tsl +var a; +a := 1; +``` + +`{$explicit+}` 下的显式声明： + +代码块身份：可直接照写示例 + +```tsl +{$explicit+} +var a; +a := 1; +writeLn(a); +``` + +代码块身份：输出片段 + +```text +1 +``` + +### 常量初始化 + +顶层最稳的常量写法： + +代码块身份：可直接照写示例 + +```tsl +const value = 1; +echo value; +``` + +代码块身份：输出片段 + +```text +1 +``` + +顶层 `const =` 也可以写常量表达式： + +代码块身份：可直接照写示例 + +```tsl +const value = 1 + 2 * 3; +writeLn(value); +``` + +代码块身份：输出片段 + +```text +7 +``` + +函数内部 `const` 段： + +代码块身份：可直接照写示例 + +```tsl +function Demo(); +const max_retries = 1 + 2 * 3; +begin + return max_retries; +end; +``` + +`unit` 接口常量： + +代码块身份：可直接照写示例 + +```tsl +unit DemoUnit; + +interface + +const value = 1; +function GetValue(); + +implementation + +function GetValue(); +begin + return value; +end; + +end. +``` + +类成员常量： + +代码块身份：可直接照写示例 + +```tsl +type DemoType = class +public + const value = 1; +end; +``` + +顶层 `const =` 只有在“后面继续接可执行语句”的脚本模型里才成立： + +代码块身份：可直接照写示例 + +```tsl +const max_retries = 3 + 4; +value := max_retries; +``` + +### 多参数赋值 + +多参数赋值： + +代码块身份：可直接照写示例 + +```tsl +[r1, r2] := array(1, 3, 5, 7, 9); +writeLn(r1); +writeLn(r2); +``` + +代码块身份：输出片段 + +```text +1 +3 +``` + +单变量拆包时，末尾逗号不能省略： + +代码块身份：可直接照写示例 + +```tsl +[re, ] := array(1, 2, 3, 4); +writeLn(re); +``` + +代码块身份：输出片段 + +```text +1 +``` + +左侧变量比右侧数组更长时，多出的变量为 `nil`： + +代码块身份：可直接照写示例 + +```tsl +[r1, r2] := array(1); +writeLn(r1); +writeLn(r2 = nil); +``` + +代码块身份：输出片段 + +```text +1 +1 +``` + +右侧元素也可以是数组： + +代码块身份：可直接照写示例 + +```tsl +[r1, r2] := array((1, 2), (3, 4)); +writeLn(r1[0]); +writeLn(r1[1]); +writeLn(r2[0]); +writeLn(r2[1]); +``` + +结果说明： + +- 依次输出 `1`、`2`、`3`、`4` + +代码块身份：输出片段 + +```text +1 +2 +3 +4 +``` + +函数返回数组后也可以直接拆包： + +代码块身份：可直接照写示例 + +```tsl +[error, re] := PairAdd(3, 4); +writeLn(error); +writeLn(re); + +function PairAdd(a, b); +begin + return array(0, a + b); +end; +``` + +结果说明： + +- 依次输出 `0`、`7` + +代码块身份：输出片段 + +```text +0 +7 +``` + +函数参数里也可以使用多参数赋值： + +代码块身份：可直接照写示例 + +```tsl +writeLn(Test(e := 3, [f, g] := array(1, 2), g)); + +function Test(a, b, c); +begin + return a + b + c; +end; +``` + +结果说明： + +- 输出 `6` + +代码块身份：输出片段 + +```text +6 +``` + +## 默认生成模板 + +普通变量和顶层常量的默认骨架如下： + +代码块身份：可直接照写示例 + +```tsl +const max_retries = 3; +counter := max_retries; +items := array(1, 2, 3); +``` + +## 禁止项 + +- 以为普通变量必须先写 `var` 才能使用。 +- 把常量初始化写成普通变量赋值风格。 +- 以为 `const =` 顶层单独写一行就一定成立。 +- 以为 `const` 可以只声明名字，不写初始化表达式。 +- 以为单变量拆包可以写成 `[a] := array(...)`。 +- 以为 `{$explicit+}` 开启后仍然可以继续直接写未声明变量。 + +代码块身份：反例 / 不可照写 + +```text +const value = 1; +value := 2; +``` + +上面这类写法会编译失败，报错点在重新赋值这一行。 + +代码块身份：反例 / 不可照写 + +```text +const value = 1; +``` + +上面这类“顶层单独一行”的 `const =` 也会编译失败。 + +代码块身份：反例 / 不可照写 + +```text +const value; +``` + +上面这类没有初始化表达式的 `const` 会编译失败；`const` 必须写初始化值。 + +错误原因是常量语句缺少初始化表达式。 + +代码块身份：反例 / 不可照写 + +```text +[re] := array(1, 2, 3); +``` + +上面这种单变量拆包写法会报 `left side can not be assign to`。单变量时必须写成 `[re, ] := ...`。 + +代码块身份：反例 / 不可照写 + +```text +{$explicit+} +a := 1; +``` + +上面这类写法会编译失败，主因是 `variable not defined`。 + +代码块身份：输出片段 + +```text +variable not defined +``` diff --git a/docs/tsl/syntax/05_functions_and_calls.md b/docs/tsl/syntax/05_functions_and_calls.md new file mode 100644 index 00000000..1bdbe7ea --- /dev/null +++ b/docs/tsl/syntax/05_functions_and_calls.md @@ -0,0 +1,988 @@ +# TSL 函数与调用 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[09_units_and_scope.md](09_units_and_scope.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[18_external_calls_and_threads.md](18_external_calls_and_threads.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只负责 `function` / `procedure` 的定义、调用、参数传递和值返回。跨 `unit` 声明边界、外部系统交互和业务函数库只在本页保留路由或最小边界。 + +## 本篇职责 + +回答“如何正确声明 `function` 和 `procedure`、`.tsl` 脚本语句区如何调用后置函数声明、怎样使用参数修饰、普通函数默认参数与可变参数，以及哪些函数写法会直接编译失败”。 + +## 智能体函数/调用判断流程 + +1. 先判断目标文件是 `.tsl` 还是 `.tsf`；文件形态不明确时回 [02_core_model.md](02_core_model.md)。 +2. `.tsl` 中先写语句区，再把 `function` / `procedure` 声明放在后面；不要在声明区后面追加脚本语句。 +3. `.tsf` 中把顶层 `function` / `procedure` 当成模块 / 函数扩展声明；不要写成顺序执行入口。 +4. 用户只说“写一个函数”且没有指定 `procedure` 时，默认用 `function`。 +5. 只有用户明确要求 `procedure` / 过程时，才用 `procedure`；即使任务没有返回值，也默认用 `function`。 +6. 调用普通 TSL 函数时，命名参数只写 `name: value`；不要把 `name = value` 当成命名参数。 +7. 参数是否写回调用方要看 `const` / `var` / `{$varByRef-}` / `in` / `out`，不要默认按其他语言习惯推断。 +8. 默认参数先按普通函数规则处理；涉及 `unit interface` 或 `unit const` 默认值时，跳到 [09_units_and_scope.md](09_units_and_scope.md)。 +9. 匿名函数和 TSL 函数值只按本页明确的 `call(f, ...)` / `##f(...)` 生成；`external`、原生函数指针包装、C 回调、线程和系统交互跳到 [18_external_calls_and_threads.md](18_external_calls_and_threads.md)。 +10. 没有对应代码块时不要发明函数/调用写法；尤其不要把二进制函数、系统函数、TSL 函数值、原生函数指针和匿名函数都套成同一种调用语法。 + +## 核心规则 + +- 最稳妥的函数骨架仍然是 `function Name(...); begin ... end;`。 +- 用户提示词里的“函数”默认对应 `function`，不要自动改写成 `procedure`。 +- `procedure Name(...); begin ... end;` 只在用户明确要求 `procedure` / 过程时生成；不要因为没有返回值就自动改用 `procedure`。 +- 在 `.tsl` 文件模型层，脚本语句后可以接函数声明；语句区在前顺序执行，声明区在后提供函数/过程定义。见 [02_core_model.md](02_core_model.md)。 +- 在 `.tsf` 文件模型层，顶层 `function` / `procedure` 是模块/函数扩展声明；部署到解释器 `funcext` 后可被脚本直接调用。 +- 函数头后默认保留分号；不要为了简写主动省略。 +- 一个函数定义体里可以同时出现主函数和子函数。 +- 函数支持参数类型注解和返回值类型注解。 +- 不带类型注解时，多个参数用逗号分隔。 +- 带类型注解时，多个参数用分号分隔。 +- 没有明确类型名证据时，不要为了“看起来更完整”而发明参数类型或返回类型。 +- `const` 与 `var` 形参修饰属于文档明确写法。 +- 按文档运行时边界，未修饰参数可以写回调用方；这是运行时默认行为，不是语言规范保证。 +- `{$varByRef-}` 会把未修饰参数切换成按值传递；`var` 形参仍保持引用语义。 +- 在 `{$varByRef-}` 下，调用时可以用 `in` / `out` 前缀逐个参数覆盖默认传递方式。 +- 如果不确定任务是否需要写回语义，优先显式用 `const` 形参，或先切到 `{$varByRef-}`；不要依赖未修饰参数的运行时默认行为。 +- `return expr;` 会直接返回当前函数结果。 +- `exit;` 会立即结束当前函数；在本页最小样例里，如果此前没有写入返回结果，调用方观察到的是默认值 `0`。 +- 调用时支持命名参数，写法是 `name: value`。 +- 命名参数也支持 `call(...)` 这类按函数名或函数指针转调的模型。 +- 一旦某次调用里开始使用命名参数，后面的参数就不能再退回位置参数。 +- 对二进制函数 / 系统函数直接使用命名参数，会报 `named parameter mode can't support here`；这类函数要先用 TSL 再封一层。 +- 函数参数支持默认值。 +- 普通函数的默认值规则不要直接等同到 `unit interface` 声明；跨 `unit` 的默认参数边界只照本页最小反例和 [09_units_and_scope.md](09_units_and_scope.md) 处理。 +- 尾部 `...` 形式的可变参数属于文档明确写法。 +- 在可变参数函数体里，`Params`、`ParamCount`、`RealParamCount` 都可用。 +- 可变参数组可以通过 `...` 转发给另一个函数调用。 +- 可变参数组也可以通过 `call(fc, ...)`、`##fc(...)`、`invoke(obj, name, 0, ...)` 转发；这些属于调用转发边界，只在有对应文档明确样例时生成。 +- `a := function(...) begin ... end;` 这种匿名函数写法属于文档明确写法。 +- 匿名函数可以直接作为参数传入另一个函数。 +- `thisFunction(FuncName)` 可以把已知函数绑定成函数值。 +- 匿名函数和 TSL 函数值的稳定调用方式仍是 `call(f, ...)` 或 `##f(...)`。 +- `f(...)` 这种“函数变量直接调用”写法不作为可写事实；无论 `f` 是匿名函数、`findFunction(...)` 还是 `thisFunction(...)` 返回的函数指针，都不要默认写成直调。 +- `::FuncName(...)` 可以指向全局/系统函数，用来绕过当前作用域里的同名局部函数。 +- `external`、原生函数指针包装、`makeInstance` / C 回调和线程调用统一移到 [18_external_calls_and_threads.md](18_external_calls_and_threads.md)。 +- 不要在 `.tsl` 的函数声明区之后继续追加脚本语句。 + +## 可直接照写示例 + +使用这些示例时遵守： + +- 普通运行示例默认按 `.tsl` 脚本语句区书写；入口语句放前面，函数 / 过程 / 类型声明放在后置声明区。 +- `.tsf` 函数 / 过程示例只按可复用顶层声明理解，不要在 `.tsf` 里追加顺序执行入口语句。 +- `procedure` 示例只在用户明确要求 `procedure` / 过程时复制；普通“写函数”任务不要用。 +- `external`、原生函数指针包装、C 回调、线程、系统交互和二进制函数边界不在本页硬推断；命中这些任务时跳到 [18_external_calls_and_threads.md](18_external_calls_and_threads.md) 或函数库文档。 + +### 基础函数 / 过程骨架 + +`.tsl` 语句区调用后置函数声明： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +test(); + +function test(); +begin + echo "test"; +end; +``` + +代码块身份：输出片段 + +```text +test +``` + +最短函数骨架： + +代码块身份：可直接照写示例 + +```tsl +function Add(a, b); +begin + return a + b; +end; +``` + +主函数加子函数： + +代码块身份：可直接照写示例 + +```tsl +function MultiFunc(); +begin + return Twice(3); +end; + +function Twice(x); +begin + return x * 2; +end; +``` + +显式要求 `procedure` 时的最短骨架： + +代码块身份：可直接照写示例 + +```tsl +procedure LogDone(); +begin +end; +``` + +显式要求 `procedure` 且需要写回参数时的最小运行样例： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +Bump(a); +writeLn(a); + +procedure Bump(var x); +begin + x := x + 1; +end; +``` + +代码块身份：输出片段 + +```text +2 +``` + +### 签名增强 + +带参数类型和返回值类型： + +代码块身份：可直接照写示例 + +```tsl +function Demo(a: integer): integer; +begin + return a; +end; +``` + +带类型时的多参数分隔： + +代码块身份：可直接照写示例 + +```tsl +function Demo(a: integer; b: integer); +begin + return a + b; +end; +``` + +参数修饰： + +代码块身份：可直接照写示例 + +```tsl +a := 10; +writeLn(ReadConst(a)); +SetVar(a); +writeLn(a); + +function ReadConst(const x); +begin + return x + 1; +end; +function SetVar(var x); +begin + x := x + 5; +end; +``` + +结果说明： + +- `ReadConst(a)` 输出 `11` +- `SetVar(a)` 之后，`a` 输出 `15` +- 直接给 `const` 形参赋值会编译失败 + +代码块身份：输出片段 + +```text +11 +15 +``` + +### 参数传递方式 + +未修饰参数默认写回调用方： + +代码块身份：可直接照写示例 + +```tsl +x := 1; +TouchDefault(x); +writeLn(x); + +function TouchDefault(a); +begin + a := 9; +end; +``` + +结果说明： + +- `TouchDefault(x)` 之后，`x` 输出 `9` + +代码块身份：输出片段 + +```text +9 +``` + +`{$varByRef-}` 与 `var` 形参： + +代码块身份：可直接照写示例 + +```tsl +x := 1; +TouchDefault(x); +writeLn(x); +y := 1; +TouchValue(y); +writeLn(y); +z := 1; +TouchForcedVar(z); +writeLn(z); + +function TouchDefault(a); +begin + a := 9; +end; +{$varByRef-} +function TouchValue(a); +begin + a := 8; +end; +function TouchForcedVar(var a); +begin + a := 7; +end; +{$varByRef+} +``` + +结果说明： + +- 默认模式下，`TouchDefault(x)` 后 `x` 输出 `9` +- `{$varByRef-}` 下，未修饰参数版本 `TouchValue(y)` 之后，`y` 仍输出 `1` +- `{$varByRef-}` 下，`var` 形参版本 `TouchForcedVar(z)` 之后，`z` 输出 `7` + +代码块身份：输出片段 + +```text +9 +1 +7 +``` + +`in` / `out` 调用前缀： + +代码块身份：可直接照写示例 + +```tsl +a := 0; +b := 0; +c := 0; +Touch3(a, b, c); +writeLn(a); +writeLn(b); +writeLn(c); +Touch3(in a, out b, c); +writeLn(a); +writeLn(b); +writeLn(c); + +{$varByRef-} +function Touch3(a, b, c); +begin + a := 1; + b := 2; + c := 3; +end; +``` + +结果说明： + +- 在 `{$varByRef-}` 下，直接调用 `Touch3(a, b, c)` 后依次输出 `0`、`0`、`0` +- 同样在 `{$varByRef-}` 下，`Touch3(in a, out b, c)` 后依次输出 `0`、`2`、`0` +- 说明 `in` / `out` 可以在调用点逐个参数覆盖默认传递方式 + +代码块身份：输出片段 + +```text +0 +0 +0 +0 +2 +0 +``` + +### `return` 与 `exit` + +代码块身份：可直接照写示例 + +```tsl +writeLn(Demo(1)); +writeLn(Demo(0)); + +function Demo(x); +begin + if x > 0 then + exit; + return 99; +end; +``` + +结果说明： + +- `Demo(1)` 输出 `0` +- `Demo(0)` 输出 `99` +- 说明 `exit;` 会立即结束当前函数体 +- 在这个最小例子里，因为 `exit;` 之前没有写入返回结果，调用方观察到的是默认值 `0` + +代码块身份：输出片段 + +```text +0 +99 +``` + +### 调用增强 + +命名参数调用： + +代码块身份：可直接照写示例 + +```tsl +writeLn(Pack(a: 1, b: 2)); + +function Pack(a, b); +begin + return a * 10 + b; +end; +``` + +代码块身份：输出片段 + +```text +12 +``` + +结果说明： + +- `Pack(a: 1, b: 2)` 返回 `12` +- `Pack(b: 2, a: 1)` 返回 `12` +- `Pack(1, b: 2)` 返回 `12` + +跳过中间参数时，未命中的参数保持 `nil`： + +代码块身份：可直接照写示例 + +```tsl +TestFunc(1, c: 3); + +function TestFunc(a, b, c); +begin + writeLn(ifNil(b)); + return 0; +end; +``` + +结果说明： + +- 输出 `1` +- 说明 `TestFunc(1, c: 3)` 这种调用里，中间参数 `b` 会保持 `nil` + +代码块身份：输出片段 + +```text +1 +``` + +通过 `call(...)` 也支持命名参数： + +代码块身份：可直接照写示例 + +```tsl +writeLn(call("TestFunc", a: 1, c: 2, b: 3)); + +function TestFunc(a, b, c); +begin + return a * 100 + b * 10 + c; +end; +``` + +结果说明： + +- 输出 `132` +- 说明 `call(...)` 也支持按参数名传值 +- 说明命名参数传入后不再按位置解释，而是按名字绑定到形参 + +代码块身份：输出片段 + +```text +132 +``` + +### 默认参数 + +默认值参数： + +代码块身份：可直接照写示例 + +```tsl +function AddOne(a = 1); +begin + return a + 1; +end; +``` + +带类型时也支持默认值： + +代码块身份：可直接照写示例 + +```tsl +function TypedAdd(a: integer = 1): integer; +begin + return a + 1; +end; +``` + +多个参数时，后面的参数可以带默认值： + +代码块身份：可直接照写示例 + +```tsl +function Pack(a, b = 2); +begin + return a * 10 + b; +end; +``` + +代码块身份：可直接照写示例 + +```tsl +function Pack(a: integer; b: integer = 2): integer; +begin + return a * 10 + b; +end; +``` + +默认值也可以写成表达式： + +代码块身份：可直接照写示例 + +```tsl +function ExprDefault(a = 1 + 2); +begin + return a; +end; +``` + +结果说明： + +- `AddOne()` 返回 `2` +- `AddOne(5)` 返回 `6` +- `TypedAdd()` 返回 `2` +- `TypedAdd(5)` 返回 `6` +- `Pack(1)` 返回 `12` +- `Pack(a: 1)` 返回 `12` +- `ExprDefault()` 返回 `3` + +`unit interface` 声明下的默认参数要单独看。普通函数默认参数可用，不等于跨 `unit` 声明边界也同样可靠。 + +代码块身份：反例 / 不可照写 + +```text +unit UnitConst; +interface + +const default_value = 888; +function F(a, b = 100, c = default_value); +``` + +边界说明： + +- `F(1)` 输出 `101`，`F(1, 2)` 输出 `3` +- 同一组文件下，`UnitConst.default_value` 可读到 `888`，而 `F(1, 2, 3)` 输出 `6` +- 因此不要把“普通函数默认参数可用”直接泛化成“`unit interface` 里引用 `unit const` 的默认参数也同样可靠” +- 这类跨 `unit` 的声明边界，统一回看 [09_units_and_scope.md](09_units_and_scope.md) + +### 可变参数 `...` + +尾部可变参数： + +代码块身份：可直接照写示例 + +```tsl +function SumAll(...); +begin + s := 0; + for i, v in Params do + s := s + v; + return s; +end; +``` + +可变参数转发： + +代码块身份：可直接照写示例 + +```tsl +function Forward(...); +begin + return SumAll(...); +end; + +function SumAll(...); +begin + s := 0; + for i, v in Params do + s := s + v; + return s; +end; +``` + +`ParamCount` 与 `RealParamCount`： + +代码块身份：可直接照写示例 + +```tsl +function CountArgs(a, b, ...); +begin + return ParamCount * 10 + RealParamCount; +end; +``` + +结果说明： + +- `SumAll(1, 2, 3, 4)` 返回 `10` +- `Forward(1, 2, 3, 4)` 返回 `10` +- `CountArgs(1, 2, 3, 4)` 返回 `44` +- `CountArgs(1, 2)` 返回 `22` + +通过 `call` 与 `##` 转发可变参数： + +代码块身份：可直接照写示例 + +```tsl +writeLn(DoFunc("Sum3", 1, 2, 3)); +writeLn(DoFunc2(thisFunction(Sum3), 1, 2, 3)); + +function Sum3(a, b, c); +begin + return a + b + c; +end; +function DoFunc(fc, ...); +begin + return call(fc, ...); +end; +function DoFunc2(fc, ...); +begin + return ##fc(...); +end; +``` + +结果说明： + +- `DoFunc("Sum3", 1, 2, 3)` 输出 `6` +- `DoFunc2(thisFunction(Sum3), 1, 2, 3)` 输出 `6` + +代码块身份：输出片段 + +```text +6 +6 +``` + +通过 `invoke` 转发可变参数： + +代码块身份：可直接照写示例 + +```tsl +writeLn(DoInvoke("Dispatch", "Int", 2, 20, 200)); +writeLn(DoInvoke("Dispatch", "Other", 1, 2, 3)); + +type TestC = class +public + function FuncA(a, b, c); + begin + return a + b + c; + end; + function FuncB(a, b, c); + begin + return a * 100 + b * 10 + c; + end; + function Dispatch(kind, ...); + begin + if kind = "Int" then + begin + return FuncA(...); + end + else + begin + return FuncB(...); + end + end; +end; +function DoInvoke(fc_name, ...); +begin + obj := new TestC(); + return invoke(obj, fc_name, 0, ...); +end; +``` + +结果说明： + +- `DoInvoke("Dispatch", "Int", 2, 20, 200)` 输出 `222` +- `DoInvoke("Dispatch", "Other", 1, 2, 3)` 输出 `123` + +代码块身份：输出片段 + +```text +222 +123 +``` + +### 匿名函数与函数指针 + +匿名函数变量： + +代码块身份：可直接照写示例 + +```tsl +a := function(x, y) +begin + return x + y; +end; +writeLn(call(a, 1, 2)); +writeLn(##a(5, 6)); +``` + +结果说明： + +- `call(a, 1, 2)` 输出 `3` +- `##a(5, 6)` 输出 `11` + +代码块身份：输出片段 + +```text +3 +11 +``` + +匿名函数也可以直接作为参数传入： + +代码块身份：可直接照写示例 + +```tsl +writeLn(Apply(function(x, y) +begin + return x * y; +end)); + +function Apply(fun); +begin + return call(fun, 2, 3); +end; +``` + +结果说明： + +- 输出 `6` + +代码块身份：输出片段 + +```text +6 +``` + +函数指针变量也可以通过 `findFunction(...)` 拿到： + +代码块身份：可直接照写示例 + +```tsl +f := findFunction("Add"); +writeLn(##f(1, 2)); + +function Add(a, b); +begin + return a + b; +end; +``` + +结果说明： + +- 输出 `3` + +代码块身份：输出片段 + +```text +3 +``` + +也可以通过 `thisFunction(...)` 从已知函数名直接拿到： + +代码块身份：可直接照写示例 + +```tsl +f := thisFunction(Add); +writeLn(Call(f, 3, 4)); + +function Add(a, b); +begin + return a + b; +end; +``` + +结果说明： + +- 输出 `7` +- 说明 `thisFunction(Add)` 可以得到稳定可调用的函数值 + +代码块身份：输出片段 + +```text +7 +``` + +直接 `f(...)` 不要当成可靠写法： + +代码块身份：反例 / 不可照写 + +```text +// 匿名函数变量直接调用 +a := function(x, y) +begin + return x + y; +end; +writeLn(a(7, 8)); +``` + +结果说明： + +- 上面这种匿名函数变量直调会报 `function: compile error or not found` +- `findFunction(...)` 和 `thisFunction(...)` 返回的函数值也不要写成 `f(...)` 直调 +- 因此本页只把 `call(f, ...)` 和 `##f(...)` 写成稳定规则 + +### `::` 指向全局函数 + +当当前作用域里有同名局部函数时，可以用 `::FuncName(...)` 指定去调全局/系统函数： + +代码块身份：可直接照写示例 + +```tsl +r := Demo(); +writeLn(r[0]); +writeLn(r[1]); + +function Demo(); +begin + return array(strToInt("123"), ::strToInt("123")); +end; +function strToInt(s); +begin + return 888; +end; +``` + +结果说明： + +- 第一项 `strToInt("123")` 命中局部函数，输出 `888` +- 第二项 `::strToInt("123")` 命中全局系统函数，输出 `123` +- 说明 `::` 可以绕过当前作用域的同名局部函数，直接指向全局/系统函数 + +代码块身份：输出片段 + +```text +888 +123 +``` + +如果 `::FuncName(...)` 指向的全局函数本身不存在，会在运行时报 `function: compile error or not found` + +### 系统交互专题 + +`external`、原生函数指针包装、`makeInstance` / C 回调和线程调用，统一见 [18_external_calls_and_threads.md](18_external_calls_and_threads.md)。这一篇只保留“普通函数怎样定义和调用”的主线。 + +## 默认生成模板 + +如果你只是要写一个能被智能体稳定续写的 `.tsl` 脚本，从语句区起步，需要函数时把声明区放在后面： + +代码块身份：可直接照写示例 + +```tsl +Hello(); + +function Hello(); +begin + echo "hello"; +end; +``` + +如果你要写 `.tsf` 模块/函数扩展，默认从 `function` 骨架起步： + +代码块身份：可直接照写示例 + +```tsl +function HelloValue(); +begin + return 1; +end; +``` + +只有用户明确要求 `procedure` / 过程时，才用下面这个 `.tsf` 骨架： + +代码块身份：可直接照写示例 + +```tsl +procedure HelloProc(); +begin +end; +``` + +## 禁止项 + +- 在 `.tsl` 的声明区后面继续写脚本语句。 +- 用户只说“写一个函数”时，默认改成 `procedure`。 +- 因为任务没有返回值，就自动改成 `procedure`。 +- 为了简写主动省略函数头后的分号；默认保留分号。 +- 以为 `procedure` 只是 `function` 的别名，不涉及参数传递语义。 +- 带类型注解时仍然用逗号分隔参数。 +- 没有类型名证据时，发明说明性参数类型或返回类型。 +- 以为默认未修饰参数天然就是按值传递。 +- 把 `a = 1` 这种比较表达式误当成命名参数调用。 +- 以为默认值只能用于无类型参数。 +- 在 `const` 形参上直接赋值。 +- 把普通函数的默认值规则原样套到 `unit interface` 里的 `const` 默认参数上。 +- 把匿名函数或 `findFunction(...)` 返回值默认写成 `f(...)` 直调。 +- 把命名参数直接套到二进制函数或系统函数上。 +- 在一次调用里先进入命名参数模式，后面又退回位置参数。 + +代码块身份：反例 / 不可照写 + +```text +a := 1; +Add(1, 2); + +function Add(a, b); +begin + return a + b; +end; + +echo "after function"; +``` + +上面的问题不在 `Add` 本身，而在于 `.tsl` 的函数声明区后面又继续出现脚本语句。正确做法是把会执行的语句全部放在声明区之前。 + +代码块身份：输出片段 + +```text +invalid statement +``` + +代码块身份：反例 / 不可照写 + +```text +function Demo(a: integer, b: integer); +begin + return a + b; +end; +``` + +上面这种写法会编译失败；参数一旦带类型，分隔符应改成分号。 + +代码块身份：反例 / 不可照写 + +```text +Pack(a = 1, b = 2); +``` + +这类写法不要当成命名参数。它虽然可能编译通过，但文档结果不符合命名参数语义，不能当成可靠的命名参数语法。 + +代码块身份：反例 / 不可照写 + +```text +function Demo(a: integer, b: integer = 2): integer; +begin + return a + b; +end; +``` + +上面这种写法也不对；参数一旦带类型，分隔符仍然应保持分号。 + +代码块身份：反例 / 不可照写 + +```text +function TouchDefault(a); +begin + a := 9; +end; +``` + +不要把上面这种未修饰参数自动理解成“按值传递”。按文档边界，它会把调用方实参改掉；如果任务要求按值语义，先看 `{$varByRef-}` 和 `in` / `out` 的例子。 + +代码块身份：反例 / 不可照写 + +```text +function Bad(const x); +begin + x := 2; +end; +``` + +上面这种写法会编译失败；`const` 形参不能被重新赋值。 + +代码块身份：反例 / 不可照写 + +```text +unit UnitConst; +interface + +const default_value = 888; +function F(a, b = 100, c = default_value); +``` + +不要把上面这种 `unit interface` 声明直接当成已经等价于普通函数默认参数规则。按文档结果，对应的 `F(1)` 输出是 `101`，不是按 `default_value = 888` 补成的结果；具体边界见 [09_units_and_scope.md](09_units_and_scope.md)。 + +代码块身份：反例 / 不可照写 + +```text +a := function(x, y) +begin + return x + y; +end; +writeLn(a(7, 8)); +``` + +不要把上面这种匿名函数变量的直调写法直接当成可靠规则。它会报 `function:a compile error or not found`；稳定写法仍然是 `call(a, 7, 8)` 或 `##a(7, 8)`。 + +代码块身份：反例 / 不可照写 + +```text +writeLn(intToStr(value: 200)); +``` + +不要把上面这种写法直接套到二进制函数或系统函数上。它会报 `named parameter mode can't support here`；如果确实要命名传参，先用 TSL 函数再封一层。 + +代码块身份：反例 / 不可照写 + +```text +function Pack(a, b, c); +begin + return a * 100 + b * 10 + c; +end; +begin + writeLn(Pack(a: 1, 2, c: 3)); +end. +``` + +不要在同一次调用里“先进入命名参数模式，再退回位置参数”。这类写法会直接编译失败，错误信息包含 `paramname: not found`。 diff --git a/docs/tsl/syntax/05_variables_and_constants.md b/docs/tsl/syntax/05_variables_and_constants.md deleted file mode 100644 index 0f0b1507..00000000 --- a/docs/tsl/syntax/05_variables_and_constants.md +++ /dev/null @@ -1,344 +0,0 @@ -# Variables And Constants - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[04_values_and_literals.md](04_values_and_literals.md)、[06_functions_and_calls.md](06_functions_and_calls.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 5 篇，共 32 篇。上一篇：[04_values_and_literals.md](04_values_and_literals.md)。下一篇：[06_functions_and_calls.md](06_functions_and_calls.md)。 - -这一篇收拢变量、常量与两种常量写法。 - -## 这一篇解决什么问题 - -回答“普通变量怎样直接使用、`var` 在什么位置出现、常量有哪些基本写法、哪些名字一旦绑定就不能再赋值”。 - -## Agent 变量/常量判断流程 - -1. 普通变量默认直接用 `:=` 首次赋值，不要先补一个没有需求证据的 `var` 段。 -2. 只有用户要求显式声明或遇到 `{$Explicit+}` 时才优先写 `var`。 -3. 顶层脚本常量优先用 `const name := value;`；需要后续脚本语句时，仍按 `.tsl` 语句区规则组织。 -4. `const Name = value;` 优先放在函数 `const` 段、`unit` 接口或类成员里；不要和顶层 `const :=` 任意互换。 -5. 多参数赋值按 `[a, b] := array(...)` 写；单变量拆包必须写成 `[name, ] := array(...)`。 -6. 没有已验证代码块时不要发明变量/常量写法；尤其不要从 Pascal 的声明习惯反推 TSL 必须先声明变量。 - -## 必须记住的规则 - -- 默认变量模型是“直接赋值即得到变量”，不要求先写 `var`。 -- 例如：`a := 1; b := array(1, 2, 3);` 这种写法已验证可直接编译。 -- `var name;` 目前只能当成一种显式声明写法，不能当成默认必需步骤。 -- `const Name = value;` 和 `const name := value;` 不能当成完全等价的两种写法。 -- 已验证： - - `const Name = value;` 适合函数内部 `const` 段、`unit` 接口常量、类成员常量。 - - `const name := value;` 适合顶层直接写的常量，单独成段也能编译。 -- 当前已验证：函数内部 `const = expr`、以及松散脚本顶层的 `const = expr` / `const := expr`，都可以把右侧写成常量表达式。 -- 这两种常量在当前解释器里都不能再次赋值。 -- 当前解释器接受多参数赋值：`[a, b] := array(...)`。 -- 左侧只有一个变量时，末尾逗号不能省略，必须写成 `[a, ] := array(...)`。 -- 当左侧变量数大于右侧数组长度时，多出的变量会得到 `nil`。 -- 右侧数组元素也可以是数组；拆出来的变量会直接得到对应子数组。 -- 多参数赋值也可以出现在函数调用参数里。 -- 截至 `2026-04-15` 的最小验证里，`{$Explicit+}` 开启后，后续变量必须先用 `var` 声明；未声明变量会报 `variable not defined`。 - -## 已验证语法 - -默认变量模型： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -b := array(1, 2, 3); -WriteLn(a); -WriteLn(b[1]); -``` - -代码块身份：已验证输出片段 - -```text -1 -2 -``` - -显式 `var` 写法： - -代码块身份：已验证可执行示例 - -```tsl -var a; -a := 1; -``` - -`{$Explicit+}` 下的显式声明： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin -{$Explicit+} - var a; - a := 1; - WriteLn(a); -end. -``` - -代码块身份：已验证输出片段 - -```text -1 -``` - -顶层最稳的常量写法： - -代码块身份：已验证可执行示例 - -```tsl -const value := 1; -``` - -顶层 `const :=` 也可以写常量表达式： - -代码块身份：已验证可执行示例 - -```tsl -const value := 1 + 2 * 3; -WriteLn(value); -``` - -代码块身份：已验证输出片段 - -```text -7 -``` - -函数内部 `const` 段： - -代码块身份：已验证可执行示例 - -```tsl -function Demo(); -const MaxRetries = 1 + 2 * 3; -begin - return MaxRetries; -end; -``` - -`unit` 接口常量： - -代码块身份：已验证可执行示例 - -```tsl -unit DemoUnit; -interface -const value = 1; -function GetValue(); -implementation -function GetValue(); -begin - return value; -end; -end. -``` - -类成员常量： - -代码块身份：已验证可执行示例 - -```tsl -type DemoType = class - const value = 1; -end; -``` - -顶层 `const =` 只有在“后面继续接可执行语句”的脚本模型里才已验证成立： - -代码块身份：已验证可执行示例 - -```tsl -const MaxRetries = 3 + 4; -value := MaxRetries; -``` - -代码块身份：已验证可执行示例 - -```tsl -var a; -a := 1; -``` - -多参数赋值： - -代码块身份：已验证可执行示例 - -```tsl -[r1, r2] := array(1, 3, 5, 7, 9); -WriteLn(r1); -WriteLn(r2); -``` - -代码块身份：已验证输出片段 - -```text -1 -3 -``` - -单变量拆包时，末尾逗号不能省略： - -代码块身份：已验证可执行示例 - -```tsl -[re, ] := array(1, 2, 3, 4); -WriteLn(re); -``` - -代码块身份：已验证输出片段 - -```text -1 -``` - -左侧变量比右侧数组更长时，多出的变量为 `nil`： - -代码块身份：已验证可执行示例 - -```tsl -[r1, r2] := array(1); -WriteLn(r1); -WriteLn(r2 = nil); -``` - -代码块身份：已验证输出片段 - -```text -1 -1 -``` - -右侧元素也可以是数组： - -代码块身份：已验证可执行示例 - -```tsl -[r1, r2] := array((1, 2), (3, 4)); -WriteLn(r1[0]); -WriteLn(r1[1]); -WriteLn(r2[0]); -WriteLn(r2[1]); -``` - -已验证运行结果： - -- 依次输出 `1`、`2`、`3`、`4` - -函数返回数组后也可以直接拆包： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function PairAdd(a, b); -begin - return array(0, a + b); -end; -begin - [error, re] := PairAdd(3, 4); - WriteLn(error); - WriteLn(re); -end. -``` - -已验证运行结果： - -- 依次输出 `0`、`7` - -函数参数里也可以使用多参数赋值： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Test(a, b, c); -begin - return a + b + c; -end; -begin - WriteLn(Test(e := 3, [f, g] := array(1, 2), g)); -end. -``` - -已验证运行结果： - -- 输出 `6` - -## 最小可编译示例 - -如果你只是想先落一个可续写的普通变量和顶层常量骨架，用下面这组： - -代码块身份：已验证可执行示例 - -```tsl -const MaxRetries := 3; -counter := MaxRetries; -items := array(1, 2, 3); -``` - -## 常见误写 - -- 以为普通变量必须先写 `var` 才能使用。 -- 以为 `const =` 和 `const :=` 只是初始化方式不同，可以在任何上下文里互换。 -- 以为 `const =` 顶层单独写一行就一定成立。 -- 以为单变量拆包可以写成 `[a] := array(...)`。 -- 以为 `{$Explicit+}` 开启后仍然可以继续直接写未声明变量。 - -代码块身份：反例 / 不可照写 - -```text -const value := 1; -value := 2; -``` - -上面这类写法会编译失败，报错点在重新赋值这一行。 - -代码块身份：反例 / 不可照写 - -```text -const value = 1; -``` - -上面这类“顶层单独一行”的 `const =` 在当前解释器里也会编译失败。 - -代码块身份：反例 / 不可照写 - -```text -[re] := array(1, 2, 3); -``` - -上面这种单变量拆包写法在当前解释器里会报 `left side can not be assign to`。单变量时必须写成 `[re, ] := ...`。 - -代码块身份：反例 / 不可照写 - -```text -program test; -begin -{$Explicit+} - a := 1; -end. -``` - -上面这类写法在当前解释器里会编译失败，主因是 `variable not defined`。 - -代码块身份：已验证输出片段 - -```text -variable not defined -``` - -## 跳转指引 - -- 回看基本类型：见 [04_values_and_literals.md](04_values_and_literals.md) -- 进入表达式：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 看词法和编译选项：见 [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) -- 看类型与转换：见 [19_types_and_conversions.md](19_types_and_conversions.md) diff --git a/docs/tsl/syntax/06_expressions_and_operators.md b/docs/tsl/syntax/06_expressions_and_operators.md new file mode 100644 index 00000000..2f35d8b6 --- /dev/null +++ b/docs/tsl/syntax/06_expressions_and_operators.md @@ -0,0 +1,743 @@ +# TSL 表达式与运算符 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页表格和专题入口继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[04_variables_and_constants.md](04_variables_and_constants.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[07_control_flow.md](07_control_flow.md)、[08_objects_and_classes.md](08_objects_and_classes.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇集中放语言级表达式与运算符。智能体写代码时，只使用本页和对应专题页已经本页明确的表达式事实，不要把其他语言或外部资料里的运算符习惯直接搬进 TSL。 + +## 本篇职责 + +回答“赋值、算术、比较、逻辑、位运算、集合/类型关系、条件求值、表达式对象、访问/调用和专题运算符入口在 TSL 里怎样写”。 + +## 智能体表达式/运算符判断流程 + +1. 先判断要写基础表达式运算符，还是集合、矩阵、对象重载、运行时调用或 TS-SQL 这类专题运算符。 +2. 普通变量赋值只能用 `:=`，不要把 `=` 当赋值写法；`const name = value;` 是常量初始化规则，回看 [04_variables_and_constants.md](04_variables_and_constants.md)。 +3. 在普通表达式里，比较才用 `=`，并且把比较表达式放在 `writeLn(...)`、条件或其他需要布尔值的位置。 +4. 函数签名里的默认参数 `name = value` 不是比较表达式；默认参数规则回 [05_functions_and_calls.md](05_functions_and_calls.md)。 +5. 普通算术优先使用 `+`、`-`、`*`、`/`、`%`；整数除法和取模可用 `div`、`mod`；幂运算用 `^`；一元倒数用 `!x`。 +6. 逻辑表达式优先使用 `and`、`or`、`not`；`&&`、`||` 也已可用，但不要把 `!` 写成逻辑非。 +7. 已有变量做原地更新时，才使用 `+=`、`-=`、`*=`、`/=`、`%=`、`^=`、`.&=`、`.|=`、`.^=`、`a++;`、`a--;`、`++a;`、`--a;`。 +8. 条件求值优先用 `flag ? true_value : false_value`；需要 Pascal 风格时可用 `if condition then true_value else false_value` 的形态，但必须带 `else`。 +9. 需要延迟求值或动态表达式对象时，才使用 `@expr` 或 `&"..."`，并用本页明确的 `eval(...)` 形态求值。 +10. 空安全访问只照本页文档明确形态写：`a?.member`、`a?.[index]`、以及 `c?.a?.[1]`。不要外推成任意深度、任意组合都可写。 +11. 需要连续比较时，标量用 `:<` / `:>` 这组链式比较；数组逐元素比较用 `::<` / `::>` 这组矩阵链式比较。 +12. 命中集合、矩阵、对象重载、函数值调用、网格调用、运行时后缀或 TS-SQL 时，按“专题运算符入口表”跳到对应页面。 +13. `{$ifdef ...}` 只作为能力探测；编译选项边界回 [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)。 +14. 任务需要的运算符没有文档事实时，不要生成猜测写法；只能切到对应专题页、项目自身文档或项目专属规则，仍无结论时记录文档缺口。 + +## 核心规则 + +- 本页是 TSL 表达式与运算符的生成规则页；写代码时只使用本页或对应专题页明确记录的运算符和表达式形态。 + +### 本页直接生成的运算符 + + +| 类别 | 运算符 / 形态 | 生成规则 | +| --- | --- | --- | +| 普通赋值 | `:=` | 变量赋值默认只用 `:=`。 | +| 常量初始化 | `const name = value;` | 这是常量声明规则，不按普通赋值处理。 | +| 函数默认参数 | `name = value` | 这是函数签名规则，不按比较表达式处理。 | +| 复合赋值 | `+=`、`-=`、`*=`、`/=`、`%=`、`^=`、`.&=`、`.|=`、`.^=` | 已有变量需要原地更新时使用。 | +| 自增 / 自减 | `a++`、`a--`、`++a`、`--a` | 普通数字变量可直接用；对象重载语义回 [24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)。 | +| 算术 | `+`、`-`、`*`、`/`、`%`、`div`、`mod`、`^` | 普通数值计算使用；`^` 是幂运算。 | +| 一元正负号 | `+x`、`-x` | 可直接用于数值表达式。 | +| 一元倒数 | `!x` | 整型、实型输入返回实型倒数；矩阵逆/广义逆回 [22_matrix_deep_dive.md](22_matrix_deep_dive.md)。 | +| 字符串连接 | `+`、`$` | 字符串拼接两种写法都已写入文档；默认优先用 `+`。 | +| 比较 | `=`、`<>`、`<`、`>`、`<=`、`>=` | `=` 只作比较，不作普通赋值。 | +| 逻辑 | `and`、`or`、`not`、`&&`、|| | 默认优先写 `and` / `or` / `not`；不要用 `!` 表示逻辑非。 | +| 位运算 | `.&`、`.|`、`.^` | 生成代码时写成无空格形态：`.&`、`.|`、`.^`。 | +| 成员 / 下标 / 调用 | `obj.member`、`value[index]`、`Func(args)` | 普通访问和调用可直接使用；类、对象、函数细节回对应专题。 | +| 空安全访问 | `a?.member`、`a?.[index]`、`c?.a?.[1]` | 只按已写入文档形态生成。 | +| 条件求值 | `flag ? true_value : false_value` | 普通条件表达式默认写法。 | +| Pascal 风格条件表达式 | `if condition then true_value else false_value` | 必须带 `else`。 | +| 表达式对象 | `@expr`、`&"..."` | 需要延迟求值或动态表达式对象时使用，并用 `eval(...)` 求值。 | +| 逗号表达式 | `(exp1, exp2, ..., expN)` | 从左到右求值，返回最后一个表达式结果。 | +| 集合 / 匹配 / 类型关系 | `in`、`sqlin`、`like`、`is` | 否定形态见下一行；集合运算回 [12_matrix_and_collections.md](12_matrix_and_collections.md)。 | +| 否定关系 | `not in`、`not sqlin`、`not like`、`not is` | 直接使用这几种文档明确形态，不自行重组。 | +| 标量链式比较 | `:<`、`:>`、`:<>`、`:==`、`:>=`、`:<=` | 连续标量比较才使用。 | +| 矩阵链式比较 | `::<`、`::>`、`::<>`、`::==`、`::>=`、`::<=` | 数组逐元素链式比较才使用；数组与矩阵样数据细节回 [12_matrix_and_collections.md](12_matrix_and_collections.md)。 | + +### 专题运算符入口 + +| 运算符 / 形态 | 责任页 | 生成规则 | +| --- | --- | --- | +| `call(f, ...)`、`##f(...)`、`::FuncName(...)` | [05_functions_and_calls.md](05_functions_and_calls.md) | 函数值调用、变参转发和全局函数限定调用只按函数页生成。 | +| 调用点 `in` / `out`、变参 `...` | [05_functions_and_calls.md](05_functions_and_calls.md) | 这是参数传递 / 变参规则，不按普通表达式运算符处理。 | +| `#Func() with array(...)` | [10_runtime_context_and_with.md](10_runtime_context_and_with.md) | 运行时环境参数调用只按运行时上下文页生成。 | +| `#Func(args)`、`timeout N`、`dupvalue(...)` | [10_runtime_context_and_with.md](10_runtime_context_and_with.md) | 网格调用和运行时服务后缀只按运行时上下文页生成。 | +| `union2`、`intersect`、`minus`、`outersect` | [12_matrix_and_collections.md](12_matrix_and_collections.md) | 行集合并、交、差、对称差只按数组/集合页生成。 | +| `union`、|、`:|` | [23_fmarray.md](23_fmarray.md) | `FMArray` 行拼接和矩阵并右方（按列拼接）只按 `FMArray` 页生成。 | +| `->`、`!matrix` | [22_matrix_deep_dive.md](22_matrix_deep_dive.md) | 数列数组初始化、矩阵逆/广义逆只按矩阵深水页生成。 | +| 反引号转置 `` `value `` | [23_fmarray.md](23_fmarray.md) | `FMArray` 转置只按 `FMArray` 页生成。 | +| `operator +`、`operator <`、`operator[]`、`operator[0]`、`operator[1]`、`operator for`、`operator mrows/mcols/msize`、`operator++`、`operator +=` | [24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md) | 对象运算符重载只按对象重载页生成。 | +| `select` / `sselect` / `vselect` / `mselect`、`where`、`group by`、`order by`、`join` | [14_ts_sql.md](14_ts_sql.md) | TS-SQL 是查询语法，不按普通表达式拼接。 | + + +默认生成规则： + +- 普通变量赋值使用 `:=`；常量初始化不按普通赋值判断，见 [04_variables_and_constants.md](04_variables_and_constants.md)。 +- `=` 在普通表达式里用于比较，不用于赋值。 +- `const name = value;` 和函数签名默认参数 `name = value` 不按本页普通表达式比较判断。 +- 普通算术使用 `+`、`-`、`*`、`/`、`%`、`div`、`mod`、`^`。 +- 需要数值倒数时用 `!x`；整型和实型输入都会得到实型结果。 +- 普通逻辑优先使用 `and`、`or`、`not`；`&&`、`||` 已写入文档但不作为默认主写法。 +- 普通条件求值默认用 `flag ? true_value : false_value`。 +- 需要 Pascal 风格表达式时，才用 `if condition then true_value else false_value`，且必须带 `else`。 +- 字符串拼接默认用 `+`；需要明确字符串连接时也可用 `$`。 +- 字符串匹配用 `like` 时按正则理解，不按 SQL `%` 通配理解。 + +按需生成规则： + +- 已有变量需要原地更新时，才用 `+=`、`-=`、`*=`、`/=`、`%=`、`^=`、`.&=`、`.|=`、`.^=`、`a++;`、`a--;`、`++a;`、`--a;`。 +- 需要矩阵逆/广义逆时才使用 `!A`，并回 [22_matrix_deep_dive.md](22_matrix_deep_dive.md) 确认矩阵生成规则。 +- 位运算需要明确写成点前缀形态：`.&`、`.|`、`.^`；普通 `&` 不作为位与写法使用。 +- 需要延迟求值或动态表达式对象时，才用 `@expr` 或 `&"..."`，并用 `eval(...)` 求值。 +- 需要在一个表达式内按顺序执行多个子表达式时，才用逗号表达式 `(exp1, exp2, ..., expN)`。 +- 空安全访问只按 `a?.member`、`a?.[index]` 和本页示例里的 `c?.a?.[1]` 生成，不外推任意深链。 +- 否定形式只照 `not in`、`not like`、`not sqlin`、`not is` 这几种文档明确写法生成。 +- 连续标量比较才用 `:>`、`:<`、`:<>`、`:==`、`:>=`、`:<=`。 +- 数组逐元素链式比较才用 `::>`、`::<`、`::<>`、`::==`、`::>=`、`::<=`。 + +边界规则： + +- 没有文档事实的运算符，不生成猜测写法，也不从其他语言习惯反推 TSL 语法。 +- `{$ifdef ifexp}` 可用于探测 `if ... then ... else ...` 表达式能力；不要写成普通业务分支。 +- `{$ifdef nilinvoke}` 可用于探测 nil 调用相关能力；编译选项细节见 [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)。 + +## 可直接照写示例 + +使用这些示例时遵守： + +- `:=` 是普通变量赋值写法；常量初始化规则回 [04_variables_and_constants.md](04_variables_and_constants.md)。 +- 函数调用、命名参数、默认参数和函数值调用边界回 [05_functions_and_calls.md](05_functions_and_calls.md)；不要把函数签名里的 `name = value` 当成比较表达式。 +- 分支/循环语句回 [07_control_flow.md](07_control_flow.md)；对象成员和类相关表达式回 [08_objects_and_classes.md](08_objects_and_classes.md)。 +- 字符串字面量、拼接与文本边界回 [03_values_and_literals.md](03_values_and_literals.md)；数组扩展和矩阵样数据回 [12_matrix_and_collections.md](12_matrix_and_collections.md)。 +- `{$ifdef ...}` 能力探测回 [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)，不要写成普通业务逻辑。 + +### 基础赋值和条件求值 + +代码块身份：可直接照写示例 + +```tsl +a := 1; +b := 2; +flag := a < b; +value := flag ? 10 : 20; +writeLn(value); +``` + +代码块身份：输出片段 + +```text +10 +``` + +运算赋值： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +a += 2; +writeLn(a); +``` + +代码块身份：输出片段 + +```text +3 +``` + +基础算术： + +代码块身份：可直接照写示例 + +```tsl +writeLn(1 + 2); +writeLn(5 - 2); +writeLn(3 * 4); +writeLn(8 / 2); +writeLn(9 % 4); +writeLn(9 div 4); +writeLn(9 mod 4); +writeLn(2 ^ 3); +writeLn(-3 + 5); +writeLn(+3); +``` + +代码块身份：输出片段 + +```text +3 +3 +12 +4 +1 +2 +1 +8 +2 +3 +``` + +基础比较： + +代码块身份：可直接照写示例 + +```tsl +writeLn(1 < 2); +writeLn(2 > 1); +writeLn(2 <= 2); +writeLn(2 >= 2); +writeLn(2 = 2); +writeLn(2 <> 3); +``` + +代码块身份：输出片段 + +```text +1 +1 +1 +1 +1 +1 +``` + +一元倒数： + +代码块身份：可直接照写示例 + +```tsl +a := 2; +b := 4.0; +ra := !a; +rb := !b; +writeLn(ra); +writeLn(rb); +writeLn(dataType(ra)); +writeLn(dataType(rb)); +``` + +代码块身份：输出片段 + +```text +0.5 +0.25 +1 +1 +``` + +说明： + +- 整型 `a` 和实型 `b` 都可以用 `!` 求倒数。 +- 上面两个 `dataType(...)` 都输出 `1`，表示结果是实型。 + +逻辑运算： + +代码块身份：可直接照写示例 + +```tsl +writeLn((1 < 2) and (2 < 3)); +writeLn((1 > 2) or (2 < 3)); +writeLn(not (1 > 2)); +writeLn((1 < 2) && (2 < 3)); +writeLn((1 > 2) || (2 < 3)); +``` + +代码块身份：输出片段 + +```text +1 +1 +1 +1 +1 +``` + +位运算： + +代码块身份：可直接照写示例 + +```tsl +writeLn(6 .& 3); +writeLn(4 .| 1); +writeLn(6 .^ 3); +``` + +代码块身份：输出片段 + +```text +2 +5 +5 +``` + +基础算术复合赋值： + +代码块身份：可直接照写示例 + +```tsl +a := 10; +a -= 3; +writeLn(a); +a *= 4; +writeLn(a); +a /= 7; +writeLn(a); +a %= 5; +writeLn(a); +``` + +代码块身份：输出片段 + +```text +7 +28 +4 +4 +``` + +幂运算和位运算也可以使用复合赋值： + +代码块身份：可直接照写示例 + +```tsl +a := 2; +a ^= 3; +writeLn(a); +b := 6; +b .&= 3; +writeLn(b); +c := 4; +c .|= 1; +writeLn(c); +d := 6; +d .^= 3; +writeLn(d); +``` + +代码块身份：输出片段 + +```text +8 +2 +5 +5 +``` + +字符串同样支持 `+=`： + +代码块身份：可直接照写示例 + +```tsl +s := "A"; +s += "B"; +writeLn(s); +``` + +代码块身份：输出片段 + +```text +AB +``` + +`$` 也可以用于字符串连接： + +代码块身份：可直接照写示例 + +```tsl +writeLn("A" $ "B"); +``` + +代码块身份：输出片段 + +```text +AB +``` + +字符串拼接、比较和 `like`： + +代码块身份：可直接照写示例 + +```tsl +writeLn("222" + "888"); +writeLn("A" < "a"); +writeLn("AB" < "ABC"); +writeLn("ABC" = "ABC"); +writeLn("2009-01-01" like "\\d{4}-\\d{2}-\\d{2}"); +``` + +代码块身份：输出片段 + +```text +222888 +1 +1 +1 +1 +``` + +说明： + +- 字符串可以直接用 `+` 拼接。 +- 字符串比较区分字符序和大小写；当前例子里 `"A" < "a"` 为真。 +- `like` 的右侧可以直接写正则模式。 + +`like` 不要按 SQL `%` 通配去理解： + +代码块身份：可直接照写示例 + +```tsl +writeLn("abc" like "a.*"); +writeLn("abc" like "a%"); +``` + +代码块身份：输出片段 + +```text +1 +0 +``` + +因此 `like` 更接近“正则匹配”，不是 SQL 那套 `%` / `_` 通配语义。 + +自增与自减： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +a++; +writeLn(a); +a--; +writeLn(a); +``` + +代码块身份：输出片段 + +```text +2 +1 +``` + +前置自增与自减： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +++a; +writeLn(a); +--a; +writeLn(a); +``` + +代码块身份：输出片段 + +```text +2 +1 +``` + +`if` 表达式： + +代码块身份：可直接照写示例 + +```tsl +writeLn(if 2 > 1 then 2 else 1); +``` + +代码块身份：输出片段 + +```text +2 +``` + +`if condition then true_value else false_value` 必须带 `else`，否则不是本页可照写的表达式形态。 + +### 表达式对象 + +`@` 表达式前导： + +代码块身份：可直接照写示例 + +```tsl +base_value := 1; +expr_value := @base_value + 1; +result_value := eval(expr_value); +writeLn(result_value); +``` + +代码块身份：输出片段 + +```text +2 +``` + +`@base_value + 1` 会得到一个可交给 `eval(...)` 求值的表达式对象。 + +`&"..."` 表达式常量： + +代码块身份：可直接照写示例 + +```tsl +base_value := 1; +expr_value := &"base_value + 1"; +result_value := eval(expr_value); +writeLn(result_value); +``` + +代码块身份：输出片段 + +```text +2 +``` + +`&"base_value + 1"` 会把字符串编译成表达式对象，再由 `eval(...)` 求值。 + +逗号表达式： + +代码块身份：可直接照写示例 + +```tsl +writeLn(Demo()); + +function Demo(); +begin + return (a := 1, b := 2, c := 3, a + b + c); +end; +``` + +代码块身份：输出片段 + +```text +6 +``` + +逗号表达式会按从左到右顺序执行前面的赋值，再返回最后一个表达式结果。 + +逗号表达式也可以继续参与外层计算： + +代码块身份：可直接照写示例 + +```tsl +result_value := (b := 2, c := 3, b * c) * c; +writeLn(result_value); +``` + +代码块身份：输出片段 + +```text +18 +``` + +逗号表达式本身可以作为一个普通子表达式继续参与后续运算。 + +### 空安全访问 + +代码块身份：可直接照写示例 + +```tsl +a := nil; +writeLn(a?.value = nil); +h := new Holder(); +h.value := 7; +writeLn(h?.value); +arr := nil; +writeLn(arr?.[0] = nil); + +type Holder = class + value; +end; +``` + +代码块身份：输出片段 + +```text +1 +7 +1 +``` + +更深一层的混合空安全访问，本页只写入下面这个形态： + +代码块身份：可直接照写示例 + +```tsl +c := nil; +writeLn(c?.a?.[1] = nil); +``` + +代码块身份：输出片段 + +```text +1 +``` + +不要从这一段外推成所有深度、所有成员/下标组合都可写。 + +### 否定形式运算 + +代码块身份：可直接照写示例 + +```tsl +writeLn(1 not in array(2, 3)); +writeLn("2009-1-1" not like "\\d{4}-\\d{2}-\\d{2}"); +writeLn(1 not sqlin array(2, 3)); +obj := new A(); +writeLn(obj not is class(B)); + +type A = class +end; +type B = class +end; +``` + +代码块身份：输出片段 + +```text +1 +1 +1 +1 +``` + +### 标量链式比较 + +代码块身份：可直接照写示例 + +```tsl +writeLn(1 :< 2 :< 3); +writeLn(3 :> 2 :> 1); +writeLn(1 :== 1 :== 1); +writeLn(3 :>= 2 :>= 2); +writeLn(1 :<= 2 :<= 3); +writeLn(1 :<> 2 :<> 3); +``` + +代码块身份：输出片段 + +```text +1 +1 +1 +1 +1 +1 +``` + +### 矩阵链式比较 + +代码块身份：可直接照写示例 + +```tsl +r := array(1, 2, -1) ::< array(2, 1, 0) ::< array(3, 2, 1); +writeLn(r[0]); +writeLn(r[1]); +writeLn(r[2]); +s := array(1, 2, -1) ::< 2 ::< array(3, 2, 1); +writeLn(s[0]); +writeLn(s[1]); +writeLn(s[2]); +``` + +代码块身份：输出片段 + +```text +1 +0 +1 +1 +0 +0 +``` + +矩阵链式比较会按元素位置分别得到结果数组，并且可以和标量混用。 + +### 条件编译探测 + +代码块身份：可直接照写示例 + +```tsl +{$ifdef ifexp} +writeLn(1); +{$else} +writeLn(0); +{$endif} +{$ifdef nilinvoke} +writeLn(1); +{$else} +writeLn(0); +{$endif} +``` + +代码块身份：输出片段 + +```text +1 +1 +``` + +这只能作为能力探测示例使用；智能体不要把条件编译探测写成普通业务逻辑。 + +## 默认生成模板 + +如果你只需要最小的“比较 + 三目”例子，直接用这个： + +代码块身份：可直接照写示例 + +```tsl +flag := 1 < 2; +value := flag ? 10 : 20; +writeLn(value); +``` + +代码块身份：输出片段 + +```text +10 +``` + +## 禁止项 + +- 用 `=` 当赋值运算符。 +- 把 `==` / `!=` 当成等值 / 不等值比较；本页比较使用 `=` / `<>`。 +- 把 `!` 当成逻辑非；本页逻辑非使用 `not`，`!` 是一元倒数/矩阵逆相关运算符。 +- 把普通 `&` 当成位与；位与使用 `.&`。 +- 把 `$=` 当成字符串复合赋值；字符串原地拼接使用 `+=`。 +- 把 `if` 表达式写成没有 `else` 的半句。 +- 把本页明确的 `c?.a?.[1]` 外推成所有深链式空安全访问都可靠。 +- 从其他语言推断 TSL 运算符能力。 + +代码块身份：反例 / 不可照写 + +```text +a = 1; +``` + +代码块身份：输出片段 + +```text +invalid statement +``` + +上面这种写法会编译失败，因为单独的 `=` 在这里会被当成不成立的表达式。 + +代码块身份：反例 / 不可照写 + +```text +v := if 2 > 1 then 2; +``` + +代码块身份：输出片段 + +```text +invalid statement +``` + +上面这种写法也会编译失败；`if` 表达式必须带 `else`。 diff --git a/docs/tsl/syntax/06_functions_and_calls.md b/docs/tsl/syntax/06_functions_and_calls.md deleted file mode 100644 index 47413fda..00000000 --- a/docs/tsl/syntax/06_functions_and_calls.md +++ /dev/null @@ -1,1030 +0,0 @@ -# Functions And Calls - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[03_core_model.md](03_core_model.md)（优先）、[10_units_and_scope.md](10_units_and_scope.md)、[21_external_calls_and_threads.md](21_external_calls_and_threads.md) - -手册位置：第 6 篇，共 32 篇。上一篇：[05_variables_and_constants.md](05_variables_and_constants.md)。下一篇：[07_expressions_and_operators.md](07_expressions_and_operators.md)。 - -这一篇只负责 `function` / `procedure` 的定义、调用、参数传递和值返回，不延伸到业务函数库。 - -## 这一篇解决什么问题 - -回答“如何正确声明 `function` 和 `procedure`、`.tsl` 脚本语句区如何调用后置函数声明、怎样使用参数修饰、默认参数与可变参数，以及哪些函数写法会直接编译失败”。 - -## Agent 函数/调用判断流程 - -1. 先判断当前文件是 `.tsl` 还是 `.tsf`；文件形态不明确时回 [03_core_model.md](03_core_model.md)。 -2. `.tsl` 中先写语句区，再把 `function` / `procedure` 声明放在后面；不要在声明区后面追加脚本语句。 -3. `.tsf` 中把顶层 `function` / `procedure` 当成模块 / 函数扩展声明；不要写成顺序执行入口。 -4. 需要返回值时用 `function`，不需要返回值时用 `procedure`。 -5. 调用普通 TSL 函数时，命名参数只写 `name: value`；不要把 `name = value` 当成命名参数。 -6. 参数是否写回调用方要看 `const` / `var` / `{$VarByRef-}` / `in` / `out`，不要默认按其他语言习惯推断。 -7. 没有已验证代码块时不要发明函数/调用写法；尤其不要把二进制函数、系统函数、函数指针和匿名函数都套成同一种调用语法。 - -## 必须记住的规则 - -- 最稳妥的函数骨架仍然是 `function Name(...); begin ... end;`。 -- 不需要返回值时，可以改用 `procedure Name(...); begin ... end;`。 -- 在 `.tsl` 文件模型层，脚本语句后可以接函数声明；语句区在前顺序执行，声明区在后提供函数/过程定义。见 [03_core_model.md](03_core_model.md)。 -- 在 `.tsf` 文件模型层，顶层 `function` / `procedure` 是模块/函数扩展声明；部署到解释器 `funcext` 后可被脚本直接调用。 -- 当前解释器接受省略函数头后的分号，但文档默认仍保留这个分号。 -- 一个函数定义体里可以同时出现主函数和子函数。 -- 函数支持参数类型注解和返回值类型注解。 -- 不带类型注解时，多个参数用逗号分隔。 -- 带类型注解时，多个参数用分号分隔。 -- 当前解释器接受 `const` 与 `var` 形参修饰。 -- 当前解释器的运行时默认行为是：未修饰参数可以写回调用方；这是运行时默认，不是语言规范保证。 -- `{$VarByRef-}` 会把未修饰参数切换成按值传递；`var` 形参仍保持引用语义。 -- 在 `{$VarByRef-}` 下，调用时可以用 `in` / `out` 前缀逐个参数覆盖默认传递方式。 -- 如果不确定当前任务是否需要写回语义，优先显式用 `const` 形参，或先切到 `{$VarByRef-}`；不要依赖未修饰参数的运行时默认行为。 -- `return expr;` 会直接返回当前函数结果。 -- `exit;` 会立即结束当前函数；在当前最小样例里，如果此前没有写入返回结果，调用方观察到的是默认值 `0`。 -- 调用时支持命名参数，写法是 `name: value`。 -- 命名参数当前也支持 `call(...)` 这类按函数名或函数指针转调的模型。 -- 一旦某次调用里开始使用命名参数，后面的参数就不能再退回位置参数。 -- 对二进制函数 / 系统函数直接使用命名参数，当前会报 `named parameter mode can't support here`；这类函数要先用 TSL 再封一层。 -- 函数参数支持默认值。 -- 普通函数的默认值规则不要直接等同到 `unit interface` 声明；跨 `unit` 的默认参数边界见这一篇后面的对照例子，以及 [10_units_and_scope.md](10_units_and_scope.md)。 -- 当前解释器支持尾部 `...` 形式的可变参数。 -- 在可变参数函数体里，`Params`、`ParamCount`、`RealParamCount` 都已验证可用。 -- 可变参数组可以通过 `...` 转发给另一个函数调用。 -- 可变参数组也可以通过 `call(fc, ...)`、`##fc(...)`、`invoke(obj, name, 0, ...)` 转发。 -- 当前解释器接受 `a := function(...) begin ... end;` 这种匿名函数写法。 -- 匿名函数可以直接作为参数传入另一个函数。 -- 当前解释器接受 `ThisFunction(FuncName)` 把已知函数绑定成函数值。 -- 当前解释器里，匿名函数和函数指针的稳定调用方式仍是 `call(f, ...)` 或 `##f(...)`。 -- 当前解释器没有通过 `f(...)` 这种“函数变量直接调用”写法；无论 `f` 是匿名函数、`FindFunction(...)` 还是 `ThisFunction(...)` 返回的函数指针，都不要默认写成直调。 -- 当前解释器接受 `::FuncName(...)` 指向全局/系统函数，用来绕过当前作用域里的同名局部函数。 -- `external`、`MakeInstance` 和线程调用统一移到 [21_external_calls_and_threads.md](21_external_calls_and_threads.md)。 -- 不要在 `.tsl` 的函数声明区之后继续追加脚本语句。 - -## 已验证语法 - -### 基础函数 / 过程骨架 - -`.tsl` 语句区调用后置函数声明： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -test(); - -function test(); -begin - echo "test"; -end; -``` - -代码块身份：已验证输出片段 - -```text -test -``` - -最短函数骨架： - -代码块身份：已验证可执行示例 - -```tsl -function Add(a, b); -begin - return a + b; -end; -``` - -主函数加子函数： - -代码块身份：已验证可执行示例 - -```tsl -function MultiFunc(); -begin - return Twice(3); -end; - -function Twice(x); -begin - return x * 2; -end; -``` - -函数头省略分号在当前解释器里也可编译： - -代码块身份：已验证可执行示例 - -```tsl -function MissingSemi() -begin - return 1; -end; -``` - -最短 `procedure` 骨架： - -代码块身份：已验证可执行示例 - -```tsl -procedure LogDone(); -begin -end; -``` - -`procedure` 写回参数的最小运行样例： - -这是验证样例外壳，不作为正式顶层模型归类依据。 - -代码块身份：已验证可执行示例 - -```tsl -program test; -procedure Bump(var x); -begin - x := x + 1; -end; -begin - a := 1; - Bump(a); - WriteLn(a); -end. -``` - -代码块身份：已验证输出片段 - -```text -2 -``` - -### 签名增强 - -带参数类型和返回值类型： - -代码块身份：已验证可执行示例 - -```tsl -function Demo(a: integer): integer; -begin - return a; -end; -``` - -带类型时的多参数分隔： - -代码块身份：已验证可执行示例 - -```tsl -function Demo(a: integer; b: integer); -begin - return a + b; -end; -``` - -类型名可以写成更偏说明性的名字： - -代码块身份：已验证可执行示例 - -```tsl -function Demo(a: input_value; b: handler): result_type; -begin - return a; -end; -``` - -参数修饰： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function ReadConst(const x); -begin - return x + 1; -end; -procedure SetVar(var x); -begin - x := x + 5; -end; -begin - a := 10; - WriteLn(ReadConst(a)); - SetVar(a); - WriteLn(a); -end. -``` - -已验证运行结果： - -- `ReadConst(a)` 输出 `11` -- `SetVar(a)` 之后，`a` 输出 `15` -- 直接给 `const` 形参赋值会编译失败 - -### 参数传递方式 - -默认参数写回调用方： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function TouchDefault(a); -begin - a := 9; -end; -begin - x := 1; - TouchDefault(x); - WriteLn(x); -end. -``` - -已验证运行结果： - -- `TouchDefault(x)` 之后，`x` 输出 `9` - -`{$VarByRef-}` 与 `var` 形参： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function TouchDefault(a); -begin - a := 9; -end; -{$VarByRef-} -function TouchValue(a); -begin - a := 8; -end; -function TouchForcedVar(var a); -begin - a := 7; -end; -{$VarByRef+} -begin - x := 1; - TouchDefault(x); - WriteLn(x); - y := 1; - TouchValue(y); - WriteLn(y); - z := 1; - TouchForcedVar(z); - WriteLn(z); -end. -``` - -已验证运行结果： - -- 默认模式下，`TouchDefault(x)` 后 `x` 输出 `9` -- `{$VarByRef-}` 下，未修饰参数版本 `TouchValue(y)` 之后，`y` 仍输出 `1` -- `{$VarByRef-}` 下，`var` 形参版本 `TouchForcedVar(z)` 之后，`z` 输出 `7` - -`in` / `out` 调用前缀： - -代码块身份：已验证可执行示例 - -```tsl -program test; -{$VarByRef-} -procedure Touch3(a, b, c); -begin - a := 1; - b := 2; - c := 3; -end; -begin - a := 0; - b := 0; - c := 0; - Touch3(a, b, c); - WriteLn(a); - WriteLn(b); - WriteLn(c); - Touch3(in a, out b, c); - WriteLn(a); - WriteLn(b); - WriteLn(c); -end. -``` - -已验证运行结果： - -- 在 `{$VarByRef-}` 下，直接调用 `Touch3(a, b, c)` 后依次输出 `0`、`0`、`0` -- 同样在 `{$VarByRef-}` 下，`Touch3(in a, out b, c)` 后依次输出 `0`、`2`、`0` -- 说明 `in` / `out` 可以在调用点逐个参数覆盖当前默认传递方式 - -### `return` 与 `exit` - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Demo(x); -begin - if x > 0 then - exit; - return 99; -end; -begin - WriteLn(Demo(1)); - WriteLn(Demo(0)); -end. -``` - -已验证运行结果： - -- `Demo(1)` 输出 `0` -- `Demo(0)` 输出 `99` -- 说明 `exit;` 会立即结束当前函数体 -- 在这个最小例子里，因为 `exit;` 之前没有写入返回结果，调用方观察到的是默认值 `0` - -### 调用增强 - -命名参数调用： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn(Pack(a: 1, b: 2)); - -function Pack(a, b); -begin - return a * 10 + b; -end; -``` - -代码块身份：已验证输出片段 - -```text -12 -``` - -已验证补充： - -- `Pack(a: 1, b: 2)` 返回 `12` -- `Pack(b: 2, a: 1)` 返回 `12` -- `Pack(1, b: 2)` 返回 `12` - -跳过中间参数时，未命中的参数当前保持 `nil`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function TestFunc(a, b, c); -begin - WriteLn(IfNil(b)); - return 0; -end; -begin - TestFunc(1, c: 3); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明 `TestFunc(1, c: 3)` 这种调用里，中间参数 `b` 当前会保持 `nil` - -通过 `call(...)` 也支持命名参数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function TestFunc(a, b, c); -begin - return a * 100 + b * 10 + c; -end; -begin - WriteLn(call("TestFunc", a: 1, c: 2, b: 3)); -end. -``` - -已验证运行结果： - -- 输出 `132` -- 说明 `call(...)` 当前也支持按参数名传值 -- 说明命名参数传入后不再按位置解释，而是按名字绑定到形参 - -命名参数可以调换顺序： - -代码块身份：已验证可执行示例 - -```tsl -function NamedArgsDemo(); -begin - return Pack(b: 2, a: 1); -end; - -function Pack(a, b); -begin - return a * 10 + b; -end; -``` - -命名参数也可以和位置参数混用： - -代码块身份：已验证可执行示例 - -```tsl -function NamedArgsDemo(); -begin - return Pack(1, b: 2); -end; - -function Pack(a, b); -begin - return a * 10 + b; -end; -``` - -### 默认参数 - -默认值参数： - -代码块身份：已验证可执行示例 - -```tsl -function AddOne(a = 1); -begin - return a + 1; -end; -``` - -带类型时也支持默认值： - -代码块身份：已验证可执行示例 - -```tsl -function TypedAdd(a: integer = 1): integer; -begin - return a + 1; -end; -``` - -多个参数时，后面的参数可以带默认值： - -代码块身份：已验证可执行示例 - -```tsl -function Pack(a, b = 2); -begin - return a * 10 + b; -end; -``` - -代码块身份：已验证可执行示例 - -```tsl -function Pack(a: integer; b: integer = 2): integer; -begin - return a * 10 + b; -end; -``` - -默认值也可以写成表达式： - -代码块身份：已验证可执行示例 - -```tsl -function ExprDefault(a = 1 + 2); -begin - return a; -end; -``` - -已验证运行结果： - -- `AddOne()` 返回 `2` -- `AddOne(5)` 返回 `6` -- `TypedAdd()` 返回 `2` -- `TypedAdd(5)` 返回 `6` -- `Pack(1)` 返回 `12` -- `Pack(a: 1)` 返回 `12` -- `ExprDefault()` 返回 `3` - -`unit interface` 声明下的默认参数要单独看： - -以下是不可照写的对比：普通函数默认参数能跑通，不等于跨 `unit` 声明边界也同样可靠。 - -代码块身份：反例 / 不可照写 - -```text -// P.tsf -function P(a = 5, b = 6); -begin - return a + b; -end; - -// UnitLiteral.tsf -unit UnitLiteral; -interface -function H(a = 5); -implementation -function H(a); -begin - return a; -end; -end. - -// UnitConst.tsf -unit UnitConst; -interface -const CS = 888; -function F(a, b = 100, c = CS); -implementation -function F(a, b, c); -begin - return a + b + c; -end; -end. - -// main.tsl -program test; -uses UnitLiteral, UnitConst; -begin - WriteLn(P()); - WriteLn(H()); - WriteLn(F(1)); - WriteLn(F(1, 2)); -end. - -// command -tsl .\main.tsl -LIBPATH "D:\path\to\dir\" -``` - -已验证运行结果： - -- 普通函数 `P()` 输出 `11` -- `unit interface` 里声明的字面量默认值 `H()` 输出 `5` -- `F(1)` 输出 `101`，`F(1, 2)` 输出 `3` -- 同一组文件下，`UnitConst.CS` 当前仍可读到 `888`，而 `F(1, 2, 3)` 输出 `6` -- 因此当前解释器下，不要把“普通函数默认参数可用”直接泛化成“`unit interface` 里引用 `unit const` 的默认参数也同样可靠” -- 这组多文件结果依赖真实查找路径；当前验证命令是把对应目录放进 `-LIBPATH` -- 这类跨 `unit` 的声明边界，统一回看 [10_units_and_scope.md](10_units_and_scope.md) - -### 可变参数 `...` - -尾部可变参数： - -代码块身份：已验证可执行示例 - -```tsl -function SumAll(...); -begin - s := 0; - for i, v in Params do - s := s + v; - return s; -end; -``` - -可变参数转发： - -代码块身份：已验证可执行示例 - -```tsl -function Forward(...); -begin - return SumAll(...); -end; - -function SumAll(...); -begin - s := 0; - for i, v in Params do - s := s + v; - return s; -end; -``` - -`ParamCount` 与 `RealParamCount`： - -代码块身份：已验证可执行示例 - -```tsl -function CountArgs(a, b, ...); -begin - return ParamCount * 10 + RealParamCount; -end; -``` - -已验证运行结果： - -- `SumAll(1, 2, 3, 4)` 返回 `10` -- `Forward(1, 2, 3, 4)` 返回 `10` -- `CountArgs(1, 2, 3, 4)` 返回 `44` -- `CountArgs(1, 2)` 返回 `22` - -通过 `call` 与 `##` 转发可变参数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Sum3(a, b, c); -begin - return a + b + c; -end; -function DoFunc(fc, ...); -begin - return call(fc, ...); -end; -function DoFunc2(fc, ...); -begin - return ##fc(...); -end; -begin - WriteLn(DoFunc("Sum3", 1, 2, 3)); - WriteLn(DoFunc2(thisfunction(Sum3), 1, 2, 3)); -end. -``` - -已验证运行结果： - -- `DoFunc("Sum3", 1, 2, 3)` 输出 `6` -- `DoFunc2(thisfunction(Sum3), 1, 2, 3)` 输出 `6` - -通过 `invoke` 转发可变参数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TestC = class -public - function FuncA(a, b, c); - begin - return a + b + c; - end; - function FuncB(a, b, c); - begin - return a * 100 + b * 10 + c; - end; - function Dispatch(kind, ...); - begin - if kind = "Int" then - return FuncA(...) - else - return FuncB(...); - end; -end; -function DoInvoke(fc_name, ...); -begin - obj := new TestC(); - return invoke(obj, fc_name, 0, ...); -end; -begin - WriteLn(DoInvoke("Dispatch", "Int", 2, 20, 200)); - WriteLn(DoInvoke("Dispatch", "Other", 1, 2, 3)); -end. -``` - -已验证运行结果： - -- `DoInvoke("Dispatch", "Int", 2, 20, 200)` 输出 `222` -- `DoInvoke("Dispatch", "Other", 1, 2, 3)` 输出 `123` - -### 匿名函数与函数指针 - -匿名函数变量： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a := function(x, y) - begin - return x + y; - end; - WriteLn(call(a, 1, 2)); - WriteLn(##a(5, 6)); -end. -``` - -已验证运行结果： - -- `call(a, 1, 2)` 输出 `3` -- `##a(5, 6)` 输出 `11` - -匿名函数也可以直接作为参数传入： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Apply(fun); -begin - return call(fun, 2, 3); -end; -begin - WriteLn(Apply(function(x, y) - begin - return x * y; - end)); -end. -``` - -已验证运行结果： - -- 输出 `6` - -函数指针变量也可以通过 `FindFunction(...)` 拿到： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Add(a, b); -begin - return a + b; -end; -begin - f := FindFunction("Add"); - WriteLn(##f(1, 2)); -end. -``` - -已验证运行结果： - -- 输出 `3` - -也可以通过 `ThisFunction(...)` 从已知函数名直接拿到： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Add(a, b); -begin - return a + b; -end; -begin - f := ThisFunction(Add); - WriteLn(Call(f, 3, 4)); -end. -``` - -已验证运行结果： - -- 输出 `7` -- 说明 `ThisFunction(Add)` 当前可以得到稳定可调用的函数值 - -直接 `f(...)` 在当前解释器里不要当成可靠写法： - -代码块身份：反例 / 不可照写 - -```text -// 匿名函数变量直接调用 -program test; -begin - a := function(x, y) - begin - return x + y; - end; - WriteLn(a(7, 8)); -end. - -// FindFunction 返回值直接调用 -program test; -function Add(a, b); -begin - return a + b; -end; -begin - f := FindFunction("Add"); - WriteLn(f(3, 4)); -end. - -// ThisFunction 返回值直接调用 -program test; -function Add(a, b); -begin - return a + b; -end; -begin - f := ThisFunction(Add); - WriteLn(f(3, 4)); -end. -``` - -已验证结果： - -- 上面三种 `f(...)` 直调写法都会报 `function: compile error or not found` -- 因此当前手册只把 `call(f, ...)` 和 `##f(...)` 写成稳定规则 - -### `::` 指向全局函数 - -当当前作用域里有同名局部函数时，可以用 `::FuncName(...)` 指定去调全局/系统函数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Demo(); -begin - return array(StrToInt("123"), ::StrToInt("123")); -end; -function StrToInt(s); -begin - return 888; -end; -begin - r := Demo(); - WriteLn(r[0]); - WriteLn(r[1]); -end. -``` - -已验证运行结果： - -- 第一项 `StrToInt("123")` 命中局部函数，输出 `888` -- 第二项 `::StrToInt("123")` 命中全局系统函数，输出 `123` -- 说明 `::` 可以绕过当前作用域的同名局部函数，直接指向全局/系统函数 - -如果 `::FuncName(...)` 指向的全局函数本身不存在，当前解释器会在运行时报 `function: compile error or not found` - -### 系统交互专题 - -`external`、动态库函数指针、`MakeInstance` 和线程调用，统一见 [21_external_calls_and_threads.md](21_external_calls_and_threads.md)。这一篇只保留“普通函数怎样定义和调用”的主线。 - -## 最小可编译示例 - -如果你只是要写一个能被 agent 稳定续写的 `.tsl` 脚本，从语句区起步，需要函数时把声明区放在后面： - -代码块身份：已验证可执行示例 - -```tsl -Hello(); - -function Hello(); -begin - echo "hello"; -end; -``` - -如果你要写 `.tsf` 模块/函数扩展，从下面任一骨架起步： - -代码块身份：已验证可执行示例 - -```tsl -function HelloValue(); -begin - return 1; -end; -``` - -代码块身份：已验证可执行示例 - -```tsl -procedure HelloProc(); -begin -end; -``` - -## 常见误写 - -- 在 `.tsl` 的声明区后面继续写脚本语句。 -- 以为函数头后的分号是当前解释器的硬性要求。 -- 以为 `procedure` 只是 `function` 的别名，不涉及参数传递语义。 -- 带类型注解时仍然用逗号分隔参数。 -- 以为默认未修饰参数天然就是按值传递。 -- 把 `a = 1` 这种比较表达式误当成命名参数调用。 -- 以为默认值只能用于无类型参数。 -- 在 `const` 形参上直接赋值。 -- 把普通函数的默认值规则原样套到 `unit interface` 里的 `const` 默认参数上。 -- 把匿名函数或 `FindFunction(...)` 返回值默认写成 `f(...)` 直调。 -- 把命名参数直接套到二进制函数或系统函数上。 -- 在一次调用里先进入命名参数模式，后面又退回位置参数。 - -代码块身份：反例 / 不可照写 - -```text -a := 1; -Add(1, 2); - -function Add(a, b); -begin - return a + b; -end; - -echo "after function"; -``` - -上面的问题不在 `Add` 本身，而在于 `.tsl` 的函数声明区后面又继续出现脚本语句。正确做法是把会执行的语句全部放在声明区之前。 - -代码块身份：已验证输出片段 - -```text -invalid statement -``` - -代码块身份：反例 / 不可照写 - -```text -function Demo(a: integer, b: integer); -begin - return a + b; -end; -``` - -上面这种写法会编译失败；参数一旦带类型，分隔符应改成分号。 - -代码块身份：反例 / 不可照写 - -```text -Pack(a = 1, b = 2) -``` - -这类写法不要当成命名参数。它虽然可能编译通过，但当前已验证返回结果不对，不能当成可靠的命名参数语法。 - -代码块身份：反例 / 不可照写 - -```text -function Demo(a: integer, b: integer = 2): integer; -begin - return a + b; -end; -``` - -上面这种写法也不对；参数一旦带类型，分隔符仍然应保持分号。 - -代码块身份：反例 / 不可照写 - -```text -function TouchDefault(a); -begin - a := 9; -end; -``` - -不要把上面这种未修饰参数自动理解成“按值传递”。在当前解释器里，它会把调用方实参改掉；如果当前任务要求按值语义，先看 `{$VarByRef-}` 和 `in` / `out` 的例子。 - -代码块身份：反例 / 不可照写 - -```text -procedure Bad(const x); -begin - x := 2; -end; -``` - -上面这种写法会编译失败；`const` 形参在当前解释器里不能被重新赋值。 - -代码块身份：反例 / 不可照写 - -```text -unit UnitConst; -interface -const CS = 888; -function F(a, b = 100, c = CS); -``` - -不要把上面这种 `unit interface` 声明直接当成已经等价于普通函数默认参数规则。在当前解释器里，对应的 `F(1)` 实测输出是 `101`，不是按 `CS = 888` 补成的结果；具体边界见 [10_units_and_scope.md](10_units_and_scope.md)。 - -代码块身份：反例 / 不可照写 - -```text -a := function(x, y) -begin - return x + y; -end; -WriteLn(a(7, 8)); -``` - -不要把上面这种匿名函数变量的直调写法直接当成可靠规则。在当前解释器里，它会报 `function:a compile error or not found`；稳定写法仍然是 `call(a, 7, 8)` 或 `##a(7, 8)`。 - -代码块身份：反例 / 不可照写 - -```text -WriteLn(IntToStr(value: 200)); -``` - -不要把上面这种写法直接套到二进制函数或系统函数上。当前解释器里，它会报 `named parameter mode can't support here`；如果确实要命名传参，先用 TSL 函数再封一层。 - -代码块身份：反例 / 不可照写 - -```text -function Pack(a, b, c); -begin - return a * 100 + b * 10 + c; -end; -begin - WriteLn(Pack(a: 1, 2, c: 3)); -end. -``` - -不要在同一次调用里“先进入命名参数模式，再退回位置参数”。当前这类写法会直接编译失败，错误信息包含 `paramname: not found`。 - -## 跳转指引 - -- 回看最短骨架：见 [02_quickstart.md](02_quickstart.md) -- 回看流程控制：见 [08_control_flow.md](08_control_flow.md) -- 当函数变多时：见 [10_units_and_scope.md](10_units_and_scope.md) -- 看 `external`、`MakeInstance` 和线程调用：见 [21_external_calls_and_threads.md](21_external_calls_and_threads.md) diff --git a/docs/tsl/syntax/07_control_flow.md b/docs/tsl/syntax/07_control_flow.md new file mode 100644 index 00000000..cd8db1a0 --- /dev/null +++ b/docs/tsl/syntax/07_control_flow.md @@ -0,0 +1,450 @@ +# TSL 控制流 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页规则和示例继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只收录流程控制与异常控制，不讨论金融语义。 + +## 本篇职责 + +回答“`if`、`case`、`for`、`while`、`repeat`、`break`、`continue`、`try`、`raise` 这些流程结构在 TSL 里到底怎么写，哪些写法可以直接生成”。 + +## 智能体控制流判断流程 + +1. 先判断任务需要条件分支、循环、`case`、异常处理还是调试跳转。 +2. `if` / `for` / `while` / `repeat` 优先照本页文档骨架写，不要套用其他 Pascal 方言。 +3. 生成带 `else` 的条件分支时，默认用 `begin ... end` 包住 `then` 和 `else` 分支，让分支内部语句正常以分号结尾；控制流块的 `end` 默认不加分号，也不要在 `else` 前提前加分号。 +4. `case` 只按语句形态生成；不要把 `case` 放到赋值右侧生成表达式形态。 +5. 没有文档事实时不要发明控制流写法。 + +## 核心规则 + +- `if ... then ... else ...` 默认写成块式分支：`then begin ... end else begin ... end`。 +- 块式分支内部的普通语句照常用分号结尾；语句形态的控制流块 `end` 默认不加分号。 +- `for` 支持 `to`、`downto`、可选 `step`，以及 `for i, v in array` 遍历。 +- `while` 和 `repeat ... until` 都可直接使用；`repeat` 至少会先执行一轮再判断结束条件。 +- `break` 会跳出当前最近一层循环，`continue` 会跳过当前轮剩余语句。 +- `case ... of ... else ... end` 只作为语句形态生成；`end` 后默认不加分号。 +- `case` 分支标签支持逗号并列和 `to` 区间。 +- `try ... except ... end` 可以捕获 `raise` 产生的错误，并继续执行后续语句。 +- `exceptObject.errInfo` 在 `except` 块中可读，能拿到当前错误信息。 +- `exceptObject.errLine` 和 `exceptObject.errNo` 在 `except` 块中也可读。 +- `try ... finally ... end` 无论是否报错，都会先执行 `finally`；如果没有 `except` 吞掉错误，脚本仍会在 `finally` 之后报错终止。 +- `raise "message"` 是最小抛错写法。 +- `goto`、`debugReturn`、`debugRunEnv`、计时和性能分析器这类“控制流补充工具”统一放到 [15_debug_and_profiler.md](15_debug_and_profiler.md)。 + +## 可直接照写示例 + +使用这些示例时遵守： + +- 条件表达式、比较、布尔值和普通赋值回 [06_expressions_and_operators.md](06_expressions_and_operators.md)。 +- 函数里的控制流只按控制流语法处理；函数文件模型、返回值和参数规则回 [05_functions_and_calls.md](05_functions_and_calls.md)。 +- `goto`、`debugReturn`、计时和性能分析器不在本页生成，统一回 [15_debug_and_profiler.md](15_debug_and_profiler.md)。 + +### `if`、`while`、`repeat ... until` + +代码块身份：可直接照写示例 + +```tsl +flag := 1; +if flag > 0 then +begin + value := 1; +end +else +begin + value := 0; +end + +counter := 0; +while counter < 3 do + counter := counter + 1; + +repeat + counter := counter - 1; +until counter = 0; +writeLn(value); +writeLn(counter); +``` + +代码块身份：输出片段 + +```text +1 +0 +``` + +### `for` 的几种主干写法 + +最基础的递增循环： + +代码块身份：可直接照写示例 + +```tsl +sum := 0; +for i := 0 to 2 do + sum := sum + i; +writeLn(sum); +``` + +代码块身份：输出片段 + +```text +3 +``` + +带 `step` 的递增循环： + +代码块身份：可直接照写示例 + +```tsl +s := 0; +for i := 1 to 5 step 2 do + s := s + i; +writeLn(s); +``` + +输出说明： + +- 输出 `9` + +代码块身份：输出片段 + +```text +9 +``` + +带 `step` 的 `downto` 递减循环： + +代码块身份：可直接照写示例 + +```tsl +s := 0; +for i := 5 downto 1 step 2 do + s := s + i; +writeLn(s); +``` + +输出说明： + +- 输出 `9` + +代码块身份：输出片段 + +```text +9 +``` + +数组遍历： + +代码块身份：可直接照写示例 + +```tsl +data := array(10, 20, 30); +for i, v in data do + writeLn(i * 100 + v); +``` + +输出说明： + +- 依次输出 `10`、`120`、`230` +- 这说明 `for i, v in data` 里的 `i` 从 `0` 开始 + +代码块身份：输出片段 + +```text +10 +120 +230 +``` + +### `break` 与 `continue` + +`break`： + +代码块身份：可直接照写示例 + +```tsl +i := 0; +sum := 0; +while true do +begin + i := i + 1; + if i > 3 then + break; + sum := sum + i; +end +writeLn(sum); +writeLn(i); +``` + +输出说明： + +- `sum` 输出 `6` +- `i` 输出 `4` + +代码块身份：输出片段 + +```text +6 +4 +``` + +`continue`： + +代码块身份：可直接照写示例 + +```tsl +i := 0; +sum := 0; +while i < 4 do +begin + i := i + 1; + if i = 2 then + continue; + sum := sum + i; +end +writeLn(sum); +``` + +输出说明： + +- 输出 `8` + +代码块身份：输出片段 + +```text +8 +``` + +### `case` 语句形态 + +普通分支： + +代码块身份：可直接照写示例 + +```tsl +a := 2; +case a of +1: + writeLn("one"); +2: + writeLn("two"); +else + writeLn("other"); +end +``` + +输出说明： + +- 输出 `two` + +代码块身份：输出片段 + +```text +two +``` + +并列标签与区间： + +代码块身份：可直接照写示例 + +```tsl +a := 4; +case a of +1, 2: + writeLn("small"); +3 to 5: + writeLn("mid"); +else + writeLn("other"); +end +``` + +输出说明： + +- 输出 `mid` + +代码块身份：输出片段 + +```text +mid +``` + +### `try ... except` + +代码块身份：可直接照写示例 + +```tsl +writeLn("before"); +try + raise "boom"; +except + writeLn("caught"); + writeLn(exceptObject.errInfo); +end +writeLn("after"); +``` + +输出说明： + +- 先输出 `before` +- 再输出 `caught` +- `exceptObject.errInfo` 输出包含 `raise: boom` 的错误信息 +- 最后继续输出 `after` + +代码块身份：输出片段 + +```text +before +caught +raise: boom +after +``` + +`exceptObject` 的扩展字段： + +代码块身份：可直接照写示例 + +```tsl +try + raise "boom"; +except + writeLn(exceptObject.errLine); + writeLn(exceptObject.errNo); +end +``` + +输出说明： + +- `exceptObject.errLine` 输出 `4` +- `exceptObject.errNo` 输出 `2` +- 说明异常对象除了 `errInfo` 以外，也能直接提供出错行号和错误号 + +代码块身份：输出片段 + +```text +4 +2 +``` + +### `try ... finally` + +正常路径： + +代码块身份：可直接照写示例 + +```tsl +writeLn("before"); +try + writeLn("body"); +finally + writeLn("finally"); +end +writeLn("after"); +``` + +输出说明： + +- 依次输出 `before`、`body`、`finally`、`after` + +代码块身份：输出片段 + +```text +before +body +finally +after +``` + +报错路径： + +代码块身份：可直接照写示例 + +```tsl +writeLn("before"); +try + writeLn("body"); + raise "boom"; +finally + writeLn("finally"); +end +writeLn("after"); +``` + +输出说明： + +- 先输出 `before` +- 再输出 `body` +- 然后仍会输出 `finally` +- 随后脚本报错终止，`after` 不会执行 + +代码块身份：输出片段 + +```text +before +body +finally +``` + +### `raise` + +代码块身份：可直接照写示例 + +```tsl +writeLn("before"); +raise "boom"; +writeLn("after"); +``` + +输出说明： + +- 先输出 `before` +- 随后脚本报错终止，`after` 不会执行 + +代码块身份：输出片段 + +```text +before +``` + +## 默认生成模板 + +最短条件分支的默认骨架如下： + +代码块身份：可直接照写示例 + +```tsl +flag := 1; +if flag > 0 then +begin + value := 1; +end +else +begin + value := 0; +end +``` + +## 禁止项 + +- 在 `else` 前面误加分号。 +- 生成没有分号的裸分支赋值，例如 `then value := 1 else ...`；带 `else` 时用块式分支。 +- 以为 `try ... finally` 会吞掉异常。 +- 把 `case` 写成赋值右侧表达式。 +- 在还没搞清表达式规则前，先把复杂业务函数塞进条件里。 +- 把控制流问题和函数文件模型问题混在一起排查。 + +代码块身份：反例 / 不可照写 + +```text +if flag > 0 then + value := 1; +else + value := 0; +``` + +上面这种写法会编译失败，因为 `else` 前面的分号会让 `if` 语句在上一行提前结束。生成带 `else` 的赋值分支时，不要改成省略分号的裸分支；使用前文的块式分支。 diff --git a/docs/tsl/syntax/07_expressions_and_operators.md b/docs/tsl/syntax/07_expressions_and_operators.md deleted file mode 100644 index dad778dd..00000000 --- a/docs/tsl/syntax/07_expressions_and_operators.md +++ /dev/null @@ -1,492 +0,0 @@ -# Expressions And Operators - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[08_control_flow.md](08_control_flow.md)、[09_objects_and_classes.md](09_objects_and_classes.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 7 篇，共 32 篇。上一篇：[06_functions_and_calls.md](06_functions_and_calls.md)。下一篇：[08_control_flow.md](08_control_flow.md)。 - -这一篇集中放语言级表达式与运算符。agent 写代码时，只能从本页已验证代码块归纳表达式写法，不要把其他语言或外部资料里的运算符习惯直接搬进 TSL。 - -## 这一篇解决什么问题 - -回答“赋值、比较、条件求值、表达式对象、空安全访问和链式比较在 TSL 里怎样写”。 - -## Agent 表达式/运算符判断流程 - -1. 先判断要写赋值、比较、条件求值、表达式对象、空安全访问还是链式比较。 -2. 普通赋值只能用 `:=`，不要把 `=` 当赋值写法。 -3. 比较才用 `=`，并且把比较表达式放在 `WriteLn(...)`、条件或其他需要布尔值的位置。 -4. 已有变量做复合运算时，才使用 `+=`、`-=`、`*=`、`/=`、`%=`、`a++;`、`a--;`。 -5. 条件求值优先用 `flag ? true_value : false_value`；需要 Pascal 风格时可用 `if condition then true_value else false_value` 的形态，但必须带 `else`。 -6. 需要延迟求值或动态表达式对象时，才使用 `@expr` 或 `&"..."`，并用已验证的 `eval(...)` 形态求值。 -7. 空安全访问只照本页已验证形态写：`a?.member`、`a?.[index]`、以及已验证的 `c?.a?.[1]`。不要外推成任意深度、任意组合都可写。 -8. 需要连续比较时，标量用 `:<` / `:>` 这组链式比较；数组逐元素比较用 `::<` / `::>` 这组矩阵链式比较。 -9. 没有已验证代码块时不要发明表达式/运算符写法。 - -## 必须记住的规则 - -- 当前页只收已经单独验证过的基础表达式，不把未经逐条验证的扩展运算体系一次并进正文。 -- 普通赋值使用 `:=`。 -- 已验证支持 `+=`、`-=`、`*=`、`/=`、`%=` 这几种基础运算赋值。 -- 已验证支持语句级 `a++;` 与 `a--;`。 -- `=` 用于比较，不用于赋值。 -- 已验证支持字符串 `+` 拼接、字符串比较和 `like` 正则匹配。 -- 已验证支持 `flag ? true_value : false_value` 和 `if condition then true_value else false_value` 这两种条件求值写法。 -- 已验证支持 `@expr` 把后面的内容声明成表达式对象。 -- 已验证支持 `&"..."` 把字符串编译成表达式对象。 -- 已验证支持逗号表达式 `(exp1, exp2, ..., expN)`，并按从左到右顺序求值。 -- 已验证支持空安全访问 `a?.member`、`a?.[index]` 和本页示例里的 `c?.a?.[1]`。 -- 已验证支持 `not in`、`not like`、`not sqlin`、`not is` 这几种否定形式运算。 -- 已验证支持标量链式比较 `:>`、`:<`、`:<>`、`:==`、`:>=`、`:<=`。 -- 已验证支持矩阵链式比较 `::>`、`::<`、`::<>`、`::==`、`::>=`、`::<=`。 -- `{$IFDEF ifexp}` 可用于探测 `if ... then ... else ...` 表达式能力。 -- `{$IFDEF nilinvoke}` 可用于探测 nil 调用相关能力。 - -## 已验证语法 - -### 基础赋值和条件求值 - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -b := 2; -flag := a < b; -value := flag ? 10 : 20; -WriteLn(value); -``` - -代码块身份：已验证输出片段 - -```text -10 -``` - -运算赋值： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -a += 2; -WriteLn(a); -``` - -代码块身份：已验证输出片段 - -```text -3 -``` - -基础算术复合赋值： - -代码块身份：已验证可执行示例 - -```tsl -a := 10; -a -= 3; -WriteLn(a); -a *= 4; -WriteLn(a); -a /= 7; -WriteLn(a); -a %= 5; -WriteLn(a); -``` - -代码块身份：已验证输出片段 - -```text -7 -28 -4 -4 -``` - -字符串同样支持 `+=`： - -代码块身份：已验证可执行示例 - -```tsl -s := "A"; -s += "B"; -WriteLn(s); -``` - -代码块身份：已验证输出片段 - -```text -AB -``` - -字符串拼接、比较和 `like`： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("222" + "888"); -WriteLn("A" < "a"); -WriteLn("AB" < "ABC"); -WriteLn("ABC" = "ABC"); -WriteLn("2009-01-01" like "\\d{4}-\\d{2}-\\d{2}"); -``` - -代码块身份：已验证输出片段 - -```text -222888 -1 -1 -1 -1 -``` - -说明： - -- 字符串可以直接用 `+` 拼接。 -- 字符串比较区分字符序和大小写；当前例子里 `"A" < "a"` 为真。 -- `like` 的右侧可以直接写正则模式。 - -`like` 不要按 SQL `%` 通配去理解： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("abc" like "a.*"); -WriteLn("abc" like "a%"); -``` - -代码块身份：已验证输出片段 - -```text -1 -0 -``` - -因此 `like` 更接近“正则匹配”，不是 SQL 那套 `%` / `_` 通配语义。 - -自增与自减： - -代码块身份：已验证可执行示例 - -```tsl -a := 1; -a++; -WriteLn(a); -a--; -WriteLn(a); -``` - -代码块身份：已验证输出片段 - -```text -2 -1 -``` - -`if` 表达式： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn(if 2 > 1 then 2 else 1); -``` - -代码块身份：已验证输出片段 - -```text -2 -``` - -`if condition then true_value else false_value` 必须带 `else`，否则不是本页可照写的表达式形态。 - -### 表达式对象 - -`@` 表达式前导： - -代码块身份：已验证可执行示例 - -```tsl -A := 1; -B := @A + 1; -C := eval(B); -WriteLn(C); -``` - -代码块身份：已验证输出片段 - -```text -2 -``` - -`@A + 1` 会得到一个可交给 `eval(...)` 求值的表达式对象。 - -`&"..."` 表达式常量： - -代码块身份：已验证可执行示例 - -```tsl -A := 1; -B := &"A + 1"; -C := eval(B); -WriteLn(C); -``` - -代码块身份：已验证输出片段 - -```text -2 -``` - -`&"A + 1"` 会把字符串编译成表达式对象，再由 `eval(...)` 求值。 - -逗号表达式： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Demo(); -begin - return (a := 1, b := 2, c := 3, a + b + c); -end; -begin - WriteLn(Demo()); -end. -``` - -代码块身份：已验证输出片段 - -```text -6 -``` - -逗号表达式会按从左到右顺序执行前面的赋值，再返回最后一个表达式结果。 - -逗号表达式也可以继续参与外层计算： - -代码块身份：已验证可执行示例 - -```tsl -A := (b := 2, c := 3, b * c) * c; -WriteLn(A); -``` - -代码块身份：已验证输出片段 - -```text -18 -``` - -逗号表达式本身可以作为一个普通子表达式继续参与后续运算。 - -### 空安全访问 - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Holder = class - value; -end; -begin - a := nil; - WriteLn(a?.value = nil); - h := new Holder(); - h.value := 7; - WriteLn(h?.value); - arr := nil; - WriteLn(arr?.[0] = nil); -end. -``` - -代码块身份：已验证输出片段 - -```text -1 -7 -1 -``` - -更深一层的混合空安全访问，本页只确认下面这个形态： - -代码块身份：已验证可执行示例 - -```tsl -c := nil; -WriteLn(c?.a?.[1] = nil); -``` - -代码块身份：已验证输出片段 - -```text -1 -``` - -不要从这一段外推任意深度、任意成员/下标混合都可写。 - -### 否定形式运算 - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class -end; -type B = class -end; -begin - WriteLn(1 not in array(2, 3)); - WriteLn("2009-1-1" not like "\\d{4}-\\d{2}-\\d{2}"); - WriteLn(1 not sqlin array(2, 3)); - obj := new A(); - WriteLn(obj not is class(B)); -end. -``` - -代码块身份：已验证输出片段 - -```text -1 -1 -1 -1 -``` - -### 标量链式比较 - -代码块身份：已验证可执行示例 - -```tsl -WriteLn(1 :< 2 :< 3); -WriteLn(3 :> 2 :> 1); -WriteLn(1 :== 1 :== 1); -WriteLn(3 :>= 2 :>= 2); -WriteLn(1 :<= 2 :<= 3); -WriteLn(1 :<> 2 :<> 3); -``` - -代码块身份：已验证输出片段 - -```text -1 -1 -1 -1 -1 -1 -``` - -### 矩阵链式比较 - -代码块身份：已验证可执行示例 - -```tsl -r := array(1, 2, -1) ::< array(2, 1, 0) ::< array(3, 2, 1); -WriteLn(r[0]); -WriteLn(r[1]); -WriteLn(r[2]); -s := array(1, 2, -1) ::< 2 ::< array(3, 2, 1); -WriteLn(s[0]); -WriteLn(s[1]); -WriteLn(s[2]); -``` - -代码块身份：已验证输出片段 - -```text -1 -0 -1 -1 -0 -0 -``` - -矩阵链式比较会按元素位置分别得到结果数组，并且可以和标量混用。 - -### 条件编译探测 - -代码块身份：已验证可执行示例 - -```tsl -{$IFDEF ifexp} -WriteLn(1); -{$ELSE} -WriteLn(0); -{$ENDIF} -{$IFDEF nilinvoke} -WriteLn(1); -{$ELSE} -WriteLn(0); -{$ENDIF} -``` - -代码块身份：已验证输出片段 - -```text -1 -1 -``` - -这只能作为能力探测示例使用；agent 不要把条件编译探测写成普通业务逻辑。 - -## 最小可编译示例 - -如果你只需要最小的“比较 + 三目”例子，直接用这个： - -代码块身份：已验证可执行示例 - -```tsl -flag := 1 < 2; -value := flag ? 10 : 20; -WriteLn(value); -``` - -代码块身份：已验证输出片段 - -```text -10 -``` - -## 常见误写 - -- 用 `=` 当赋值运算符。 -- 把 `if` 表达式写成没有 `else` 的半句。 -- 把已验证的 `c?.a?.[1]` 外推成所有深链式空安全访问都可靠。 - -代码块身份：反例 / 不可照写 - -```text -a = 1; -``` - -代码块身份：已验证输出片段 - -```text -invalid statement -``` - -上面这种写法会编译失败，因为单独的 `=` 在这里会被当成不成立的表达式。 - -代码块身份：反例 / 不可照写 - -```text -v := if 2 > 1 then 2; -``` - -代码块身份：已验证输出片段 - -```text -invalid statement -``` - -上面这种写法也会编译失败；`if` 表达式必须带 `else`。 - -## 跳转指引 - -- 回看基本类型：见 [04_values_and_literals.md](04_values_and_literals.md) -- 把表达式放进流程里：见 [08_control_flow.md](08_control_flow.md) diff --git a/docs/tsl/syntax/08_control_flow.md b/docs/tsl/syntax/08_control_flow.md deleted file mode 100644 index fe69ee98..00000000 --- a/docs/tsl/syntax/08_control_flow.md +++ /dev/null @@ -1,388 +0,0 @@ -# Control Flow - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[07_expressions_and_operators.md](07_expressions_and_operators.md)、[16_debug_and_profiler.md](16_debug_and_profiler.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 8 篇，共 32 篇。上一篇：[07_expressions_and_operators.md](07_expressions_and_operators.md)。下一篇：[09_objects_and_classes.md](09_objects_and_classes.md)。 - -这一篇只收录流程控制与异常控制，不讨论金融语义。 - -## 这一篇解决什么问题 - -回答“`if`、`case`、`for`、`while`、`repeat`、`break`、`continue`、`try`、`raise` 这些流程结构在 TSL 里到底怎么写，哪些写法已经被当前解释器实测验证过”。 - -## Agent 控制流判断流程 - -1. 先判断任务需要条件分支、循环、`case`、异常处理还是调试跳转。 -2. `if` / `for` / `while` / `repeat` 优先照本页已验证骨架写，不要套用其他 Pascal 方言。 -3. 需要多条语句时再补 `begin ... end`，不要在 `else` 前提前加分号。 -4. `case` 表达式和 `case` 语句分开判断；`@case` 不作为默认主写法。 -5. 没有已验证代码块时不要发明控制流写法。 - -## 必须记住的规则 - -- `if ... then ... else ...` 可以直接跟单条语句；需要多条语句时再补 `begin ... end`。 -- `for` 已验证支持 `to`、`downto`、可选 `step`，以及 `for i, v in array` 遍历。 -- `while` 和 `repeat ... until` 都可直接使用；`repeat` 至少会先执行一轮再判断结束条件。 -- `break` 会跳出当前最近一层循环，`continue` 会跳过当前轮剩余语句。 -- `case ... of ... else ... end;` 已验证支持语句形态和表达式形态。 -- `case` 分支标签已验证支持逗号并列和 `to` 区间。 -- `try ... except ... end;` 可以捕获 `raise` 产生的错误，并继续执行后续语句。 -- `ExceptObject.ErrInfo` 在 `except` 块中可读，能拿到当前错误信息。 -- `ExceptObject.ErrLine` 和 `ExceptObject.ErrNo` 在 `except` 块中当前也可读。 -- `try ... finally ... end;` 无论是否报错，都会先执行 `finally`；如果没有 `except` 吞掉错误，脚本仍会在 `finally` 之后报错终止。 -- `raise "message"` 是当前解释器已验证可用的最小抛错写法。 -- `goto`、`DEBUGRETURN`、`DebugRunEnv`、计时和 profiler 这类“控制流补充工具”统一放到 [16_debug_and_profiler.md](16_debug_and_profiler.md)。 - -## 已验证语法 - -### `if`、`while`、`repeat ... until` - -代码块身份：已验证可执行示例 - -```tsl -flag := 1; -if flag > 0 then - value := 1 -else - value := 0; - -counter := 0; -while counter < 3 do - counter := counter + 1; - -repeat - counter := counter - 1; -until counter = 0; -``` - -### `for` 的几种主干写法 - -最基础的递增循环： - -代码块身份：已验证可执行示例 - -```tsl -sum := 0; -for i := 0 to 2 do - sum := sum + i; -``` - -带 `step` 的递增循环： - -代码块身份：已验证可执行示例 - -```tsl -s := 0; -for i := 1 to 5 step 2 do - s := s + i; -WriteLn(s); -``` - -已验证运行结果： - -- 输出 `9` - -代码块身份：已验证输出片段 - -```text -9 -``` - -带 `step` 的 `downto` 递减循环： - -代码块身份：已验证可执行示例 - -```tsl -s := 0; -for i := 5 downto 1 step 2 do - s := s + i; -WriteLn(s); -``` - -已验证运行结果： - -- 输出 `9` - -数组遍历： - -代码块身份：已验证可执行示例 - -```tsl -data := array(10, 20, 30); -for i, v in data do - WriteLn(i * 100 + v); -``` - -已验证运行结果： - -- 依次输出 `10`、`120`、`230` -- 这说明 `for i, v in data` 里的 `i` 从 `0` 开始 - -### `break` 与 `continue` - -`break`： - -代码块身份：已验证可执行示例 - -```tsl -i := 0; -sum := 0; -while true do -begin - i := i + 1; - if i > 3 then - break; - sum := sum + i; -end; -WriteLn(sum); -WriteLn(i); -``` - -已验证运行结果： - -- `sum` 输出 `6` -- `i` 输出 `4` - -`continue`： - -代码块身份：已验证可执行示例 - -```tsl -i := 0; -sum := 0; -while i < 4 do -begin - i := i + 1; - if i = 2 then - continue; - sum := sum + i; -end; -WriteLn(sum); -``` - -已验证运行结果： - -- 输出 `8` - -### `case` 语句形态 - -普通分支： - -代码块身份：已验证可执行示例 - -```tsl -a := 2; -case a of -1: - WriteLn("one"); -2: - WriteLn("two"); -else - WriteLn("other"); -end; -``` - -已验证运行结果： - -- 输出 `two` - -并列标签与区间： - -代码块身份：已验证可执行示例 - -```tsl -a := 4; -case a of -1, 2: - WriteLn("small"); -3 to 5: - WriteLn("mid"); -else - WriteLn("other"); -end; -``` - -已验证运行结果： - -- 输出 `mid` - -### `case` 表达式形态 - -代码块身份：已验证可执行示例 - -```tsl -a := 2; -b := case a of -1: - "one"; -2: - "two"; -else - "other"; -end; -WriteLn(b); -``` - -已验证运行结果： - -- 输出 `two` - -### `try ... except` - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("before"); -try - raise "boom"; -except - WriteLn("caught"); - WriteLn(ExceptObject.ErrInfo); -end; -WriteLn("after"); -``` - -已验证运行结果： - -- 先输出 `before` -- 再输出 `caught` -- `ExceptObject.ErrInfo` 输出包含 `raise: boom` 的错误信息 -- 最后继续输出 `after` - -`ExceptObject` 的扩展字段： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - try - raise "boom"; - except - WriteLn(ExceptObject.ErrLine); - WriteLn(ExceptObject.ErrNo); - end; -end. -``` - -已验证运行结果： - -- `ExceptObject.ErrLine` 输出 `4` -- `ExceptObject.ErrNo` 输出 `2` -- 说明当前解释器里，异常对象除了 `ErrInfo` 以外，也能直接提供出错行号和错误号 - -### `try ... finally` - -正常路径： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("before"); -try - WriteLn("body"); -finally - WriteLn("finally"); -end; -WriteLn("after"); -``` - -已验证运行结果： - -- 依次输出 `before`、`body`、`finally`、`after` - -报错路径： - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("before"); -try - WriteLn("body"); - raise "boom"; -finally - WriteLn("finally"); -end; -WriteLn("after"); -``` - -已验证运行结果： - -- 先输出 `before` -- 再输出 `body` -- 然后仍会输出 `finally` -- 随后脚本报错终止，`after` 不会执行 - -### `raise` - -代码块身份：已验证可执行示例 - -```tsl -WriteLn("before"); -raise "boom"; -WriteLn("after"); -``` - -已验证运行结果： - -- 先输出 `before` -- 随后脚本报错终止，`after` 不会执行 - -## 最小可编译示例 - -如果你只想先写一个最短条件分支，从这个开始： - -代码块身份：已验证可执行示例 - -```tsl -flag := 1; -if flag > 0 then - value := 1 -else - value := 0; -``` - -## 常见误写 - -- 在 `else` 前面误加分号。 -- 以为 `try ... finally` 会吞掉异常。 -- 把 `@case` 直接当成普通 `case` 表达式主写法。 -- 在还没搞清表达式规则前，先把复杂业务函数塞进条件里。 -- 把控制流问题和函数文件模型问题混在一起排查。 - -代码块身份：反例 / 不可照写 - -```text -if flag > 0 then - value := 1; -else - value := 0; -``` - -上面这种写法会编译失败，因为 `else` 前面的分号会让 `if` 语句在上一行提前结束。 - -代码块身份：反例 / 不可照写 - -```text -b := @case a of - 1: - "one"; - 2: - "two"; -else - "other"; -end; -WriteLn(b); -``` - -当前已验证结果显示，上面这类最小例子输出的是 ``，不能把它当成普通 `case` 表达式的可靠主语法写进新 session 默认生成结果。 - -## 跳转指引 - -- 回看条件表达式：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 继续封装成函数：见 [06_functions_and_calls.md](06_functions_and_calls.md) -- 看 `goto`、`DEBUGRETURN`、计时和 profiler：见 [16_debug_and_profiler.md](16_debug_and_profiler.md) diff --git a/docs/tsl/syntax/08_objects_and_classes.md b/docs/tsl/syntax/08_objects_and_classes.md new file mode 100644 index 00000000..e02a0fc1 --- /dev/null +++ b/docs/tsl/syntax/08_objects_and_classes.md @@ -0,0 +1,1387 @@ +# TSL 对象与类 + +文档类型：语法主线 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[09_units_and_scope.md](09_units_and_scope.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇收拢面向对象语法，只保留语言层规则。 + +## 本篇职责 + +回答“`type Name = class`、字段、`static`、方法、`property`、析构、类类型、继承和对象创建在 TSL 里怎样写”。 + +本页后半段有少量依赖 `unit` 的双文件示例；如果你还没建立 `unit` / `uses` 的多文件心智模型，先看 [09_units_and_scope.md](09_units_and_scope.md)。 + +## 智能体对象/类判断流程 + +1. 先判断要写普通对象、继承、构造函数、类方法、静态字段还是运行时创建。 +2. 对象声明优先使用本页明确的 `type Name = class ... end;` 骨架。 +3. 普通本地类创建默认用 `new ClassName()`；只有需要字符串类名、类类型变量或跨 `unit` 路径时，才用 `createObject(...)`。 +4. 类方法和静态字段优先用 `class(Name).Member` 或文档明确反射入口，不要裸写类名调用。 +5. 构造函数默认保持 `public create`，不要把 `private` / `protected create` 当成会自动执行的构造函数。 +6. 普通类成员默认显式写 `public` 段，不依赖隐式 public。 +7. 方法体内访问当前实例成员默认直接写成员名；成员读写为了性能不加 `self` 前缀。 +8. 命中对象反射 / 运行时状态、内置运行时对象、对象重载 / 迭代时，分别跳到 [20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)。 +9. 没有文档事实时不要发明对象/类写法。 + +## 核心规则 + +- 类定义统一按 `type Name = class ... end;` 写。 +- 顶层类声明可以放在松散语句之后（单向允许）。 +- 顶层类声明也可以放在顶层 `function / procedure` 之后。 +- 类声明不要写在函数体内部。 +- 在松散语句脚本里，可以先写松散语句再进入顶层类声明；但一旦进入顶层 `type Name = class ... end;` 声明，后面不能再回到松散语句模式。 +- 类里可以直接写字段和方法。 +- 字段可以写类型注解，例如 `name_: string;`。 +- 类方法参数和返回值可以写类型注解，例如 `function ReadName(): string;`。 +- 类的声明和实现可以分离：类内可以只声明方法签名，再用 `function ClassName.Method(...)` 在类外实现；带类型和 `overload` 时，类外实现保持同一组签名；类外实现属于声明区，后面不要再追加脚本语句。 +- `static` 字段可用；可以通过类类型访问，也可以通过实例访问。 +- `const` 成员可用；实例常量可通过实例读取，`static const` 可通过类类型读取，也可用于成员函数默认参数。 +- 方法体里默认直接用成员名访问当前实例成员；普通成员读写为了性能不加 `self` 前缀，也不要为了“显式”访问而补这个前缀。 +- `overload` 方法可用；同名不同参数个数的方法可以共存。 +- 基础 `property` 形态：`property Name read fieldOrMethod write fieldOrMethod`。 +- `property Name: Type ...` 这种类型注解写法可用。 +- 参数化 `property` 可用；本页只写基础模式。 +- 参数化 `property` 的 accessor 方法记录两种常见模式：读方法接同参数个数，写方法接“参数个数 + 赋值值”。 +- 索引型 `property` 可用；调用时用圆括号 `obj.Prop(index)`。 +- 固定 `index` property 可用；它可以把某个固定索引直接映射成普通属性读写。 +- `class(Name)` 和 `findClass("Name")` 都可以拿到类类型。 +- `findClass("ClassName", obj)` 可把对象转成指定父类视图。 +- `class function` 可用；本页里的“类方法”就是指 `class function`，前者是中文描述，后者是代码写法。 +- 类方法默认先拿到类类型，再在类类型上调用。 +- 基础继承写法是 `type Child = class(Parent)`。 +- 多重继承写法 `type Child = class(Base1, Base2)` 可用。 +- 基础覆盖写法是：父类方法声明为 `virtual`，子类对应方法声明为 `override`。 +- 基础祖先类调用：可以用 `Inherited;`、`Inherited MethodName(...)` 或 `class(BaseClass, ObjectName).MethodName()`。 +- 创建对象有两种方式：`new ClassName()` 最常用，`createObject(...)` 作为次选。 +- 普通本地类实例化默认生成 `new ClassName()`；`createObject("ClassName")`、`createObject(ClassType)` 只在字符串类名、类类型变量或跨 `unit` 路径场景生成。 +- 如果类里定义了 `function create(...)`，`new`、`createObject("ClassName", ...)` 和 `createObject(ClassType, ...)` 都可以透传构造参数，也都支持默认参数和命名参数。 +- 析构写法是无参 `function destroy();`；把对象引用设为 `nil` 时会触发它。 +- 工厂式 `self(0)` / `self(1)` 可用；不要生成 `self()` 这种无参工厂式写法。 +- 跨 `unit` 类路径创建和继承属于多文件边界；先回看 [09_units_and_scope.md](09_units_and_scope.md) 和 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)，不要从普通单文件 `new` / `createObject` 规则直接泛化。 +- `{$ifdef parentClassInUnit}` 为真，可用于探测“继承和构造单元中的类”能力是否可用。 +- `private` / `protected` / `public` 可用；类开头未写可见性时，成员默认按 `public` 处理，但生成代码默认显式写 `public`。 +- 同一个可见性段里后续没有切换关键字的成员，会沿用前一个可见性。 +- 外部访问 `private` / `protected` 字段或方法，会在执行时报对象成员访问错误。 +- 子类可以直接访问父类 `protected` 成员；不能直接访问父类 `private` 成员。 +- `create` 写成 `private` 或 `protected` 时，对象仍能创建，但 `new` 和 `createObject(...)` 不会执行该构造逻辑；构造函数应保持 `public`。 +- 更复杂的多重继承边界和更复杂的对象模型不在本页展开。 + +## 可直接照写示例 + +使用这些示例时遵守： + +- 普通本地类创建优先复制 `new ClassName()` 形态。 +- `createObject(...)` 示例只在字符串类名、类类型变量或跨 `unit` 路径场景复制。 +- `property` 类型注解只有在已有类型名证据时生成；不要为了完整性发明说明性类型名。 + +### 最小类与声明位置 + +最短类骨架： + +如果任务只是要“先写出一个类”，先从这个骨架起手；后面的例子再逐步进入字段、工厂函数和声明位置边界。 + +代码块身份：可直接照写示例 + +```tsl +type Person = class +end; +``` + +字段、方法和 `new`： + +代码块身份：可直接照写示例 + +```tsl +type Person = class +public + name; + function SetName(new_name); + begin + name := new_name; + end; +end; + +function MakePerson(); +begin + return new Person(); +end; +``` + +类声明位置： + +代码块身份：可直接照写示例 + +```tsl +obj := new MyClass(); +obj.value := 5; +writeLn(obj.value); + +type MyClass = class +public + value; +end; +``` + +输出说明： + +- 输出 `5` +- 说明顶层类声明可以放在松散语句之后 +- 同时也说明 `new MyClass()` 可以解析到后面才出现的类声明 + +代码块身份：输出片段 + +```text +5 +``` + +顶层函数后面也可以继续声明类： + +代码块身份：可直接照写示例 + +```tsl +function MakeObj(); +begin + return 1; +end; + +type MyClass = class +public + value; +end; +``` + +结果说明： + +- 上述声明顺序可以编译通过 + +类声明位置的反例： + +代码块身份：反例 / 不可照写 + +```text +// 函数体内部声明类 +function Demo(); +begin + type InnerClass = class + value; + end; + return 1; +end; + +// 松散语句在 type 之后继续出现 +a := 1; +type MyClass = class +public + value; +end; +writeLn(a); +``` + +结果说明： + +- 函数体内部声明类会报 `invalid statement` +- 在松散语句脚本里，`type MyClass = class ... end;` 之后继续写 `writeLn(a);` 也会报 `invalid statement` + +### 字段、静态成员、常量与可见性 + +`static` 字段： + +代码块身份：可直接照写示例 + +```tsl +class(THuman).mCount := 100; +writeLn(class(THuman).mCount); +h := new THuman(); +writeLn(class(THuman).mCount); +writeLn(h.mCount); + +type THuman = class +public + static mCount; + function create(); + begin + mCount := (mCount ?: 0) + 1; + end; +end; +``` + +输出说明： + +- `class(THuman).mCount := 100` 可以直接写静态字段 +- `class(THuman).mCount` 先输出 `100` +- 创建对象后，`class(THuman).mCount` 输出 `101` +- 通过实例读取 `h.mCount` 也输出 `101` +- 单个静态字段默认写成 `static mCount;` + +`const` 成员： + +代码块身份：可直接照写示例 + +```tsl +o := new C(); +writeLn(o.TestConst()); +writeLn(o.TestConstInParam()); +writeLn(o.mA); +writeLn(class(C).mB); + +type C = class +public + const mA = 1; + static const mB = mA + 10; + function TestConst(); + begin + return mA + mB; + end; + function TestConstInParam(b = mB); + begin + return b; + end; +end; +``` + +输出说明： + +- 依次输出 `12`、`11`、`1`、`11` +- 说明类里可以定义实例常量和 `static const` +- 说明实例常量可通过实例读取，`static const` 可通过 `class(C)` 读取 +- 说明成员常量也可用于成员函数默认参数 + +成员方法内直接访问成员： + +代码块身份：可直接照写示例 + +```tsl +c := new Counter(10); +writeLn(c.Inc()); + +type Counter = class +public + value; + function create(v); + begin + value := v; + end; + function Inc(); + begin + value := value + 1; + return value; + end; +end; +``` + +输出说明： + +- `c.Inc()` 输出 `11` + +可见性 `private` / `protected` / `public`： + +代码块身份：可直接照写示例 + +```tsl +a := new A(); +a.value := 9; +writeLn(a.value); +writeLn(a.ReadSecret()); + +type A = class +public + value; +private + secret; + backup; +public + function create(); + begin + secret := 2; + backup := 3; + end; + function ReadSecret(); + begin + return secret + backup; + end; +end; +``` + +输出说明： + +- `value` 写在显式 `public` 段里，因此 `a.value := 9` 可以直接写。 +- `backup` 跟在 `private` 段后面，没有重新切换关键字，因此仍按 `private` 处理。 +- 上述例子依次输出 `9`、`5`。 + +`protected` 可供子类直接访问： + +代码块身份：可直接照写示例 + +```tsl +b := new B(); +b.SetValue(66); +writeLn(b.GetValue()); +writeLn(b.TryCall()); + +type A = class +protected + value; + function Hidden(); + begin + return 88; + end; +end; +type B = class(A) +public + function SetValue(v); + begin + value := v; + end; + function GetValue(); + begin + return value; + end; + function TryCall(); + begin + return Hidden(); + end; +end; +``` + +输出说明： + +- 子类里可以直接访问父类 `protected` 字段。 +- 子类里也可以直接调用父类 `protected` 方法。 +- 上述例子依次输出 `66`、`88`。 + +`private` 的失败场景，这里用 `text` 展示反例： + +代码块身份：反例 / 不可照写 + +```text +// 外部访问 private 字段 +a := new A(); +writeLn(a.secret); + +type A = class +private + secret; +public + function create(); + begin + secret := 7; + end; +end; + +// 子类调用父类 private 方法 +b := new B(); +writeLn(b.TryCall()); + +type A = class +private + function Hidden(); + begin + return 77; + end; +end; +type B = class(A) +public + function TryCall(); + begin + return Hidden(); + end; +end; +``` + +输出说明： + +- 外部访问 `a.secret` 会在执行时报对象成员访问错误。 +- 子类里直接调用父类 `private` 方法也会在执行时报错。 +- `private` / `protected` 方法访问也遵循同样边界：外部不能调 `private` / `protected` 方法，子类只能调 `protected` 方法，不能调 `private` 方法。 + +### 构造函数边界 + +`create` 建议保持 `public`： + +代码块身份：可直接照写示例 + +```tsl +a := new A(111); +writeLn(a.value); + +type A = class +public + value; +private + function create(v); + begin + value := v; + end; +end; +``` + +输出说明： + +- `a := new A(111)` 可以创建对象。 +- 上述例子里的 `a.value` 输出 ``，说明 `private create` 没有执行。 +- `protected create`、`createObject("A", ...)` 和 `createObject(class(A), ...)` 也按同一规则处理；构造函数应保持 `public`。 + +### 属性、类型注解与类外实现 + +基础 `property`： + +代码块身份：可直接照写示例 + +```tsl +b := new MyBox(); +b.Value := 7; +writeLn(b.Value); +b.Value := -1; +writeLn(b.Value); + +type MyBox = class +public + _value; + function SetValue(v); + begin + if v > 0 then + _value := v; + end; + property Value read _value write SetValue; +end; +``` + +输出说明： + +- `b.Value := 7` 后，`b.Value` 输出 `7` +- `b.Value := -1` 后，`b.Value` 仍输出 `7` + +带类型注解的 `property`： + +代码块身份：可直接照写示例 + +```tsl +b := new MyBox(); +b.Value := 9; +writeLn(b.Value); + +type MyBox = class +public + _value; + function SetValue(v); + begin + _value := v; + end; + property Value: integer read _value write SetValue; +end; +``` + +输出说明： + +- `property Value: integer ...` 这种类型注解写法可以通过 +- 上述例子中的 `b.Value` 输出 `9` + +字段和类方法类型注解： + +代码块身份：可直接照写示例 + +```tsl +box := new TypedBox("abc", 7); +writeLn(box.Name); +writeLn(box.Value); +writeLn(box.ReadName()); + +type TypedBox = class +public + function create(_name: string; _value: any); + begin + name_ := _name; + value_ := _value; + end; + function ReadName(): string; + begin + return name_; + end; + property Name: string read name_ write name_; + property Value: any read value_ write value_; +private + name_: string; + value_: any; +end; +``` + +输出说明： + +- `name_: string;` 和 `value_: any;` 可以作为类字段类型注解。 +- `function create(_name: string; _value: any);` 可以作为类方法参数类型注解。 +- `function ReadName(): string;` 可以作为类方法返回值类型注解。 +- 上述例子依次输出 `abc`、`7`、`abc`。 + +代码块身份：输出片段 + +```text +abc +7 +abc +``` + +类内声明、类外实现的带类型重载方法： + +代码块身份：可直接照写示例 + +```tsl +a := new PairBox("left"); +writeLn(a.Left); +writeLn(a.Right); +b := new PairBox("left", 2); +writeLn(b.Left); +writeLn(b.Right); +writeLn(b.ReadLeft()); + +type PairBox = class +public + function create(_left: string); overload; + function create(_left: string; _right: any); overload; + function ReadLeft(): string; + property Left: string read left_ write left_; + property Right: any read right_ write right_; +private + left_: string; + right_: any; +end; + +function PairBox.create(_left: string); overload; +begin + create(_left, nil); +end; + +function PairBox.create(_left: string; _right: any); overload; +begin + left_ := _left; + right_ := _right; +end; + +function PairBox.ReadLeft(): string; +begin + return left_; +end; +``` + +输出说明： + +- 类内可以只声明带类型的重载方法签名。 +- 类外实现写成 `function PairBox.create(...); overload;`，并保持同样的参数类型和 `overload` 标记。 +- 类外实现属于声明区；写完后不要再追加脚本语句。 +- 从一个构造函数转调另一个构造函数时，直接写 `create(_left, nil);`，不要加 `self` 前缀。 +- 上述例子依次输出 `left`、``、`left`、`2`、`left`。 + +代码块身份：输出片段 + +```text +left + +left +2 +left +``` + +索引型 `property`： + +代码块身份：可直接照写示例 + +```tsl +aa := new A(); +aa.idx(0) := "abc"; +writeLn(aa.idx(0)); + +type A = class +public + arr; + function create(); + begin + arr := array(); + end; + function rIndex(i); + begin + return arr[i]; + end; + function wIndex(i, value); + begin + arr[i] := value; + end; + property idx read rIndex write wIndex; +end; +``` + +输出说明： + +- `aa.idx(0) := "abc"` 可以写入索引 property +- `aa.idx(0)` 输出 `abc` + +固定 `index` property： + +代码块身份：可直接照写示例 + +```tsl +aa := new A(); +aa.idx0 := "abc"; +writeLn(aa.idx0); +writeLn(aa.idx(0)); + +type A = class +public + arr; + function create(); + begin + arr := array(); + end; + function rIndex(i); + begin + return arr[i]; + end; + function wIndex(i, value); + begin + arr[i] := value; + end; + property idx read rIndex write wIndex; + property idx0 index 0 read rIndex write wIndex; +end; +``` + +输出说明： + +- `aa.idx0 := "abc"` 可以写入固定整数索引 property +- `aa.idx0` 输出 `abc` +- `aa.idx(0)` 也输出 `abc` + +固定字符串索引： + +代码块身份：可直接照写示例 + +```tsl +aa := new A(); +aa.school := "math"; +writeLn(aa.school); +writeLn(aa.idx("High school")); + +type A = class +public + arr; + function create(); + begin + arr := array(); + end; + function rIndex(i); + begin + return arr[i]; + end; + function wIndex(i, value); + begin + arr[i] := value; + end; + property idx read rIndex write wIndex; + property school index "High school" read rIndex write wIndex; +end; +``` + +输出说明： + +- `property school index "High school"` 这种固定字符串索引写法可以通过 +- `aa.school` 输出 `math` +- `aa.idx("High school")` 也输出 `math` + +参数化 `property`： + +代码块身份：可直接照写示例 + +```tsl +d := new MyDate(); +d.DateV(2025, 8) := 10; +writeLn(d.DateV()); + +type MyDate = class +public + _year; + _month; + _day; + function getDateV(); + begin + return _year * 10000 + _month * 100 + _day; + end; + function setDateV(y, m, d); + begin + _year := y; + _month := m; + _day := d; + end; + property DateV(y, m) read getDateV write setDateV; +end; +``` + +输出说明： + +- `d.DateV(2025, 8) := 10` 可以给参数化 property 赋值 +- `d.DateV()` 输出 `20250810` + +参数化 `property` 的 accessor 方法参数： + +代码块身份：可直接照写示例 + +```tsl +aa := new A(); +aa.Item(2) := "x"; +writeLn(aa.Item(2)); + +type A = class +public + arr; + function create(); + begin + arr := array(); + end; + function getItem(i); + begin + return arr[i]; + end; + function setItem(i, value); + begin + arr[i] := value; + end; + property Item(i): string read getItem write setItem; +end; +``` + +输出说明： + +- `read getItem` 这种“读方法接同参数个数”的写法可以通过 +- `write setItem` 这种“写方法接参数个数 + 赋值值”的写法可以通过 +- 上述例子中的 `aa.Item(2)` 输出 `x` + +### 对象创建与类类型 + +`new` 关键字： + +代码块身份：可直接照写示例 + +```tsl +type Person = class +end; + +function MakePerson(); +begin + return new Person(); +end; +``` + +通过类类型创建对象： + +代码块身份：可直接照写示例 + +```tsl +cls := findClass("Person"); +obj := createObject(cls); +obj.value := 42; +writeLn(obj.value); + +type Person = class +public + value; +end; +``` + +输出说明： + +- `createObject(cls)` 可以通过类类型创建对象 +- 上述例子中的 `obj.value` 输出 `42` + +也可以用 `class(Name)` 取得类类型： + +代码块身份：可直接照写示例 + +```tsl +cls := class(Person); +obj := createObject(cls, 44); +writeLn(obj.value); + +type Person = class +public + value; + function create(v); + begin + value := v; + end; +end; +``` + +输出说明： + +- `class(Person)` 可以拿到 `Person` 的类类型 +- `createObject(cls, 44)` 输出 `44` + +构造参数、默认值和命名参数： + +代码块身份：可直接照写示例 + +```tsl +a := new Person(22, c:99); +writeLn(a.x); +writeLn(a.y); +writeLn(a.z); +b := createObject("Person", 11); +writeLn(b.x); +writeLn(b.y); +writeLn(b.z); + +type Person = class +public + x; + y; + z; + function create(a, b = 20, c = 30); + begin + x := a; + y := b; + z := c; + end; +end; +``` + +输出说明： + +- `new Person(22, c:99)` 依次输出 `22`、`20`、`99` +- `createObject("Person", 11)` 依次输出 `11`、`20`、`30` +- 说明构造函数默认参数和命名参数不只适用于普通函数调用，也适用于对象创建 + +类类型也同样支持默认参数和命名参数： + +代码块身份：可直接照写示例 + +```tsl +cls := findClass("Person"); +obj := createObject(cls, 33, c:77); +writeLn(obj.x); +writeLn(obj.y); +writeLn(obj.z); + +type Person = class +public + x; + y; + z; + function create(a, b = 20, c = 30); + begin + x := a; + y := b; + z := c; + end; +end; +``` + +输出说明： + +- `createObject(cls, 33, c:77)` 依次输出 `33`、`20`、`77` +- 因此类类型入口下的 `createObject(cls, ...)` 也遵循同样的构造参数规则 + +`class function`： + +代码块身份：可直接照写示例 + +```tsl +cls1 := class(MathBox); +writeLn(cls1.Add(3, 4)); +cls2 := findClass("MathBox"); +writeLn(cls2.Add(5, 6)); + +type MathBox = class +public + class function Add(x, y); + begin + return x + y; + end; +end; +``` + +输出说明： + +- `class(MathBox).Add(...)` 可以调用类方法 +- `findClass("MathBox").Add(...)` 可以调用类方法 +- 上述例子依次输出 `7`、`11` + +### 类方法、重载、继承与析构 + +`overload` 方法： + +代码块身份：可直接照写示例 + +```tsl +t := new TestClass(); +writeLn(t.fun(1, 2)); +writeLn(t.fun(5)); + +type TestClass = class +public + function fun(p1, p2); overload; + begin + return p1 + p2; + end; + function fun(p1); overload; + begin + return p1 + 10; + end; +end; +``` + +输出说明： + +- 依次输出 `3`、`15` +- 说明同名不同参数个数的方法可以共存 + +基础继承： + +代码块身份：可直接照写示例 + +```tsl +d := new Dog(); +writeLn(d.Speak()); + +type Animal = class +public + function Speak(); + begin + return 1; + end; +end; +type Dog = class(Animal) +end; +``` + +输出说明： + +- `type Dog = class(Animal)` 可以继承父类实例方法 +- 上述例子中的 `d.Speak()` 输出 `1` + +多重继承： + +代码块身份：可直接照写示例 + +```tsl +obj := new C(); +writeLn(obj.Fa()); +writeLn(obj.Fb()); + +type A = class +public + function Fa(); + begin + return 1; + end; +end; +type B = class +public + function Fb(); + begin + return 2; + end; +end; +type C = class(A, B) +end; +``` + +输出说明： + +- `type C = class(A, B)` 可以同时继承 `A` 和 `B` 的方法 +- 上述例子依次输出 `1`、`2` + +多重继承下的同名方法优先级： + +代码块身份：可直接照写示例 + +```tsl +obj := new C(); +writeLn(obj.Speak()); + +type A = class +public + function Speak(); + begin + return 1; + end; +end; +type B = class +public + function Speak(); + begin + return 2; + end; +end; +type C = class(A, B) +end; +``` + +输出说明： + +- 当多个父类存在同名方法时，本例优先命中第一个父类 `A` +- 上述例子中的 `obj.Speak()` 输出 `1` + +基础 `virtual` / `override`： + +代码块身份：可直接照写示例 + +```tsl +d := new Dog(); +writeLn(d.Speak()); + +type Animal = class +public + function Speak(); virtual; + begin + return 1; + end; +end; +type Dog = class(Animal) +public + function Speak(); override; + begin + return 2; + end; +end; +``` + +输出说明： + +- 父类 `virtual` + 子类 `override` 组合可以通过 +- 上述例子中的 `d.Speak()` 输出 `2` + +`class(BaseClass, ObjectName).MethodName()`： + +代码块身份：可直接照写示例 + +```tsl +obj := new B(); +writeLn(obj.Speak()); +writeLn(class(A, obj).Speak()); + +type A = class +public + function Speak(); virtual; + begin + return 1; + end; +end; +type B = class(A) +public + function Speak(); override; + begin + return 2; + end; +end; +``` + +输出说明： + +- `obj.Speak()` 输出 `2` +- `class(A, obj).Speak()` 会定向调用祖先类方法，因此输出 `1` + +`findClass("ClassName", obj)` 强制转型： + +代码块身份：可直接照写示例 + +```tsl +objb := new ClassB(); +obj := findClass("ClassA", objb); +writeLn(obj.Fuc()); +writeLn(obj is class(ClassA)); +writeLn(obj is class(ClassB)); + +type ClassA = class +public + function Fuc(); virtual; + begin + return 1; + end; +end; +type ClassB = class(ClassA) +public + function Fuc(); override; + begin + return 2; + end; +end; +``` + +输出说明： + +- `findClass("ClassA", objb)` 会把 `objb` 转成 `ClassA` 视图 +- 上述例子中的 `obj.Fuc()` 输出 `1` +- 转型后的 `obj is class(ClassA)` 输出 `1` +- 转型后的 `obj is class(ClassB)` 输出 `0` + +`Inherited;`： + +代码块身份：可直接照写示例 + +```tsl +obj := new B(); +obj.Speak(); + +type A = class +public + function Speak(); virtual; + begin + writeLn(1); + end; +end; +type B = class(A) +public + function Speak(); override; + begin + Inherited; + writeLn(2); + end; +end; +``` + +输出说明： + +- `Inherited;` 会先执行父类同名同参数方法 +- 上述例子依次输出 `1`、`2` + +`Inherited MethodName(...)`： + +代码块身份：可直接照写示例 + +```tsl +obj := new B(); +obj.Run(); + +type A = class +public + function BaseValue(x); + begin + writeLn(x + 1); + end; +end; +type B = class(A) +public + function Run(); + begin + Inherited BaseValue(5); + writeLn(9); + end; +end; +``` + +输出说明： + +- `Inherited BaseValue(5)` 可以显式调用父类指定方法 +- 上述例子依次输出 `6`、`9` + +析构函数 `destroy`： + +代码块身份：可直接照写示例 + +```tsl +h := new THuman(); +writeLn(class(THuman).GetCount()); +h := nil; +writeLn(class(THuman).GetCount()); + +type THuman = class +public + static mCount; + function create(); + begin + mCount := (mCount ?: 0) + 1; + end; + function destroy(); + begin + mCount--; + writeLn(mCount); + end; + class function GetCount(); + begin + return mCount; + end; +end; +``` + +输出说明： + +- 创建对象后，`class(THuman).GetCount()` 输出 `1` +- `h := nil` 时会触发 `destroy()`，中途输出 `0` +- 释放后再次读取 `class(THuman).GetCount()` 也输出 `0` + +`self(0)` / `self(1)`： + +代码块身份：可直接照写示例 + +```tsl +c := new ChildBox(); +a := c.MakeOwner(); +b := c.MakeBase(); +writeLn(a is class(ChildBox)); +writeLn(b is class(ChildBox)); + +type BaseBox = class +public + function MakeOwner(); + begin + return self(1); + end; + function MakeBase(); + begin + return self(0); + end; +end; +type ChildBox = class(BaseBox) +end; +``` + +输出说明： + +- `self(1)` 返回的对象在这个例子里是 `ChildBox`，因此输出 `1` +- `self(0)` 返回的对象在这个例子里不是 `ChildBox`，因此输出 `0` + +### 跨 unit 类路径 + +`unit` 中的嵌套类路径创建属于跨 `unit` 边界，这里用 `text` 展示骨架： + +代码块身份：配置片段 / 概念骨架 +代码块说明：跨 `unit` 类路径骨架；依赖 `unit` 查找路径和目标环境对象模型，不是可直接复制的单文件最小示例。 + +```text +// Unit1.tsf +unit Unit1; + +interface + +type Class1 = class +public + type Class2 = class + public + value; + end; +end; + +implementation + +end. + +// main.tsl + +uses Unit1; +obj := createObject("Unit1.Class1.Class2"); +obj.value := 42; +writeLn(obj.value); +``` + +输出说明： + +- 这个骨架只说明字符串路径创建需要按跨 `unit` 边界处理。 +- 生成实际代码前先回看 [09_units_and_scope.md](09_units_and_scope.md) 和 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。 +- 不要把它直接改写成普通本地类的 `new ClassName()` 模式。 + +继承单元中的嵌套类路径属于跨 `unit` 边界，这里也用 `text` 展示骨架： + +代码块身份：配置片段 / 概念骨架 +代码块说明：跨 `unit` 父类路径骨架；依赖 `unit` 查找路径和目标环境对象模型，不是可直接复制的单文件最小示例。 + +```text +// Unit1.tsf +unit Unit1; + +interface + +type Class1 = class +public + type Class2 = class + public + value; + end; +end; + +implementation + +end. + +// main.tsl + +uses Unit1; + +type MyNewClass = class(Unit1.Class1.Class2) +end; +``` + +输出说明： + +- 这个骨架只说明继承声明里的父类路径形态属于跨 `unit` 边界。 +- 不要把它泛化成普通表达式 `class(Unit1.Class1.Class2)`。 +- 对象创建方式不要从普通本地类 `new ClassName()` 规则直接外推。 + +能力探测： + +代码块身份：可直接照写示例 + +```tsl +{$ifdef parentClassInUnit} +writeLn(1); +{$else} +writeLn(0); +{$endif} +``` + +输出说明： + +- `{$ifdef parentClassInUnit}` 输出 `1` + +## 默认生成模板 + +最短类骨架直接复用本页开头的“最短类骨架”。 + +代码块身份：可直接照写示例 + +```tsl +type Person = class +end; +``` + +## 禁止项 + +- 以下误写不可照写；本节只收容易被智能体从相近语言或相邻 TSL 写法外推出来的边界，不重复列已经在核心规则里明确的普通规则。 +- 不把裸类名成员访问当成文档事实；类方法和静态字段默认用 `class(Name).Member` 或文档明确反射入口。 +- 把 `self()` 当成本页明确的工厂式写法。 +- 把 `private` / `protected create` 当成一定会自动执行的构造函数。 +- 在子类里把父类 `private` 成员当成 `protected` 成员来访问。 +- 把带命名空间的 `new a.b.c` 直接当成文档事实。 +- 把 `class(Unit1.Class1.Class2)` 这种表达式写法直接当成文档事实。 + +代码块身份：反例 / 不可照写 + +```text +obj := new Unit1.Class1.Class2(); +``` + +上面这种写法不作为可写事实；本页只把 `createObject("Unit1.Class1.Class2")` 这种路径创建写成可用事实。 + +代码块身份：反例 / 不可照写 + +```text +cls := class(Unit1.Class1.Class2); +``` + +上面这种表达式写法不作为可写事实；本页只把继承声明里的 `class(Unit1.Class1.Class2)` 和字符串路径创建写成可用事实。 + +代码块身份：反例 / 不可照写 + +```text +MathBox.Add(1, 2); +THuman.mCount := 7; +``` + +上面这种裸类名成员访问不作为可写事实；类方法可用 `class(MathBox).Add(...)` 或 `findClass("MathBox").Add(...)` 调用，静态字段可用 `class(THuman).mCount` 访问。 + +代码块身份：反例 / 不可照写 + +```text +self(); +``` + +上面这种无参工厂式 `self()` 不作为可写事实；本页只把 `self(0)` / `self(1)` 这种工厂式写成可用事实。普通成员访问仍直接写成员名，不加 `self` 前缀。 diff --git a/docs/tsl/syntax/09_objects_and_classes.md b/docs/tsl/syntax/09_objects_and_classes.md deleted file mode 100644 index 8c762be7..00000000 --- a/docs/tsl/syntax/09_objects_and_classes.md +++ /dev/null @@ -1,1334 +0,0 @@ -# Objects And Classes - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[10_units_and_scope.md](10_units_and_scope.md)（优先）、[23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 9 篇，共 32 篇。上一篇：[08_control_flow.md](08_control_flow.md)。下一篇：[10_units_and_scope.md](10_units_and_scope.md)。 - -这一篇收拢面向对象语法，只保留语言层规则。 - -## 这一篇解决什么问题 - -回答“`type Name = class`、字段、`static`、方法、`property`、析构、类类型、继承和对象创建在 TSL 里怎样写”。 - -本页后半段有少量依赖 `unit` 的双文件示例；如果你还没建立 `unit` / `uses` 的多文件心智模型，先看 [10_units_and_scope.md](10_units_and_scope.md)。 - -## Agent 对象/类判断流程 - -1. 先判断要写普通对象、继承、构造函数、类方法、静态字段还是运行时创建。 -2. 对象声明优先使用本页已验证的 `type Name = class ... end;` 骨架。 -3. 类方法和静态字段优先用 `class(Name).Member` 或已验证反射入口，不要裸写类名调用。 -4. 构造函数默认保持 `public create`，不要把 `private` / `protected create` 当成会自动执行的构造函数。 -5. 没有已验证代码块时不要发明对象/类写法。 - -## 必须记住的规则 - -- 类定义统一按 `type Name = class ... end;` 写。 -- 顶层类声明当前已验证可以放在松散语句之后（单向允许）。 -- 顶层类声明当前也已验证可以放在顶层 `function / procedure` 之后。 -- 类声明当前没有通过写在函数体内部。 -- 在松散语句脚本里，可以先写松散语句再进入顶层类声明；但一旦进入顶层 `type Name = class ... end;` 声明，后面不能再回到松散语句模式。 -- 类里可以直接写字段和方法。 -- `static` 字段已验证可用；可以通过类类型访问，也可以通过实例访问。 -- `const` 成员已验证可用；实例常量可通过实例读取，`static const` 可通过类类型读取，也已验证可用于成员函数默认参数。 -- 方法体里可以用 `self` 指向当前实例。 -- `overload` 方法已验证可用；同名不同参数个数的方法可以共存。 -- 基础 `property` 形态已验证：`property Name read fieldOrMethod write fieldOrMethod`。 -- `property Name: Type ...` 这种类型注解写法已验证可用。 -- 参数化 `property` 已验证；当前这篇只写已经单独跑通的基础模式。 -- 参数化 `property` 的 accessor 方法当前已验证两种常见模式：读方法接同参数个数，写方法接“参数个数 + 赋值值”。 -- 索引型 `property` 已验证；调用时用圆括号 `obj.Prop(index)`。 -- 固定 `index` property 已验证；它可以把某个固定索引直接映射成普通属性读写。 -- `class(Name)` 和 `FindClass("Name")` 都可以拿到类类型。 -- `FindClass("ClassName", obj)` 已验证可把对象转成指定父类视图。 -- `class function` 已验证可用；本页里的“类方法”就是指 `class function`，前者是中文描述，后者是代码写法。 -- 当前解释器下更稳妥的类方法调用方式是先拿到类类型，再在类类型上调用。 -- 基础继承写法是 `type Child = class(Parent)`。 -- 多重继承写法 `type Child = class(Base1, Base2)` 已验证可用。 -- 基础覆盖写法是：父类方法声明为 `virtual`，子类对应方法声明为 `override`。 -- 基础祖先类调用已验证：可以用 `Inherited;`、`Inherited MethodName(...)` 或 `class(BaseClass, ObjectName).MethodName()`。 -- 已验证的对象创建写法至少有三种：`CreateObject("ClassName")`、`CreateObject(ClassType)` 和 `new ClassName()`。 -- 如果没有特殊需求，默认优先用 `new ClassName()`；只有需要字符串路径、类类型变量或跨 `unit` 路径时，再改用 `CreateObject(...)`。 -- 如果类里定义了 `function create(...)`，`new`、`CreateObject("ClassName", ...)` 和 `CreateObject(ClassType, ...)` 都已验证可以透传构造参数，也都已验证支持默认参数和命名参数。 -- 当前已验证的析构写法是无参 `function destroy();`；把对象引用设为 `nil` 时会触发它。 -- 工厂式 `self(0)` / `self(1)` 已验证可用；当前解释器没有通过 `self()` 这种无参工厂式写法。 -- 已做双文件运行验证：如果类定义在 `unit` 的嵌套路径里，可以用 `CreateObject("Unit1.Class1.Class2")` 这种字符串路径创建对象。 -- 已做双文件运行验证：可以写 `type MyNewClass = class(Unit1.Class1.Class2)` 直接继承单元里的嵌套类路径。 -- 已验证 `{$IFDEF ParentClassInUnit}` 为真，可用于探测“继承和构造单元中的类”能力是否可用。 -- `private` / `protected` / `public` 已验证可用；类开头未写可见性时，成员默认按 `public` 处理。 -- 同一个可见性段里后续没有切换关键字的成员，会沿用前一个可见性。 -- 外部访问 `private` / `protected` 字段或方法，会在执行时报对象成员访问错误。 -- 子类可以通过 `self` 访问父类 `protected` 成员；不能通过 `self` 访问父类 `private` 成员。 -- `create` 写成 `private` 或 `protected` 时，对象仍能创建，但 `new` 和 `CreateObject(...)` 不会执行该构造逻辑；构造函数应保持 `public`。 -- 更复杂的多重继承边界和更复杂的对象模型还没有在这篇里完整展开。 - -## 已验证语法 - -最短类骨架： - -如果你现在只是要“先写出一个类”，先从这个骨架起手；后面的例子再逐步进入字段、工厂函数和声明位置边界。 - -代码块身份：已验证可执行示例 - -```tsl -type Person = class -end; -``` - -字段、方法和 `CreateObject`： - -代码块身份：已验证可执行示例 - -```tsl -type Person = class - name; - function SetName(new_name); - begin - name := new_name; - end; -end; - -function MakePerson(); -begin - return CreateObject("Person"); -end; -``` - -类声明位置： - -代码块身份：已验证可执行示例 - -```tsl -obj := CreateObject("MyClass"); -obj.value := 5; -WriteLn(obj.value); - -type MyClass = class - value; -end; -``` - -已验证运行结果： - -- 输出 `5` -- 说明在当前解释器里，顶层类声明可以放在松散语句之后 -- 同时也说明 `CreateObject("MyClass")` 可以解析到后面才出现的类声明 - -代码块身份：已验证输出片段 - -```text -5 -``` - -顶层函数后面也可以继续声明类： - -代码块身份：已验证可执行示例 - -```tsl -function MakeObj(); -begin - return 1; -end; - -type MyClass = class - value; -end; -``` - -已验证结果： - -- 上述 `.tsf` 例子可以编译通过 - -类声明位置的反例： - -代码块身份：反例 / 不可照写 - -```text -// 函数体内部声明类 -function Demo(); -begin - type InnerClass = class - value; - end; - return 1; -end; - -// 松散语句在 type 之后继续出现 -a := 1; -type MyClass = class - value; -end; -WriteLn(a); -``` - -已验证结果： - -- 函数体内部声明类会报 `invalid statement` -- 在松散语句脚本里，`type MyClass = class ... end;` 之后继续写 `WriteLn(a);` 也会报 `invalid statement` - -`static` 字段： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type THuman = class - static - mCount; - function create(); - begin - mCount := (mCount ?: 0) + 1; - end; -end; -begin - class(THuman).mCount := 100; - WriteLn(class(THuman).mCount); - h := new THuman(); - WriteLn(class(THuman).mCount); - WriteLn(h.mCount); -end. -``` - -已验证运行结果： - -- `class(THuman).mCount := 100` 可以直接写静态字段 -- `class(THuman).mCount` 先输出 `100` -- 创建对象后，`class(THuman).mCount` 输出 `101` -- 通过实例读取 `h.mCount` 也输出 `101` - -同一字段也接受内联声明： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type THuman = class - static mCount; - function create(); - begin - mCount := (mCount ?: 0) + 1; - end; -end; -begin - class(THuman).mCount := 100; - h := new THuman(); - WriteLn(class(THuman).mCount); -end. -``` - -已验证运行结果： - -- `static mCount;` 这种内联写法也可以通过 -- 上述例子中的 `class(THuman).mCount` 输出 `101` - -`const` 成员： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type C = class -public - const mA = 1; - static const mB = mA + 10; - function TestConst(); - begin - return mA + mB; - end; - function TestConstInParam(b = mB); - begin - return b; - end; -end; -begin - o := new C(); - WriteLn(o.TestConst()); - WriteLn(o.TestConstInParam()); - WriteLn(o.mA); - WriteLn(class(C).mB); -end. -``` - -已验证运行结果： - -- 依次输出 `12`、`11`、`1`、`11` -- 说明类里可以定义实例常量和 `static const` -- 说明实例常量可通过实例读取，`static const` 可通过 `class(C)` 读取 -- 说明成员常量当前也可用于成员函数默认参数 - -`self` 指向当前实例： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Counter = class - value; - function create(v); - begin - self.value := v; - end; - function Inc(); - begin - self.value := self.value + 1; - return self.value; - end; -end; -begin - c := new Counter(10); - WriteLn(c.Inc()); -end. -``` - -已验证运行结果： - -- `c.Inc()` 输出 `11` - -可见性 `private` / `protected` / `public`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - value; -private - secret; - backup; -public - function create(); - begin - self.secret := 2; - self.backup := 3; - end; - function ReadSecret(); - begin - return self.secret + self.backup; - end; -end; -begin - a := new A(); - a.value := 9; - WriteLn(a.value); - WriteLn(a.ReadSecret()); -end. -``` - -已验证运行结果： - -- 类开头没有显式可见性时，`value` 默认按 `public` 处理，因此 `a.value := 9` 可以直接写。 -- `backup` 跟在 `private` 段后面，没有重新切换关键字，因此仍按 `private` 处理。 -- 上述例子依次输出 `9`、`5`。 - -`protected` 可供子类通过 `self` 访问： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class -protected - value; - function Hidden(); - begin - return 88; - end; -end; -type B = class(A) -public - function SetValue(v); - begin - self.value := v; - end; - function GetValue(); - begin - return self.value; - end; - function TryCall(); - begin - return self.Hidden(); - end; -end; -begin - b := new B(); - b.SetValue(66); - WriteLn(b.GetValue()); - WriteLn(b.TryCall()); -end. -``` - -已验证运行结果： - -- 子类里可以通过 `self.value` 访问父类 `protected` 字段。 -- 子类里也可以通过 `self.Hidden()` 调用父类 `protected` 方法。 -- 上述例子依次输出 `66`、`88`。 - -`private` 的失败场景，因为是已验证反例，这里用 `text` 展示： - -代码块身份：反例 / 不可照写 - -```text -// 外部访问 private 字段 -program test; -type A = class -private - secret; -public - function create(); - begin - self.secret := 7; - end; -end; -begin - a := new A(); - WriteLn(a.secret); -end. - -// 子类访问父类 private 字段 -program test; -type A = class -private - secret; -public - function ReadSecret(); - begin - return self.secret; - end; -end; -type B = class(A) -public - function SetSecret(v); - begin - self.secret := v; - end; -end; -begin - b := new B(); - b.SetSecret(77); - WriteLn(b.ReadSecret()); -end. -``` - -已验证运行结果： - -- 外部访问 `a.secret` 会在执行时报对象成员访问错误。 -- 子类里通过 `self.secret` 访问父类 `private` 字段也会在执行时报错。 -- 同样的规则也已单独用 `private` / `protected` 方法访问做过复核：外部不能调 `private` / `protected` 方法，子类只能调 `protected` 方法，不能调 `private` 方法。 - -`create` 建议保持 `public`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class -public - value; -private - function create(v); - begin - self.value := v; - end; -end; -begin - a := new A(111); - WriteLn(a.value); -end. -``` - -已验证运行结果： - -- `a := new A(111)` 可以创建对象。 -- 上述例子里的 `a.value` 输出 ``，说明 `private create` 没有执行。 -- 同样的结果已单独用 `protected create`、`CreateObject("A", ...)` 和 `CreateObject(class(A), ...)` 复核；当前解释器里构造函数应保持 `public`。 - -基础 `property`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type MyBox = class - _value; - function SetValue(v); - begin - if v > 0 then - _value := v; - end; - property Value read _value write SetValue; -end; -begin - b := new MyBox(); - b.Value := 7; - WriteLn(b.Value); - b.Value := -1; - WriteLn(b.Value); -end. -``` - -已验证运行结果： - -- `b.Value := 7` 后，`b.Value` 输出 `7` -- `b.Value := -1` 后，`b.Value` 仍输出 `7` - -带类型注解的 `property`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type MyBox = class - _value; - function SetValue(v); - begin - _value := v; - end; - property Value: score_value read _value write SetValue; -end; -begin - b := new MyBox(); - b.Value := 9; - WriteLn(b.Value); -end. -``` - -已验证运行结果： - -- `property Value: score_value ...` 这种类型注解写法可以通过 -- 上述例子中的 `b.Value` 输出 `9` - -索引型 `property`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - arr; - function create(); - begin - arr := array(); - end; - function rIndex(i); - begin - return arr[i]; - end; - function wIndex(i, value); - begin - arr[i] := value; - end; - property idx read rIndex write wIndex; -end; -begin - aa := new A(); - aa.idx(0) := "abc"; - WriteLn(aa.idx(0)); -end. -``` - -已验证运行结果： - -- `aa.idx(0) := "abc"` 可以写入索引 property -- `aa.idx(0)` 输出 `abc` - -固定 `index` property： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - arr; - function create(); - begin - arr := array(); - end; - function rIndex(i); - begin - return arr[i]; - end; - function wIndex(i, value); - begin - arr[i] := value; - end; - property idx read rIndex write wIndex; - property idx0 index 0 read rIndex write wIndex; -end; -begin - aa := new A(); - aa.idx0 := "abc"; - WriteLn(aa.idx0); - WriteLn(aa.idx(0)); -end. -``` - -已验证运行结果： - -- `aa.idx0 := "abc"` 可以写入固定整数索引 property -- `aa.idx0` 输出 `abc` -- `aa.idx(0)` 也输出 `abc` - -固定字符串索引： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - arr; - function create(); - begin - arr := array(); - end; - function rIndex(i); - begin - return arr[i]; - end; - function wIndex(i, value); - begin - arr[i] := value; - end; - property idx read rIndex write wIndex; - property school index "High school" read rIndex write wIndex; -end; -begin - aa := new A(); - aa.school := "math"; - WriteLn(aa.school); - WriteLn(aa.idx("High school")); -end. -``` - -已验证运行结果： - -- `property school index "High school"` 这种固定字符串索引写法可以通过 -- `aa.school` 输出 `math` -- `aa.idx("High school")` 也输出 `math` - -参数化 `property`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type MyDate = class - _year; - _month; - _day; - function getDateV(); - begin - return _year * 10000 + _month * 100 + _day; - end; - function setDateV(y, m, d); - begin - _year := y; - _month := m; - _day := d; - end; - property DateV(y, m) read getDateV write setDateV; -end; -begin - d := new MyDate(); - d.DateV(2025, 8) := 10; - WriteLn(d.DateV()); -end. -``` - -已验证运行结果： - -- `d.DateV(2025, 8) := 10` 可以给参数化 property 赋值 -- `d.DateV()` 输出 `20250810` - -参数化 `property` 的 accessor 方法参数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - arr; - function create(); - begin - arr := array(); - end; - function getItem(i); - begin - return arr[i]; - end; - function setItem(i, value); - begin - arr[i] := value; - end; - property Item(i): slot_type read getItem write setItem; -end; -begin - aa := new A(); - aa.Item(2) := "x"; - WriteLn(aa.Item(2)); -end. -``` - -已验证运行结果： - -- `read getItem` 这种“读方法接同参数个数”的写法可以通过 -- `write setItem` 这种“写方法接参数个数 + 赋值值”的写法可以通过 -- 上述例子中的 `aa.Item(2)` 输出 `x` - -`new` 关键字： - -代码块身份：已验证可执行示例 - -```tsl -type Person = class -end; - -function MakePerson(); -begin - return new Person(); -end; -``` - -通过类类型创建对象： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Person = class - value; -end; -begin - cls := FindClass("Person"); - obj := CreateObject(cls); - obj.value := 42; - WriteLn(obj.value); -end. -``` - -已验证运行结果： - -- `CreateObject(cls)` 可以通过类类型创建对象 -- 上述例子中的 `obj.value` 输出 `42` - -也可以用 `class(Name)` 取得类类型： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Person = class - value; - function create(v); - begin - value := v; - end; -end; -begin - cls := class(Person); - obj := CreateObject(cls, 44); - WriteLn(obj.value); -end. -``` - -已验证运行结果： - -- `class(Person)` 可以拿到 `Person` 的类类型 -- `CreateObject(cls, 44)` 输出 `44` - -构造参数、默认值和命名参数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Person = class - a; - b; - c; - function create(a, b = 20, c = 30); - begin - self.a := a; - self.b := b; - self.c := c; - end; -end; -begin - a := CreateObject("Person", 11); - WriteLn(a.a); - WriteLn(a.b); - WriteLn(a.c); - b := new Person(22, c:99); - WriteLn(b.a); - WriteLn(b.b); - WriteLn(b.c); -end. -``` - -已验证运行结果： - -- `CreateObject("Person", 11)` 依次输出 `11`、`20`、`30` -- `new Person(22, c:99)` 依次输出 `22`、`20`、`99` -- 说明构造函数默认参数和命名参数不只适用于普通函数调用，也适用于对象创建 - -类类型也同样支持默认参数和命名参数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Person = class - a; - b; - c; - function create(a, b = 20, c = 30); - begin - self.a := a; - self.b := b; - self.c := c; - end; -end; -begin - cls := FindClass("Person"); - obj := CreateObject(cls, 33, c:77); - WriteLn(obj.a); - WriteLn(obj.b); - WriteLn(obj.c); -end. -``` - -已验证运行结果： - -- `CreateObject(cls, 33, c:77)` 依次输出 `33`、`20`、`77` -- 因此类类型入口下的 `CreateObject(cls, ...)` 也遵循同样的构造参数规则 - -`class function`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type MathBox = class - class function Add(x, y); - begin - return x + y; - end; -end; -begin - cls1 := class(MathBox); - WriteLn(cls1.Add(3, 4)); - cls2 := FindClass("MathBox"); - WriteLn(cls2.Add(5, 6)); -end. -``` - -已验证运行结果： - -- `class(MathBox).Add(...)` 可以调用类方法 -- `FindClass("MathBox").Add(...)` 可以调用类方法 -- 上述例子依次输出 `7`、`11` - -`overload` 方法： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TestClass = class - function fun(p1, p2); overload; - begin - return p1 + p2; - end; - function fun(p1); overload; - begin - return p1 + 10; - end; -end; -begin - t := new TestClass(); - WriteLn(t.fun(1, 2)); - WriteLn(t.fun(5)); -end. -``` - -已验证运行结果： - -- 依次输出 `3`、`15` -- 说明同名不同参数个数的方法当前可以共存 - -基础继承： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Animal = class - function Speak(); - begin - return 1; - end; -end; -type Dog = class(Animal) -end; -begin - d := new Dog(); - WriteLn(d.Speak()); -end. -``` - -已验证运行结果： - -- `type Dog = class(Animal)` 可以继承父类实例方法 -- 上述例子中的 `d.Speak()` 输出 `1` - -多重继承： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - function Fa(); - begin - return 1; - end; -end; -type B = class - function Fb(); - begin - return 2; - end; -end; -type C = class(A, B) -end; -begin - obj := new C(); - WriteLn(obj.Fa()); - WriteLn(obj.Fb()); -end. -``` - -已验证运行结果： - -- `type C = class(A, B)` 可以同时继承 `A` 和 `B` 的方法 -- 上述例子依次输出 `1`、`2` - -多重继承下的同名方法优先级： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - function Speak(); - begin - return 1; - end; -end; -type B = class - function Speak(); - begin - return 2; - end; -end; -type C = class(A, B) -end; -begin - obj := new C(); - WriteLn(obj.Speak()); -end. -``` - -已验证运行结果： - -- 当多个父类存在同名方法时，当前例子优先命中第一个父类 `A` -- 上述例子中的 `obj.Speak()` 输出 `1` - -基础 `virtual` / `override`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Animal = class - function Speak(); virtual; - begin - return 1; - end; -end; -type Dog = class(Animal) - function Speak(); override; - begin - return 2; - end; -end; -begin - d := new Dog(); - WriteLn(d.Speak()); -end. -``` - -已验证运行结果： - -- 父类 `virtual` + 子类 `override` 组合可以通过 -- 上述例子中的 `d.Speak()` 输出 `2` - -`class(BaseClass, ObjectName).MethodName()`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - function Speak(); virtual; - begin - return 1; - end; -end; -type B = class(A) - function Speak(); override; - begin - return 2; - end; -end; -begin - obj := new B(); - WriteLn(obj.Speak()); - WriteLn(class(A, obj).Speak()); -end. -``` - -已验证运行结果： - -- `obj.Speak()` 输出 `2` -- `class(A, obj).Speak()` 会定向调用祖先类方法，因此输出 `1` - -`FindClass("ClassName", obj)` 强制转型： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type ClassA = class - function Fuc(); virtual; - begin - return 1; - end; -end; -type ClassB = class(ClassA) - function Fuc(); override; - begin - return 2; - end; -end; -begin - objb := new ClassB(); - obj := FindClass("ClassA", objb); - WriteLn(obj.Fuc()); - WriteLn(obj is class(ClassA)); - WriteLn(obj is class(ClassB)); -end. -``` - -已验证运行结果： - -- `FindClass("ClassA", objb)` 会把 `objb` 转成 `ClassA` 视图 -- 上述例子中的 `obj.Fuc()` 输出 `1` -- 转型后的 `obj is class(ClassA)` 输出 `1` -- 转型后的 `obj is class(ClassB)` 输出 `0` - -`Inherited;`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - function Speak(); virtual; - begin - WriteLn(1); - end; -end; -type B = class(A) - function Speak(); override; - begin - Inherited; - WriteLn(2); - end; -end; -begin - obj := new B(); - obj.Speak(); -end. -``` - -已验证运行结果： - -- `Inherited;` 会先执行父类同名同参数方法 -- 上述例子依次输出 `1`、`2` - -`Inherited MethodName(...)`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - function BaseValue(x); - begin - WriteLn(x + 1); - end; -end; -type B = class(A) - function Run(); - begin - Inherited BaseValue(5); - WriteLn(9); - end; -end; -begin - obj := new B(); - obj.Run(); -end. -``` - -已验证运行结果： - -- `Inherited BaseValue(5)` 可以显式调用父类指定方法 -- 上述例子依次输出 `6`、`9` - -析构函数 `destroy`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type THuman = class - static mCount; - function create(); - begin - mCount := (mCount ?: 0) + 1; - end; - function destroy(); - begin - mCount--; - WriteLn(mCount); - end; - class function GetCount(); - begin - return mCount; - end; -end; -begin - h := new THuman(); - WriteLn(class(THuman).GetCount()); - h := nil; - WriteLn(class(THuman).GetCount()); -end. -``` - -已验证运行结果： - -- 创建对象后，`class(THuman).GetCount()` 输出 `1` -- `h := nil` 时会触发 `destroy()`，中途输出 `0` -- 释放后再次读取 `class(THuman).GetCount()` 也输出 `0` - -`self(0)` / `self(1)`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type BaseBox = class - function MakeOwner(); - begin - return self(1); - end; - function MakeBase(); - begin - return self(0); - end; -end; -type ChildBox = class(BaseBox) -end; -begin - c := new ChildBox(); - a := c.MakeOwner(); - b := c.MakeBase(); - WriteLn(a is class(ChildBox)); - WriteLn(b is class(ChildBox)); -end. -``` - -已验证运行结果： - -- `self(1)` 返回的对象在这个例子里是 `ChildBox`，因此输出 `1` -- `self(0)` 返回的对象在这个例子里不是 `ChildBox`，因此输出 `0` - -`unit` 中的嵌套类路径创建，因为依赖多文件环境，这里用 `text` 展示： - -代码块身份：配置片段 / 概念骨架 -代码块说明：已在多文件环境下验证；这里只用来展示结构和结果，不是可直接复制的单文件最小示例。 - -```text -// Unit1.tsf -unit Unit1; -interface -type Class1 = class - type Class2 = class - value; - end; -end; -implementation -end. - -// main.tsl -program test; -begin - obj := CreateObject("Unit1.Class1.Class2"); - obj.value := 42; - WriteLn(obj.value); -end. -``` - -已验证运行结果： - -- `CreateObject("Unit1.Class1.Class2")` 可以创建对象 -- 上述例子中的 `obj.value` 输出 `42` - -继承单元中的嵌套类路径，因为依赖多文件环境，这里也用 `text` 展示： - -代码块身份：配置片段 / 概念骨架 -代码块说明：已在多文件环境下验证；这里只用来展示结构和结果，不是可直接复制的单文件最小示例。 - -```text -// Unit1.tsf -unit Unit1; -interface -type Class1 = class - type Class2 = class - value; - end; -end; -implementation -end. - -// main.tsl -program test; -type MyNewClass = class(Unit1.Class1.Class2) -end; -begin - obj := CreateObject("MyNewClass"); - obj.value := 42; - WriteLn(obj.value); -end. -``` - -已验证运行结果： - -- `type MyNewClass = class(Unit1.Class1.Class2)` 可以通过并继承该路径类 -- 上述例子中的 `obj.value` 输出 `42` - -能力探测： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin -{$IFDEF ParentClassInUnit} - WriteLn(1); -{$ELSE} - WriteLn(0); -{$ENDIF} -end. -``` - -已验证运行结果： - -- `{$IFDEF ParentClassInUnit}` 输出 `1` - -## 最小可编译示例 - -如果你只是想先起一个最短类骨架，直接复用本页开头的“最短类骨架”。 - -代码块身份：已验证可执行示例 - -```tsl -type Person = class -end; -``` - -## 常见误写 - -- 以下误写中，有代码块的条目都已经单独验证；没有单独代码块展开的文字条目，属于已知语义陷阱或错误泛化，不要把它们当成可写事实。 -- 把类写成裸 `class Person`。 -- 还没建立类定义就直接写 `CreateObject("Person")` 或 `new Person()`。 -- 把 `MathBox.Add(...)` 这种裸类名调用直接当成当前解释器已验证的类方法调用写法。 -- 把 `THuman.mCount` 这种裸类名静态字段访问直接当成当前解释器已验证事实。 -- 把 `self()` 当成当前解释器已验证的工厂式写法。 -- 把 `private` / `protected create` 当成当前解释器一定会自动执行的构造函数。 -- 在子类里把父类 `private` 成员当成 `protected` 成员来访问。 -- 把带命名空间的 `new a.b.c` 直接当成当前解释器已支持事实。 -- 把 `class(Unit1.Class1.Class2)` 这种表达式写法直接当成当前解释器已验证事实。 -- 以为类声明既然能放在松散语句后面，就还能在 `type` 后面继续回到松散语句模式。 - -代码块身份：反例 / 不可照写 - -```text -obj := new Unit1.Class1.Class2(); -``` - -上面这种写法在当前已记录验证里没有通过；当前只把 `CreateObject("Unit1.Class1.Class2")` 这种路径创建写成已验证事实。 - -代码块身份：反例 / 不可照写 - -```text -cls := class(Unit1.Class1.Class2); -``` - -上面这种表达式写法在当前解释器里没有通过；当前只把继承声明里的 `class(Unit1.Class1.Class2)` 和字符串路径创建写成已验证事实。 - -代码块身份：反例 / 不可照写 - -```text -MathBox.Add(1, 2); -``` - -上面这种裸类名调用在当前解释器里没有通过；当前已验证可用的是先拿到类类型，再用 `class(MathBox).Add(...)` 或 `FindClass("MathBox").Add(...)` 调用。 - -代码块身份：反例 / 不可照写 - -```text -THuman.mCount := 7; -``` - -上面这种裸类名静态字段访问在当前解释器里没有通过；当前已验证可用的是 `class(THuman).mCount`。 - -代码块身份：反例 / 不可照写 - -```text -self(); -``` - -上面这种无参工厂式 `self()` 在当前解释器里没有通过；当前只把 `self` 实例引用，以及 `self(0)` / `self(1)` 写成已验证事实。 - -代码块身份：反例 / 不可照写 - -```text -a := 1; -type MyClass = class - value; -end; -WriteLn(a); -``` - -上面这种写法在当前解释器里没有通过，会报 `invalid statement`。当前只把“松散语句后面可以接顶层类声明”写成已验证事实，不把它泛化成“`type` 之后还能继续写松散语句”。 - -## 跳转指引 - -- 回看 unit 与作用域：见 [10_units_and_scope.md](10_units_and_scope.md) -- 最后统一扫坑：见 [12_pitfalls.md](12_pitfalls.md) -- 继续看对象运行时和更深对象能力：见 [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) 和 [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) diff --git a/docs/tsl/syntax/10_units_and_scope.md b/docs/tsl/syntax/09_units_and_scope.md similarity index 54% rename from docs/tsl/syntax/10_units_and_scope.md rename to docs/tsl/syntax/09_units_and_scope.md index 7c20bc66..f6892471 100644 --- a/docs/tsl/syntax/10_units_and_scope.md +++ b/docs/tsl/syntax/09_units_and_scope.md @@ -1,74 +1,82 @@ -# Units And Scope +# TSL unit 与作用域 文档类型：语法主线 是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md)（优先）、[03_core_model.md](03_core_model.md)、[12_pitfalls.md](12_pitfalls.md) +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) -手册位置：第 10 篇，共 32 篇。上一篇：[09_objects_and_classes.md](09_objects_and_classes.md)。下一篇：[11_runtime_context_and_with.md](11_runtime_context_and_with.md)。 +这一篇只讲“怎么写和怎么调用 `unit`”。`namespace`、查找路径、`unit` 生命周期、`tsl.conf` 与运行时入口统一放到 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。 -这一篇只讲“怎么写和怎么调用 `unit`”。`namespace`、查找路径、`unit` 生命周期、`tsl.conf` 与运行时入口统一放到 [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md)。 - -## 这一篇解决什么问题 +## 本篇职责 回答下面几类最常见的问题： - 什么时候该把一组函数写成 `unit` - `uses` 到底能放在哪里 -- `interface uses` 和 `implementation uses` 的可见性差别是什么 +- `interface` 段 `uses` 和 `implementation` 段 `uses` 的可见性差别是什么 - 多个 `unit` 里有同名接口时，未限定调用到底命中谁 - 怎样显式指定要调用哪个 `unit` 的接口 -## Agent unit/作用域判断流程 +## 智能体 unit/作用域判断流程 1. 先判断当前交付是 `.tsl` 可执行脚本、`.tsf` 扩展模块，还是 `unit` 文件。 2. `unit` 文件只描述可复用单元；脚本入口仍放在 `.tsl`。 3. `uses` 必须放在普通语句之前；普通语句后不要再追加顶层 `uses`。 -4. 默认参数、接口段、实现段和作用域边界只照本页已验证形态写。 -5. 没有已验证代码块时不要发明 unit/作用域写法。 +4. 默认参数、接口段、实现段和作用域边界只照本页文档明确形态写。 +5. 命中 `unit` 生命周期、命名空间、查找路径、`tsl.conf` 或命令行查找路径参数时，跳到 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。 +6. 没有对应代码块时不要发明 unit/作用域写法。 -## 必须记住的规则 +## 核心规则 - `unit` 是完整的顶层主体；常见完整形态是 `unit Name; interface ... implementation ... end.`。 -- `unit` 也可以省略 `interface` / `implementation` 写成简写形态；当前解释器下，这种简写里定义的函数对外可调用。 +- `unit` 也可以省略 `interface` / `implementation` 写成简写形态；这种简写里定义的函数对外可调用。 - 如果没有特殊需求，默认优先用完整形态；简写形态只在不需要显式区分 `interface` / `implementation` 时再用。 +- 完整 `unit` 示例中，`implementation` 前保留空行，避免接口段和实现段挤在一起。 +- `unit` 允许接口声明与实现段分离：`interface` 段可以只声明函数签名或类方法签名，函数体和类方法体放到 `implementation` 段。 +- 类方法放在 `implementation` 段实现时，使用 `function ClassName.Method(...)` 形态。 - 顶层 `uses` 可以放在文件最前面，让后续整个文件直接看到被引入 `unit` 的接口。 -- 当前解释器允许连续多条顶层 `uses`；真正会失败的是前面已经出现普通语句后，再写顶层 `uses`。 +- 顶层导入多个 `unit` 时，只生成单条逗号合并写法：`uses UnitA, UnitB;`；不要生成连续多条顶层 `uses`。真正会失败的是前面已经出现普通语句后，再写顶层 `uses`。 - 函数体里的 `uses` 必须是函数体第一条语句，而且一个函数体里只能写一次。 - 类定义体里的 `uses` 必须是类定义体第一条语句，而且一个类定义体里只能写一次。 -- `interface uses` 对整个 `unit` 可见；`implementation uses` 只对实现段和在实现段里定义的方法体可见。 +- 如果函数体或类定义体需要多个 `unit`，默认把这些 `uses` 提升到顶层并合并成单条 `uses UnitA, UnitB;`；不要在函数体或类定义体里连写两条 `uses`。 +- 写在 `interface` 段的 `uses` 对整个 `unit` 可见；写在 `implementation` 段的 `uses` 只对实现段和在实现段里定义的方法体可见。 - 只写在 `implementation` 里的函数，对 `unit` 外部不可见。 - 出现重名接口时，未限定调用按 `uses` 从后往前解析；最后一个 `uses` 的同名接口优先。 - 要显式指定某个 `unit` 的接口，可以用 `UnitA.Ping()`、`unit(UnitA).Ping()` 或 `call("UnitA.Ping")`。 -- `unit` 生命周期、接口状态、命名空间和查找路径细节，转去看 [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md)。 +- `unit` 生命周期、接口状态、命名空间和查找路径细节，转去看 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。 -## 已验证语法 +## 可直接照写示例 ### 最小 `unit` -代码块身份：已验证可执行示例 +代码块身份：可直接照写示例 ```tsl unit DemoUnit; + interface + function Ping(); + implementation + function Ping(); begin return 1; end; + end. ``` -已验证结果： +结果说明： -- 上面这就是当前解释器可通过的最小完整 `unit` 骨架。 +- 上面这就是最小完整 `unit` 骨架。 - `unit` 文件结尾要用 `end.`，不是普通函数或类的 `end;`。 -如果该 `unit` 被脚本 `uses DemoUnit;` 后调用 `WriteLn(Ping());`，可观察输出为： +如果该 `unit` 被脚本 `uses DemoUnit;` 后调用 `writeLn(Ping());`，可观察输出为： -代码块身份：已验证输出片段 +代码块身份：输出片段 ```text 1 @@ -76,7 +84,7 @@ end. ### 简写 `unit` -代码块身份：已验证可执行示例 +代码块身份：可直接照写示例 ```tsl unit SpecialUnit; @@ -85,22 +93,21 @@ function Abcd(); begin return 10; end; - function Abcd2(); begin return 20; end; initialization - Writeln("INIT"); + writeLn("INIT"); finalization - Writeln("FINAL"); + writeLn("FINAL"); end. ``` -已验证结果： +结果说明： - `unit SpecialUnit;` 后可以省略 `interface` / `implementation`。 - 这种简写形态里定义的 `Abcd()`、`Abcd2()` 外部可以直接调用。 @@ -111,23 +118,32 @@ end. 沿用同一个 `DemoUnit.tsf`，分别看顶层、函数体、类体三种 `uses` 位置： 代码块身份：配置片段 / 概念骨架 -代码块说明：已在多文件环境下验证；这里只用来展示结构和结果，不是可直接复制的单文件最小示例。 +代码块说明：多文件结构骨架；依赖 `unit` 查找路径，不是可直接复制的单文件最小示例。 ```text // DemoUnit.tsf unit DemoUnit; + interface + function Ping(); + implementation + function Ping(); begin return 11; end; + end. // main.tsl -program test; uses DemoUnit; +obj := new Worker(); +writeLn(Ping()); +writeLn(RunInFunction()); +writeLn(obj.Run()); + function RunInFunction(); begin uses DemoUnit; @@ -135,23 +151,15 @@ begin end; type Worker = class uses DemoUnit; +public function Run(); begin return Ping(); end; end; -begin - obj := new Worker(); - WriteLn(Ping()); - WriteLn(RunInFunction()); - WriteLn(obj.Run()); -end. - -// command -tsl .\main.tsl -LIBPATH "D:\path\to\dir\" ``` -已验证结果： +结果说明： - 顶层 `uses DemoUnit;` 后，脚本主体可以直接调用 `Ping()`。 - 函数体第一行写 `uses DemoUnit;` 后，`RunInFunction()` 输出 `11`。 @@ -185,6 +193,7 @@ end; // 类里不是第一行 type Worker = class +public value; uses DemoUnit; end; @@ -196,28 +205,34 @@ type Worker = class end; ``` -已验证结果： +结果说明： - 顶层前面如果已经出现 `a := 1;` 这类普通语句，再写顶层 `uses` 会报 `invalid statement`。 - 函数体里，`uses` 不是第一行或者重复出现，都会失败。 - 类定义体里，`uses` 不是第一行或者重复出现，都会失败。 -- 当前解释器允许连续多条顶层 `uses`，所以“顶层只能写一条 `uses`”不是已验证事实。 +- 函数体或类定义体里重复 `uses` 的失败点是“第二条 `uses`”，不是顶层导入多个 `unit`。 +- 顶层导入多个 `unit` 时只生成 `uses UnitA, UnitB;` 这种逗号合并写法；连续多条顶层 `uses` 不再作为文档明确生成形态。 -### `interface uses` 和 `implementation uses` +### `interface` 段 `uses` 和 `implementation` 段 `uses` 代码块身份：配置片段 / 概念骨架 -代码块说明：已在多文件环境下验证；这里只用来展示结构和结果，不是可直接复制的单文件最小示例。 +代码块说明：多文件结构骨架；依赖 `unit` 查找路径，不是可直接复制的单文件最小示例。 ```text // UnitB.tsf unit UnitB; + interface + function FB(); + implementation + function FB(); begin return 100; end; + end. // UnitC.tsf @@ -225,9 +240,13 @@ end. // UnitA.tsf unit UnitA; + interface + uses UnitB; + type TBox = class +public function FromInterface(); begin return FB(); @@ -236,8 +255,11 @@ type TBox = class end; function CallB(); function CallC(); + implementation + uses UnitC; + function TBox.FromImplementation(); begin return FC(); @@ -250,38 +272,82 @@ function CallC(); begin return FC(); end; + end. // main.tsl -program test; + uses UnitA; +obj := new TBox(); +writeLn(CallB()); +writeLn(CallC()); +writeLn(obj.FromInterface()); +writeLn(obj.FromImplementation()); +``` + +结果说明： + +- 在 `interface` 段写 `uses UnitB;` 后，`FB()` 对整个 `unit` 都可见，`CallB()` 输出 `100`。 +- 在 `implementation` 段写 `uses UnitC;` 后，`FC()` 对实现段函数和在实现段定义的方法体可见，`CallC()` 与 `obj.FromImplementation()` 都输出 `200`。 +- 接口段里的内联方法 `FromInterface()` 能访问 `interface` 段 `uses` 引入的接口，因此输出 `100`。 +- 接口段里的内联方法不能看到只在 `implementation` 段 `uses` 引入的接口。 + +### 接口声明与实现段分离 + +代码块身份：可直接照写示例 + +```tsl +unit SplitDemo; + +interface + +function MakeValue(); +type UnitBox = class +public + value; + function create(_value); + function ReadValue(); +end; + +implementation + +function MakeValue(); begin - obj := new TBox(); - WriteLn(CallB()); - WriteLn(CallC()); - WriteLn(obj.FromInterface()); - WriteLn(obj.FromImplementation()); + return 10; +end; +function UnitBox.create(_value); +begin + value := _value; +end; +function UnitBox.ReadValue(); +begin + return value; +end; + end. ``` -已验证结果： +结果说明： -- `interface uses UnitB;` 后，`FB()` 对整个 `unit` 都可见，`CallB()` 输出 `100`。 -- `implementation uses UnitC;` 后，`FC()` 对实现段函数和在实现段定义的方法体可见，`CallC()` 与 `obj.FromImplementation()` 都输出 `200`。 -- 接口段里的内联方法 `FromInterface()` 能访问 `interface uses` 引入的接口，因此输出 `100`。 -- 当前解释器没有让接口段里的内联方法看到只在 `implementation uses` 引入的接口。 +- 普通函数可以在 `interface` 段只声明 `function MakeValue();`，再在 `implementation` 段写函数体。 +- 类方法可以在类体里只声明签名，再在 `implementation` 段写 `function UnitBox.Method(...)` 实现。 +- 类方法实现放在 `implementation` 段时，仍属于该 `unit` 的实现段。 ### 实现段私有函数 代码块身份：配置片段 / 概念骨架 -代码块说明：已在多文件环境下验证；这里只用来展示结构和结果，不是可直接复制的单文件最小示例。 +代码块说明：多文件结构骨架；依赖 `unit` 查找路径，不是可直接复制的单文件最小示例。 ```text // PrivateDemo.tsf unit PrivateDemo; + interface + function PublicFunc(); + implementation + function PublicFunc(); begin return PrivateFunc(); @@ -290,36 +356,47 @@ function PrivateFunc(); begin return 77; end; + end. // main.tsl -program test; + uses PrivateDemo; -begin - WriteLn(PublicFunc()); - WriteLn(PrivateFunc()); -end. +writeLn(PublicFunc()); ``` -已验证结果： +结果说明： - `PublicFunc()` 输出 `77`，说明接口函数可以调用实现段私有函数。 - 外部直接调用 `PrivateFunc()` 时，会报 `function:PrivateFunc compile error or not found`。 +代码块身份：反例 / 不可照写 + +```text +uses PrivateDemo; +writeLn(PrivateFunc()); +``` + +上面这种写法不可照写；`PrivateFunc()` 只写在 `implementation` 段，对 `unit` 外部不可见。 + ### 重名解析与限定调用 重名函数最小对照： 代码块身份：配置片段 / 概念骨架 -代码块说明：已在多文件环境下验证；这里只用来展示结构和结果，不是可直接复制的单文件最小示例。 +代码块说明：多文件结构骨架；依赖 `unit` 查找路径，不是可直接复制的单文件最小示例。 ```text // UnitA.tsf unit UnitA; + interface + function Ping(); function Hello(); + implementation + function Ping(); begin return 101; @@ -328,6 +405,7 @@ function Hello(); begin return 111; end; + end. // UnitB.tsf @@ -335,16 +413,16 @@ end. // main.tsl uses UnitA, UnitB; -WriteLn(Ping()); -WriteLn(UnitA.Hello()); -WriteLn(UnitB.Hello()); -WriteLn(unit(UnitA).Ping()); -WriteLn(call("UnitB.Ping")); +writeLn(Ping()); +writeLn(UnitA.Hello()); +writeLn(UnitB.Hello()); +writeLn(unit(UnitA).Ping()); +writeLn(call("UnitB.Ping")); ``` -已验证结果： +结果说明： -- 未限定的 `Ping()` 输出 `202`，说明当前解析顺序是 `uses` 从后往前。 +- 未限定的 `Ping()` 输出 `202`，说明解析顺序是 `uses` 从后往前。 - `UnitA.Hello()` 输出 `111`，`UnitB.Hello()` 输出 `222`。 - `unit(UnitA).Ping()` 输出 `101`。 - `call("UnitB.Ping")` 输出 `202`。 @@ -352,74 +430,80 @@ WriteLn(call("UnitB.Ping")); 重名类最小对照： 代码块身份：配置片段 / 概念骨架 -代码块说明：已在多文件环境下验证；这里只用来展示结构和结果，不是可直接复制的单文件最小示例。 +代码块说明：多文件结构骨架；依赖 `unit` 查找路径，不是可直接复制的单文件最小示例。 ```text // UnitA.tsf unit UnitA; + interface + type Box = class +public value; - function Create(); - begin - value := 101; - end; + function create(); end; + implementation + +function Box.create(); +begin + value := 101; +end; + end. // UnitB.tsf -// 与 UnitA.tsf 同形，只把 Create() 里写入的 101 改成 202 +// 与 UnitA.tsf 同形，只把 Box.create() 里写入的 101 改成 202 // main.tsl uses UnitA, UnitB; obj := new Box(); -WriteLn(obj.value); -objA := CreateObject("UnitA.Box"); -WriteLn(objA.value); -objB := CreateObject("UnitB.Box"); -WriteLn(objB.value); +writeLn(obj.value); +objA := createObject("UnitA.Box"); +writeLn(objA.value); +objB := createObject("UnitB.Box"); +writeLn(objB.value); ``` -已验证结果： +结果说明： - 未限定的 `new Box()` 输出 `202`。 -- `CreateObject("UnitA.Box")` 输出 `101`。 -- `CreateObject("UnitB.Box")` 输出 `202`。 +- `createObject("UnitA.Box")` 输出 `101`。 +- `createObject("UnitB.Box")` 输出 `202`。 - 重名类的未限定解析顺序和重名函数一致，也是按 `uses` 从后往前。 -## 最小可编译示例 +## 默认生成模板 如果你只是要先写出一个最小、可被其他文件引用的 `unit`，从下面这个骨架起步： -代码块身份：已验证可执行示例 +代码块身份：可直接照写示例 ```tsl unit DemoUnit; + interface + function Ping(); + implementation + function Ping(); begin return 1; end; + end. ``` 后面的多文件片段只在需要 `uses`、可见性或重名解析时再回来看。 -## 常见误写 +## 禁止项 - 把依赖外部 `unit` 的 `uses` 例子误当成单文件最小示例。 - 在还没把目标 `unit` 放进查找路径前，就把“找不到接口”误判成 `uses` 语法错。 - 把函数体或类定义体里的 `uses` 写在第一条语句之后。 - 在同一个函数体或类定义体里重复写第二个 `uses`。 -- 把“顶层 `uses` 只能写一次”当成当前解释器规则。 +- 生成连续多条顶层 `uses`；多个 `unit` 默认写成 `uses UnitA, UnitB;`。 - 把重名接口的未限定解析顺序理解成“从前到后”。 - 忘了显式指定 `UnitA.Ping()`、`unit(UnitA).Ping()` 或 `call("UnitA.Ping")`，结果误调用到最后一个 `uses` 的同名接口。 - -## 跳转指引 - -- 回看文件与顶层主体：见 [03_core_model.md](03_core_model.md) -- 查看 `unit` 生命周期、命名空间与查找路径：见 [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) -- 继续看对象运行时：见 [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) diff --git a/docs/tsl/syntax/10_runtime_context_and_with.md b/docs/tsl/syntax/10_runtime_context_and_with.md new file mode 100644 index 00000000..cd508310 --- /dev/null +++ b/docs/tsl/syntax/10_runtime_context_and_with.md @@ -0,0 +1,312 @@ +# TSL 运行时上下文、服务与全局缓存 + +文档类型：语法主线 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[14_ts_sql.md](14_ts_sql.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只处理运行时环境参数、`with` 后缀、`#` 网格调用、`timeout` 后缀、`dupvalue(...)` 和全局缓存，不处理任何金融业务语义。 + +## 本篇职责 + +回答“`setSysParam` / `getSysParam` 怎样用、`sysParams[...]` 是什么、`#Func() with array(...)` 这种后缀环境调用怎样写，网格调用怎样取回结果，以及全局缓存最小读写规则是什么”。 + +## 智能体运行时上下文判断流程 + +1. 先判断要操作系统参数、运行时上下文对象、`with` 后缀调用、`#` 网格调用、`timeout` 后缀，还是全局缓存函数。 +2. 系统参数优先用本页明确的 `setSysParam` / `getSysParam` / `sysParams[...]` 形态。 +3. `#Func() with array(...)` 只作为运行时环境调用写法，不要套到普通本地函数。 +4. 网格调用返回的不是最终值；需要最终结果时继续写 `dupvalue(...)`。 +5. 全局缓存读写要成对出现，并明确键和值的生命周期。 +6. 普通函数调用回到 [05_functions_and_calls.md](05_functions_and_calls.md)，不要把运行时服务写成普通语法糖；缓存值参与 `select` 时，查询语法仍回到 [14_ts_sql.md](14_ts_sql.md)。 +7. 如果问题是内置运行时对象本身，转到 [21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)。 +8. 本地函数后缀 `with` 属于反例时不要照写。 +9. 没有对应代码块时不要发明运行时上下文/运行时服务/全局缓存写法。 + +## 核心规则 + +- TSL 有一组运行时系统参数；本页只写通用语法形态。 +- `setSysParam(key, value)` 和 `getSysParam(key)` 可以直接用字符串键。 +- `sysParams[key]` 可以直接读写这些运行时参数。 +- 本页明确的 `with` 形式，是写在函数文件调用后面：`#Func() with array(...)`。 +- `with array(...)` 只在该次调用里临时覆盖对应键，调用结束后会恢复外部原值。 +- 如果外部原值本来不存在，`with array(...)` 调用结束后，对应键会恢复成 `nil`。 +- 不要把上面的后缀 `with` 直接泛化成“任何本地函数调用后面都能接 `with array(...)`”；本地函数后缀 `with` 属于反例。 +- 本页只收通用键的例子；像 `pn_stock()`、`pn_date()` 这类金融上下文参数，统一到 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md) 查函数事实。 +- 网格调用的最小写法是 `r := #Func(args);`。 +- 网格调用返回的不是最终值；用 `dupvalue(r)` 取回结果。 +- `timeout N` 后缀可直接接在网格调用后面。 +- 全局缓存函数的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)；本页只保留缓存引用的运行时行为示例。 +- 写入和读取全局缓存成功时返回 `1`。 +- 从全局缓存取出的值，`ifCache(v)` 会返回 `1`。 +- 一旦对取出的缓存值做本地写入，它会立刻实例化；写入后 `ifCache(v)` 返回 `0`。 +- `checkGlobalCacheExpired(v)` 对同名缓存的最新引用返回 `0`；同名缓存被重置后，旧引用会变成过期状态并返回 `1`。 +- 全局缓存取出的值可以直接参与 `select`。 + +## 可直接照写示例 + +直接设置和读取系统参数： + +代码块身份：可直接照写示例 + +```tsl +setSysParam("a", 123); +setSysParam("b", "XYZ"); +writeLn(getSysParam("a")); +writeLn(getSysParam("b")); +``` + +结果说明： + +- 依次输出 `123`、`XYZ` + +代码块身份：输出片段 + +```text +123 +XYZ +``` + +`sysParams[...]` 直接读写： + +代码块身份：可直接照写示例 + +```tsl +sysParams["a"] := 321; +sysParams["b"] := "QQ"; +writeLn(sysParams["a"]); +writeLn(sysParams["b"]); +writeLn(getSysParam("a")); +``` + +结果说明： + +- 依次输出 `321`、`QQ`、`321` +- 说明 `sysParams[...]` 和 `getSysParam(...)` / `setSysParam(...)` 指向的是同一组运行时环境参数 + +沿用同一个 `TestDo.tsf`，看 `with array(...)` 的覆盖边界： + +代码块身份：配置片段 / 概念骨架 +代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。 + +```text +// TestDo.tsf +function TestDo(); +begin + return array(getSysParam("a"), getSysParam("b")); +end; + +// main.tsl +setSysParam("a", 7); +setSysParam("b", 8); +r := #TestDo() with array("a": 101, "b": 202); +writeLn(r[0]); +writeLn(r[1]); +writeLn(getSysParam("a")); +writeLn(getSysParam("b")); +``` + +结果说明： + +- `r[0]` 输出 `101` +- `r[1]` 输出 `202` +- 调用结束后，外层 `getSysParam("a")` 输出 `7` +- 调用结束后，外层 `getSysParam("b")` 输出 `8` +- 说明 `with array(...)` 是“只在该次调用里临时覆盖，再恢复外部原值” + +沿用上一个 `TestDo.tsf`，只把 `main.tsl` 改成下面这样： + +代码块身份：配置片段 / 概念骨架 +代码块说明：多文件结构骨架；依赖函数文件查找路径，不是可直接复制的单文件最小示例。 + +```text +// main.tsl + +r := #TestDo() with array("a": 101, "b": 202); +writeLn(r[0]); +writeLn(r[1]); +writeLn(getSysParam("a") = nil); +writeLn(getSysParam("b") = nil); +``` + +结果说明： + +- 依次输出 `101`、`202`、`1`、`1` +- 说明外层原值不存在时，调用后不是“泄露”成 `101` / `202`，而是恢复成 `nil` + +### `#` 网格调用与 `dupvalue` + +代码块身份：可直接照写示例 + +```tsl +writeLn(dupvalue(#AddOne(5))); + +function AddOne(v); +begin + return v + 1; +end; +``` + +结果说明： + +- `#AddOne(5)` 可以执行 +- `dupvalue(r)` 返回最终结果 `6` + +代码块身份：输出片段 + +```text +6 +``` + +### 网格调用的 `timeout` + +代码块身份：可直接照写示例 + +```tsl +writeLn(dupvalue(#AddOne(5) timeout 3000)); + +function AddOne(v); +begin + return v + 1; +end; +``` + +结果说明： + +- `timeout 3000` 这种后缀写法可以通过并正常执行 +- 上例输出 `6` + +### `setGlobalCache`、`getGlobalCache` 与 `ifCache` + +代码块身份：可直接照写示例 + +```tsl +v1 := array(1, 2, 3); +writeLn(setGlobalCache("PB_TEST_GC_BASIC", v1)); +writeLn(getGlobalCache("PB_TEST_GC_BASIC", v2)); +writeLn(ifCache(v2)); +writeLn(length(v2)); +writeLn(v2[0], ',', v2[1], ',', v2[2]); +``` + +结果说明： + +- `setGlobalCache("PB_TEST_GC_BASIC", v1)` 返回 `1` +- `getGlobalCache("PB_TEST_GC_BASIC", v2)` 返回 `1` +- 取出的 `v2` 上 `ifCache(v2)` 返回 `1` +- `v2` 长度是 `3`，内容是 `1,2,3` + +### `checkGlobalCacheExpired` + +代码块身份：可直接照写示例 + +```tsl +setGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3)); +getGlobalCache("PB_TEST_GC_EXPIRE", v); +writeLn(checkGlobalCacheExpired(v)); +setGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3, 4)); +writeLn(checkGlobalCacheExpired(v)); +``` + +结果说明： + +- 刚取出的缓存引用上，`checkGlobalCacheExpired(v)` 返回 `0` +- 同名缓存被重新设置后，旧引用上的 `checkGlobalCacheExpired(v)` 返回 `1` + +### 写入后会实例化 + +代码块身份：可直接照写示例 + +```tsl +setGlobalCache("PB_TEST_GC_DETACH", array(1, 2, 3)); +getGlobalCache("PB_TEST_GC_DETACH", v); +writeLn(ifCache(v)); +v[0] := 100; +writeLn(ifCache(v)); +writeLn(v[0], ',', v[1], ',', v[2]); +``` + +结果说明： + +- 刚取出时 `ifCache(v)` 返回 `1` +- 对 `v[0]` 赋值后，`ifCache(v)` 立即返回 `0` +- 写入后的本地值内容是 `100,2,3` + +### 全局缓存参与 `select` + +代码块身份：可直接照写示例 + +```tsl +src := array((1, 2), (3, 4), (2, 1)); +setGlobalCache("PB_TEST_GC_SELECT", src); +getGlobalCache("PB_TEST_GC_SELECT", v); +q := select * from v order by [0] desc end; +writeLn(dataType(q)); +writeLn(mrows(q)); +writeLn(q[0][0], ',', q[0][1], ';', q[1][0], ',', q[1][1], ';', q[2][0], ',', q[2][1]); +``` + +结果说明： + +- 对缓存值做 `select` 可以正常执行 +- 返回结果的 `dataType` 是 `5` +- 行数是 `3` +- 排序后内容依次是 `(3,4)`、`(2,1)`、`(1,2)` + +## 本页不生成的范围 + +- 网格超时触发错误时的完整边界 +- `getGlobalCacheInfo`、`listGlobalCache`、`listGlobalCacheRemoved` +- 初始化 TSL、监控线程、回收策略与兼容旧系统方案 + +这些名称只作为边界提示，不作为本页可生成模板。 + +## 默认生成模板 + +最小运行时环境入口的默认骨架如下： + +代码块身份：可直接照写示例 + +```tsl +setSysParam("a", 1); +writeLn(getSysParam("a")); +``` + +需要网格调用结果时，优先从下面这个模板起步： + +代码块身份：可直接照写示例 + +```tsl +writeLn(dupvalue(#AddOne(5))); + +function AddOne(v); +begin + return v + 1; +end; +``` + +需要缓存时，从 `setGlobalCache` / `getGlobalCache` 那一节选择模板。 + +## 禁止项 + +- 把系统参数页直接写成金融函数页。 +- 把 `#Func() with array(...)` 误判成也能直接套在本地函数 `Demo()` 后面。 +- 以为 `with array(...)` 改的是全局永久值，不会恢复外层原环境。 +- 把网格句柄直接当最终值用，而不做 `dupvalue(...)`。 +- 以为从全局缓存取出的值，本地写入后仍然保持缓存身份。 +- 以为旧缓存引用在同名缓存被重置后还会继续视为“未过期”。 +- `r := #Func(args);` 保存的是网格调用句柄；需要最终结果时继续写 `dupvalue(r)`。 + +代码块身份：反例 / 不可照写 + +```text +r := Demo() with array("a": 11); + +function Demo(); +begin + return getSysParam("a"); +end; +``` + +上面这种“本地函数后缀 `with`”写法不作为可写事实；常见报错是 `Statement missing terminator`，随后出现 `function compile error`。 diff --git a/docs/tsl/syntax/11_pitfalls.md b/docs/tsl/syntax/11_pitfalls.md new file mode 100644 index 00000000..699b3d92 --- /dev/null +++ b/docs/tsl/syntax/11_pitfalls.md @@ -0,0 +1,202 @@ +# TSL 高频误写 + +文档类型：反例索引页 +是否可直接用于生成代码：否 +是否含可直接照写示例：否 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)、[03_values_and_literals.md](03_values_and_literals.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[08_objects_and_classes.md](08_objects_and_classes.md)、[09_units_and_scope.md](09_units_and_scope.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇不讲新知识，只做反例索引。 + +## 本篇职责 + +回答“哪些写法最容易凭直觉写出来，但在 TSL 里会编译失败、运行出错，或语义并不可靠”。 + +## 智能体常见误写判断流程 + +1. 先识别用户写法属于值、变量、函数、表达式、对象、`unit`、TS-SQL 还是外部调用误区。 +2. 遇到本页反例时，不要修成相邻语言习惯，必须跳回对应语法页找可直接照写示例。 +3. 反例只用于排错和避免误写，不作为可照写模板。 +4. 修复时保留 `.tsl` / `.tsf` 文件模型判断，不要只改局部语句。 +5. 没有对应条目时不要发明替代语法。 + +## 这页怎么用 + +- 先按主题扫一遍，再回到对应正文看正确写法。 +- 这里不重复讲完整规则，只保留“错法 -> 正确页”的索引。 +- 只有已经有明确反例边界的误写，才会列在这里。 +- 细节型边界放回对应专题页；本页只保留最容易诱导智能体写错的高频误写。 + +## 反例索引 + +### 文件模型与基础值 + +#### 1. 把裸 `class Name` 当成顶层类声明 + +代码块身份：反例 / 不可照写 + +```text +class Person +end; +``` + +这会编译失败。正确页：见 [08_objects_and_classes.md](08_objects_and_classes.md) + +#### 2. 把 `=` 当成赋值 + +代码块身份：反例 / 不可照写 + +```text +a = 1; +``` + +代码块身份：输出片段 + +```text +invalid statement +``` + +这会编译失败。正确页：见 [06_expressions_and_operators.md](06_expressions_and_operators.md) + +#### 3. 把字符串当成 0 基下标 + +代码块身份：反例 / 不可照写 + +```text +s := "ABC"; +writeLn(s[0]); +``` + +这会在运行时报字符串下标越界。正确页：见 [03_values_and_literals.md](03_values_and_literals.md) + +#### 4. 在 `.tsl` 声明区后面继续写脚本语句 + +代码块身份：反例 / 不可照写 + +```text +a := 1; +test(); + +function test(); +begin + echo "test"; +end; + +echo "after declaration"; +``` + +`.tsl` 可以有语句区和声明区，但顺序必须清楚：语句区在前并按顺序执行，函数 / 类声明区在后。不要在声明区后面继续写脚本语句。正确页：见 [02_core_model.md](02_core_model.md) + +### 函数与调用 + +#### 5. 把 `a = 1` 当成命名参数 + +代码块身份：反例 / 不可照写 + +```text +Pack(a = 1, b = 2); +``` + +不要把这当成可靠的命名参数写法。它虽然可能编译通过，但返回结果不符合命名参数预期。正确页：见 [05_functions_and_calls.md](05_functions_and_calls.md) + +#### 6. 把 `like` 当成 SQL `%` / `_` 通配 + +代码块身份：反例 / 不可照写 + +```text +writeLn("abc" like "a%"); +``` + +这里输出 `0`，不要按 SQL `LIKE` 去理解。本手册中，`like` 的右侧按正则模式解释。正确页：见 [06_expressions_and_operators.md](06_expressions_and_operators.md) + +### `unit` / `uses` + +#### 7. 把函数体或类定义体里的 `uses` 写错位置，或重复写第二个 `uses` + +代码块身份：反例 / 不可照写 + +```text +function Run(); +begin + a := 1; + uses DemoUnit; + return Ping(); +end; + +type Worker = class + uses UnitA; + uses UnitB; +end; +``` + +上面这两类写法都会失败。函数里的错法会报 `invalid statement`，类里的错法会报 `invalid class definition`。失败点分别是：函数体里的 `uses` 不是第一条语句；类定义体里出现了第二条 `uses`。 + +注意：这个反例只针对函数体和类定义体里的 `uses`；需要多个 `unit` 时，默认回到顶层写成单条 `uses UnitA, UnitB;`。正确页：见 [09_units_and_scope.md](09_units_and_scope.md) + +### 类与对象 + +#### 8. 把裸类名当成 `class function` 或静态字段的直接访问入口 + +代码块身份：反例 / 不可照写 + +```text +MathBox.Add(1, 2); + +THuman.mCount := 7; +``` + +这两种写法都不作为可写事实。可用写法是先拿到类类型，再用 `class(MathBox).Add(...)` / `findClass("MathBox").Add(...)` 调类方法，以及 `class(THuman).mCount` 访问静态字段。正确页：见 [08_objects_and_classes.md](08_objects_and_classes.md) + +#### 9. 把 `private` / `protected create` 当成一定会执行的构造函数 + +代码块身份：反例 / 不可照写 + +```text +a := new A(111); +writeLn(a.value); + +type A = class +public + value; +private + function create(v); + begin + value := v; + end; +end; +``` + +这不会报“不能创建对象”，但 `create` 不会执行；上面的 `a.value` 输出 ``。正确页：见 [08_objects_and_classes.md](08_objects_and_classes.md) + +#### 10. 在子类里把父类 `private` 成员当成 `protected` 成员用 + +代码块身份：反例 / 不可照写 + +```text +b := new B(); +writeLn(b.TryCall()); + +type A = class +private + function Hidden(); + begin + return 77; + end; +end; +type B = class(A) +public + function TryCall(); + begin + return Hidden(); + end; +end; +``` + +这会在执行时报父类 `private` 方法不可访问。正确页：见 [08_objects_and_classes.md](08_objects_and_classes.md) + +## 禁止项收口 + +- 不要把本页任何 `反例 / 不可照写` 代码块改写成默认正向模板。 +- 不要只凭 Pascal、JavaScript、Python 或 SQL 直觉修正 TSL 写法。 +- 不要在本页发明替代语法；每个反例都要回到条目末尾标出的正确专题页。 +- 不要把反例边界写成可用语法。 diff --git a/docs/tsl/syntax/11_runtime_context_and_with.md b/docs/tsl/syntax/11_runtime_context_and_with.md deleted file mode 100644 index 94b79eec..00000000 --- a/docs/tsl/syntax/11_runtime_context_and_with.md +++ /dev/null @@ -1,178 +0,0 @@ -# Runtime Context And With - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[07_expressions_and_operators.md](07_expressions_and_operators.md)、[22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md)、[../finance/market_data_context.md](../finance/market_data_context.md) - -手册位置：第 11 篇，共 32 篇。上一篇：[10_units_and_scope.md](10_units_and_scope.md)。下一篇：[12_pitfalls.md](12_pitfalls.md)。 - -这一篇只处理运行时环境参数和 `with` 后缀，不处理任何金融业务语义。 - -## 这一篇解决什么问题 - -回答“`SetSysParam` / `GetSysParam` 怎样用、`SysParams[...]` 是什么、`#Func() with array(...)` 这种后缀环境调用在当前解释器里怎样写”。 - -## Agent 运行时上下文判断流程 - -1. 先判断要操作系统参数、运行时上下文对象，还是 `with` 后缀调用。 -2. 系统参数优先用本页已验证的 `SetSysParam` / `GetSysParam` / `SysParams[...]` 形态。 -3. `#Func() with array(...)` 只作为运行时环境调用写法，不要套到普通本地函数。 -4. 本地函数后缀 `with` 属于反例时不要照写。 -5. 没有已验证代码块时不要发明运行时上下文写法。 - -## 必须记住的规则 - -- TSL 有一组运行时系统参数；当前页只写已经实际验证过的通用写法。 -- 已验证：`SetSysParam(key, value)` 和 `GetSysParam(key)` 可以直接用字符串键。 -- 已验证：`SysParams[key]` 可以直接读写这些运行时参数。 -- 当前已验证的 `with` 形式，是写在函数文件调用后面：`#Func() with array(...)`。 -- 当前已做双文件运行验证：`with array(...)` 只在该次调用里临时覆盖对应键，调用结束后会恢复外部原值。 -- 当前已做双文件运行验证：如果外部原值本来不存在，`with array(...)` 调用结束后，对应键会恢复成 `nil`。 -- 不要把上面的后缀 `with` 直接泛化成“任何本地函数调用后面都能接 `with array(...)`”；这一点当前没有通过。 -- 当前页只收通用键的例子；像 `pn_stock()`、`pn_date()` 这类金融上下文参数，统一放到业务层文档里解释。 - -## 已验证语法 - -直接设置和读取系统参数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - SetSysParam("a", 123); - SetSysParam("b", "XYZ"); - WriteLn(GetSysParam("a")); - WriteLn(GetSysParam("b")); -end. -``` - -已验证运行结果： - -- 依次输出 `123`、`XYZ` - -代码块身份：已验证输出片段 - -```text -123 -XYZ -``` - -`SysParams[...]` 直接读写： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - SysParams["a"] := 321; - SysParams["b"] := "QQ"; - WriteLn(SysParams["a"]); - WriteLn(SysParams["b"]); - WriteLn(GetSysParam("a")); -end. -``` - -已验证运行结果： - -- 依次输出 `321`、`QQ`、`321` -- 说明 `SysParams[...]` 和 `GetSysParam(...)` / `SetSysParam(...)` 指向的是同一组运行时环境参数 - -沿用同一个 `TestDo.tsf`，看 `with array(...)` 的覆盖边界： - -代码块身份：配置片段 / 概念骨架 - -```text -// TestDo.tsf -function TestDo(); -begin - return array(GetSysParam("a"), GetSysParam("b")); -end; - -// main.tsl -program test; -begin - SetSysParam("a", 7); - SetSysParam("b", 8); - r := #TestDo() with array("a": 101, "b": 202); - WriteLn(r[0]); - WriteLn(r[1]); - WriteLn(GetSysParam("a")); - WriteLn(GetSysParam("b")); -end. - -// command -tsl .\main.tsl -LIBPATH "D:\path\to\dir\" -``` - -已验证运行结果： - -- `r[0]` 输出 `101` -- `r[1]` 输出 `202` -- 调用结束后，外层 `GetSysParam("a")` 输出 `7` -- 调用结束后，外层 `GetSysParam("b")` 输出 `8` -- 说明 `with array(...)` 是“只在该次调用里临时覆盖，再恢复外部原值” - -沿用上一个 `TestDo.tsf`，只把 `main.tsl` 改成下面这样： - -代码块身份：配置片段 / 概念骨架 - -```text -// main.tsl -program test; -begin - r := #TestDo() with array("a": 101, "b": 202); - WriteLn(r[0]); - WriteLn(r[1]); - WriteLn(GetSysParam("a") = nil); - WriteLn(GetSysParam("b") = nil); -end. -``` - -已验证运行结果： - -- 依次输出 `101`、`202`、`1`、`1` -- 说明外层原值不存在时，调用后不是“泄露”成 `101` / `202`，而是恢复成 `nil` - -## 最小可编译示例 - -如果你只是想先记住最小的运行时环境入口，用这个： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - SetSysParam("a", 1); - WriteLn(GetSysParam("a")); -end. -``` - -## 常见误写 - -- 把系统参数页直接写成金融函数页。 -- 把 `#Func() with array(...)` 误判成也能直接套在本地函数 `Demo()` 后面。 -- 以为 `with array(...)` 改的是全局永久值，不会恢复外层原环境。 - -代码块身份：反例 / 不可照写 - -```text -program test; -function Demo(); -begin - return GetSysParam("a"); -end; -begin - r := Demo() with array("a": 11); -end. -``` - -上面这种“本地函数后缀 `with`”写法在当前解释器里没有通过，会报 `Statement missing terminator`，随后出现 `function compile error`。 - -## 跳转指引 - -- 回看表达式与调用：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 涉及函数文件查找路径：见 [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) -- 业务层环境参数：见 [../finance/index.md](../finance/index.md) diff --git a/docs/tsl/syntax/12_matrix_and_collections.md b/docs/tsl/syntax/12_matrix_and_collections.md new file mode 100644 index 00000000..f3f4fb5e --- /dev/null +++ b/docs/tsl/syntax/12_matrix_and_collections.md @@ -0,0 +1,235 @@ +# TSL 数组、键表、矩阵样数据与集合运算 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：否 +遇到不确定时：先按本页候选页继续判断；[13_resultset_and_filters.md](13_resultset_and_filters.md)、[22_matrix_deep_dive.md](22_matrix_deep_dive.md)、[23_fmarray.md](23_fmarray.md)、[14_ts_sql.md](14_ts_sql.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇收拢 `array(...)` 的扩展用法：顺序数组、字符串键表、嵌套数组、本页明确的矩阵样比较，以及 `in` / `sqlin` / `union2` / `intersect` / `minus` / `outersect` 这类去重型集合关系。 + +## 本篇职责 + +回答“`array(...)` 在 TSL 里除了最普通的一维数组，还能怎样组织数据；哪些矩阵样写法属于本页文档明确形态；元素、子集、整行和行集合关系应该怎样判断”。 + +## 智能体数组/矩阵样数据判断流程 + +1. 先判断需要顺序数组、字符串键表、嵌套数组、矩阵样比较，还是去重型集合关系。 +2. 普通容器优先从 `array(...)` 起手；下标和键访问回看值语法页。 +3. 矩阵链式比较只照 `::` 系列文档明确示例写，不要混用标量链式比较。 +4. 基础成员判断用 `in` / `not in`；整行存在判断用 `sqlin` / `not sqlin`；去重型行集合并、交、差、对称差用 `union2` / `intersect` / `minus` / `outersect`。 +5. 结果集过滤或 TS-SQL 查询需求分别跳转到 [13_resultset_and_filters.md](13_resultset_and_filters.md) 或 [14_ts_sql.md](14_ts_sql.md)。 +6. 没有对应代码块时不要发明数组/矩阵样数据/集合关系写法。 + +## 核心规则 + +- `array(...)` 既可以写顺序数组，也可以写字符串键表。 +- 顺序数组下标从 `0` 开始；字符串仍然从 `1` 开始。 +- `array(...)` 可以继续嵌套，形成二维或矩阵样数据。 +- 矩阵链式比较 `::>`、`::<`、`::<>`、`::==`、`::>=`、`::<=` 属于本页文档明确形态。 +- `in` / `not in` 处理的是元素存在关系，以及左侧为数组时的子集关系。 +- `sqlin` / `not sqlin` 处理的是行存在关系；左侧要当成一整行去匹配右侧结果集。 +- `union2`、`intersect`、`minus`、`outersect` 都按“行”运算，而不是按单元格逐个运算。 +- 集合运算结果会折叠重复行；如果需求是保留重复记录，改看 [13_resultset_and_filters.md](13_resultset_and_filters.md)。 +- 当数据本身就是一维数组时，按行集合运算和按元素集合运算是一致的。 +- 左侧是数组时，先判定需求语义：子集关系用 `in`，整行存在关系用 `sqlin`。 + +## 可直接照写示例 + +### 基础数组与键表 + +顺序数组与字符串键表： + +代码块身份：可直接照写示例 + +```tsl +arr := array(10, 20, 30); +hash := array("Code": "0001", "Price": 12.3); +writeLn("ARR0=", arr[0]); +writeLn("ARR1=", arr[1]); +writeLn("HASH=", hash["Code"]); +``` + +结果说明： + +- `arr[0] = 10` +- `arr[1] = 20` +- `hash["Code"] = "0001"` + +嵌套数组： + +代码块身份：可直接照写示例 + +```tsl +[r1, r2] := array((1, 2), (3, 4)); +writeLn(r1[0]); +writeLn(r1[1]); +writeLn(r2[0]); +writeLn(r2[1]); +``` + +结果说明： + +- 依次输出 `1`、`2`、`3`、`4` +- 说明 `array((1, 2), (3, 4))` 这种嵌套数组写法可以按普通数组继续读取 + +代码块身份：输出片段 + +```text +1 +2 +3 +4 +``` + +### 矩阵样比较 + +矩阵链式比较： + +代码块身份：可直接照写示例 + +```tsl +r := array(1, 2, -1) ::< array(2, 1, 0) ::< array(3, 2, 1); +writeLn(r[0]); +writeLn(r[1]); +writeLn(r[2]); +s := array(1, 2, -1) ::< 2 ::< array(3, 2, 1); +writeLn(s[0]); +writeLn(s[1]); +writeLn(s[2]); +``` + +结果说明： + +- `array(1, 2, -1) ::< array(2, 1, 0) ::< array(3, 2, 1)` 的三个元素依次输出 `1`、`0`、`1` +- `array(1, 2, -1) ::< 2 ::< array(3, 2, 1)` 的三个元素依次输出 `1`、`0`、`0` +- 说明矩阵链式比较会按元素位置分别得到结果数组，并且可以和标量混用 + +### `in`、`not in`、`sqlin`、`not sqlin` + +`in` 既可以判断单个元素是否存在，也可以判断左侧数组是否是右侧结果集的子集： + +代码块身份：可直接照写示例 + +```tsl +writeLn(1 in array(1, 2, 2)); +writeLn(1 in array(0, 2)); +writeLn(1 in array((1), (2))); +writeLn(array(1, 2) in array(1, 2, 3, 4)); +writeLn(array(1, 3) in array((1, 2), (3, 4))); +writeLn(array(1, 2) in array(1)); +writeLn(1 not in array(0, 2)); +``` + +结果说明： + +- `1 in array(1, 2, 2)` 输出 `1` +- `1 in array(0, 2)` 输出 `0` +- `1 in array((1), (2))` 输出 `1` +- `array(1, 2) in array(1, 2, 3, 4)` 输出 `1` +- `array(1, 3) in array((1, 2), (3, 4))` 输出 `1` +- `array(1, 2) in array(1)` 输出 `0` +- `1 not in array(0, 2)` 输出 `1` + +代码块身份：输出片段 + +```text +1 +0 +1 +1 +``` + +`sqlin` 按整行判断左侧是否存在于右侧结果集中： + +代码块身份：可直接照写示例 + +```tsl +writeLn(1 sqlin array(1, 2)); +writeLn(array(1, 2) sqlin array(1, 2, 3)); +writeLn(array(1, 2) sqlin array((1, 2), (3, 4))); +writeLn(array(5, 6) not sqlin array((1, 2), (3, 4))); +``` + +结果说明： + +- `1 sqlin array(1, 2)` 输出 `1` +- `array(1, 2) sqlin array(1, 2, 3)` 输出 `0` +- `array(1, 2) sqlin array((1, 2), (3, 4))` 输出 `1` +- `array(5, 6) not sqlin array((1, 2), (3, 4))` 输出 `1` +- `in` 看元素或子集 +- `sqlin` 看整行 + +### 行集合并、交、差、对称差 + +下面这组最小例子展示“按行运算”和“结果会折叠重复行”： + +代码块身份：可直接照写示例 + +```tsl +left_rows := array((1, 2), (1, 2), (2, 3)); +right_rows := array((1, 2), (3, 4)); +union_rows := left_rows union2 right_rows; +intersect_rows := left_rows intersect right_rows; +minus_rows := left_rows minus right_rows; +outersect_rows := left_rows outersect right_rows; +``` + +结果说明： + +- `left_rows union2 right_rows` 共有三行：`(1,2)`、`(2,3)`、`(3,4)` +- `left_rows intersect right_rows` 只有一行：`(1,2)` +- `left_rows minus right_rows` 只有一行：`(2,3)` +- `left_rows outersect right_rows` 有两行：`(2,3)`、`(3,4)` +- `left_rows` 原本有两行相同的 `(1,2)`，但 `union2` / `intersect` 的结果都只保留一份，说明集合运算会折叠重复行 + +更大的四列结果集文档结果： + +- `array((1,2,3,4),(2,3,4,5),(1,1,1,1)) union2 array((1,2,3,4),(3,4,5,6),(2,2,2,2))` + 返回 `array((1,2,3,4),(2,3,4,5),(1,1,1,1),(3,4,5,6),(2,2,2,2))` +- 同一组输入下： + `intersect` 返回 `array((1,2,3,4))` +- 同一组输入下： + `minus` 返回 `array((2,3,4,5),(1,1,1,1))` +- 同一组输入下： + `outersect` 返回 `array((2,3,4,5),(1,1,1,1),(3,4,5,6),(2,2,2,2))` + +## 和过滤运算的区别 + +- 集合运算先把数据当成“行集合”来看，再做包含、并交差。 +- 过滤运算先保留“原结果集里的每一条命中记录”；因此重复行会保留下来。 +- 需要“集合关系”时留在本页。 +- 需要“从原表里筛出哪些行”时看 [13_resultset_and_filters.md](13_resultset_and_filters.md)。 + +## 默认生成模板 + +按需求语义从下面两种模板中选择： + +代码块身份：可直接照写示例 + +```tsl +matched := 1 in array(1, 2, 3); +row_matched := array(1, 2) sqlin array((1, 2), (3, 4)); +``` + +## 本页不生成的范围 + +- 专门的结果集过滤函数 +- TS-SQL 查询与写回 +- 更大范围的矩阵函数族 + +这些内容分别进入 [13_resultset_and_filters.md](13_resultset_and_filters.md)、[14_ts_sql.md](14_ts_sql.md)、[22_matrix_deep_dive.md](22_matrix_deep_dive.md) 或 [23_fmarray.md](23_fmarray.md)，不再外跳到原目录。 + +## 禁止项 + +- 不要把字符串下标按数组的 `0` 起始规则来写；字符串索引回看 [03_values_and_literals.md](03_values_and_literals.md)。 +- 不要把矩阵链式比较 `::...` 和标量链式比较混写成同一种语法。 +- 不要把 `in` 和 `sqlin` 当成同一个概念。 +- 不要期待 `union2` 保留重复行。 +- 不要用集合运算去做“保留原始重复记录”的过滤任务。 +- 不要把二维结果集默认当成“按元素逐个比较”的集合运算。 +- 左侧数组要表达“这些值是否都属于右侧集合”时，用 `in`。 +- 左侧数组要表达“这一整行是否存在于右侧结果集”时，用 `sqlin`。 +- `minus` 表达集合差集；如果任务要求保留左侧原始重复次数，改走 [13_resultset_and_filters.md](13_resultset_and_filters.md) 的过滤规则。 +- 不要在本页发明结果集过滤、TS-SQL 查询、写回语法或更大矩阵函数族。 +- 不要把普通 `array(...)` 自动升级成 `FMArray`；只有任务明确命中时才进入 [23_fmarray.md](23_fmarray.md)。 diff --git a/docs/tsl/syntax/12_pitfalls.md b/docs/tsl/syntax/12_pitfalls.md deleted file mode 100644 index d5338291..00000000 --- a/docs/tsl/syntax/12_pitfalls.md +++ /dev/null @@ -1,288 +0,0 @@ -# Pitfalls - -文档类型：反例索引页 -是否可直接用于生成代码：否 -是否含已验证可执行示例：否 -是否含已验证反例：是 -遇到不确定时跳转到：[03_core_model.md](03_core_model.md)、[06_functions_and_calls.md](06_functions_and_calls.md)、[09_objects_and_classes.md](09_objects_and_classes.md) - -手册位置：第 12 篇，共 32 篇。上一篇：[11_runtime_context_and_with.md](11_runtime_context_and_with.md)。下一篇：[13_matrix_and_collections.md](13_matrix_and_collections.md)。 - -这一篇不讲新知识，只做反例索引。 - -## 这一篇解决什么问题 - -回答“哪些写法最容易凭直觉写出来，但在 TSL 里会编译失败、运行出错，或语义并不可靠”。 - -## Agent 常见误写判断流程 - -1. 先识别用户写法属于值、变量、函数、表达式、对象、unit、TS-SQL 还是外部调用误区。 -2. 遇到本页反例时，不要修成相邻语言习惯，必须跳回对应语法页找已验证正例。 -3. 反例只用于排错和避免误写，不作为可照写模板。 -4. 修复时保留 `.tsl` / `.tsf` 文件模型判断，不要只改局部语句。 -5. 没有已验证代码块时不要发明替代语法。 - -## 这页怎么用 - -- 先按主题扫一遍，再回到对应正文看正确写法。 -- 这里不重复讲完整规则，只保留“错法 -> 正确页”的索引。 -- 只有已经单独验证过的误写，才会列在这里。 - -## 已验证反例索引 - -### 文件模型与基础值 - -#### 1. 把裸 `class Name` 当成顶层类声明 - -代码块身份：反例 / 不可照写 - -```text -class Person -end; -``` - -这会编译失败。正确页：见 [09_objects_and_classes.md](09_objects_and_classes.md) - -#### 2. 把 `=` 当成赋值 - -代码块身份：反例 / 不可照写 - -```text -a = 1; -``` - -代码块身份：已验证输出片段 - -```text -invalid statement -``` - -这会编译失败。正确页：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) - -#### 3. 把字符串当成 0 基下标 - -代码块身份：反例 / 不可照写 - -```text -s := "ABC"; -WriteLn(s[0]); -``` - -这会在运行时报字符串下标越界。正确页：见 [04_values_and_literals.md](04_values_and_literals.md) - -#### 4. 把普通字符串里的 `"\uXXXX"` 直接当成和 `L"\uXXXX"` 一样的单字符宽串 - -代码块身份：反例 / 不可照写 - -```text -WriteLn(Length("\u0041")); -WriteLn(Length(L"\u0041")); -``` - -这不是同一件事。当前解释器里前者输出 `2`，后者输出 `1`。正确页：见 [04_values_and_literals.md](04_values_and_literals.md) - -#### 5. 把 `U""` 误当成和 `L""` 一样的宽串 - -代码块身份：反例 / 不可照写 - -```text -WriteLn(IfWString(U"\u5929\u8F6F")); -WriteLn(IfWString(L"\u5929\u8F6F")); -``` - -这不是同一回事。当前解释器里前者输出 `0`，后者输出 `1`。正确页：见 [04_values_and_literals.md](04_values_and_literals.md) - -#### 6. 把带 `#0` / `\0` 的字符串当成会自动截断的零结尾串 - -代码块身份：反例 / 不可照写 - -```text -s := "A"#0"B"; -WriteLn(Length(s)); -``` - -这不要按 C 风格字符串去理解。当前解释器里这里输出 `3`，说明 `#0` 仍是字符串内容的一部分。正确页：见 [04_values_and_literals.md](04_values_and_literals.md) - -#### 7. 在 `.tsl` 声明区后面继续写脚本语句 - -代码块身份：反例 / 不可照写 - -```text -a := 1; -test(); - -function test(); -begin - echo "test"; -end; - -echo "after declaration"; -``` - -`.tsl` 可以有语句区和声明区，但顺序必须清楚：语句区在前并按顺序执行，函数/类声明区在后。不要在声明区后面继续写脚本语句。正确页：见 [03_core_model.md](03_core_model.md) - -#### 8. 顶层单独写 `const Name = value;` - -代码块身份：反例 / 不可照写 - -```text -const value = 1; -``` - -这在当前解释器里会编译失败。正确页：见 [05_variables_and_constants.md](05_variables_and_constants.md) - -### 函数与调用 - -#### 9. 把 `a = 1` 当成命名参数 - -代码块身份：反例 / 不可照写 - -```text -Pack(a = 1, b = 2) -``` - -这不要当成可靠的命名参数写法。它虽然可能编译通过，但实测返回结果不对。正确页：见 [06_functions_and_calls.md](06_functions_and_calls.md) - -#### 10. 把 `like` 当成 SQL `%` / `_` 通配 - -代码块身份：反例 / 不可照写 - -```text -WriteLn("abc" like "a%"); -``` - -这在当前解释器里输出 `0`，不要按 SQL `LIKE` 去理解。当前手册里，`like` 的右侧按正则模式解释。正确页：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) - -#### 11. 把普通函数默认参数规则直接套到 `unit interface` 的 `const` 默认参数 - -代码块身份：反例 / 不可照写 - -```text -unit UnitConst; -interface -const CS = 888; -function F(a, b = 100, c = CS); -``` - -这不要直接当成已经等价于普通函数默认参数规则的写法。在当前解释器里，对应的 `F(1)` 实测输出是 `101`，不是按 `CS = 888` 补值。正确页：见 [06_functions_and_calls.md](06_functions_and_calls.md) 和 [10_units_and_scope.md](10_units_and_scope.md) - -#### 12. 把 `external` 后面的 DLL 名直接写成字符串拼接表达式 - -代码块身份：反例 / 不可照写 - -```text -function TickFromExpr(): int64; stdcall; external "kernel32"$"."$"dll" name "GetTickCount64"; -``` - -这会编译失败，错误是 `dll filename const string not found after external`。正确页：见 [06_functions_and_calls.md](06_functions_and_calls.md) - -### Unit 与查找路径 - -#### 13. 把“文件就在当前目录”当成当前命令行解释器已经能找到对应 `unit` / `.tsf` - -代码块身份：反例 / 不可照写 - -```text -program test; -uses DemoUnit; -begin - WriteLn(Ping()); -end. -``` - -如果 `DemoUnit.tsf` 所在目录没有进入 `-LIBPATH`、`tsl.conf` 的 `Libpath=` 或运行时查找路径，上面这种写法虽然语法能过，但运行时仍然找不到 `Ping()`。正确页：见 [10_units_and_scope.md](10_units_and_scope.md) - -#### 14. 把函数体或类定义体里的 `uses` 写在第一条语句之后，或在同一作用域里重复写第二个 `uses` - -代码块身份：反例 / 不可照写 - -```text -function Run(); -begin - a := 1; - uses DemoUnit; - return Ping(); -end; - -type Worker = class - uses UnitA; - uses UnitB; -end; -``` - -上面这两类写法都没有通过。函数里的错法会报 `invalid statement`，类里的错法会报 `invalid class definition`。正确页：见 [10_units_and_scope.md](10_units_and_scope.md) - -#### 15. 把限定读取 `DemoUnit.VarName` 误当成也支持限定赋值 - -代码块身份：反例 / 不可照写 - -```text -DemoUnit.UnitCounter := 13; -``` - -这在当前解释器里会编译失败，错误是左值不可赋值。正确页：见 [10_units_and_scope.md](10_units_and_scope.md) - -### 类与对象 - -#### 16. 把裸类名当成 `class function` 或静态字段的直接访问入口 - -代码块身份：反例 / 不可照写 - -```text -MathBox.Add(1, 2); - -THuman.mCount := 7; -``` - -这两种写法在当前解释器里都没有通过。当前已验证可用的是先拿到类类型，再用 `class(MathBox).Add(...)` / `FindClass("MathBox").Add(...)` 调类方法，以及 `class(THuman).mCount` 访问静态字段。正确页：见 [09_objects_and_classes.md](09_objects_and_classes.md) - -#### 17. 把 `private` / `protected create` 当成一定会执行的构造函数 - -代码块身份：反例 / 不可照写 - -```text -program test; -type A = class -public - value; -private - function create(v); - begin - self.value := v; - end; -end; -begin - a := new A(111); - WriteLn(a.value); -end. -``` - -这不会报“不能创建对象”，但 `create` 不会执行；上面的 `a.value` 实测输出 ``。正确页：见 [09_objects_and_classes.md](09_objects_and_classes.md) - -#### 18. 在子类里把父类 `private` 成员当成 `protected` 成员用 - -代码块身份：反例 / 不可照写 - -```text -program test; -type A = class -private - secret; -end; -type B = class(A) -public - function SetSecret(v); - begin - self.secret := v; - end; -end; -``` - -这会在执行时报对象成员访问错误。正确页：见 [09_objects_and_classes.md](09_objects_and_classes.md) - -## 跳转指引 - -- 整体读法：见 [01_introduction.md](01_introduction.md) -- 函数写法：见 [06_functions_and_calls.md](06_functions_and_calls.md) -- unit / uses：见 [10_units_and_scope.md](10_units_and_scope.md) -- 类写法：见 [09_objects_and_classes.md](09_objects_and_classes.md) diff --git a/docs/tsl/syntax/13_matrix_and_collections.md b/docs/tsl/syntax/13_matrix_and_collections.md deleted file mode 100644 index 207c1ba1..00000000 --- a/docs/tsl/syntax/13_matrix_and_collections.md +++ /dev/null @@ -1,118 +0,0 @@ -# Matrix And Collections - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：否 -遇到不确定时跳转到：[14_resultset_and_filters.md](14_resultset_and_filters.md)、[26_matrix_deep_dive.md](26_matrix_deep_dive.md)、[27_fmarray.md](27_fmarray.md) - -手册位置：第 13 篇，共 32 篇。上一篇：[12_pitfalls.md](12_pitfalls.md)。下一篇：[14_resultset_and_filters.md](14_resultset_and_filters.md)。 - -这一篇收拢 `array(...)` 的扩展用法：顺序数组、字符串键表、嵌套数组，以及已经在当前解释器下单独验证过的矩阵样比较。 - -## 这一篇解决什么问题 - -回答“`array(...)` 在 TSL 里除了最普通的一维数组，还能怎样组织数据；哪些矩阵样写法已经稳定验证过”。 - -## Agent 矩阵/集合判断流程 - -1. 先判断需要顺序数组、字符串键表、嵌套数组，还是矩阵样比较。 -2. 普通集合优先从 `array(...)` 起手；下标和键访问回看值语法页。 -3. 矩阵链式比较只照 `::` 系列已验证示例写，不要混用标量链式比较。 -4. 集合过滤或 TS-SQL 查询需求跳转到结果集/TS-SQL 页面。 -5. 没有已验证代码块时不要发明矩阵/集合写法。 - -## 必须记住的规则 - -- `array(...)` 既可以写顺序数组，也可以写字符串键表。 -- 顺序数组下标从 `0` 开始；字符串仍然从 `1` 开始。 -- `array(...)` 可以继续嵌套，形成二维或矩阵样数据。 -- 当前解释器接受矩阵链式比较 `::>`、`::<`、`::<>`、`::==`、`::>=`、`::<=`。 -- 当前这篇只收已经单独验证过的数组 / 键表 / 矩阵样主干，不把结果集过滤和 TS-SQL 混进来。 - -## 已验证语法 - -顺序数组与字符串键表： - -代码块身份：已验证可执行示例 - -```tsl -arr := array(10, 20, 30); -hash := array("Code": "0001", "Price": 12.3); -WriteLn("ARR0=", arr[0]); -WriteLn("ARR1=", arr[1]); -WriteLn("HASH=", hash["Code"]); -``` - -已验证运行结果对应关系： - -- `arr[0] = 10` -- `arr[1] = 20` -- `hash["Code"] = "0001"` - -代码块身份：已验证输出片段 - -```text -1 -2 -3 -4 -``` - -嵌套数组： - -代码块身份：已验证可执行示例 - -```tsl -[r1, r2] := array((1, 2), (3, 4)); -WriteLn(r1[0]); -WriteLn(r1[1]); -WriteLn(r2[0]); -WriteLn(r2[1]); -``` - -已验证运行结果： - -- 依次输出 `1`、`2`、`3`、`4` -- 说明 `array((1, 2), (3, 4))` 这种嵌套数组写法可以稳定通过，并可按普通数组继续读取 - -矩阵链式比较： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - r := array(1, 2, -1) ::< array(2, 1, 0) ::< array(3, 2, 1); - WriteLn(r[0]); - WriteLn(r[1]); - WriteLn(r[2]); - s := array(1, 2, -1) ::< 2 ::< array(3, 2, 1); - WriteLn(s[0]); - WriteLn(s[1]); - WriteLn(s[2]); -end. -``` - -已验证运行结果： - -- `array(1, 2, -1) ::< array(2, 1, 0) ::< array(3, 2, 1)` 的三个元素依次输出 `1`、`0`、`1` -- `array(1, 2, -1) ::< 2 ::< array(3, 2, 1)` 的三个元素依次输出 `1`、`0`、`0` -- 说明矩阵链式比较会按元素位置分别得到结果数组，并且可以和标量混用 - -## 暂不在本页展开的部分 - -- 专门的结果集过滤函数 -- TS-SQL 查询与写回 -- 更大范围的矩阵函数族 - -这些内容会继续收拢到后面的进阶专题，而不是再外跳到旧目录。 - -## 跳转指引 - -- 回看基础值与索引：见 [04_values_and_literals.md](04_values_and_literals.md) -- 回看表达式层比较：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 进入结果集过滤：见 [14_resultset_and_filters.md](14_resultset_and_filters.md) -- 进入集合运算专题：见 [25_set_operations.md](25_set_operations.md) -- 进入矩阵深水专题：见 [26_matrix_deep_dive.md](26_matrix_deep_dive.md) -- 进入 `FMArray`：见 [27_fmarray.md](27_fmarray.md) diff --git a/docs/tsl/syntax/13_resultset_and_filters.md b/docs/tsl/syntax/13_resultset_and_filters.md new file mode 100644 index 00000000..7b3617c6 --- /dev/null +++ b/docs/tsl/syntax/13_resultset_and_filters.md @@ -0,0 +1,212 @@ +# TSL 结果集与过滤 + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[14_ts_sql.md](14_ts_sql.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只讲结果集过滤语法：怎样按某一列过滤、怎样按整行过滤、怎样只返回行下标，以及怎样按字段列表过滤。它不负责 TS-SQL 查询语法，也不把去重型集合运算和业务选股逻辑混进来。 + +## 本篇职责 + +回答“已有数组或二维结果集时，想按某个过滤集保留命中的行、排除命中的行，或者只拿到符合条件的行下标时，应该怎么写”。 + +## 智能体结果集/过滤判断流程 + +1. 先判断任务是 `filterIn(...)` / `filterNotIn(...)` 过滤、结果集字段访问、去重型集合运算，还是 TS-SQL 查询。 +2. 字段访问优先照本页明确的字符串键或结果集字段形态写。 +3. 复杂查询需求优先跳转到 [14_ts_sql.md](14_ts_sql.md)，不要把查询语法硬塞进过滤函数。 +4. `in` / `sqlin` / `union2` / `intersect` / `minus` / `outersect` 这类去重型集合关系跳转到 [12_matrix_and_collections.md](12_matrix_and_collections.md)。 +5. 金融数据筛选要先确认数据来源；函数事实见 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)，项目字段和业务上下文回项目实际接口。 +6. 没有对应代码块时不要发明结果集/过滤写法。 + +## 核心规则 + +- 结果集过滤主函数是 `filterIn(...)` 和 `filterNotIn(...)`。 +- `filterIn(rows, filter_array, field)` 返回命中的子结果集；`filterNotIn(...)` 返回未命中的子结果集。 +- 第四个参数写成 `false` 时，返回值不再是子结果集，而是符合条件的行下标数组。 +- `Field` 写成字符串时，表示按某一列过滤。 +- `Field` 写成 `nil` 时，表示按整行过滤；一维数组也走这个入口。 +- `Field` 写成 `array("A", "B")` 这类字段名数组时，表示只按这些列做匹配。 +- 过滤运算不会自动去重；原结果集里有重复行时，命中的重复行会原样保留下来。 +- 去重型的并、交、差运算不放在这一篇，见 [12_matrix_and_collections.md](12_matrix_and_collections.md)。 + +## 可直接照写示例 + +### 按单列过滤 + +按 `"Code"` 列做包含与排除： + +代码块身份：可直接照写示例 + +```tsl +rows := array( + ("Code": "0001", "V1": 8.9, "V2": 12), + ("Code": "0002", "V1": 9, "V2": 10), + ("Code": "0003", "V1": 8, "V2": 8), + ("Code": "0004", "V1": 1, "V2": 2) +); +code_arr := array("0001", "0003"); +keep_rows := filterIn(rows, code_arr, "Code"); +drop_rows := filterNotIn(rows, code_arr, "Code"); +writeLn(keep_rows[0]["Code"]); +writeLn(keep_rows[1]["Code"]); +writeLn(drop_rows[0]["Code"]); +writeLn(drop_rows[1]["Code"]); +``` + +结果说明： + +- `filterIn(rows, code_arr, "Code")` 返回两行：`0001`、`0003` +- `filterNotIn(rows, code_arr, "Code")` 返回两行：`0002`、`0004` + +代码块身份：输出片段 + +```text +0001 +0003 +0002 +0004 +``` + +### 返回行下标 + +第四个参数写成 `false` 时，返回行下标而不是子结果集： + +代码块身份：可直接照写示例 + +```tsl +rows := array( + ("Code": "0001", "V1": 8.9, "V2": 12), + ("Code": "0002", "V1": 9, "V2": 10), + ("Code": "0003", "V1": 8, "V2": 8), + ("Code": "0004", "V1": 1, "V2": 2) +); +code_arr := array("0001", "0003"); +keep_index := filterIn(rows, code_arr, "Code", false); +drop_index := filterNotIn(rows, code_arr, "Code", false); +``` + +结果说明： + +- `filterIn(rows, code_arr, "Code", false)` 返回 `array(0, 2)` +- `filterNotIn(rows, code_arr, "Code", false)` 返回 `array(1, 3)` + +这些下标可以直接继续拿去切子结果集： + +代码块身份：可直接照写示例 + +```tsl +rows := array( + ("Code": "0001", "V1": 8.9, "V2": 12), + ("Code": "0002", "V1": 9, "V2": 10), + ("Code": "0003", "V1": 8, "V2": 8), + ("Code": "0004", "V1": 1, "V2": 2) +); +code_arr := array("0001", "0003"); +keep_index := filterIn(rows, code_arr, "Code", false); +picked := rows[keep_index, array("Code", "V1")]; +``` + +### `Field = nil` 时按整行过滤 + +整行过滤与一维数组过滤都走 `Field = nil`： + +代码块身份：可直接照写示例 + +```tsl +rows := array( + ("A": 1, "B": 2, "C": 3), + ("A": 2, "B": 3, "C": 4), + ("A": 1, "B": 2, "C": 3), + ("A": 4, "B": 5, "C": 6), + ("A": 4, "B": 5, "C": 6) +); +filter_rows := array( + ("A": 1, "B": 2, "C": 3), + ("A": 2, "B": 3, "C": 4) +); +keep_rows := filterIn(rows, filter_rows, nil); +left_only := filterNotIn(array(1, 2, 3, 4, 5, 5, 6, 7), array(1, 2, 3, 4), nil); +``` + +结果说明： + +- `filterIn(rows, filter_rows, nil)` 返回三行：`(1,2,3)`、`(2,3,4)`、`(1,2,3)` +- 这里第一行和第三行都被保留下来，说明过滤不会自动去重 +- `filterNotIn(array(1, 2, 3, 4, 5, 5, 6, 7), array(1, 2, 3, 4), nil)` 返回 `array(5, 5, 6, 7)` + +### 按字段列表过滤 + +如果只想按部分列判断是否命中，把 `Field` 写成字段名数组： + +代码块身份：可直接照写示例 + +```tsl +rows := array( + ("A": 1, "B": 2, "C": 3), + ("A": 2, "B": 3, "C": 4), + ("A": 1, "B": 2, "C": 5), + ("A": 4, "B": 5, "C": 6) +); +filter_rows := array( + ("A": 1, "B": 2), + ("A": 2, "B": 3) +); +keep_rows := filterIn(rows, filter_rows, array("A", "B")); +keep_index := filterIn(rows, filter_rows, array("A", "B"), false); +sub_result := rows[keep_index, array("A", "C")]; +``` + +结果说明： + +- `filterIn(rows, filter_rows, array("A", "B"))` 返回三行：`(1,2,3)`、`(2,3,4)`、`(1,2,5)` +- `filterIn(rows, filter_rows, array("A", "B"), false)` 返回 `array(0, 1, 2)` +- `rows[keep_index, array("A", "C")]` 返回三行：`(1,3)`、`(2,4)`、`(1,5)` + +## 和集合运算的区别 + +- 过滤运算按“原结果集中的每一行是否命中”来决定保留或排除。 +- 集合运算按“行集合”来做并、交、差；结果默认会折叠重复行。 +- 需要保留重复记录时，优先看这一篇。 +- 需要去重后的并集、交集、差集时，优先看 [12_matrix_and_collections.md](12_matrix_and_collections.md)。 + +## 默认生成模板 + +结果集过滤的默认骨架如下： + +代码块身份：可直接照写示例 + +```tsl +rows := array( + ("Code": "0001"), + ("Code": "0002") +); +code_arr := array("0001"); +keep_rows := filterIn(rows, code_arr, "Code"); +``` + +## 禁止项 + +- 把 `filterIn(...)` 当成去重工具。 +- 过滤整行时忘了把 `Field` 写成 `nil`。 +- 需要返回下标时漏掉第四个参数 `false`。 +- 已经只按部分列过滤，却仍然把 `Field` 写成单个字符串。 +- 把过滤运算和 `union2` / `intersect` 这类集合运算混为一谈。 + +代码块身份：反例 / 不可照写 + +```text +keep_rows := filterIn(rows, filter_rows, "A"); +``` + +上面这种写法只会按单列 `"A"` 判断，不会同时比较 `A` 和 `B`；如果需求是“按多个字段联合过滤”，应改成 `array("A", "B")`。 + +代码块身份：反例 / 不可照写 + +```text +keep_rows := filterIn(rows, filter_rows); +``` + +不要把 `Field` 省略当成“默认按整行过滤”。本页只把显式写出 `nil` 作为可靠规则。 diff --git a/docs/tsl/syntax/14_resultset_and_filters.md b/docs/tsl/syntax/14_resultset_and_filters.md deleted file mode 100644 index 80f59fa2..00000000 --- a/docs/tsl/syntax/14_resultset_and_filters.md +++ /dev/null @@ -1,226 +0,0 @@ -# Result Sets And Filters - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[13_matrix_and_collections.md](13_matrix_and_collections.md)、[15_ts_sql.md](15_ts_sql.md)、[25_set_operations.md](25_set_operations.md) - -手册位置：第 14 篇，共 32 篇。上一篇：[13_matrix_and_collections.md](13_matrix_and_collections.md)。下一篇：[15_ts_sql.md](15_ts_sql.md)。 - -这一篇只讲结果集过滤语法：怎样按某一列过滤、怎样按整行过滤、怎样只返回行下标，以及怎样按字段列表过滤。它不负责 TS-SQL 查询语法，也不把集合运算和业务选股逻辑混进来。 - -## 这一篇解决什么问题 - -回答“已有数组或二维结果集时，想按某个过滤集保留命中的行、排除命中的行，或者只拿到符合条件的行下标时，应该怎么写”。 - -## Agent 结果集/过滤判断流程 - -1. 先判断任务是普通数组过滤、结果集字段访问，还是 TS-SQL 查询。 -2. 字段访问优先照本页已验证的字符串键或结果集字段形态写。 -3. 复杂查询需求优先跳转到 TS-SQL 页面，不要把业务过滤硬塞进基础表达式。 -4. 金融业务筛选要回到 finance 层确认上下文。 -5. 没有已验证代码块时不要发明结果集/过滤写法。 - -## 必须记住的规则 - -- 结果集过滤主函数是 `FilterIn(...)` 和 `FilterNotIn(...)`。 -- `FilterIn(R, FilterArray, Field)` 返回命中的子结果集；`FilterNotIn(...)` 返回未命中的子结果集。 -- 第四个参数写成 `false` 时，返回值不再是子结果集，而是符合条件的行下标数组。 -- `Field` 写成字符串时，表示按某一列过滤。 -- `Field` 写成 `nil` 时，表示按整行过滤；一维数组也走这个入口。 -- `Field` 写成 `array("A", "B")` 这类字段名数组时，表示只按这些列做匹配。 -- 过滤运算不会自动去重；原结果集里有重复行时，命中的重复行会原样保留下来。 -- 去重型的并、交、差运算不放在这一篇，见 [25_set_operations.md](25_set_operations.md)。 - -## 已验证语法 - -### 按单列过滤 - -按 `"Code"` 列做包含与排除： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - R := array( - ("Code": "0001", "V1": 8.9, "V2": 12), - ("Code": "0002", "V1": 9, "V2": 10), - ("Code": "0003", "V1": 8, "V2": 8), - ("Code": "0004", "V1": 1, "V2": 2) - ); - CodeArr := array("0001", "0003"); - KeepRows := FilterIn(R, CodeArr, "Code"); - DropRows := FilterNotIn(R, CodeArr, "Code"); -end. -``` - -已验证运行结果： - -- `FilterIn(R, CodeArr, "Code")` 返回两行：`0001`、`0003` -- `FilterNotIn(R, CodeArr, "Code")` 返回两行：`0002`、`0004` - -代码块身份：已验证输出片段 - -```text -0001 -0003 -0002 -0004 -``` - -### 返回行下标 - -第四个参数写成 `false` 时，返回行下标而不是子结果集： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - R := array( - ("Code": "0001", "V1": 8.9, "V2": 12), - ("Code": "0002", "V1": 9, "V2": 10), - ("Code": "0003", "V1": 8, "V2": 8), - ("Code": "0004", "V1": 1, "V2": 2) - ); - CodeArr := array("0001", "0003"); - KeepIndex := FilterIn(R, CodeArr, "Code", false); - DropIndex := FilterNotIn(R, CodeArr, "Code", false); -end. -``` - -已验证运行结果： - -- `FilterIn(R, CodeArr, "Code", false)` 返回 `array(0, 2)` -- `FilterNotIn(R, CodeArr, "Code", false)` 返回 `array(1, 3)` - -这些下标可以直接继续拿去切子结果集： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - R := array( - ("Code": "0001", "V1": 8.9, "V2": 12), - ("Code": "0002", "V1": 9, "V2": 10), - ("Code": "0003", "V1": 8, "V2": 8), - ("Code": "0004", "V1": 1, "V2": 2) - ); - CodeArr := array("0001", "0003"); - KeepIndex := FilterIn(R, CodeArr, "Code", false); - Picked := R[KeepIndex, array("Code", "V1")]; -end. -``` - -### `Field = nil` 时按整行过滤 - -整行过滤与一维数组过滤都走 `Field = nil`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - R := array( - ("A": 1, "B": 2, "C": 3), - ("A": 2, "B": 3, "C": 4), - ("A": 1, "B": 2, "C": 3), - ("A": 4, "B": 5, "C": 6), - ("A": 4, "B": 5, "C": 6) - ); - R1 := array( - ("A": 1, "B": 2, "C": 3), - ("A": 2, "B": 3, "C": 4) - ); - KeepRows := FilterIn(R, R1, nil); - LeftOnly := FilterNotIn(array(1, 2, 3, 4, 5, 5, 6, 7), array(1, 2, 3, 4), nil); -end. -``` - -已验证运行结果： - -- `FilterIn(R, R1, nil)` 返回三行：`(1,2,3)`、`(2,3,4)`、`(1,2,3)` -- 这里第一行和第三行都被保留下来，说明过滤不会自动去重 -- `FilterNotIn(array(1, 2, 3, 4, 5, 5, 6, 7), array(1, 2, 3, 4), nil)` 返回 `array(5, 5, 6, 7)` - -### 按字段列表过滤 - -如果只想按部分列判断是否命中，把 `Field` 写成字段名数组： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - R := array( - ("A": 1, "B": 2, "C": 3), - ("A": 2, "B": 3, "C": 4), - ("A": 1, "B": 2, "C": 5), - ("A": 4, "B": 5, "C": 6) - ); - R1 := array( - ("A": 1, "B": 2), - ("A": 2, "B": 3) - ); - KeepRows := FilterIn(R, R1, array("A", "B")); - KeepIndex := FilterIn(R, R1, array("A", "B"), false); - SubResult := R[KeepIndex, array("A", "C")]; -end. -``` - -已验证运行结果： - -- `FilterIn(R, R1, array("A", "B"))` 返回三行：`(1,2,3)`、`(2,3,4)`、`(1,2,5)` -- `FilterIn(R, R1, array("A", "B"), false)` 返回 `array(0, 1, 2)` -- `R[KeepIndex, array("A", "C")]` 返回三行：`(1,3)`、`(2,4)`、`(1,5)` - -## 和集合运算的区别 - -- 过滤运算按“原结果集中的每一行是否命中”来决定保留或排除。 -- 集合运算按“行集合”来做并、交、差；结果默认会折叠重复行。 -- 需要保留重复记录时，优先看这一篇。 -- 需要去重后的并集、交集、差集时，优先看 [25_set_operations.md](25_set_operations.md)。 - -## 最小可编译示例 - -如果你只想先记住最短写法，从这个骨架开始： - -代码块身份：已验证可执行示例 - -```tsl -KeepRows := FilterIn(R, CodeArr, "Code"); -``` - -## 常见误写 - -- 把 `FilterIn(...)` 当成去重工具。 -- 过滤整行时忘了把 `Field` 写成 `nil`。 -- 需要返回下标时漏掉第四个参数 `false`。 -- 已经只按部分列过滤，却仍然把 `Field` 写成单个字符串。 -- 把过滤运算和 `Union2` / `Intersect` 这类集合运算混为一谈。 - -代码块身份：反例 / 不可照写 - -```text -KeepRows := FilterIn(R, R1, "A"); -``` - -上面这种写法只会按单列 `"A"` 判断，不会同时比较 `A` 和 `B`；如果需求是“按多个字段联合过滤”，应改成 `array("A", "B")`。 - -代码块身份：反例 / 不可照写 - -```text -KeepRows := FilterIn(R, R1); -``` - -不要把 `Field` 省略当成“默认按整行过滤”。当前手册只把显式写出 `nil` 作为可靠规则。 - -## 跳转指引 - -- 回看数组和子矩阵：见 [13_matrix_and_collections.md](13_matrix_and_collections.md) -- 看表达式层 `in` / `sqlin`：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 看去重型集合运算：见 [25_set_operations.md](25_set_operations.md) -- 进入 TS-SQL：见 [15_ts_sql.md](15_ts_sql.md) diff --git a/docs/tsl/syntax/14_ts_sql.md b/docs/tsl/syntax/14_ts_sql.md new file mode 100644 index 00000000..d0e1c8bd --- /dev/null +++ b/docs/tsl/syntax/14_ts_sql.md @@ -0,0 +1,338 @@ +# TSL TS-SQL + +文档类型：语法主线 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[13_resultset_and_filters.md](13_resultset_and_filters.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇是 TS-SQL 的唯一语法入口：内存数组查询、返回形态、字段访问、`where` / `group by` / `order by`、一维数组查询、多表 `join`、`thisGroup`、`thisRowIndex`、`refMaxOf` / `refMinOf` 都在这里收拢。 + +## 本篇职责 + +回答“写 TS-SQL 查询时，怎样从最小 `select ... from ... end` 骨架开始，逐步处理筛选、分组、排序、多表联接、组内子查询和极值引用”。 + +## 智能体 TS-SQL 判断流程 + +1. 先判断要写 `select`、`sselect`、`vselect`、`mselect`，还是 `join` / `thisGroup` / 极值引用。 +2. 内存数组查询优先从 `select ... from source_rows end` 最小骨架起手。 +3. 二维结果集字段访问用 `["字段名"]`；多表查询字段访问用 `[表序号].["字段名"]`。 +4. 在一维数组上做 TS-SQL 时，优先使用 `thisRow` 和 `thisRowIndex`。 +5. 只想按已有结果集保留/排除行时跳到 [13_resultset_and_filters.md](13_resultset_and_filters.md)；要做去重型集合关系时跳到 [12_matrix_and_collections.md](12_matrix_and_collections.md)；要在 `FMArray` 上做查询或写回边界时跳到 [23_fmarray.md](23_fmarray.md)。 +6. 没有对应代码块时不要发明 TS-SQL 写法。 + +## 核心规则 + +- TS-SQL 是 TSL 自带的类 SQL 查询语法，不是金融业务函数库。 +- 基础查询文档骨架是：以 `select` / `sselect` / `vselect` / `mselect` 开始，以 `end` 收尾。 +- `from` 后面可以直接跟内存数组结果集。 +- 在内存二维结果集上，文档字段访问写法是 `["字段名"]`。 +- 在一维数组上做 TS-SQL 时，优先使用 `thisRow` 和 `thisRowIndex`。 +- `select` 返回二维结果，`sselect` 返回一维结果，`vselect` 返回单值，`mselect` 返回 `Matrix`。 +- `where`、`group by`、`order by` 可以直接接在 `from` 后面继续使用。 +- 多表 `join` 时，字段访问应写成 `[表序号].["字段名"]`。 +- `thisGroup` 不是普通值，而是分组后的子结果集；要通过子 `select` / `vselect` 的 `from thisGroup` 来访问。 +- `thisRowIndex` 在 `order by` 之后仍可返回原始行位置，而不是排序后的序号。 +- `refMaxOf(...)` 和 `refMinOf(...)` 可与 `maxOf(...)` / `minOf(...)` 配合，取极值所在行的另一列值。 +- 访问金融表、时间序列或业务数据源时，语法和业务语义要分开看；本页只讲语言层查询骨架。 + +## 可直接照写示例 + +### 最小查询骨架 + +代码块身份：可直接照写示例 + +```tsl +source_rows := array( + ("A": 1, "B": 3), + ("A": 2, "B": 1) +); +query_result := select * from source_rows end; +writeLn(length(query_result)); +``` + +结果说明： + +- `query_result` 的长度是 `2` +- 两行依次是 `(1,3)`、`(2,1)` +- 说明 TS-SQL 的最短可靠入口就是“准备结果集，然后 `select ... from source_rows end`” + +代码块身份：输出片段 + +```text +2 +``` + +### 字段选择 + +代码块身份：可直接照写示例 + +```tsl +source_rows := array( + ("A": 1, "B": 3), + ("A": 2, "B": 1), + ("A": 1, "B": 2) +); +query_result := select ["A"], ["B"] from source_rows end; +writeLn(length(query_result)); +``` + +结果说明： + +- `query_result` 的长度是 `3` +- 三行依次是 `(1,3)`、`(2,1)`、`(1,2)` +- 说明 `select ["A"], ["B"] from source_rows end` 会按原顺序返回二维结果集 + +### 四个查询入口怎样分工 + +代码块身份：可直接照写示例 + +```tsl +source_rows := array( + ("A": 1, "B": 3), + ("A": 2, "B": 1), + ("A": 1, "B": 2) +); +selected_values := sselect ["A"] from source_rows end; +sum_value := vselect sumOf(["B"]) from source_rows end; +matrix_result := mselect * from source_rows end; +col_index := mcols(matrix_result, 1); +``` + +结果说明： + +- `sselect ["A"] from source_rows end` 返回一维数组 `array(1, 2, 1)` +- `vselect sumOf(["B"]) from source_rows end` 返回单值 `6` +- `mselect * from source_rows end` 的行数是 `3`、列数是 `2` +- `mcols(matrix_result, 1)` 返回列索引 `array("A", "B")` +- 本页只把 `mselect` 的“返回 Matrix 且保留行列信息”写成文档主干；不要在本页发明直接单元格读取规则 + +### `where` 和 `order by` + +代码块身份：可直接照写示例 + +```tsl +source_rows := array( + ("A": 1, "B": 3), + ("A": 2, "B": 1), + ("A": 1, "B": 2) +); +query_result := select * from source_rows where ["B"] > 1 order by ["B"] end; +``` + +结果说明： + +- `query_result` 的长度是 `2` +- 两行依次是 `(1,2)`、`(1,3)` +- 说明 `where ["B"] > 1` 会先筛选，再按 `order by ["B"]` 的升序返回 + +### `group by` + +代码块身份：可直接照写示例 + +```tsl +source_rows := array( + ("A": 1, "B": 3), + ("A": 2, "B": 1), + ("A": 1, "B": 2) +); +group_result := select ["A"], sumOf(["B"]) as "SumB" + from source_rows + group by ["A"] + order by ["A"] + end; +``` + +结果说明： + +- `group_result` 的长度是 `2` +- 第一行是 `(1,5)` +- 第二行是 `(2,1)` +- 说明 `group by ["A"]` 后可以直接接聚集函数，并用 `as "SumB"` 指定返回列名 + +### 一维数组上的 `thisRow` 与 `thisRowIndex` + +代码块身份：可直接照写示例 + +```tsl +values := array(10, 20, 30); +row_values := sselect thisRow from values end; +row_indexes := sselect thisRowIndex from values end; +query_result := select thisRow as "Value", thisRowIndex as "Idx" + from values + where thisRow > 15 + order by thisRow + end; +``` + +结果说明： + +- `sselect thisRow from values end` 返回 `array(10, 20, 30)` +- `sselect thisRowIndex from values end` 返回 `array(0, 1, 2)` +- 上面的 `select ... from values where thisRow > 15 order by thisRow end` 返回两行：第一行 `Value=20, Idx=1`，第二行 `Value=30, Idx=2` + +### `join` + +代码块身份：可直接照写示例 + +```tsl +left_rows := array( + ("ID": 1, "V1": 10), + ("ID": 2, "V1": 20) +); +right_rows := array( + ("ID": 1, "V2": 100), + ("ID": 3, "V2": 300) +); +join_result := select [1].["ID"], [1].["V1"], [2].["V2"] + from left_rows join right_rows on [1].["ID"] = [2].["ID"] + end; +writeLn(length(join_result)); +writeLn(join_result[0]["ID"]); +writeLn(join_result[0]["V1"]); +writeLn(join_result[0]["V2"]); +``` + +结果说明： + +- `join_result` 的长度是 `1` +- 唯一一行是 `(1,10,100)` +- 说明 `from left_rows join right_rows on ...` 和 `[1].["字段"]`、`[2].["字段"]` 这种多表字段访问属于文档明确写法 + +代码块身份：输出片段 + +```text +1 +1 +10 +100 +``` + +### `thisGroup` + +代码块身份：可直接照写示例 + +```tsl +source_rows := array( + ("A": 1, "B": 3, "Name": "x"), + ("A": 2, "B": 1, "Name": "y"), + ("A": 1, "B": 2, "Name": "z") +); +group_result := select ["A"], maxb := maxOf(["B"]) as "MaxB", + vselect ["Name"] from thisGroup where ["B"] = maxb end as "TopName" + from source_rows + group by ["A"] + order by ["A"] + end; +``` + +结果说明： + +- `group_result` 的长度是 `2` +- 第一行是 `(1,3,"x")` +- 第二行是 `(2,1,"y")` +- 说明 `thisGroup` 可以在分组上下文里作为子结果集继续 `vselect` + +### `thisRowIndex` 在排序后仍指向原始位置 + +代码块身份：可直接照写示例 + +```tsl +source_rows := array( + ("A": 1, "B": 3), + ("A": 2, "B": 1), + ("A": 1, "B": 2) +); +query_result := select thisRowIndex as "Idx", ["B"] + from source_rows + order by ["B"] + end; +``` + +结果说明： + +- `query_result` 的三行依次是 `(1,1)`、`(2,2)`、`(0,3)` +- 说明 `order by ["B"]` 之后，`thisRowIndex` 仍返回原表中的原始下标 + +### `refMaxOf` 与 `refMinOf` + +代码块身份：可直接照写示例 + +```tsl +source_rows := array((6, 20), (5, 20), (9, 2), (2, 20), (7, 18)); +max_ref_result := select maxOf([0]) as "MaxA", refMaxOf([1]) as "RefB" from source_rows end; +min_ref_result := select minOf([0]) as "MinA", refMinOf([1]) as "RefB" from source_rows end; +``` + +结果说明： + +- `max_ref_result` 只有一行，结果是 `(9,2)` +- `min_ref_result` 只有一行，结果是 `(2,20)` +- 说明 `refMaxOf([1])` 取到了 `[0]` 最大值所在行的 `[1]`，`refMinOf([1])` 取到了 `[0]` 最小值所在行的 `[1]` + +## 本页不生成的范围 + +- `with on` +- `left join` / `right join` / `full join` +- `RefsOf` +- `insert` / `update` / `delete` +- `TSQLInsert` / `TSQLSetValue` / `TSQLBatchInsert` +- `TSQLEdit` / `TSQLPost` / `TSQLFinal` +- 面向 SQL 表、业务表或时间序列的数据查询与写回 + +这些内容不作为本页可生成事实；业务数据源先查 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)、[../modules/pytsl_api.md](../modules/pytsl_api.md) 或项目实际接口。 + +## 默认生成模板 + +TS-SQL 的最短默认骨架如下： + +代码块身份：可直接照写示例 + +```tsl +query_result := select * from source_rows end; +``` + +## 禁止项 + +- 不要把数据库 SQL 方言直接迁移成 TS-SQL 代码。 +- 不要把 `select` 当成普通函数调用，忘了以 `end` 收尾。 +- 在二维结果集里直接写 `A` 而不是 `["A"]`。 +- 多表联接时继续写成 `["ID"]`，没有加表序号。 +- 处理一维数组时直接把 `[0]` 当成稳定列访问。 +- 把 `thisGroup` 当成普通字段或普通变量。 +- 把排序后的 `thisRowIndex` 误当成排序序号。 +- 把 `with on`、写回接口和时间序列缓存写进默认模板。 + +代码块身份：反例 / 不可照写 + +```text +query_result := select A from source_rows end; +``` + +上面这种写法不要当成本页可靠规则。二维结果集字段访问，本页只把 `["A"]` 这种写法写成文档主干。 + +代码块身份：反例 / 不可照写 + +```text +query_result := select [0] from values end; +``` + +这种对一维数组直接用 `[0]` 的写法虽然返回长度为 `3` 的结果，但取到的值是 `nil`，不能当成可靠入口。对一维数组应改用 `thisRow` 和 `thisRowIndex`。 + +代码块身份：反例 / 不可照写 + +```text +query_result := select ["ID"], ["V1"], ["V2"] + from left_rows join right_rows on ["ID"] = ["ID"] + end; +``` + +上面这种写法不要当成本页可靠规则。多表查询里，本页只把 `[1].["字段"]`、`[2].["字段"]` 这种带表序号的访问方式写成文档主干。 + +代码块身份：反例 / 不可照写 + +```text +group_value := thisGroup; +``` + +不要把 `thisGroup` 当成普通值直接使用。可靠入口是 `select ... from thisGroup end` 或 `vselect ... from thisGroup end`。 diff --git a/docs/tsl/syntax/15_debug_and_profiler.md b/docs/tsl/syntax/15_debug_and_profiler.md new file mode 100644 index 00000000..ad64b618 --- /dev/null +++ b/docs/tsl/syntax/15_debug_and_profiler.md @@ -0,0 +1,258 @@ +# TSL 调试与性能分析器 + +文档类型：语法主线 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[07_control_flow.md](07_control_flow.md)、[10_runtime_context_and_with.md](10_runtime_context_and_with.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇收拢本页明确的调试、计时、性能分析器和调用栈相关入口。 + +## 本篇职责 + +回答“`goto`、`debugReturn`、`debugRunEnv`、`mtic` / `mtoc`、`setProfiler`、`__line__` 和 `__stack_frame` 怎样写、会怎样表现”。 + +## 智能体调试/性能分析器判断流程 + +1. 先判断任务需要跳转、提前返回、运行环境调试、计时还是性能分析器。 +2. 普通控制流优先回到 [07_control_flow.md](07_control_flow.md)，本页只处理调试补充工具。 +3. `debugReturn` 会结束整段脚本，不能当成普通函数返回。 +4. 计时和性能分析器只照文档最小调用写，不要补未写入文档参数。 +5. 没有对应代码块时不要发明调试/性能分析器写法。 + +## 核心规则 + +- `goto label_name;` 属于文档明确写法，但目标位置以 `label label_name; statement` 这种内联形式作为默认生成形态。 +- 本页正向边界只覆盖“跳到同一函数 / 同一脚本体后面的位置”，不要先把更复杂的跨层跳转边界写成事实。 +- `debugReturn value;` 会直接结束整段脚本，后面的语句不会继续执行。 +- `debugRunEnv(0)` 和 `debugRunEnv(1)` 可直接调用；它们面向调试客户端的副作用，不作为本页输出事实。 +- `debugRunEnvDo Func(...)` 可直接写，并且会返回被调用函数的结果。 +- `mtic` 会生成一个计时起点；`mtoc` 和 `mtoc(tick)` 都会返回秒数。 +- `setProfiler(...)` 和 `getProfilerInfo(...)` 的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)；本页只保留性能分析器行为示例。 +- `setProfiler(7)` 配合 `getProfilerInfo(1)`，可以在不弹窗的情况下拿到性能分析器信息。 +- `__line__` 会返回所在代码行号。 +- `__stack_frame` 会返回调用栈帧数组；最小 `toStn(...)` 观察结果里，每一项是 `(line, "function")` 这一类二元组。 + +## 可直接照写示例 + +### `goto` + +代码块身份：可直接照写示例 + +```tsl +data := array((1, 2), (3, 4)); +target := 3; +found := 0; +for i := 0 to length(data) - 1 do +begin + for j := 0 to length(data[i]) - 1 do + begin + if data[i][j] = target then + goto found_label; + end +end +writeLn(0); +goto done_label; +label found_label; found := 1; +writeLn(found); +label done_label; writeLn(9); +``` + +结果说明： + +- 依次输出 `1`、`9` +- 说明 `goto found_label;` 可以跳到后面的 `label found_label; ...` +- 也说明默认目标写法是把 `label` 和第一条目标语句放在同一行 + +跨函数跳转不作为可写事实： + +代码块身份：反例 / 不可照写 + +```text +Inner(); +label out_label; writeLn(1); + +function Inner(); +begin + goto out_label; +end; +``` + +结果说明： + +- 上面这段会运行报错，核心信息是 `Goto label can not found!` +- 本页正向边界只覆盖“同一函数 / 同一脚本体后面的位置” +- 不要把 `goto` 泛化成能跨函数跳到外层 `label` + +目标 `label` 单独成行不作为可写事实： + +代码块身份：反例 / 不可照写 + +```text +goto done_label; +label done_label; +writeLn("after"); +``` + +结果说明： + +- 上面这种把 `label` 单独放一行、下一行再写目标语句的最小例子，会报 `Statement missing terminator` +- 因此本页只把 `label name; statement` 这种内联形式写成文档事实 + +### `debugReturn` + +代码块身份：可直接照写示例 + +```tsl +writeLn("before"); +a := Inner(3); +writeLn("after"); + +function Inner(bb); +begin + debugReturn bb; +end; +``` + +结果说明： + +- 只输出 `before` +- 说明 `debugReturn bb;` 不只是结束 `Inner(...)`，而是直接让整段脚本提前返回 +- 因此 `Inner(3)` 后面的 `writeLn("after")` 不会执行 + +### `debugRunEnv` 与 `debugRunEnvDo` + +`debugRunEnv(0)` / `debugRunEnv(1)`： + +代码块身份：可直接照写示例 + +```tsl +a := 1; +debugRunEnv(0); +debugRunEnv(1); +writeLn(1); +``` + +结果说明： + +- 输出 `1` +- 说明这两个调用能正常执行，不会中断后续语句 +- 但它们把变量 / 系统参数送到调试窗口的效果，不作为本页输出事实 + +`debugRunEnvDo Func(...)`： + +代码块身份：可直接照写示例 + +```tsl +r := debugRunEnvDo Demo(2); +writeLn(r); + +function Demo(x); +begin + y := x + 1; + return y; +end; +``` + +结果说明： + +- 输出 `3` +- 说明 `debugRunEnvDo Demo(2)` 可以直接写 +- 也说明它会把被调用函数的结果继续返回给外层 + +### `mtic` 与 `mtoc` + +代码块身份：可直接照写示例 + +```tsl +t1 := mtic; +s := 0; +for i := 0 to 9999 do + s := s + i; +te1 := mtoc(t1); +t2 := mtic; +for j := 0 to 9999 do + s := s + j; +te2 := mtoc; +writeLn(te1 >= 0); +writeLn(te2 >= 0); +``` + +结果说明： + +- 依次输出 `1`、`1` +- 说明 `mtoc(t1)` 和无参 `mtoc` 都能返回可用的秒数结果 + +### `setProfiler` 与 `getProfilerInfo` + +代码块身份：可直接照写示例 + +```tsl +setProfiler(7); +a := 99; +b := intToStr(a); +c := rand(10, 1); +info := getProfilerInfo(1); +writeLn(ifArray(info)); +writeLn(length(info) > 0); +``` + +结果说明： + +- 依次输出 `1`、`1` +- 说明 `setProfiler(7)` 可以开启性能分析器统计 +- 说明 `getProfilerInfo(1)` 会直接返回性能分析器信息，而且结果是非空数组 + +### `__line__` 与 `__stack_frame` + +`__line__`： + +代码块身份：可直接照写示例 + +```tsl +a := __line__; +writeLn(a); +``` + +结果说明： + +- 输出 `3` +- 说明 `__line__` 直接返回所在代码行号 + +`__stack_frame`： + +代码块身份：可直接照写示例 + +```tsl +s := Outer(); +writeLn(toStn(s)); + +function Inner(); +begin + return __stack_frame; +end; +function Outer(); +begin + return Inner(); +end; +``` + +结果说明： + +代码块身份：输出片段 + +```text +array( +(11,"__main__"), +(8,"Outer")) +``` + +- 说明 `__stack_frame` 返回的是调用栈帧数组 +- 在这个最小例子里，可以直接看到调用位置行号和调用者函数名 + +## 禁止项 + +- 不要把 `debugReturn` 当成普通函数 `return` 使用。 +- 不要假设 `goto` 可以跨函数、跨脚本体或跳到单独成行的 `label`。 +- 不要给计时或性能分析器调用补未写入文档参数。 +- 不要把调试客户端副作用写成普通输出事实。 diff --git a/docs/tsl/syntax/15_ts_sql.md b/docs/tsl/syntax/15_ts_sql.md deleted file mode 100644 index de495124..00000000 --- a/docs/tsl/syntax/15_ts_sql.md +++ /dev/null @@ -1,135 +0,0 @@ -# TS-SQL - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：否 -遇到不确定时跳转到：[28_ts_sql_core.md](28_ts_sql_core.md)、[29_ts_sql_advanced.md](29_ts_sql_advanced.md)、[14_resultset_and_filters.md](14_resultset_and_filters.md) - -手册位置：第 15 篇，共 32 篇。上一篇：[14_resultset_and_filters.md](14_resultset_and_filters.md)。下一篇：[16_debug_and_profiler.md](16_debug_and_profiler.md)。 - -这一篇不再只是跳转页。它负责把 TS-SQL 放回整个语言阅读主线里：先知道它是什么、最短骨架怎么写、什么时候继续进入 `28` 和 `29` 两篇专题。 - -## 这一篇解决什么问题 - -回答“第一次进入 TS-SQL 时，应该先记住哪些固定骨架，怎样区分基础查询和高级查询，以及哪些内容属于语法、哪些已经属于业务层数据访问”。 - -## Agent TS-SQL 判断流程 - -1. 先判断是 TS-SQL 总览、核心查询，还是进阶查询。 -2. 第一次落代码优先跳转到 `28_ts_sql_core.md` 的最小 `select ... from ... end` 骨架。 -3. 需要 join、分组上下文或极值引用时再进入 `29_ts_sql_advanced.md`。 -4. 不要把 SQL 数据库语法直接当作 TS-SQL 语法。 -5. 没有已验证代码块时不要发明 TS-SQL 写法。 - -## 必须记住的规则 - -- TS-SQL 是 TSL 自带的类 SQL 查询语法，不是金融业务函数库。 -- 基础查询当前的稳定骨架是：以 `select` / `sselect` / `vselect` / `mselect` 开始，以 `end` 收尾。 -- 在内存二维结果集上，当前稳定字段访问写法是 `["字段名"]`。 -- 在一维数组上做 TS-SQL 时，当前应优先使用 `ThisRow` 和 `ThisRowIndex`。 -- `select` 返回二维结果，`sselect` 返回一维结果，`vselect` 返回单值，`mselect` 返回 `Matrix`。 -- `join`、`ThisGroup`、`RefMaxOf` / `RefMinOf` 这类更深查询，已经进入进阶页，不要和入门骨架混写。 -- 访问金融表、时间序列或业务数据源时，语法和业务语义要分开看；本页只讲语言层查询骨架。 - -## 已验证语法 - -### 最小查询骨架 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1) - ); - R := select * from T end; - WriteLn(Length(R)); -end. -``` - -已验证运行结果： - -- `R` 的长度是 `2` -- 两行依次是 `(1,3)`、`(2,1)` -- 说明 TS-SQL 的最短可靠入口就是“准备结果集，然后 `select ... from T end`” - -代码块身份：已验证输出片段 - -```text -2 -``` - -### 四个查询入口怎样分工 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1), - ("A": 1, "B": 2) - ); - S := sselect ["A"] from T end; - V := vselect sumof(["B"]) from T end; - M := mselect * from T end; - C := MCols(M, 1); -end. -``` - -已验证运行结果： - -- `sselect ["A"] from T end` 返回一维数组 `array(1, 2, 1)` -- `vselect sumof(["B"]) from T end` 返回单值 `6` -- `mselect * from T end` 的行数是 `3`、列数是 `2` -- `MCols(M, 1)` 返回列索引 `array("A", "B")` - -### 什么时候进入进阶页 - -当查询开始出现多表字段、联接条件或组内子查询时，就不要继续停留在本页： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - A := array( - ("ID": 1, "V1": 10), - ("ID": 2, "V1": 20) - ); - B := array( - ("ID": 1, "V2": 100), - ("ID": 3, "V2": 300) - ); - R := select [1].["ID"], [1].["V1"], [2].["V2"] - from A join B on [1].["ID"] = [2].["ID"] - end; -end. -``` - -已验证运行结果： - -- `R` 的长度是 `1` -- 唯一一行是 `(1,10,100)` -- 说明一旦开始写 `[1].["字段"]`、`join`、`on` 这类结构，就已经进入 [29_ts_sql_advanced.md](29_ts_sql_advanced.md) 的责任范围 - -## 暂不在本页展开的部分 - -- `with on` -- `insert` / `update` / `delete` -- 面向 SQL 表或业务表的数据写回 -- 时间序列查询选项 -- 更深的缓存、对象化接口和写回类 - -这些内容不是不能写，而是应先去对应专题页或业务文档，不要在这篇入门页提前固化成默认模板。 - -## 跳转指引 - -- 如果你其实要先做结果集过滤：去 [14_resultset_and_filters.md](14_resultset_and_filters.md) -- 如果你刚开始写 TS-SQL：先去 [28_ts_sql_core.md](28_ts_sql_core.md) -- 如果你已经需要 `join` / `ThisGroup` / `RefMaxOf`：去 [29_ts_sql_advanced.md](29_ts_sql_advanced.md) -- 如果你其实是在做业务查询任务：去 [../finance/index.md](../finance/index.md) diff --git a/docs/tsl/syntax/16_debug_and_profiler.md b/docs/tsl/syntax/16_debug_and_profiler.md deleted file mode 100644 index 13b6dcf5..00000000 --- a/docs/tsl/syntax/16_debug_and_profiler.md +++ /dev/null @@ -1,285 +0,0 @@ -# Debug And Profiler - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[08_control_flow.md](08_control_flow.md)、[30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 16 篇，共 32 篇。上一篇：[15_ts_sql.md](15_ts_sql.md)。下一篇：[18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md)。 - -这一篇收拢当前已经验证过的调试、计时、profiler 和调用栈相关入口。 - -## 这一篇解决什么问题 - -回答“`goto`、`DebugReturn`、`DebugRunEnv`、`MTIC` / `MTOC`、`SetProfiler`、`__line__` 和 `__stack_frame` 在当前解释器里怎样写、会怎样表现”。 - -## Agent 调试/Profiler 判断流程 - -1. 先判断任务需要跳转、提前返回、运行环境调试、计时还是 profiler。 -2. 普通控制流优先回到 `08_control_flow.md`，本页只处理调试补充工具。 -3. `DebugReturn` 会结束整段脚本，不能当成普通函数返回。 -4. 计时和 profiler 只照已验证最小调用写，不要补未验证参数。 -5. 没有已验证代码块时不要发明调试/Profiler 写法。 - -## 必须记住的规则 - -- `goto label_name;` 当前已验证可用，但目标位置当前以 `label label_name; statement` 这种内联形式最稳。 -- 当前正向验证只覆盖“跳到同一函数 / 同一脚本体后面的位置”，不要先把更复杂的跨层跳转边界写成事实。 -- `DebugReturn value;` 在当前解释器里会直接结束整段脚本，后面的语句不会继续执行。 -- `DebugRunEnv(0)` 和 `DebugRunEnv(1)` 当前都可直接调用；它们面向调试客户端的副作用，在 CLI 里不直接可见。 -- `DebugRunEnvDo Func(...)` 当前已验证可直接写，并且会返回被调用函数的结果。 -- `MTIC` 会生成一个计时起点；`MTOC` 和 `MTOC(tick)` 当前都会返回秒数。 -- `SetProfiler(7)` 配合 `GetProfilerInfo(1)`，当前可以在不弹窗的情况下拿到 profiler 信息。 -- `__line__` 当前会返回所在代码行号。 -- `__stack_frame` 当前会返回调用栈帧数组；最小 `ToSTN(...)` 观察结果里，每一项是 `(line, "function")` 这一类二元组。 - -## 已验证语法 - -### `goto` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - data := array((1, 2), (3, 4)); - target := 3; - found := 0; - for i := 0 to Length(data) - 1 do - begin - for j := 0 to Length(data[i]) - 1 do - begin - if data[i][j] = target then - goto found_label; - end; - end; - WriteLn(0); - goto done_label; - label found_label; found := 1; - WriteLn(found); - label done_label; WriteLn(9); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`9` -- 说明 `goto found_label;` 当前可以跳到后面的 `label found_label; ...` -- 也说明当前最稳的目标写法是把 `label` 和第一条目标语句放在同一行 - -跨函数跳转当前没有通过： - -代码块身份：反例 / 不可照写 - -```text -program test; -function Inner(); -begin - goto out_label; -end; -begin - Inner(); - label out_label; WriteLn(1); -end. -``` - -已验证结果： - -- 上面这段会运行报错，核心信息是 `Goto label can not found!` -- 当前正向验证只覆盖“同一函数 / 同一脚本体后面的位置” -- 不要把 `goto` 泛化成能跨函数跳到外层 `label` - -目标 `label` 单独成行当前也没有通过： - -代码块身份：反例 / 不可照写 - -```text -program test; -begin - goto done_label; - label done_label; - WriteLn("after"); -end. -``` - -已验证结果： - -- 上面这种把 `label` 单独放一行、下一行再写目标语句的最小例子，在当前解释器里会报 `Statement missing terminator` -- 因此当前手册只把 `label name; statement` 这种内联形式写成已验证事实 - -### `DEBUGRETURN` - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Inner(bb); -begin - DebugReturn bb; -end; -begin - WriteLn("before"); - a := Inner(3); - WriteLn("after"); -end. -``` - -已验证运行结果： - -- 只输出 `before` -- 说明 `DebugReturn bb;` 不只是结束 `Inner(...)`，而是直接让整段脚本提前返回 -- 因此 `Inner(3)` 后面的 `WriteLn("after")` 当前不会执行 - -### `DebugRunEnv` 与 `DebugRunEnvDo` - -`DebugRunEnv(0)` / `DebugRunEnv(1)`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a := 1; - DebugRunEnv(0); - DebugRunEnv(1); - WriteLn(1); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明这两个调用在当前 CLI 环境里至少能正常执行，不会中断后续语句 -- 但它们把变量 / 系统参数送到调试窗口的效果，在 CLI 中不能直接观察到 - -`DebugRunEnvDo Func(...)`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Demo(x); -begin - y := x + 1; - return y; -end; -begin - r := DebugRunEnvDo Demo(2); - WriteLn(r); -end. -``` - -已验证运行结果： - -- 输出 `3` -- 说明 `DebugRunEnvDo Demo(2)` 当前可以直接写 -- 也说明它当前会把被调用函数的结果继续返回给外层 - -### `MTIC` 与 `MTOC` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - t1 := MTIC; - s := 0; - for i := 0 to 9999 do - s := s + i; - te1 := MTOC(t1); - t2 := MTIC; - for j := 0 to 9999 do - s := s + j; - te2 := MTOC; - WriteLn(te1 >= 0); - WriteLn(te2 >= 0); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1` -- 说明 `MTOC(t1)` 和无参 `MTOC` 当前都能返回可用的秒数结果 - -### `SetProfiler` 与 `GetProfilerInfo` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - SetProfiler(7); - a := 99; - b := IntToStr(a); - c := rand(10, 1); - info := GetProfilerInfo(1); - WriteLn(IfArray(info)); - WriteLn(Length(info) > 0); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1` -- 说明 `SetProfiler(7)` 当前可以开启 profiler 统计 -- 说明 `GetProfilerInfo(1)` 当前会直接返回 profiler 信息，而且结果是非空数组 - -### `__line__` 与 `__stack_frame` - -`__line__`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a := __line__; - WriteLn(a); -end. -``` - -已验证运行结果： - -- 输出 `3` -- 说明 `__line__` 当前直接返回所在代码行号 - -`__stack_frame`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Inner(); -begin - return __stack_frame; -end; -function Outer(); -begin - return Inner(); -end; -begin - s := Outer(); - WriteLn(ToSTN(s)); -end. -``` - -已验证运行结果： - -代码块身份：已验证输出片段 - -```text -array( -(11,"__main__"), -(8,"Outer")) -``` - -- 说明 `__stack_frame` 当前返回的是调用栈帧数组 -- 在这个最小例子里，可以直接看到调用位置行号和调用者函数名 - -## 跳转指引 - -- 回看主线流程控制：见 [08_control_flow.md](08_control_flow.md) -- 运行时环境参数：见 [11_runtime_context_and_with.md](11_runtime_context_and_with.md) -- 回看语法主入口：见 [index.md](index.md) -- 看运行时服务和全局缓存：见 [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) diff --git a/docs/tsl/syntax/16_lexical_structure_and_compile_options.md b/docs/tsl/syntax/16_lexical_structure_and_compile_options.md new file mode 100644 index 00000000..5981e617 --- /dev/null +++ b/docs/tsl/syntax/16_lexical_structure_and_compile_options.md @@ -0,0 +1,219 @@ +# TSL 词法结构与编译选项 + +文档类型：语法深水专题 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[17_types_and_conversions.md](17_types_and_conversions.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇吸收语法手册里“词法层”和“编译期开关”相关内容：标识符、注释、条件编译和依赖编译选项。 + +## 本篇职责 + +回答“TSL 的词法层规则和编译期开关应该去哪里查，而不是把这些边界混进值、函数、类的正文里”。 + +## 智能体词法/编译选项判断流程 + +1. 先判断要写注释、标识符、条件编译，还是编译选项。 +2. 注释、大小写、条件编译指令只照本页文档明确形态写。 +3. `{$explicit+}` 会改变变量声明要求，生成代码前先判断是否需要 `var`。 +4. `{$varByRef+}` / `{$varByRef-}` 会影响未修饰形参传递语义，细节回看函数页。 +5. 没有对应代码块时不要发明词法/编译选项写法。 + +## 核心规则 + +- 标识符大小写无关；下划线可出现在标识符中。 +- `//` 是行注释；首行 `#!` 可作为 CGI 风格注释；`{ ... }` 与 `(* ... *)` 是块注释。 +- 条件编译指令使用 `{$define}`、`{$undef}`、`{$ifdef}`、`{$ifndef}`、`{$else}`、`{$endif}`。 +- 条件编译只编译命中的分支；未命中的分支不参与脚本编译。 +- `{$explicit+}` 开启后，后续变量必须先用 `var` 声明；`{$explicit-}` 可以在同一源文件里重新关闭这个要求。 +- `{$varByRef-}` 与 `{$varByRef+}` 会切换“未修饰形参”的默认传递方式，细节见 [05_functions_and_calls.md](05_functions_and_calls.md)。 +- `{$i}` / `{$include}` 不作为本页可生成的默认能力。 +- `{$dependency ...}` 这类编辑器辅助编译选项不作为本页正文事实。 + +## 可直接照写示例 + +### 标识符、注释与条件编译 + +大小写无关与下划线标识符： + +代码块身份：可直接照写示例 + +```tsl +my_var := 7; +writeLn(my_var); +writeLn(MY_VAR); +``` + +结果说明： + +- 依次输出 `7`、`7` +- 说明标识符大小写无关，下划线可以出现在标识符中 + +代码块身份：输出片段 + +```text +7 +7 +``` + +注释与条件编译： + +代码块身份：可直接照写示例 + +```tsl +#! shebang style comment + +a := 1; // line comment +{ + (* nested comment marker *) +} +writeLn(a); +{$define FLAG} +{$ifdef FLAG} +writeLn(10); +{$else} +writeLn(20); +{$endif} +{$undef FLAG} +{$ifndef FLAG} +writeLn(30); +{$else} +writeLn(40); +{$endif} +``` + +结果说明： + +- 依次输出 `1`、`10`、`30` +- 说明首行 `#!`、`//`、`{ ... }`、`(* ... *)` 都属于文档明确注释形态 +- 说明 `define` / `undef` / `ifdef` / `ifndef` / `else` / `endif` 这一组条件编译指令可以正常生效 + +### 显式变量声明开关 + +`{$explicit+}` 的文档明确形态： + +代码块身份：可直接照写示例 + +```tsl +{$explicit+} +var a; +a := 1; +writeLn(a); +``` + +结果说明： + +- 输出 `1` +- 说明 `{$explicit+}` 开启后，配合 `var` 声明可以正常通过 + +`{$explicit-}` 可以在同一源文件里关掉显式声明要求： + +代码块身份：可直接照写示例 + +```tsl +{$explicit+} +var a; +a := 1; +{$explicit-} +b := 2; +writeLn(a + b); +``` + +结果说明： + +- 输出 `3` +- 说明 `{$explicit-}` 会从出现位置开始取消“变量必须先声明”的限制 + +### 条件编译分支边界 + +条件编译不会去编译未命中的坏代码分支： + +代码块身份：可直接照写示例 + +```tsl +{$undef NEVER} +{$ifdef NEVER} +MissingFunction( +{$else} +writeLn(1); +{$endif} +``` + +结果说明： + +- 输出 `1` +- 说明未命中的条件编译分支不会参与脚本编译 + +### 参数默认传递开关 + +`{$varByRef-}` 与 `{$varByRef+}`： + +代码块身份：可直接照写示例 + +```tsl +x := 1; +TouchDefault(x); +writeLn(x); +y := 1; +TouchValue(y); +writeLn(y); +z := 1; +TouchForcedVar(z); +writeLn(z); +r := 1; +TouchRestored(r); +writeLn(r); + +function TouchDefault(a); +begin + a := 9; +end; +{$varByRef-} +function TouchValue(a); +begin + a := 8; +end; +function TouchForcedVar(var a); +begin + a := 7; +end; +{$varByRef+} +function TouchRestored(a); +begin + a := 6; +end; +``` + +结果说明： + +- 依次输出 `9`、`1`、`7`、`6` +- 说明默认模式下，未修饰参数仍会写回调用方 +- 说明 `{$varByRef-}` 下，未修饰参数会改成按值传递 +- 说明 `var` 形参在 `{$varByRef-}` 下仍保持引用语义 +- 也说明 `{$varByRef+}` 可以把默认语义重新切回可写回模式 + +## 禁止项 + +- 不要在 `{$explicit+}` 后继续直接使用未声明变量。 +- 不要把 `{$i ...}` / `{$include ...}` 包含文件写法当成可用能力。 +- 不要把 `反例 / 不可照写` 代码块复制进正向示例。 + +代码块身份：反例 / 不可照写 + +```text +{$explicit+} +a := 1; +``` + +上面这种写法不作为可写事实；`{$explicit+}` 后必须先声明再使用变量。 + +代码块身份：反例 / 不可照写 + +```text +writeLn(1); + +{$i "common.inc"} +``` + +上面这种包含文件写法不作为本页可生成的默认能力。 diff --git a/docs/tsl/syntax/17_types_and_conversions.md b/docs/tsl/syntax/17_types_and_conversions.md new file mode 100644 index 00000000..558fd6e9 --- /dev/null +++ b/docs/tsl/syntax/17_types_and_conversions.md @@ -0,0 +1,332 @@ +# TSL 类型与转换 + +文档类型：语法深水专题 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[04_variables_and_constants.md](04_variables_and_constants.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇吸收语言基础里“数据类型、初始值、弱类型行为、类型转换、复数类型”这一层。 + +## 本篇职责 + +回答“当问题不再是怎么声明变量或书写普通字面量，而是运行时值会变成什么类型、默认值是什么、怎样显式转换、复数怎样表示时，应该看哪里”。`var` / `const` 声明选择回看 [04_variables_and_constants.md](04_variables_and_constants.md)，编译期开关回看 [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)。 + +## 智能体类型/转换判断流程 + +1. 先判断要写数值字面量、日期时间、真假值、nil、复数，还是类型转换边界。 +2. 整数、实数、日期时间、特殊实数和复数只照本页文档字面量写。 +3. 不要把能编译的混合类型表达式误判为能按预期自动转换。 +4. 遇到 `var` / `const` 声明选择跳转到 [04_variables_and_constants.md](04_variables_and_constants.md)，遇到 `{$explicit+}` / `{$explicit-}` 等编译选项跳转到 [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)。 +5. 遇到字符串字面量、编码或文本边界跳转到 [03_values_and_literals.md](03_values_and_literals.md)。 +6. 没有对应代码块时不要发明类型/转换写法。 + +## 核心规则 + +- 整数常量支持十进制、`0x` 十六进制、`0b` 二进制和 `0o` 八进制。 +- `100L` 这类后缀写法表示 `Int64` 常量。 +- 超过 32 位整数范围的十进制整数字面量 `2147483648` 按 `Int64`，不按实数处理。 +- 实数写法包括 `1.5`、`1.0E2`、`1E2`；其中 `1E2` 按实数，不按整数处理。 +- 日期时间字面量可写成 `20111231T`、`20101231.0931T`。 +- `true` 和 `false` 可以直接使用；打印结果分别是 `1` 和 `0`。 +- 条件判断里，`0` 按假值处理，非 `0` 数值按真值处理。 +- `inf` 和 `nan` 是特殊实数常量；`ifReal(inf)`、`ifReal(nan)` 都返回 `1`。 +- `inf > 1000` 为真，`nan = nan` 为假。 +- 未初始化的普通变量会得到整数 `0`。 +- 新建对象的普通成员变量默认值是 `nil`。 +- 对空数组读取一个尚未赋值的下标时，结果是 `nil`。 +- `ifNil(nil)` 可用于显式空值判定。 +- 空字符串、空数组和 `nil` 都按假值处理。 +- `nil` 可以参与加法；`nil + 1` 和 `1 + nil` 都返回 `1`，`nil + nil` 仍然是 `nil`。 +- `ifNumber(...)` 会把整数、`Int64`、实数都视为数值；普通字符串不算数值。 +- TSL 不是“完全禁止混合类型表达式”；像 `b + a` 这种“整数 + 字符串”会通过编译，但在运行时会报 `operand type error`。 +- 因此，类型转换要显式写出来，例如 `strToInt(...)`，不要把运行时失败留给解释器。 +- 复数字面量可以直接写成 `a + bj`，也可以用 `complex(a, b)` 构造。 +- `dataType(z)` 对复数返回 `41`，`ifComplex(z)` 对复数返回 `1`。 +- `real`、`imag`、`conj`、`abs` 都可用于复数。 +- 实数 `x` 与复数 `x + 0j` 的相等比较结果为真。 +- `complex(array(...), imag)` 会返回 `Array`；`complex(fmarray..., imag)` 会返回 `FMArray`，并且其单元格类型是 `41`。 + +## 可直接照写示例 + +### 数值、日期与真值 + +基础数字字面量与类型判定： + +代码块身份：可直接照写示例 + +```tsl +writeLn(ifInt(100)); +writeLn(ifInt(0x10)); +writeLn(ifInt(0b10)); +writeLn(ifInt(0o10)); +writeLn(ifInt64(100L)); +writeLn(ifReal(1.5)); +writeLn(ifReal(1.0E2)); +writeLn(ifInt(1E2)); +writeLn(ifReal(1E2)); +``` + +结果说明： + +- 前七行都输出 `1` +- `ifInt(1E2)` 输出 `0` +- `ifReal(1E2)` 输出 `1` +- 说明 `100`、`0x10`、`0b10`、`0o10` 都按整数处理 +- 说明 `100L` 按 `Int64` 处理 +- 说明 `1E2` 按实数，不按整数处理 + +代码块身份：输出片段 + +```text +1 +0 +1 +``` + +超 32 位整数与日期时间字面量： + +代码块身份：可直接照写示例 + +```tsl +writeLn(ifInt64(2147483648)); +writeLn(ifReal(2147483648)); +d1 := 20111231T; +d2 := 20101231.0931T; +writeLn(dateToStr(d1)); +writeLn(dateToStr(d2)); +writeLn(timeToStr(d2)); +``` + +结果说明： + +- 依次输出 `1`、`0`、`2011-12-31`、`2010-12-31`、`09:31:00` +- 说明 `2147483648` 按 `Int64`，不按实数处理 +- 说明 `20111231T`、`20101231.0931T` 这类日期时间字面量可以直接使用 + +布尔常量、数值真值和特殊实数： + +代码块身份：可直接照写示例 + +```tsl +writeLn(true); +writeLn(false); +if 2 then writeLn(1) else writeLn(0); +if 0 then writeLn(1) else writeLn(0); +if -1 then writeLn(1) else writeLn(0); +writeLn(ifReal(inf)); +writeLn(ifReal(nan)); +writeLn(inf > 1000); +writeLn(nan = nan); +``` + +结果说明： + +- 前两行分别输出 `1`、`0` +- `if 2` 输出 `1`，`if 0` 输出 `0`，`if -1` 输出 `1` +- `ifReal(inf)` 和 `ifReal(nan)` 都输出 `1` +- `inf > 1000` 输出 `1` +- `nan = nan` 输出 `0` +- 说明 `true` / `false` / `inf` / `nan` 属于文档明确常量 +- 说明数值条件判断里，`0` 为假，非 `0` 为真 + +### 初始值与空值 + +变量初始值与缺失值： + +代码块身份：可直接照写示例 + +```tsl +writeLn(a); +h := new Holder(); +writeLn(h.value = nil); +arr := array(); +writeLn(arr[0] = nil); + +type Holder = class +public + value; +end; +``` + +结果说明： + +- 依次输出 `0`、`1`、`1` +- 说明未初始化普通变量默认是整数 `0` +- 说明类成员默认值是 `nil` +- 也说明空数组读取尚未赋值的下标时，结果是 `nil` + +`nil` 的显式判定与加法边界： + +代码块身份：可直接照写示例 + +```tsl +writeLn(ifNil(nil)); +writeLn(nil + 1); +writeLn(1 + nil); +writeLn(nil + nil = nil); +``` + +结果说明： + +- 依次输出 `1`、`1`、`1`、`1` +- 说明 `ifNil(nil)` 是可用的显式空值判定 +- 说明 `nil` 可以直接参与加法 +- 其中 `nil + 1` 和 `1 + nil` 都得到 `1` +- `nil + nil` 仍保持为 `nil` + +空值条件判断： + +代码块身份：可直接照写示例 + +```tsl +if "" then writeLn(0) else writeLn(1); +if array() then writeLn(0) else writeLn(1); +if nil then writeLn(0) else writeLn(1); +``` + +结果说明： + +- 依次输出 `1`、`1`、`1` +- 说明空字符串、空数组和 `nil` 都按假值处理 + +`ifNumber(...)` 的最小边界： + +代码块身份：可直接照写示例 + +```tsl +writeLn(ifNumber(100)); +writeLn(ifNumber(100L)); +writeLn(ifNumber(1.5)); +writeLn(ifNumber("100")); +``` + +结果说明： + +- 依次输出 `1`、`1`、`1`、`0` +- 说明 `ifNumber(...)` 接受整数、`Int64`、实数 +- 也说明普通数字字符串不会被 `ifNumber(...)` 直接当成数值 + +### 显式类型转换 + +显式类型转换的正向例子： + +代码块身份：可直接照写示例 + +```tsl +a := "1234"; +b := 1; +c := b + strToInt(a); +writeLn(c); +``` + +结果说明： + +- 输出 `1235` +- 说明显式转换后，字符串数值与整数可以按预期参与加法 + +### 复数 + +复数常量、类型与基础读取： + +代码块身份：可直接照写示例 + +```tsl +z1 := 4 + 3j; +z2 := complex(5, -2); +writeLn(dataType(z1)); +writeLn(ifComplex(z1)); +writeLn(real(z1)); +writeLn(imag(z1)); +writeLn(z2); +``` + +结果说明： + +- `dataType(4 + 3j)` 返回 `41` +- `ifComplex(4 + 3j)` 返回 `1` +- `real(4 + 3j)` 返回 `4` +- `imag(4 + 3j)` 返回 `3` +- `complex(5, -2)` 打印结果是 `5-2j` + +代码块身份：输出片段 + +```text +41 +1 +4 +3 +``` + +共轭、模与等值比较： + +代码块身份：可直接照写示例 + +```tsl +z := 4 + 3j; +c := conj(z); +writeLn(abs(z)); +writeLn(real(c)); +writeLn(imag(c)); +if 3.15 = 3.15 + 0j then + writeLn(1); +else + writeLn(0); +``` + +结果说明： + +- `abs(4 + 3j)` 返回 `5` +- `conj(4 + 3j)` 的实部是 `4`、虚部是 `-3` +- `3.15 = 3.15 + 0j` 比较结果为真 + +复数 `Array` 与复数 `FMArray`： + +代码块身份：可直接照写示例 + +```tsl +a := complex(array(1, 2, 3), 5.5); +f := complex(fmarray[1, 2, 3], 5.5); +writeLn(dataType(a)); +writeLn(length(a)); +writeLn(a[0], ',', a[1], ',', a[2]); +writeLn(dataType(f)); +writeLn(dataType(f, 1)); +writeLn(length(f)); +writeLn(f[0], ',', f[1], ',', f[2]); +``` + +结果说明： + +- `complex(array(1, 2, 3), 5.5)` 的 `dataType` 是 `5` +- 上述复数数组长度是 `3`，三个元素依次是 `1+5.5j`、`2+5.5j`、`3+5.5j` +- `complex(fmarray[1, 2, 3], 5.5)` 的 `dataType` 是 `27` +- 上述复数 `FMArray` 的单元格类型 `dataType(f, 1)` 是 `41` +- 该 `FMArray` 长度是 `3`，三个元素依次是 `1+5.5j`、`2+5.5j`、`3+5.5j` + +复数最短骨架： + +代码块身份：可直接照写示例 + +```tsl +z := 4 + 3j; +writeLn(real(z)); +writeLn(imag(z)); +``` + +## 禁止项 + +- 不要把“能编译”误解成“会自动按期望类型转换”。 +- 不要把数字字符串直接当成数值参与算术；需要数值语义时先显式转换。 +- 不要从其他语言的 truthy/falsy 或隐式转换规则反推 TSL。 +- 不要把复数统计函数、分解函数与更大函数族当成本页文档能力。 + +代码块身份：反例 / 不可照写 + +```text +a := "1234"; +b := 1; +writeLn(b + a); +``` + +上面这种写法不作为可写事实。它可能通过编译，但运行时会报 `Addition instruction error, operand type error`；不要把“能编译”误解成“会自动按你期望的类型转换”。 diff --git a/docs/tsl/syntax/18_external_calls_and_threads.md b/docs/tsl/syntax/18_external_calls_and_threads.md new file mode 100644 index 00000000..c42ea820 --- /dev/null +++ b/docs/tsl/syntax/18_external_calls_and_threads.md @@ -0,0 +1,257 @@ +# TSL 外部调用与线程 + +文档类型：语法深水专题 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇吸收函数专题里和外部系统交互有关的部分：`external`、动态库调用、原生函数指针包装、C 回调和线程调用。 + +## 本篇职责 + +回答“普通函数怎么写已经清楚后，外部 DLL、原生函数指针、C 回调、多线程这些系统交互能力应该去哪里查”。 + +## 智能体外部调用/线程判断流程 + +1. 先判断要声明外部函数、包装原生函数指针、生成 C 回调，还是处理线程相关能力。 +2. 外部函数声明只照本页明确的调用约定、`external` 和可选 `name` 形态写。 +3. DLL 名优先写字面量或文档中的类常量，不要拼接表达式。 +4. 原生函数指针包装、C 回调和线程相关能力只照本页文档边界写。 +5. 没有对应代码块时不要发明外部调用/线程写法。 + +## 核心规则 + +- 外部函数声明的文档明确形态是 `function Name(...): Type; stdcall|cdecl; external "dll" [name "symbol"];`。 +- 当 TSL 函数名和 DLL 导出名一致时，`name "symbol"` 可以省略。 +- Windows 示例默认显式写调用约定；不要把省略调用约定当成跨平台默认规则。 +- 无返回值的外部接口可声明为 `procedure Name(...); ... external ...;`。 +- `function(...): ...; external fp;` 可以把原生函数指针重新包装成 TSL 可调用对象。 +- DLL 名写法包括字面量字符串和类常量字符串；不要把字符串拼接表达式直接当成稳定写法。 +- `makeInstance(thisFunction(Func), "cdecl", 0)` 可以把 TSL 函数包装成 C 调用约定函数指针。 +- Windows 线程示例用 `makeInstance(..., "cdecl", 1)` 生成可交给 `CreateThread` 的回调指针。 +- 外部库名和调用约定要按目标平台选择；不要把 Windows 的 `kernel32.dll` 示例直接复制到 Linux，或把 Linux 的 `.so` 示例直接复制到 Windows。 +- 本页线程示例是 Windows 专题，用到了 `kernel32.dll`。 + +## 可直接照写示例 + +### 最小 `external` 声明 + +代码块身份：可直接照写示例 + +```tsl +writeLn(Tick64Alias() > 0); + +function Tick64Alias(): int64; stdcall; external "kernel32.dll" name "GetTickCount64"; +``` + +结果说明： + +- 输出 `1` +- 说明 `stdcall` + `external "dll" name "symbol"` 是本页明确的外部函数声明骨架 +- 也说明 TSL 里的函数名可以和 DLL 导出名不同，再通过 `name "ExportName"` 绑定 + +代码块身份：输出片段 + +```text +1 +``` + +Linux / POSIX 环境的同类最小骨架： + +代码块身份：可直接照写示例 + +```tsl +writeLn(getpid() > 0); + +function getpid(): integer; cdecl; external "libc.so.6"; +``` + +代码块身份：输出片段 + +```text +1 +``` + +这段说明 Linux / POSIX 目标下可以用 `.so` 库名声明外部函数；生成代码时仍要先判断用户的目标平台。 + +当本地函数名和 DLL 导出名一致时，`name` 可以省略： + +代码块身份：可直接照写示例 + +```tsl +writeLn(GetTickCount64() > 0); + +function GetTickCount64(): int64; stdcall; external "kernel32.dll"; +``` + +结果说明： + +- 输出 `1` +- 说明当本地函数名和导出名一致时，`name "symbol"` 不是强制写法 + +Windows 的同一 API 示例里，省略调用约定与显式 `cdecl` 也列入文档边界： + +代码块身份：可直接照写示例 + +```tsl +writeLn(TickNoConv() > 0); +writeLn(TickCdecl() > 0); + +function TickNoConv(): int64; external "kernel32.dll" name "GetTickCount64"; +function TickCdecl(): int64; cdecl; external "kernel32.dll" name "GetTickCount64"; +``` + +结果说明： + +- 依次输出 `1`、`1` +- 这只说明 Windows 的同一 API 示例里，这两种写法属于文档边界 +- 不要把这个结果直接泛化成“所有平台、所有架构下调用约定都等价” + +### `procedure external` + +代码块身份：可直接照写示例 + +```tsl +t1 := Tick64(); +SleepMs(20); +t2 := Tick64(); +writeLn(t2 >= t1); + +function Tick64(): int64; stdcall; external "kernel32.dll" name "GetTickCount64"; +procedure SleepMs(ms: integer); stdcall; external "kernel32.dll" name "Sleep"; +``` + +结果说明： + +- 输出 `1` +- 说明无返回值的外部过程可以直接声明为 `procedure` + +### 原生函数指针包装 + +代码块身份：可直接照写示例 + +```tsl +h := LoadLibraryA("kernel32.dll"); +fp := GetProcAddress(h, "GetTickCount64"); +f := function(): int64; stdcall; external fp; +writeLn(h <> nil); +writeLn(fp <> nil); +writeLn(##f() > 0); + +function LoadLibraryA(s: string): pointer; stdcall; external "kernel32.dll" name "LoadLibraryA"; +function GetProcAddress(hModule: pointer; lpProcName: string): pointer; stdcall; external "kernel32.dll" name "GetProcAddress"; +``` + +结果说明： + +- 依次输出 `1`、`1`、`1` +- 说明 `function(...); ... external fp;` 不只适用于 `makeInstance(...)` 的结果，也适用于 `GetProcAddress(...)` 返回的原生函数指针 + +### DLL 名的文档边界 + +类常量字符串： + +代码块身份：可直接照写示例 + +```tsl +d := new Demo(); +writeLn(d.Run()); + +type Demo = class +public + const kernel_dll = "kernel32.dll"; + function Run(); + begin + return TickConst() > 0; + end; + function TickConst(): int64; stdcall; external kernel_dll name "GetTickCount64"; +end; +``` + +结果说明： + +- 输出 `1` +- 说明类常量字符串可以用于 `external kernel_dll` 这种 DLL 名位置 + +不作为可写事实边界： + +代码块身份：反例 / 不可照写 + +```text +function TickFromExpr(): int64; stdcall; external "kernel32"$"."$"dll" name "GetTickCount64"; +``` + +上面这种 DLL 名字符串拼接表达式不作为可写事实，会报 `dll filename const string not found after external`。本页只把字面量字符串和类常量字符串写成可靠规则。 + +### `makeInstance` + +代码块身份：可直接照写示例 + +```tsl +fp := makeInstance(thisFunction(Add), "cdecl", 0); +f := function(a: integer; b: integer): integer; external fp; +writeLn(fp <> nil); +writeLn(##f(3, 4)); + +function Add(a: integer; b: integer): integer; +begin + return a + b; +end; +``` + +结果说明： + +- `fp <> nil` 输出 `1` +- `##f(3, 4)` 输出 `7` +- 说明 `makeInstance(...)` 生成的函数指针可以再通过 `function(...); external fp;` 包装回 TSL 侧调用 + +### 线程模式最小正例 + +代码块身份：可直接照写示例 + +```tsl +setGlobalCache("THREAD_TEST_KEY", 0); +fp := makeInstance(thisFunction(Worker), "cdecl", 1); +h := CreateThread(nil, nil, fp, nil, 0, tid); +writeLn(fp <> nil); +writeLn(h <> nil); +writeLn(WaitForSingleObject(h, 5000) >= 0); +getGlobalCache("THREAD_TEST_KEY", v); +writeLn(v); +CloseHandle(h); + +function CreateThread(attr: pointer; size: pointer; addr: pointer; p: pointer; flag: Integer; var thread_id: Integer): pointer; stdcall; external "kernel32.dll" name "CreateThread"; +function WaitForSingleObject(h: pointer; timeout: Integer): Integer; stdcall; external "kernel32.dll" name "WaitForSingleObject"; +function CloseHandle(h: pointer): Integer; stdcall; external "kernel32.dll" name "CloseHandle"; +function Worker(p: pointer): integer; +begin + setGlobalCache("THREAD_TEST_KEY", 1); + return 1; +end; +``` + +结果说明： + +- 依次输出 `1`、`1`、`1`、`1` +- 说明 `makeInstance(..., "cdecl", 1)` 可以生成可用于 `CreateThread` 的回调指针 +- 也说明线程体里的 `setGlobalCache(...)` 可用于这个最小闭环 + +## 默认生成模板 + +DLL 引入的最小默认骨架如下： + +代码块身份：可直接照写示例 + +```tsl +writeLn(Tick64Alias() > 0); + +function Tick64Alias(): int64; stdcall; external "kernel32.dll" name "GetTickCount64"; +``` + +## 禁止项 + +- 把 `external` 的 DLL 名直接写成字符串拼接表达式。 +- 省略了外部函数的参数类型或返回类型。 +- 把 `makeInstance(...)` 生成的结果默认写成普通函数名直调，而不是先包装或用 `##f(...)`。 +- 直接把 Windows 线程示例当成跨平台事实。 diff --git a/docs/tsl/syntax/18_lexical_structure_and_compile_options.md b/docs/tsl/syntax/18_lexical_structure_and_compile_options.md deleted file mode 100644 index ffd4f78a..00000000 --- a/docs/tsl/syntax/18_lexical_structure_and_compile_options.md +++ /dev/null @@ -1,250 +0,0 @@ -# Lexical Structure And Compile Options - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[19_types_and_conversions.md](19_types_and_conversions.md)、[12_pitfalls.md](12_pitfalls.md)、[01_introduction.md](01_introduction.md) - -手册位置：第 18 篇，共 32 篇。上一篇：[16_debug_and_profiler.md](16_debug_and_profiler.md)。下一篇：[19_types_and_conversions.md](19_types_and_conversions.md)。 - -这一篇吸收语法手册里“词法层”和“编译期开关”相关内容：保留字、标识符、注释、条件编译、文件包含、依赖编译选项。 - -## 这一篇解决什么问题 - -回答“TSL 的词法层规则和编译期开关应该去哪里查，而不是把这些边界混进值、函数、类的正文里”。 - -## Agent 词法/编译选项判断流程 - -1. 先判断要写注释、标识符、条件编译，还是编译选项。 -2. 注释、大小写、条件编译指令只照本页已验证形态写。 -3. `{$Explicit+}` 会改变变量声明要求，生成代码前先判断是否需要 `var`。 -4. `{$VarByRef+}` / `{$VarByRef-}` 会影响未修饰形参传递语义，细节回看函数页。 -5. 没有已验证代码块时不要发明词法/编译选项写法。 - -## 必须记住的规则 - -- 标识符大小写无关；当前最小运行验证里，下划线也可以出现在标识符中。 -- 当前解释器接受 `//` 行注释、首行 `#!` CGI 风格注释、`{ ... }` 块注释，以及 `(* ... *)` 块注释。 -- 当前解释器接受 `{$DEFINE}`、`{$UNDEF}`、`{$IFDEF}`、`{$IFNDEF}`、`{$ELSE}`、`{$ENDIF}` 这组条件编译指令。 -- 条件编译当前已验证只会编译命中的分支；未命中的分支里即使放坏代码，也不会阻止脚本通过。 -- 当前解释器接受 `{$Explicit+}`；一旦开启，后续变量必须先用 `var` 声明，否则会报 `variable not defined`。 -- 当前解释器也接受 `{$Explicit-}`；它可以在同一源文件里把“先声明后使用”的要求重新关掉。 -- 当前解释器接受 `{$VarByRef-}` 与 `{$VarByRef+}`；它们会切换“未修饰形参”的默认传递方式，细节见 [06_functions_and_calls.md](06_functions_and_calls.md)。 -- 当前命令行解释器里，`{$I}` / `{$INCLUDE}` 的最小相对路径和绝对路径样例都没有跑通；错误信息是 `include file ... not found or include feature not implemented`。 -- `{$dependency ...}` 这类编辑器辅助编译选项，本轮还没有拿到正向最小验证，不先写成正文事实。 - -## 已验证语法 - -大小写无关与下划线标识符： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - My_Var := 7; - WriteLn(my_var); - WriteLn(MY_VAR); -end. -``` - -已验证运行结果： - -- 依次输出 `7`、`7` -- 说明当前解释器下标识符大小写无关 -- 也说明下划线可以出现在标识符中 - -代码块身份：已验证输出片段 - -```text -7 -7 -``` - -注释与条件编译： - -代码块身份：已验证可执行示例 - -```tsl -#! shebang style comment -program test; -begin - a := 1; // line comment - { - (* nested comment marker *) - } - WriteLn(a); -{$DEFINE FLAG} -{$IFDEF FLAG} - WriteLn(10); -{$ELSE} - WriteLn(20); -{$ENDIF} -{$UNDEF FLAG} -{$IFNDEF FLAG} - WriteLn(30); -{$ELSE} - WriteLn(40); -{$ENDIF} -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`10`、`30` -- 说明首行 `#!`、`//`、`{ ... }`、`(* ... *)` 在当前解释器里都能通过 -- 也说明 `DEFINE` / `UNDEF` / `IFDEF` / `IFNDEF` / `ELSE` / `ENDIF` 这一组条件编译指令在当前解释器里可以正常生效 - -`{$Explicit+}` 的正向最小例子： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin -{$Explicit+} - var a; - a := 1; - WriteLn(a); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明 `{$Explicit+}` 开启后，配合 `var` 声明可以正常通过 - -`{$Explicit-}` 可以在同一源文件里关掉显式声明要求： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin -{$Explicit+} - var a; - a := 1; -{$Explicit-} - b := 2; - WriteLn(a + b); -end. -``` - -已验证运行结果： - -- 输出 `3` -- 说明 `{$Explicit-}` 会从出现位置开始取消“变量必须先声明”的限制 - -条件编译不会去编译未命中的坏代码分支： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin -{$UNDEF NEVER} -{$IFDEF NEVER} - { 未命中分支里的坏代码示意见下方反例块 } -{$ELSE} - WriteLn(1); -{$ENDIF} -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明未命中的条件编译分支不会参与当前脚本编译 - -未命中分支里拿来做验证的坏代码外形： - -代码块身份：反例 / 不可照写 - -```text -this is bad code -``` - -上面这类内容只用于说明“坏代码”长什么样，不要直接写进正向示例块。 - -`{$VarByRef-}` 与 `{$VarByRef+}`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function TouchDefault(a); -begin - a := 9; -end; -{$VarByRef-} -function TouchValue(a); -begin - a := 8; -end; -function TouchForcedVar(var a); -begin - a := 7; -end; -{$VarByRef+} -function TouchRestored(a); -begin - a := 6; -end; -begin - x := 1; - TouchDefault(x); - WriteLn(x); - y := 1; - TouchValue(y); - WriteLn(y); - z := 1; - TouchForcedVar(z); - WriteLn(z); - r := 1; - TouchRestored(r); - WriteLn(r); -end. -``` - -已验证运行结果： - -- 依次输出 `9`、`1`、`7`、`6` -- 说明默认模式下，未修饰参数仍会写回调用方 -- 说明 `{$VarByRef-}` 下，未修饰参数会改成按值传递 -- 说明 `var` 形参在 `{$VarByRef-}` 下仍保持引用语义 -- 也说明 `{$VarByRef+}` 可以把默认语义重新切回可写回模式 - -## 当前已验证的反向边界 - -代码块身份：反例 / 不可照写 - -```text -program test; -begin -{$Explicit+} - a := 1; -end. -``` - -上面这段最小样例已实测编译失败，报错主因是 `variable not defined`。 - -代码块身份：反例 / 不可照写 - -```text -program test; -{$I "common.inc"} -begin - WriteLn(1); -end. -``` - -无论把 `common.inc` 写成相对路径还是绝对路径，当前命令行解释器都没有跑通，错误信息都是 `include file ... not found or include feature not implemented`。 - -## 跳转指引 - -- 回看文件模型与顶层主体：见 [03_core_model.md](03_core_model.md) -- 回看值、字面量与字符串：见 [04_values_and_literals.md](04_values_and_literals.md) -- 回看变量、常量与显式声明：见 [05_variables_and_constants.md](05_variables_and_constants.md) -- 看类型与转换：见 [19_types_and_conversions.md](19_types_and_conversions.md) -- 看字符串与编码：见 [20_strings_and_text.md](20_strings_and_text.md) diff --git a/docs/tsl/syntax/19_namespace_libpath_and_unit_runtime.md b/docs/tsl/syntax/19_namespace_libpath_and_unit_runtime.md new file mode 100644 index 00000000..97ec18d2 --- /dev/null +++ b/docs/tsl/syntax/19_namespace_libpath_and_unit_runtime.md @@ -0,0 +1,478 @@ +# TSL 命名空间、Libpath 与 unit 运行时 + +文档类型：语法深水专题 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[09_units_and_scope.md](09_units_and_scope.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇收拢 `unit` 的运行时行为，以及 `.tsf` / `namespace` / `libpath` 的查找规则。`unit` 的基础写法、`uses` 位置和重名解析，统一放在 [09_units_and_scope.md](09_units_and_scope.md)。 + +## 本篇职责 + +回答下面这些“写法已经会了，但运行起来为什么这样”的问题： + +- `unit` 什么时候进入 `initialization` +- `finalization` 在什么时候触发 +- `unit` 里的常量、变量和 `findFunction("UnitName")` 到底暴露哪些成员 +- `tslfilename()` 返回什么 +- `namespace "..."`、`tsl.conf` 和 `-LIBPATH` 怎样影响 `.tsf` 查找 +- `syssettsllibpath()` / `sysgettsllibpath()` 怎样在运行时改查找路径 + +## 智能体命名空间/Libpath 判断流程 + +1. 先判断任务是单元命名空间访问、`-LIBPATH` 查找，还是配置文件查找。 +2. 路径和查找顺序只写平台中立规则，不写某个开发机或容器路径。 +3. `-LIBPATH` 只作为运行时部署/查找规则，不写进普通语法示例。 +4. `Libpath={$P}...` 和 `InheritParent=1` 不作为本页文档能力。 +5. 没有对应代码块时不要发明命名空间/Libpath 写法。 + +## 核心规则 + +- 完整 `unit` 形态可以包含 `interface`、`implementation`、`initialization`、`finalization`，并以 `end.` 结束。 +- `initialization` 在 `unit` 第一次被实际使用时触发，不是只因为顶层写了 `uses` 就立刻执行。 +- `finalization` 会在脚本结束前触发。 +- 直接写 `DemoUnit.Member` 时，可以读到 `interface` 和 `implementation` 里的常量、变量。 +- `findFunction("DemoUnit")` 拿到的是 `unit` 对象入口；本页只把它稳定暴露 `interface` 成员写成文档事实。 +- `DemoUnit.var_name := value` 这种限定赋值不作为可写事实；如果要改 `unit` 状态，应导出函数或方法来改。 +- `tslfilename()` 的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)；本页只保留它返回正在执行的 `.tsl` 主脚本完整路径这一行为事实。 +- `namespace "DemoNS";` 会选择 `Hello@DemoNS.tsf` 这类命名空间函数文件。 +- `tsl.conf` 的 `[system] Namespace=...` 可以设置默认命名空间；脚本里的 `namespace "..."` 会覆盖配置值。 +- 当全局 `Hello.tsf` 和 `Hello@StmtNS.tsf` 同时存在时，启用 `StmtNS` 后会优先命中命名空间版本。 +- `-LIBPATH` 必须跟在脚本文件名后面；目录项必须以 `/` 或 `\` 结尾；多路径分隔符是分号 `;`。 +- 当多个 `-LIBPATH` 目录都存在同名 `.tsf` 时，解释器按路径从前到后查找，先命中的目录优先。 +- `tsl.conf` 里的绝对 `Libpath=` 可以生效；`Libpath={$P}...` 不作为本页文档能力。 +- `syssettsllibpath()` / `sysgettsllibpath()` 可以在运行时修改和读取查找路径，路径规则与 `-LIBPATH` 相同。 +- `InheritParent=1` 不作为本页文档能力。 + +## 示例与行为 + +### `unit` 生命周期 + +代码块身份：配置片段 / 概念骨架 + +```text +// DemoUnit.tsf +unit DemoUnit; + +interface + +const unit_value = 7; +var unit_counter; +function Ping(); + +implementation + +var private_counter; +function Ping(); +begin + private_counter := private_counter + 1; + unit_counter := unit_counter + 10; + return private_counter; +end; + +initialization + writeLn("INIT"); + unit_counter := 1; + private_counter := 100; + +finalization + writeLn("FINAL"); +end. + +// main.tsl + +uses DemoUnit; + +writeLn("BEFORE"); +writeLn(DemoUnit.unit_value); +writeLn(DemoUnit.unit_counter); +writeLn(Ping()); +writeLn(DemoUnit.unit_counter); +``` + +结果说明： + +- 输出顺序是 `BEFORE`、`INIT`、`7`、`1`、`101`、`11`、`FINAL`。 +- 这说明顶层写了 `uses DemoUnit;` 之后，`initialization` 不是立刻执行，而是在第一次真正读 `DemoUnit` 成员时触发。 +- `finalization` 在脚本主体输出结束后触发。 + +代码块身份：输出片段 + +```text +BEFORE +INIT +7 +1 +101 +11 +FINAL +``` + +### `unit` 成员的读取边界 + +直接限定读取： + +代码块身份：配置片段 / 概念骨架 + +```text +// DemoUnit.tsf +unit DemoUnit; + +interface + +const public_const = 1; +var public_var; +function PublicFunc(); + +implementation + +const impl_const = 2; +var impl_var; +function PublicFunc(); +begin + return 10; +end; +function ImplFunc(); +begin + return 20; +end; + +initialization + public_var := 3; + impl_var := 4; +end. + +// main.tsl + +uses DemoUnit; + +writeLn(DemoUnit.public_const); +writeLn(DemoUnit.public_var); +writeLn(DemoUnit.impl_const); +writeLn(DemoUnit.impl_var); +writeLn(PublicFunc()); +``` + +结果说明： + +- `DemoUnit.public_const` 输出 `1`。 +- `DemoUnit.public_var` 输出 `3`。 +- `DemoUnit.impl_const` 输出 `2`。 +- `DemoUnit.impl_var` 输出 `4`。 +- `PublicFunc()` 输出 `10`。 +- 本页文档边界是：实现段函数仍私有，但实现段常量和变量可以通过 `DemoUnit.Member` 直接读取。 + +实现段函数的外部调用反例： + +代码块身份：反例 / 不可照写 + +```text +uses DemoUnit; +writeLn(ImplFunc()); +``` + +结果说明： + +- 上面这种写法会报 `function:ImplFunc compile error or not found`。 +- 因此不要把“实现段常量和变量可限定读取”泛化成“实现段函数可外部调用”。 + +`findFunction("UnitName")` 拿到的 `unit` 对象： + +代码块身份：配置片段 / 概念骨架 + +```text +// DemoUnit.tsf +unit DemoUnit; + +interface + +const public_const = 1; +var public_var; +function Ping(); + +implementation + +const impl_const = 2; +var impl_var; +function Ping(); +begin + return 11; +end; + +initialization + public_var := 3; + impl_var := 4; +end. + +// main.tsl + +uses DemoUnit; + +u := findFunction("DemoUnit"); +writeLn(u.public_const); +writeLn(u.public_var); +writeLn(u.Ping()); +``` + +结果说明： + +- `u.public_const` 输出 `1`。 +- `u.public_var` 输出 `3`。 +- `u.Ping()` 输出 `11`。 +- `findFunction("DemoUnit")` 拿到的对象入口只稳定暴露 `interface` 成员。 + +`findFunction("UnitName")` 对象入口访问实现段成员反例： + +代码块身份：反例 / 不可照写 + +```text +uses DemoUnit; +u := findFunction("DemoUnit"); +writeLn(u.impl_const); +``` + +结果说明： + +- 上面这种写法会报对象属性或方法不存在。 +- 因此不要把 `findFunction("DemoUnit")` 的对象入口等同于 `DemoUnit.Member` 限定访问。 + +限定赋值失败： + +代码块身份：反例 / 不可照写 + +```text +uses DemoUnit; +DemoUnit.unit_counter := 13; +``` + +结果说明： + +- 上面这段会编译失败，报错核心是 `left side can not be assign to`。 + +### `tslfilename()` + +代码块身份：可直接照写示例 + +```tsl +writeLn(tslfilename()); +``` + +结果说明： + +- 这一行会输出正在执行的 `.tsl` 主脚本完整路径。 +- 本页只把“主脚本路径”写成文档事实；不要把 `.tsf` 被调用场景的返回值提前写成事实。 + +### `namespace` 与默认命名空间 + +把默认命名空间、脚本覆盖、以及“全局函数与命名空间函数同名”的三组结论压成同一套最小实验： + +代码块身份：配置片段 / 概念骨架 + +```text +// tsl.conf +[system] +Namespace=ConfNS + +// 同一目录下准备三份函数文件 +// Hello.tsf +function Hello(); +begin + return 10; +end; + +// Hello@ConfNS.tsf +function Hello(); +begin + return 20; +end; + +// Hello@StmtNS.tsf +function Hello(); +begin + return 30; +end; + +// main_conf.tsl +writeLn(Hello()); + +// main_stmt.tsl +namespace "StmtNS"; +writeLn(Hello()); +``` + +结果说明： + +- `main_conf.tsl` 输出 `20`，说明 `tsl.conf` 里的 `Namespace=ConfNS` 会默认命中 `Hello@ConfNS.tsf`。 +- `main_stmt.tsl` 输出 `30`，说明脚本里的 `namespace "StmtNS";` 会覆盖 `tsl.conf` 里的 `Namespace=ConfNS`。 +- 在同一目录保留 `Hello.tsf` 后，不写 `namespace` 且不设置 `Namespace` 时，`Hello()` 输出 `10`。 +- 如果只保留 `Hello@StmtNS.tsf` 而没有全局 `Hello.tsf`，又没有启用命名空间，`Hello()` 会报找不到函数。 + +### `-LIBPATH` + +查找顺序： + +代码块身份：配置片段 / 概念骨架 +代码块说明：命令行运行形态和多文件结构骨架；这些命令不可写进 `.tsl` 源码。 + +```text +// libA/Hello.tsf +function Hello(); +begin + return 101; +end; + +// libB/Hello.tsf +function Hello(); +begin + return 202; +end; + +// main.tsl +writeLn(Hello()); + +// 命令 A +tsl .\main.tsl -LIBPATH "D:\libA\;D:\libB\" + +// 命令 B +tsl .\main.tsl -LIBPATH "D:\libB\;D:\libA\" +``` + +结果说明： + +- 命令 A 输出 `101`。 +- 命令 B 输出 `202`。 +- 解释器按 `-LIBPATH` 从前到后查找，先命中的目录优先。 + +位置与分隔符边界： + +代码块身份：配置片段 / 概念骨架 +代码块说明：命令行运行形态；这些命令不可写进 `.tsl` 源码。 + +```text +tsl -LIBPATH "D:\libA\" .\main.tsl +tsl .\main.tsl -LIBPATH "D:\libA" +tsl .\main.tsl -LIBPATH "D:\libA\,D:\libB\" +``` + +结果说明： + +- 把 `-LIBPATH` 放在脚本文件名前面时，解释器不会执行脚本，而是回到 usage 提示。 +- 路径项不带结尾 `/` 或 `\` 时，函数找不到。 +- 多路径使用分号 `;` 分隔，不使用逗号分隔。 + +### `syssettsllibpath()` 与 `sysgettsllibpath()` + +代码块身份：配置片段 / 概念骨架 + +```text +writeLn(syssettsllibpath("C:/path/to/libA/;C:/path/to/libB/")); +writeLn(sysgettsllibpath()); +writeLn(call("FnA")); +writeLn(call("FnB")); +``` + +结果说明： + +- `syssettsllibpath(".../libA/;.../libB/")` 之后，`call("FnA")` 和 `call("FnB")` 都能找到对应函数。 +- `sysgettsllibpath()` 返回设置后的完整路径串。 +- 多路径使用分号 `;` 分隔；路径项保留结尾 `/` 或 `\`。 + +### `tsl.conf` 的 `Libpath=` + +代码块身份：配置片段 / 概念骨架 + +```text +[system] +Libpath=D:\path\to\funcext\ +``` + +结果说明： + +- `tsl.conf` 设为绝对 `Libpath=` 时，脚本可以找到该目录下的 `.tsf`。 +- `Libpath={$P}funcext/` 不作为本页文档能力。 +- `InheritParent=1` 不作为本页文档能力。 + +绝对 `Libpath=` 正例： + +代码块身份：配置片段 / 概念骨架 + +```text +// tsl.conf +[system] +Libpath=D:/abs/path/to/funcext/ + +// funcext/Hello.tsf +function Hello(); +begin + return 123; +end; + +// main.tsl +writeLn(Hello()); +``` + +结果说明： + +- 上面这种绝对 `Libpath=` 配置下，`main.tsl` 输出 `123`。 + +`Libpath={$P}` 负例： + +代码块身份：反例 / 不可照写 + +```text +// tsl.conf +[system] +Libpath={$P}funcext/ + +// funcext/Hello.tsf +function Hello(); +begin + return 456; +end; + +// main.tsl +writeLn(Hello()); +``` + +结果说明： + +- 上面这种 `Libpath={$P}funcext/` 配置下，`main.tsl` 仍报 `function:Hello compile error or not found`。 +- 因此不能把 `{$P}` 替换写法当成文档规则。 + +`InheritParent=1` 的最小负例： + +代码块身份：反例 / 不可照写 + +```text +// parent/tsl.conf +[system] +Namespace=ParentNS +InheritParent=1 + +// parent/sub/Hello@ParentNS.tsf +function Hello(); +begin + return 314; +end; + +// parent/sub/main.tsl + +writeLn(Hello()); +``` + +结果说明： + +- 这组父目录配置 + 子目录脚本的最小样例会报 `function:Hello compile error or not found` +- 因此 `InheritParent=1` 不作为可写事实 + +## 禁止项 + +- 把 `DemoUnit.var_name := value` 当成可用的限定赋值。 +- 以为 `implementation` 里的常量和变量一定都不能从 `DemoUnit.Member` 读到。 +- 以为 `findFunction("DemoUnit")` 暴露的成员范围和 `DemoUnit.Member` 完全相同。 +- 把脚本内的 `namespace "..."` 当成和 `tsl.conf` 里的 `Namespace=...` 叠加，而不是覆盖。 +- 把 `-LIBPATH` 放在脚本文件名前面。 +- 用逗号分隔 `-LIBPATH` 或 `syssettsllibpath()` 的多路径。 +- 忘了给 `-LIBPATH` 或 `syssettsllibpath()` 的目录项补结尾 `/` 或 `\`。 +- 把 `Libpath={$P}...` 和 `InheritParent=1` 直接当成文档规则。 diff --git a/docs/tsl/syntax/19_types_and_conversions.md b/docs/tsl/syntax/19_types_and_conversions.md deleted file mode 100644 index 409d4db2..00000000 --- a/docs/tsl/syntax/19_types_and_conversions.md +++ /dev/null @@ -1,262 +0,0 @@ -# Types And Conversions - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[04_values_and_literals.md](04_values_and_literals.md)、[20_strings_and_text.md](20_strings_and_text.md)、[05_variables_and_constants.md](05_variables_and_constants.md) - -手册位置：第 19 篇，共 32 篇。上一篇：[18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md)。下一篇：[20_strings_and_text.md](20_strings_and_text.md)。 - -这一篇吸收语言基础里“数据类型、初始值、弱类型行为、类型转换、显式声明边界”这一层。 - -## 这一篇解决什么问题 - -回答“当问题不再是怎么写字面量，而是变量在运行时会变成什么类型、怎样转换、怎样受编译选项影响时，应该看哪里”。 - -## Agent 类型/转换判断流程 - -1. 先判断要写数值字面量、日期时间、真假值、nil，还是类型转换边界。 -2. 整数、实数、日期时间和特殊实数只照本页已验证字面量写。 -3. 不要把能编译的混合类型表达式误判为能按预期自动转换。 -4. 遇到字符串细节跳转到 `20_strings_and_text.md`，遇到值基础跳转到 `04_values_and_literals.md`。 -5. 没有已验证代码块时不要发明类型/转换写法。 - -## 必须记住的规则 - -- 当前解释器接受十进制、`0x` 十六进制、`0b` 二进制、`0o` 八进制整数常量。 -- 当前解释器接受 `100L` 这类 `Int64` 常量写法。 -- 当前最小验证里，超过 32 位整数范围的十进制整数字面量 `2147483648` 会按 `Int64`，不按实数处理。 -- 当前解释器接受 `1.5`、`1.0E2`、`1E2` 这类实数写法；其中 `1E2` 在当前解释器里按实数，不按整数处理。 -- 当前解释器接受 `20111231T`、`20101231.0931T` 这类日期时间字面量。 -- `TRUE` 和 `FALSE` 当前可以直接使用；打印结果分别是 `1` 和 `0`。 -- 条件判断里，当前已验证 `0` 按假值处理，非 `0` 数值按真值处理。 -- 当前解释器接受 `INF` 和 `NAN` 这两个特殊实数常量，并且 `IfReal(INF)`、`IfReal(NAN)` 都返回 `1`。 -- 当前已验证 `INF > 1000` 为真，而 `NAN = NAN` 为假。 -- 未初始化的普通变量当前会得到整数 `0`。 -- 新建对象的普通成员变量，默认值当前是 `nil`。 -- 对空数组读取一个尚未赋值的下标时，当前得到的是 `nil`。 -- 当前解释器接受 `IfNil(nil)` 这种显式空值判定。 -- 空字符串、空数组和 `nil` 在当前解释器里都按假值处理。 -- 当前解释器接受 `nil` 参与加法；`nil + 1` 和 `1 + nil` 都返回 `1`，`nil + nil` 仍然是 `nil`。 -- `IfNumber(...)` 当前已验证会把整数、`Int64`、实数都视为数值；普通字符串不算数值。 -- TSL 不是“完全禁止混合类型表达式”；像 `b + a` 这种“整数 + 字符串”会通过编译，但在运行时会报 `operand type error`。 -- 因此，类型转换要显式写出来，例如 `StrToInt(...)`，不要把运行时失败留给解释器。 - -## 已验证语法 - -基础数字字面量与类型判定： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(ifInt(100)); - WriteLn(ifInt(0x10)); - WriteLn(ifInt(0b10)); - WriteLn(ifInt(0o10)); - WriteLn(ifInt64(100L)); - WriteLn(ifReal(1.5)); - WriteLn(ifReal(1.0E2)); - WriteLn(ifInt(1E2)); - WriteLn(ifReal(1E2)); -end. -``` - -已验证运行结果： - -- 前七行都输出 `1` -- `ifInt(1E2)` 输出 `0` -- `ifReal(1E2)` 输出 `1` -- 说明 `100`、`0x10`、`0b10`、`0o10` 在当前解释器里都按整数处理 -- 说明 `100L` 在当前解释器里按 `Int64` 处理 -- 也说明 `1E2` 当前按实数，不按整数处理 - -代码块身份：已验证输出片段 - -```text -1 -0 -1 -``` - -超 32 位整数与日期时间字面量： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(ifInt64(2147483648)); - WriteLn(ifReal(2147483648)); - d1 := 20111231T; - d2 := 20101231.0931T; - WriteLn(DateToStr(d1)); - WriteLn(DateToStr(d2)); - WriteLn(TimeToStr(d2)); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`0`、`2011-12-31`、`2010-12-31`、`09:31:00` -- 说明 `2147483648` 在当前解释器里按 `Int64`，不按实数处理 -- 也说明 `20111231T`、`20101231.0931T` 这类日期时间字面量当前可以直接使用 - -布尔常量、数值真值和特殊实数： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(True); - WriteLn(False); - if 2 then WriteLn(1) else WriteLn(0); - if 0 then WriteLn(1) else WriteLn(0); - if -1 then WriteLn(1) else WriteLn(0); - WriteLn(IfReal(INF)); - WriteLn(IfReal(NAN)); - WriteLn(INF > 1000); - WriteLn(NAN = NAN); -end. -``` - -已验证运行结果： - -- 前两行分别输出 `1`、`0` -- `if 2` 输出 `1`，`if 0` 输出 `0`，`if -1` 输出 `1` -- `IfReal(INF)` 和 `IfReal(NAN)` 都输出 `1` -- `INF > 1000` 输出 `1` -- `NAN = NAN` 输出 `0` -- 说明当前解释器接受 `TRUE` / `FALSE` / `INF` / `NAN` -- 也说明数值条件判断里，`0` 为假，非 `0` 为真 - -变量初始值与缺失值： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Holder = class - value; -end; -begin - WriteLn(a); - h := new Holder(); - WriteLn(h.value = nil); - arr := array(); - WriteLn(arr[0] = nil); -end. -``` - -已验证运行结果： - -- 依次输出 `0`、`1`、`1` -- 说明未初始化普通变量默认是整数 `0` -- 说明类成员默认值是 `nil` -- 也说明空数组读取尚未赋值的下标时，当前得到的是 `nil` - -`nil` 的显式判定与加法边界： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(IfNil(nil)); - WriteLn(nil + 1); - WriteLn(1 + nil); - WriteLn(nil + nil = nil); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1`、`1`、`1` -- 说明 `IfNil(nil)` 是当前可用的显式空值判定 -- 说明当前解释器允许 `nil` 直接参与加法 -- 其中 `nil + 1` 和 `1 + nil` 都得到 `1` -- `nil + nil` 仍保持为 `nil` - -空值条件判断： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - if "" then WriteLn(0) else WriteLn(1); - if array() then WriteLn(0) else WriteLn(1); - if nil then WriteLn(0) else WriteLn(1); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1`、`1` -- 说明空字符串、空数组和 `nil` 在当前解释器里都按假值处理 - -`IfNumber(...)` 的最小边界： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(IfNumber(100)); - WriteLn(IfNumber(100L)); - WriteLn(IfNumber(1.5)); - WriteLn(IfNumber("100")); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1`、`1`、`0` -- 说明 `IfNumber(...)` 当前接受整数、`Int64`、实数 -- 也说明普通数字字符串不会被 `IfNumber(...)` 直接当成数值 - -显式类型转换的正向例子： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a := "1234"; - b := 1; - c := b + StrToInt(a); - WriteLn(c); -end. -``` - -已验证运行结果： - -- 输出 `1235` -- 说明显式转换后，字符串数值与整数可以按预期参与加法 - -## 当前已验证的反向边界 - -代码块身份：反例 / 不可照写 - -```text -program test; -begin - a := "1234"; - b := 1; - WriteLn(b + a); -end. -``` - -上面这段在当前解释器里可以通过编译，但运行时会报 `Addition instruction error, operand type error`。因此不要把“能编译”误解成“会自动按你期望的类型转换”。 - -## 跳转指引 - -- 回看值和字面量：见 [04_values_and_literals.md](04_values_and_literals.md) -- 回看变量与常量：见 [05_variables_and_constants.md](05_variables_and_constants.md) -- 回看表达式与运算：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 回看函数值和类值：见 [06_functions_and_calls.md](06_functions_and_calls.md) 与 [09_objects_and_classes.md](09_objects_and_classes.md) -- 看字符串专题：见 [20_strings_and_text.md](20_strings_and_text.md) -- 看数组与矩阵样数据：见 [13_matrix_and_collections.md](13_matrix_and_collections.md) diff --git a/docs/tsl/syntax/20_object_runtime_and_introspection.md b/docs/tsl/syntax/20_object_runtime_and_introspection.md new file mode 100644 index 00000000..a309c1a8 --- /dev/null +++ b/docs/tsl/syntax/20_object_runtime_and_introspection.md @@ -0,0 +1,576 @@ +# TSL 对象运行时与反射 + +文档类型：语法深水专题 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[08_objects_and_classes.md](08_objects_and_classes.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇收拢对象模型里不适合继续堆在基础类主线里的运行时内容：类信息、函数句柄、对象状态、引用计数、运行时对象枚举、弱引用与自动弱引用。普通类声明、继承、构造和普通对象创建仍以 [08_objects_and_classes.md](08_objects_and_classes.md) 为主线；本页只在用户明确需要运行时反射、内省、对象生命周期或弱引用能力时进入。 + +## 本篇职责 + +回答“类已经会声明、继承、构造之后，怎样检查类信息、函数信息、对象运行时状态、弱引用创建和弱引用访问判定”。如果只是写一个类、创建一个对象、调用对象方法，回到 [08_objects_and_classes.md](08_objects_and_classes.md)，不要因为本页存在反射或弱引用能力就改写成动态查找。 + +## 智能体对象运行时/反射判断流程 + +1. 先判断用户是否明确要求运行时类类型、方法句柄、对象状态、对象枚举、反射信息或弱引用/自动弱引用。 +2. 普通对象创建、普通方法调用、类声明和继承都回到 [08_objects_and_classes.md](08_objects_and_classes.md)，不要把 `findClass(...)` / `createObject(...)` 当默认写法。 +3. 确实命中反射时，入口优先照 `findClass`、`findFunction`、`thisFunction`、`findOverLoad` 等文档明确示例写。 +4. 访问弱引用前先做 `checkWeakRef(...)` 判定，不要假设失效弱引用安全返回 `nil`。 +5. 类内 `weakRef;` / `autoRef;` 段落式写法属于反例，不要照写。 +6. 函数值调用边界回看函数页，避免把函数指针直接当普通函数调用。 +7. 没有对应代码块时不要发明对象运行时/反射/弱引用写法。 + +## 核心规则 + +- 对象值可以用 `ifObj(...)` 做显式判定。 +- 普通本地类创建仍默认使用 `new ClassName()`；本页的 `createObject(cls)` 只用于运行时已经拿到类类型变量后的创建场景。 +- `class(Name)` 和 `findClass("Name")` 都可以拿到类类型。 +- `obj is classType` 可直接拿类类型变量来做实例判定。 +- `findClass("ParentName", obj)` 可以把实例对象降成指定父类视图。 +- `obj.classInfo(1)` 会返回类类型，并且这个类类型可以继续交给 `createObject(...)`。 +- `obj.classInfo()` 至少可以直接读出 `["classname"]`。 +- `objectstate(self)` 在构造函数内部返回 `1`；构造结束后对实例再取 `objectstate(obj)` 返回 `2`。 +- `tslassigning` 在属性写入函数里输出 `1`，在属性读取函数里输出 `0`。 +- `findFunction("MethodName", obj)` 可以拿到实例方法句柄。 +- `findFunction("MethodName", class(A))` 可以拿到类方法句柄。 +- `thisFunction(obj.Method)` 和 `thisFunction(class(A).Method)` 也可用。 +- 句柄调用方式默认写 `f.do(...)`。 +- `findOverLoad(argc, "Name", obj)` 可以按参数个数取到对应重载方法。 +- `functionInfo` 至少可以读出 `functionname`、`returntype`、`classname` 这几个字段。 +- `tslObjects(1)` 会按类名分组返回对象信息，并且分组项里的 `"obj"` 字段可以重新拿到可调用对象。 +- 对象赋值会延长对象存活；只有最后一个引用清空后才会触发 `destroy()`。 +- `self` 在本页只用于需要本实例对象引用的运行时函数，例如 `objectstate(self)`；普通成员访问仍按 [08_objects_and_classes.md](08_objects_and_classes.md) 的规则，不加 `self` 前缀。 +- 弱引用能力的条件编译宏是 `weakptr`；自动弱引用相关宏是 `autoWeak`。 +- `weakRef(obj)` 可以创建弱引用；对象仍存活时，`weakref_get(w)` 可以拿回强引用。 +- `checkWeakRef(w)` 在对象仍存活时返回 `1`，对象已释放后返回 `-1`。 +- 对已经失效的弱引用直接调用 `weakref_get(w)` 会运行报错，不要把它当成“安全返回 nil”的接口。 +- 类成员上的 `[weakRef] field;` 和 `[autoRef] field;` 可以通过。 +- `[weakRef]` 成员不会阻止对象析构；强引用释放后，对象会正常销毁。 +- 类内段落式 `weakRef;` / `autoRef;` 不作为可写事实，错误信息包含 `invalid class definition`。 + +## 可直接照写示例 + +### 对象值与类类型 + +对象值的最小显式判定： + +代码块身份：可直接照写示例 + +```tsl +obj := new RuntimeBox(); +writeLn(ifObj(obj)); + +type RuntimeBox = class +end; +``` + +结果说明： + +- 输出 `1` +- 说明 `new ...()` 得到的普通对象值可以用 `ifObj(...)` 判定 + +代码块身份：输出片段 + +```text +1 +``` + +`findClass(...)` 与类类型变量： + +代码块身份：可直接照写示例 + +```tsl +classA := findClass("A"); +obj := new A(); +writeLn(classA.FucA()); +writeLn(obj is classA); + +type A = class +public + class function FucA(); + begin + return "ClassA"; + end; +end; +``` + +结果说明： + +- 依次输出 `ClassA`、`1` +- 说明 `findClass("A")` 可以拿到类类型 +- 说明类类型变量可以直接调用类方法 +- 也说明 `obj is classA` 这种“实例对类类型变量做判定”的写法可用 + +`findClass("Parent", obj)` 的父类视图： + +代码块身份：可直接照写示例 + +```tsl +objb := new ClassB(); +obj := findClass("ClassA", objb); +writeLn(obj.Fuc()); + +type ClassA = class +public + function Fuc(); virtual; + begin + return "ClassA"; + end; +end; +type ClassB = class(ClassA) +public + function Fuc(); override; + begin + return "ClassB"; + end; +end; +``` + +结果说明： + +- 输出 `ClassA` +- 说明 `findClass("ClassA", objb)` 可以把子类实例降成父类视图 +- 也说明之后的方法分派会按父类视图执行 + +### 类信息与对象状态 + +`classInfo(1)` 返回类类型： + +代码块身份：可直接照写示例 + +```tsl +obj := new A(); +cls := obj.classInfo(1); +obj2 := createObject(cls); +writeLn(obj2 is class(A)); + +type A = class +public + value; +end; +``` + +结果说明： + +- 输出 `1` +- 说明 `obj.classInfo(1)` 可以返回类类型 +- 也说明这个类类型可以继续交给 `createObject(...)` +- 这个 `createObject(cls)` 只适用于“类类型来自运行时”的场景；普通本地类创建仍回 [08_objects_and_classes.md](08_objects_and_classes.md) 使用 `new ClassName()` + +`classInfo()` 返回的映射字段： + +代码块身份：可直接照写示例 + +```tsl +obj := new A(); +info := obj.classInfo(); +writeLn(info["classname"]); + +type A = class +end; +``` + +结果说明： + +- 输出 `a` +- 说明 `classInfo()` 至少可以直接读出 `["classname"]` +- 这个最小例子里，类名表现为小写标识符 + +`objectstate(...)`： + +代码块身份：可直接照写示例 + +```tsl +oa := new ca("abc"); +writeLn(objectstate(oa)); + +type ca = class +public + static sca; + function create(n); + begin + sca := self; + writeLn(objectstate(self)); + end; +end; +``` + +结果说明： + +- 依次输出 `1`、`2` +- 说明构造函数内部对象状态是 `1` +- 构造结束后，再对实例取 `objectstate(...)` 会得到 `2` + +`tslassigning`： + +代码块身份：可直接照写示例 + +```tsl +o := new ca(); +o.c := 3; +writeLn(o.c); + +type ca = class +public + value; + property c read getc write setc; + function setc(v); + begin + writeLn(tslassigning); + value := v; + end; + function getc(); + begin + writeLn(tslassigning); + return value; + end; +end; +``` + +结果说明： + +- 依次输出 `1`、`0`、`3` +- 说明属性写入函数里 `tslassigning` 为 `1` +- 属性读取函数里 `tslassigning` 为 `0` + +### 函数句柄与重载 + +`findFunction(...)` 查找实例方法和类方法： + +代码块身份：可直接照写示例 + +```tsl +obj := new A(); +f1 := findFunction("Add", obj); +f2 := findFunction("AddClass", class(A)); +writeLn(f1.do(3, 4)); +writeLn(f2.do(5, 6)); + +type A = class +public + function Add(x, y); + begin + return x + y; + end; + class function AddClass(x, y); + begin + return x + y; + end; +end; +``` + +结果说明： + +- 依次输出 `7`、`11` +- 说明 `findFunction(..., obj)` 能拿到实例方法句柄 +- 说明 `findFunction(..., class(A))` 能拿到类方法句柄 +- 也说明句柄调用方式默认写 `f.do(...)` + +`thisFunction(...)` 也可以直接拿方法句柄： + +代码块身份：可直接照写示例 + +```tsl +obj := new A(); +f1 := thisFunction(obj.Add); +f2 := thisFunction(class(A).AddClass); +writeLn(f1.do(3, 4)); +writeLn(f2.do(5, 6)); + +type A = class +public + function Add(x, y); + begin + return x + y; + end; + class function AddClass(x, y); + begin + return x + y; + end; +end; +``` + +结果说明： + +- 依次输出 `7`、`11` +- 说明 `thisFunction(...)` 也可以稳定得到实例方法和类方法句柄 + +`findOverLoad(...)`： + +代码块身份：可直接照写示例 + +```tsl +t := findOverLoad(2, "fun", new TestClass()); +writeLn(t.do(1, 2)); + +type TestClass = class +public + function fun(p1, p2); overload; + begin + return p1 + p2; + end; + function fun(p1); overload; + begin + return p1 + 10; + end; +end; +``` + +结果说明： + +- 输出 `3` +- 说明 `findOverLoad(2, "fun", obj)` 可以按参数个数拿到对应重载方法 + +### 函数信息、对象枚举与生命周期 + +`functionInfo` 的文档字段： + +代码块身份：可直接照写示例 + +```tsl +f := thisFunction(class(A).Add); +info := f.functionInfo; +writeLn(info["functionname"]); +writeLn(info["returntype"]); +writeLn(info["classname"]); + +type A = class +public + class function Add(a: lhs; b: rhs): sum_t; + begin + return a + b; + end; +end; +``` + +结果说明： + +- 依次输出 `add`、`sum_t`、`a` +- 说明 `functionInfo["functionname"]`、`["returntype"]`、`["classname"]` 都可直接读取 +- 这个最小例子里，返回的函数名和类名表现为小写标识符 + +`tslObjects(1)`： + +代码块身份：可直接照写示例 + +```tsl +objA := new TestClass01(100); +objB := new TestClass01(101); +objsInfo := tslObjects(1); +writeLn(length(objsInfo["TestClass01"])); +newObjA := objsInfo["TestClass01"][0, "obj"]; +writeLn(newObjA is class(TestClass01)); +writeLn(newObjA.add(1, 2)); + +type TestClass01 = class +public + value; + function create(_value); + begin + value := _value; + end; + class function add(x, y); + begin + return x + y; + end; +end; +``` + +结果说明： + +- 依次输出 `2`、`1`、`3` +- 说明 `tslObjects(1)` 可以按类名拿到对象分组 +- 分组项里的 `"obj"` 字段可以重新拿到可调用对象 + +引用计数的最小行为： + +代码块身份：可直接照写示例 + +```tsl +o1 := new T1(); +o2 := o1; +o1 := 0; +writeLn("O1 to Zero"); +o2 := 0; +writeLn("O2 to Zero"); + +type T1 = class +public + function destroy(); + begin + writeLn("destroy"); + end; +end; +``` + +结果说明： + +- 依次输出 `O1 to Zero`、`destroy`、`O2 to Zero` +- 说明只清空第一个别名时对象还不会释放 +- 最后一个引用清空后才会触发 `destroy()` + +### 弱引用与自动弱引用 + +弱引用能力的条件编译判定： + +代码块身份：可直接照写示例 + +```tsl +{$ifdef weakptr} +writeLn('weakptr'); +{$else} +writeLn('Noweakptr'); +{$endif} +{$ifdef autoWeak} +writeLn('autoWeak'); +{$else} +writeLn('NoAutoWeak'); +{$endif} +``` + +结果说明： + +- 会输出 `weakptr` +- 也会输出 `autoWeak` +- 说明弱引用能力的条件编译开关应写成 `weakptr`，自动弱引用能力的开关应写成 `autoWeak` + +对象仍然存活时： + +代码块身份：可直接照写示例 + +```tsl +a := new TNode('A'); +w := weakRef(a); +writeLn(checkWeakRef(w)); +s := weakref_get(w); +writeLn(s.name); + +type TNode = class +public + name; + function create(v); + begin + name := v; + end; +end; +``` + +结果说明： + +- `checkWeakRef(w)` 返回 `1` +- `weakref_get(w)` 能拿回强引用 +- 通过拿回的强引用可继续访问对象成员，此处输出 `A` + +同一 `TNode` 类型下，强引用释放后的主体模板： + +代码块身份：配置片段 / 概念骨架 + +```tsl +a := new TNode('A'); +w := weakRef(a); +writeLn(checkWeakRef(w)); +a := nil; +writeLn(checkWeakRef(w)); +``` + +结果说明： + +- 创建后 `checkWeakRef(w)` 返回 `1` +- 把最后一个强引用设为 `nil` 后，`checkWeakRef(w)` 返回 `-1` + +失效弱引用不应直接取强引用： + +代码块身份：反例 / 不可照写 + +```text +a := new TNode('A'); +w := weakRef(a); +a := nil; +t := weakref_get(w); +``` + +上面这种写法不作为可写事实，会运行报错；访问弱引用前应先做 `checkWeakRef(w)` 判定。 + +成员级标记可以直接写在类里： + +代码块身份：可直接照写示例 + +```tsl +writeLn(1); + +type TChild = class +public + [weakRef] owner1; + [autoRef] owner2; +end; +``` + +结果说明： + +- 上述写法可以正常执行，并输出 `1` +- 说明 `[weakRef] field;` 和 `[autoRef] field;` 都能通过 + +`[weakRef]` 成员不会阻止对象析构： + +代码块身份：可直接照写示例 + +```tsl +a := new TA(); +b := new TB(); +b.Bind(a); +a := nil; +writeLn('AfterNil'); + +type TA = class +public + function destroy(); + begin + writeLn('Destroy'); + end; +end; + +type TB = class +public + [weakRef] owner; + function Bind(v); + begin + owner := v; + end; +end; +``` + +结果说明： + +- 输出顺序是 `Destroy`、`AfterNil` +- 说明 `TB.owner` 作为 `[weakRef]` 成员，不会把 `TA` 实例继续强持有 + +## 禁止项 + +- 不要在运行时/反射页发明类声明、继承或构造语法；类基础回 [08_objects_and_classes.md](08_objects_and_classes.md)。 +- 不要为了普通对象创建先写 `findClass(...)` / `createObject(...)`；普通本地类创建回 [08_objects_and_classes.md](08_objects_and_classes.md)，默认用 `new ClassName()`。 +- 不要把函数句柄直接当普通函数直调；默认调用方式是 `f.do(...)`。 +- 不要把 `functionInfo` 示例外推成所有字段都可读。 +- 不要把引用计数样例泛化成所有对象销毁时机；只按本页文档行为描述。 +- 不要把 `objectstate(self)` 里的 `self` 泛化成普通成员访问都要加 `self` 前缀。 +- 不要把弱引用能力的条件编译宏写成 `weakRef`。 +- 不要以为 `weakref_get(deadWeakRef)` 会像普通可空访问那样安全返回 `nil`。 +- 不要以为类内段落式 `weakRef;` / `autoRef;` 也能直接通过。 +- 不要以为 `[weakRef]` 成员会继续强持有对象。 + +代码块身份：反例 / 不可照写 + +```text +type TChild = class +public + owner0; + [weakRef] owner1; + weakRef; + owner2; + autoRef; + owner3; +end; +``` + +上面这种把 `weakRef;` / `autoRef;` 当作类内段落切换的写法不作为可写事实，会编译失败，错误信息包含 `invalid class definition`。 diff --git a/docs/tsl/syntax/20_strings_and_text.md b/docs/tsl/syntax/20_strings_and_text.md deleted file mode 100644 index 11524e91..00000000 --- a/docs/tsl/syntax/20_strings_and_text.md +++ /dev/null @@ -1,238 +0,0 @@ -# Strings And Text - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[04_values_and_literals.md](04_values_and_literals.md)、[19_types_and_conversions.md](19_types_and_conversions.md)、[07_expressions_and_operators.md](07_expressions_and_operators.md) - -手册位置：第 20 篇，共 32 篇。上一篇：[19_types_and_conversions.md](19_types_and_conversions.md)。下一篇：[21_external_calls_and_threads.md](21_external_calls_and_threads.md)。 - -这一篇吸收字符串专题里较深的部分：字符串表达、编码边界、转义、非转义表达、字符串拼装和子串操作。 - -## 这一篇解决什么问题 - -回答“当任务进入字符串和编码细节，而不是只写普通字面量时，应该进入哪一篇”。 - -## Agent 字符串/文本判断流程 - -1. 先判断要写普通字符串、宽串/UTF8 前缀、原始字符串，还是字符串边界行为。 -2. 默认优先普通字符串；只有编码或宽串需求明确时才使用 `L""` / `U""`。 -3. 字符串索引、切片、转义和 `#0` 行为只照已验证示例写。 -4. 字符串表达式行为回看表达式页，不要在文本页发明运算规则。 -5. 没有已验证代码块时不要发明字符串/文本写法。 - -## 必须记住的规则 - -- 普通字符串、`L""` 宽串、`U""` UTF8 前缀串，以及 `%%` 原始字符串，当前解释器都接受。 -- `%%` 原始字符串开头后必须先跟一个空白分隔符；可以带标识符，也支持多行。 -- `L%% ...%%` 与 `U%% ...%%` 这两种带前缀的原始字符串当前也可用。 -- 普通字符串里的 `\uXXXX` 不要直接按“单字符宽串”理解；当前 `Length("\u0041") = 2`，而 `Length(L"\u0041") = 1`、`Length(U"\u0041") = 1`。 -- `U""` 不是宽串；需要在 UTF8、宽串、普通串之间显式转换时，继续用 `UTF8ToUnicode(...)`、`UTF8ToAnsi(...)`、`AnsiToUTF8(...)`、`UnicodetoUTF8(...)`、`String(...)`、`WideString(...)`。 -- `#number` 可以直接把字符码拼进字符串。 -- `\0` 和 `#0` 都能把 ASCII `0` 放进字符串，并且不会把字符串截断。 -- 字符串下标当前已验证从 `1` 开始，不从 `0` 开始；访问 `s[0]` 会运行报 `String index out of bounds`。 -- 字符串切片 `s[start:end]`、替换 `s[start:end] := sub`、删除 `s[start:end] := ""`、插入 `s[index:0] := sub` 当前都可用。 -- 基础字符串索引、切片、插入、删除和替换规则，阅读主线仍以 [04_values_and_literals.md](04_values_and_literals.md) 为准；这一篇只补已经单独实测过的深水边界。 - -## 已验证语法 - -原始字符串 `%%` 的空白分隔、标识符和多行： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - s1 := %% ABC%%; - s2 := %%tag A"B'C%%tag; - s3 := %%m -A -B%%m; - WriteLn(s1); - WriteLn(s2); - WriteLn(s3); -end. -``` - -已验证运行结果： - -- `s1` 输出 `ABC` -- `s2` 输出 `A"B'C` -- `s3` 输出两行 `A`、`B` -- 说明 `%%` 开头后的第一个空白只是分隔符，不属于正文 -- 说明 `%%tag ...%%tag` 可以用标识符配对 -- 也说明 `%%` 原始字符串支持直接跨行 - -代码块身份：已验证输出片段 - -```text -ABC -A"B'C -A -B -``` - -带前缀的原始字符串： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(L%% ABC%% = L"ABC"); - WriteLn(U%% ABC%% = "ABC"); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1` -- 说明 `L%% ...%%` 和 `U%% ...%%` 在当前解释器里都可用 - -`\uXXXX` 在普通串、宽串和 `U` 串里的边界： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(Length("\u0041")); - WriteLn(Length(L"\u0041")); - WriteLn(Length(U"\u0041")); -end. -``` - -已验证运行结果： - -- 依次输出 `2`、`1`、`1` -- 因此不要把普通字符串里的 `"\u0041"` 直接理解成和 `L"\u0041"` 一样的“单字符”写法 - -字符串显式编码转换： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - utf8_s := U"\u5929\u8F6F"; - utf8_s2 := UnicodetoUTF8(L"\u5929\u8F6F"); - wide_s := UTF8ToUnicode(utf8_s); - ansi_s := UTF8ToAnsi(utf8_s); - WriteLn(IfWString(utf8_s)); - WriteLn(utf8_s = utf8_s2); - WriteLn(wide_s = L"\u5929\u8F6F"); - WriteLn(ansi_s = String(L"\u5929\u8F6F")); -end. -``` - -已验证运行结果： - -- 依次输出 `0`、`1`、`1`、`1` -- 说明 `U""` 在当前解释器里不是宽串 -- 说明 UTF8、宽串、普通串之间的显式转换链已经拿到正向最小结果 - -ASCII `0` 字符不会截断字符串： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - s1 := "A\0B"; - s2 := "A"#0"B"; - WriteLn(Length(s1)); - WriteLn(Length(s2)); - WriteLn(s1 = s2); - WriteLn(s1[2] = #0); -end. -``` - -已验证运行结果： - -- 依次输出 `3`、`3`、`1`、`1` -- 说明 `\0` 和 `#0` 都可以把 ASCII `0` 放进字符串 -- 也说明当前字符串不是遇到 `#0` 就自动截断的 C 风格零结尾串 - -字符码拼接： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn("A"#48"B"); - WriteLn("A"#13#10"B"); -end. -``` - -已验证运行结果： - -- 第一行输出 `A0B` -- 第二组输出会分成两行 `A`、`B` -- 说明 `#48` 这类写法会按字符码直接参与字符串拼接，`#13#10` 可以直接表示换行 - -字符串下标、切片和区间改写： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - s := "ABCD"; - WriteLn(s[1]); - WriteLn(s[2]); - s := "AAABBB"; - WriteLn(s[3:4]); -end. -``` - -已验证运行结果： - -- 依次输出 `A`、`B`、`AB` -- 说明字符串下标当前从 `1` 开始 -- 也说明 `s[3:4]` 会取到起止位置都包含在内的子串 - -替换、删除和插入： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - s1 := "AAABBB"; - s1[3:4] := "111"; - WriteLn(s1); - s2 := "AAABBB"; - s2[3:4] := ""; - WriteLn(s2); - s3 := "AAABBB"; - s3[4:0] := "111"; - WriteLn(s3); -end. -``` - -已验证运行结果： - -- 三行依次输出 `AA111BB`、`AABB`、`AAA111BBB` -- 说明 `s[start:end] := sub` 可以直接替换区间 -- 说明右值设为空串时，会删除该区间 -- 说明 `s[index:0] := sub` 会在指定位置前插入子串 - -当前还额外验证到： - -代码块身份：反例 / 不可照写 - -```text -s := "ABCD"; -WriteLn(s[0]); -``` - -上面这种写法会运行报错，错误信息包含 `String index out of bounds`。不要把字符串下标按数组的 `0` 起始规则来写。 - -## 跳转指引 - -- 回看最常用字符串字面量：见 [04_values_and_literals.md](04_values_and_literals.md) -- 回看字符串上的表达式行为：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 看类型与转换：见 [19_types_and_conversions.md](19_types_and_conversions.md) -- 看值与字面量：见 [04_values_and_literals.md](04_values_and_literals.md) diff --git a/docs/tsl/syntax/21_builtin_runtime_objects.md b/docs/tsl/syntax/21_builtin_runtime_objects.md new file mode 100644 index 00000000..97ad5058 --- /dev/null +++ b/docs/tsl/syntax/21_builtin_runtime_objects.md @@ -0,0 +1,168 @@ +# TSL 内置运行时对象 + +文档类型：语法深水专题 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[10_runtime_context_and_with.md](10_runtime_context_and_with.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只收运行时内置对象的文档明确最小模型。这里讲的是语言运行时对象，不是金融业务 API。 + +## 本篇职责 + +回答“写普通 TSL/TSF 脚本时，哪些内置对象可以直接创建，最小可用接口是什么，哪些对象其实依赖特定运行上下文”。 + +## 智能体内置运行时对象判断流程 + +1. 先判断要访问哪个内置运行时对象，以及它是不是语言对象而非业务 API。 +2. 只照本页明确的最小读写路径使用内置对象。 +3. 不要把金融业务上下文对象和语言运行时对象混在一起。 +4. 需要系统参数或 `with` 后缀时跳转到运行时上下文页。 +5. 没有对应代码块时不要发明内置运行时对象写法。 + +## 核心规则 + +- `TStringList` 可以直接用 `new TStringList()` 创建。 +- `TStringList` 支持数字下标、字符串键下标、`Count` 和 `Add(...)`。 +- 流对象应先按 `TStream` 家族理解；普通脚本里的最小可靠入口是 `TMemoryStream` 这种具体类型。 +- 直接 `new TStream()` 会失败，错误信息包含 `function:TStream compile error or not found`。 +- `TMemoryStream` 支持 `Write(...)`、`Read(...)`、`Position`、`Size`。 +- `TCipher` 不是“无参即可创建”的对象；`new TCipher()` 会失败。 +- `TCipher` 的最小写法是 `new TCipher(2)`，然后设置 `Password` 再做 `Encrypt(...)` / `Decrypt(...)`。 +- `TWebRequest` 和 `TWebResponse` 在普通脚本里不作为可直接 `new` 的对象。 +- 因此，Web 请求 / 响应对象不要直接写进普通脚本模板；它们应视为特定运行上下文对象。 +- 本页失败创建示例只用于边界判断，不作为业务代码模板复制。 + +## 可直接照写示例 + +### `TStringList` + +代码块身份：可直接照写示例 + +```tsl +obj := new TStringList(); +obj.CommaText := "A=aaa,B=bbb,C=222"; +writeLn(obj[1]); +writeLn(obj["B"]); +writeLn(obj.Count); +obj.Add("D=444"); +writeLn(obj.Count); +``` + +结果说明： + +- 依次输出 `B=bbb`、`bbb`、`3`、`4` +- 说明既可以按数字下标取整行，也可以按键名取 `Name=Value` 里的值 + +代码块身份：输出片段 + +```text +B=bbb +bbb +3 +4 +``` + +### `TStream` 家族的最小可靠入口：`TMemoryStream` + +代码块身份：可直接照写示例 + +```tsl +mem := new TMemoryStream(); +buffer := "ABC"; +mem.Write(buffer, 3); +mem.Position := 0; +outbuf := "xxx"; +mem.Read(outbuf, 3); +writeLn(outbuf); +writeLn(mem.Size); +``` + +结果说明： + +- 依次输出 `ABC`、`3` +- 说明普通脚本里应优先使用 `TMemoryStream` 这类具体流对象。 + +裸 `TStream` 创建反例： + +代码块身份：反例 / 不可照写 + +```text +base := new TStream(); +writeLn(ifObj(base)); +``` + +结果说明： + +- 上面这种写法会报 `function:TStream compile error or not found`。 +- 不要把裸 `TStream` 当成可直接创建对象。 + +### `TCipher` + +无参创建反例： + +代码块身份：反例 / 不可照写 + +```text +bad := new TCipher(); +writeLn(ifObj(bad)); +``` + +结果说明： + +- 上面这种写法会报 `New Class TCipher Error.`。 +- `TCipher` 不要无参创建。 + +带模式参数创建： + +代码块身份：可直接照写示例 + +```tsl +cipher := new TCipher(2); +cipher.Password := "Tinysoft"; +enc := cipher.Encrypt("abc"); +writeLn(enc <> "abc"); +writeLn(cipher.Decrypt(enc)); +``` + +结果说明： + +- 依次输出 `1`、`abc` +- 说明 `TCipher` 必须按“带模式参数创建”来写，随后可稳定走 `Password -> Encrypt -> Decrypt` + +### `TWebRequest` / `TWebResponse` 的普通脚本边界 + +代码块身份：反例 / 不可照写 + +```text +req := new TWebRequest(); +resp := new TWebResponse(); +``` + +结果说明： + +- `new TWebRequest()` 会报 `function:TWebRequest compile error or not found`。 +- `new TWebResponse()` 会报 `function:TWebResponse compile error or not found`。 +- 普通脚本里，Web 请求 / 响应对象不能直接按普通 `new ...()` 脚本对象来写。 + +## 本页不生成的对象 + +- `TFileStream` +- `TIniFile` +- `TMemIniFile` +- `THashedStringList` +- `TRSA` +- `FTP` / `SMTP` / `POP3` +- `MailMsg` / `MessagePart` +- `TCookie` / `TCookieCollection` +- `TSessionMan` / `TSession` + +这些对象不作为本页可生成事实；不要因为未写入文档资料里出现过就默认使用。 + +## 禁止项 + +- 不要直接把 `new TStream()` 写成普通脚本里的可靠创建方式。 +- 不要无参创建 `TCipher`；最小可靠写法是 `new TCipher(2)` 后再设置 `Password`。 +- 不要把 `TWebRequest` / `TWebResponse` 写进普通脚本模板。 +- 不要把未写入文档资料里的内置对象，当成语法事实。 +- 不要把本页反例块里的失败创建代码包进 `try/except` 后当成业务模板。 diff --git a/docs/tsl/syntax/21_external_calls_and_threads.md b/docs/tsl/syntax/21_external_calls_and_threads.md deleted file mode 100644 index 7a803e67..00000000 --- a/docs/tsl/syntax/21_external_calls_and_threads.md +++ /dev/null @@ -1,285 +0,0 @@ -# External Calls And Threads - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[06_functions_and_calls.md](06_functions_and_calls.md)、[22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 21 篇，共 32 篇。上一篇：[20_strings_and_text.md](20_strings_and_text.md)。下一篇：[22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md)。 - -这一篇吸收函数专题里和外部系统交互有关的部分：`external`、动态库调用、函数指针包装、线程调用。 - -## 这一篇解决什么问题 - -回答“普通函数怎么写已经清楚后，外部 DLL、函数指针、多线程这些系统交互能力应该去哪里查”。 - -## Agent 外部调用/线程判断流程 - -1. 先判断要声明外部函数、绑定函数指针，还是处理线程相关能力。 -2. 外部函数声明只照已验证的调用约定、`external` 和可选 `name` 形态写。 -3. DLL 名优先写字面量或已验证类常量，不要拼接表达式。 -4. 函数指针包装和线程相关能力只照本页已验证边界写。 -5. 没有已验证代码块时不要发明外部调用/线程写法。 - -## 必须记住的规则 - -- 当前解释器接受 `function Name(...): Type; stdcall|cdecl; external "dll" [name "symbol"];` 这类外部函数声明。 -- 当 TSL 函数名和 DLL 导出名一致时，`name "symbol"` 可以省略。 -- 在当前 `Win64` 解释器上，同一个 `GetTickCount64` 例子里，`stdcall`、`cdecl`、省略调用约定都已跑通；手册示例仍默认把调用约定显式写出来。 -- `procedure Name(...); ... external ...;` 当前也已验证可用。 -- `function(...): ...; external fp;` 当前可以把原生函数指针重新包装成 TSL 可调用对象。 -- 当前已验证的 DLL 名写法包括字面量字符串和类常量字符串；不要把字符串拼接表达式直接当成稳定写法。 -- `MakeInstance(ThisFunction(Func), "cdecl", 0)` 当前可以把 TSL 函数包装成 C 调用约定函数指针。 -- `MakeInstance(..., "cdecl", 1)` 当前在 `Win64` 下已经拿到最小线程正例，可以直接交给 `CreateThread`。 -- 外部库名和调用约定要按目标平台选择；不要把 Windows 的 `kernel32.dll` 示例直接复制到 Linux，或把 Linux 的 `.so` 示例直接复制到 Windows。 -- 当前页的线程示例是 Windows 专题，用到了 `kernel32.dll`。 - -## 已验证语法 - -### 最小 `external` 声明 - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Tick64Alias(): int64; stdcall; external "kernel32.dll" name "GetTickCount64"; -begin - WriteLn(Tick64Alias() > 0); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明当前解释器接受 `stdcall` + `external "dll" name "symbol"` 这类外部函数声明骨架 -- 也说明 TSL 里的函数名可以和 DLL 导出名不同，再通过 `name "ExportName"` 绑定 - -代码块身份：已验证输出片段 - -```text -1 -``` - -Linux / POSIX 环境的同类最小骨架： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function getpid(): integer; cdecl; external "libc.so.6"; -begin - WriteLn(getpid() > 0); -end. -``` - -代码块身份：已验证输出片段 - -```text -1 -``` - -这段只说明 Linux / POSIX 目标下可以用 `.so` 库名声明外部函数；生成代码时仍要先判断用户的目标平台。 - -当本地函数名和 DLL 导出名一致时，`name` 可以省略： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function GetTickCount64(): int64; stdcall; external "kernel32.dll"; -begin - WriteLn(GetTickCount64() > 0); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明 `name "symbol"` 不是当前解释器下的强制写法 - -当前 `Win64` 基线下，省略调用约定与显式 `cdecl` 也通过了同一 API 的最小验证： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function TickNoConv(): int64; external "kernel32.dll" name "GetTickCount64"; -function TickCdecl(): int64; cdecl; external "kernel32.dll" name "GetTickCount64"; -begin - WriteLn(TickNoConv() > 0); - WriteLn(TickCdecl() > 0); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1` -- 这只说明当前 `Win64` 解释器下，这两种写法都能跑通这个例子 -- 不要把这个结果直接泛化成“所有平台、所有架构下调用约定都等价” - -### `procedure external` - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Tick64(): int64; stdcall; external "kernel32.dll" name "GetTickCount64"; -procedure SleepMs(ms: integer); stdcall; external "kernel32.dll" name "Sleep"; -begin - t1 := Tick64(); - SleepMs(20); - t2 := Tick64(); - WriteLn(t2 >= t1); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明无返回值的外部过程可以直接声明为 `procedure` - -### 原生函数指针包装 - -代码块身份：已验证可执行示例 - -```tsl -program test; -function LoadLibraryA(s: string): pointer; stdcall; external "kernel32.dll" name "LoadLibraryA"; -function GetProcAddress(hModule: pointer; lpProcName: string): pointer; stdcall; external "kernel32.dll" name "GetProcAddress"; -begin - h := LoadLibraryA("kernel32.dll"); - fp := GetProcAddress(h, "GetTickCount64"); - f := function(): int64; stdcall; external fp; - WriteLn(h <> nil); - WriteLn(fp <> nil); - WriteLn(##f() > 0); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1`、`1` -- 说明 `function(...); ... external fp;` 不只适用于 `MakeInstance(...)` 的结果，也适用于 `GetProcAddress(...)` 返回的原生函数指针 - -### DLL 名的已验证边界 - -类常量字符串： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Demo = class - const KRNL = "kernel32.dll"; -public - function Run(); - begin - return TickConst() > 0; - end; - function TickConst(): int64; stdcall; external KRNL name "GetTickCount64"; -end; -begin - d := new Demo(); - WriteLn(d.Run()); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明当前解释器接受“类常量字符串 -> `external KRNL`”这条最小路径 - -当前已验证的反向边界： - -代码块身份：反例 / 不可照写 - -```text -function TickFromExpr(): int64; stdcall; external "kernel32"$"."$"dll" name "GetTickCount64"; -``` - -上面这种 DLL 名字符串拼接表达式在当前解释器里会报 `dll filename const string not found after external`。因此当前手册只把字面量字符串和已单独验证过的类常量字符串写成可靠规则。 - -### `MakeInstance` - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Add(a: integer; b: integer): integer; -begin - return a + b; -end; -begin - fp := MakeInstance(ThisFunction(Add), "cdecl", 0); - f := function(a: integer; b: integer): integer; external fp; - WriteLn(fp <> nil); - WriteLn(##f(3, 4)); -end. -``` - -已验证运行结果： - -- `fp <> nil` 输出 `1` -- `##f(3, 4)` 输出 `7` -- 说明当前解释器里，`MakeInstance(...)` 生成的函数指针可以再通过 `function(...); external fp;` 包装回 TSL 侧调用 - -### 线程模式最小正例 - -代码块身份：已验证可执行示例 - -```tsl -program test; -function CreateThread(attr: pointer; size: pointer; addr: pointer; p: pointer; flag: Integer; var thread_id: Integer): pointer; stdcall; external "kernel32.dll" name "CreateThread"; -function WaitForSingleObject(h: pointer; timeout: Integer): Integer; stdcall; external "kernel32.dll" name "WaitForSingleObject"; -function CloseHandle(h: pointer): Integer; stdcall; external "kernel32.dll" name "CloseHandle"; -function Worker(p: pointer): integer; -begin - SetGlobalCache("THREAD_TEST_KEY", 1); - return 1; -end; -begin - SetGlobalCache("THREAD_TEST_KEY", 0); - fp := MakeInstance(ThisFunction(Worker), "cdecl", 1); - h := CreateThread(nil, nil, fp, nil, 0, tid); - WriteLn(fp <> nil); - WriteLn(h <> nil); - WriteLn(WaitForSingleObject(h, 5000) >= 0); - GetGlobalCache("THREAD_TEST_KEY", v); - WriteLn(v); - CloseHandle(h); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`1`、`1`、`1` -- 说明 `MakeInstance(..., "cdecl", 1)` 当前可以生成可用于 `CreateThread` 的回调指针 -- 也说明线程体里的 `SetGlobalCache(...)` 当前能够跑通这个最小闭环 - -## 最小可编译示例 - -如果你只是要先记住最小的 DLL 引入骨架，用这个： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function Tick64Alias(): int64; stdcall; external "kernel32.dll" name "GetTickCount64"; -begin - WriteLn(Tick64Alias() > 0); -end. -``` - -## 常见误写 - -- 把 `external` 的 DLL 名直接写成字符串拼接表达式。 -- 省略了外部函数的参数类型或返回类型。 -- 把 `MakeInstance(...)` 生成的结果默认写成普通函数名直调，而不是先包装或用 `##`. -- 直接把 Windows 线程示例当成跨平台事实。 - -## 跳转指引 - -- 回看函数主线：见 [06_functions_and_calls.md](06_functions_and_calls.md) -- 回看运行时边界：见 [16_debug_and_profiler.md](16_debug_and_profiler.md) -- 看 unit / namespace / 查找路径：见 [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) diff --git a/docs/tsl/syntax/22_matrix_deep_dive.md b/docs/tsl/syntax/22_matrix_deep_dive.md new file mode 100644 index 00000000..0c789d34 --- /dev/null +++ b/docs/tsl/syntax/22_matrix_deep_dive.md @@ -0,0 +1,232 @@ +# TSL 矩阵深水专题 + +文档类型：语法深水专题 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆，以及怎样读取矩阵的行列大小和索引。它和 [12_matrix_and_collections.md](12_matrix_and_collections.md) 的分工是：`13` 只讲数组与矩阵样数据，这一篇讲矩阵专用构造、运算与大小接口。 + +## 本篇职责 + +回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，怎样写矩阵逆/广义逆，以及怎样拿到矩阵的行数、列数、行索引和列索引”。 + +## 智能体矩阵深水判断流程 + +1. 先判断要写矩阵初始化、数列构造、矩阵逆/广义逆，还是矩阵尺寸与索引读取。 +2. 基础数组和矩阵样比较先回看 `12_matrix_and_collections.md`。 +3. `mrows` / `mcols` / `msize` 等函数只照文档返回形态写。 +4. 不要把列索引数组误当成单个数字。 +5. 没有对应代码块时不要发明矩阵深水写法。 + +## 核心规则 + +- 矩阵初始化函数的参数规格见 [../reference/catalog/math.md](../reference/catalog/math.md)；本页只保留矩阵行为示例和返回形态边界。 +- `zeros(...)`、`ones(...)`、`rand(...)`、`nils(...)`、`eye(...)` 都可以直接用于矩阵初始化。 +- `zeros(3)`、`ones(3)`、`nils(2)` 这类单参数写法可以直接生成一维结果。 +- `zeros(2, 3)`、`rand(2, 3)` 这类双参数写法可以直接生成二维矩阵。 +- `zeros(2, array("A", "B"))` 这种写法可以直接生成带列名的二维结果。 +- `eye(3)` 生成的是 `3 x 3` 单位矩阵，不是一维数组。 +- `->` 用来生成数列；默认步长是 `1`，也可以显式传入步长和索引数组。 +- 在矩阵语境里，`!A` 是一元倒数运算符作用于矩阵的形态，用于矩阵逆/广义逆；非方阵输入可以返回行列数互换后的广义逆结果。 +- `msize(...)`、`mrows(...)`、`mcols(...)` 的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)。 +- `msize(matrix_value)` 返回 `array(行数, 列数)`。 +- `msize(matrix_value, 1)` 返回行索引数组和列索引数组。 +- `mrows(matrix_value)` / `mcols(matrix_value)` 默认返回数量；第二个参数写成 `1` 时返回索引数组。 +- `mrows(matrix_value, 1)` / `mcols(matrix_value, 1)` 的返回值可用于索引匹配；不要把它们当成数量。 + +## 可直接照写示例 + +### 矩阵初始化 + +代码块身份：可直接照写示例 + +```tsl +zeros_1d := zeros(3); +zeros_2d := zeros(2, 3); +ones_1d := ones(3); +nils_1d := nils(2); +eye_2d := eye(3); +rand_2d := rand(2, 3); +named_zeros := zeros(2, array("A", "B")); +writeLn(length(zeros_1d)); +writeLn(mrows(zeros_2d)); +writeLn(mcols(zeros_2d)); +``` + +结果说明： + +- `zeros(3)` 的长度是 `3`，前三个元素依次是 `0`、`0`、`0` +- `zeros(2, 3)` 的行数是 `2`、列数是 `3`，第一行前三个元素是 `0`、`0`、`0` +- `ones(3)` 的前三个元素依次是 `1`、`1`、`1` +- `nils(2)` 可直接生成长度为 `2` 的结果 +- `eye(3)` 的行数是 `3`、列数是 `3`，并且 `(0,0)`、`(1,1)`、`(2,2)` 为 `1`，`(0,1)`、`(1,0)` 为 `0` +- `rand(2, 3)` 的行数是 `2`、列数是 `3` +- `zeros(2, array("A", "B"))` 的行数是 `2`、列数是 `2`，并且 `named_zeros[0]["A"]`、`named_zeros[0]["B"]`、`named_zeros[1]["A"]`、`named_zeros[1]["B"]` 都是 `0` + +代码块身份：输出片段 + +```text +3 +2 +3 +``` + +### `->` 数列数组初始化 + +默认步长为 `1`： + +代码块身份：可直接照写示例 + +```tsl +seq_default := 1 -> 5; +``` + +结果说明： + +- `seq_default` 是 `array(1, 2, 3, 4, 5)` + +显式指定步长： + +代码块身份：可直接照写示例 + +```tsl +seq_step := array(2.5, 0.5) -> 5; +``` + +结果说明： + +- `seq_step` 的长度是 `6` +- 六个元素依次是 `2.5`、`3`、`3.5`、`4`、`4.5`、`5` + +显式指定索引数组： + +代码块身份：可直接照写示例 + +```tsl +seq_indexed := array(0, 1, array("A", "B", "C", "D", "E", "F")) -> 5; +``` + +结果说明： + +- `seq_indexed` 的长度是 `6` +- `seq_indexed["A"]` 到 `seq_indexed["F"]` 依次是 `0`、`1`、`2`、`3`、`4`、`5` + +### 矩阵一元倒数 / 逆 / 广义逆：`!A` + +方阵输入返回普通矩阵逆： + +代码块身份：可直接照写示例 + +```tsl +matrix_value := array((1, 2), (3, 4)); +inverse_value := !matrix_value; +writeLn(mrows(inverse_value)); +writeLn(mcols(inverse_value)); +writeLn(inverse_value[0][0]); +writeLn(inverse_value[0][1]); +writeLn(inverse_value[1][0]); +writeLn(inverse_value[1][1]); +``` + +代码块身份：输出片段 + +```text +2 +2 +-2 +1 +1.5 +-0.5 +``` + +非方阵输入返回广义逆： + +代码块身份：可直接照写示例 + +```tsl +matrix_value := array((1, 2, 3), (4, 5, 6)); +inverse_value := !matrix_value; +writeLn(mrows(inverse_value)); +writeLn(mcols(inverse_value)); +writeLn(inverse_value[0][0]); +writeLn(inverse_value[0][1]); +writeLn(inverse_value[1][0]); +writeLn(inverse_value[1][1]); +writeLn(inverse_value[2][0]); +writeLn(inverse_value[2][1]); +``` + +代码块身份：输出片段 + +```text +3 +2 +-0.944444444444444 +0.444444444444444 +-0.111111111111111 +0.111111111111111 +0.722222222222222 +-0.222222222222222 +``` + +说明： + +- `array((1, 2, 3), (4, 5, 6))` 是 `2 x 3` 矩阵样数组。 +- `!matrix_value` 返回的是 `3 x 2` 广义逆结果。 +- 生成矩阵逆/广义逆时写 `!matrix_value`；不要把它改写成 `1 / matrix_value`。 +- `!` 不表示逻辑非；逻辑非回 [06_expressions_and_operators.md](06_expressions_and_operators.md) 使用 `not`。 + +### `msize`、`mrows`、`mcols` + +代码块身份：可直接照写示例 + +```tsl +matrix_rows := array( + ("A": 1, "B": 2), + ("A": 11, "B": 22), + ("A": 21, "B": 32) +); +size_info := msize(matrix_rows); +size_index := msize(matrix_rows, 1); +row_count := mrows(matrix_rows); +row_index := mrows(matrix_rows, 1); +col_count := mcols(matrix_rows); +col_index := mcols(matrix_rows, 1); +``` + +结果说明： + +- `msize(matrix_rows)` 返回 `array(3, 2)` +- `msize(matrix_rows, 1)` 的第一项是 `array(0, 1, 2)`，第二项是 `array("A", "B")` +- `mrows(matrix_rows)` 返回 `3` +- `mrows(matrix_rows, 1)` 返回 `array(0, 1, 2)` +- `mcols(matrix_rows)` 返回 `2` +- `mcols(matrix_rows, 1)` 返回 `array("A", "B")` + +## 默认生成模板 + +需要矩阵构造时，优先从这个最短模板开始： + +代码块身份：可直接照写示例 + +```tsl +matrix_value := zeros(2, 3); +``` + +## 决策边界和禁止项 + +- 把 `eye(3)` 当成一维数组。 +- 把 `!A` 当成逻辑非表达式。 +- 以为 `mrows(matrix_value, 1)` 和 `mcols(matrix_value, 1)` 返回的还是数量。 +- 写带步长的 `->` 时，漏掉外层 `array(...)`。 +- 还在普通数组页里硬塞矩阵专用大小接口。 + +代码块身份：反例 / 不可照写 + +```text +seq_value := 2.5, 0.5 -> 5; +``` + +上面这种写法不对。显式步长模式需要写成 `array(2.5, 0.5) -> 5`。 diff --git a/docs/tsl/syntax/22_namespace_libpath_and_unit_runtime.md b/docs/tsl/syntax/22_namespace_libpath_and_unit_runtime.md deleted file mode 100644 index 37d7f576..00000000 --- a/docs/tsl/syntax/22_namespace_libpath_and_unit_runtime.md +++ /dev/null @@ -1,445 +0,0 @@ -# Namespace Libpath And Unit Runtime - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[10_units_and_scope.md](10_units_and_scope.md)、[23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 22 篇，共 32 篇。上一篇：[21_external_calls_and_threads.md](21_external_calls_and_threads.md)。下一篇：[23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md)。 - -这一篇收拢 `unit` 的运行时行为，以及 `.tsf` / `namespace` / `libpath` 的查找规则。`unit` 的基础写法、`uses` 位置和重名解析，统一放在 [10_units_and_scope.md](10_units_and_scope.md)。 - -## 这一篇解决什么问题 - -回答下面这些“写法已经会了，但运行起来为什么这样”的问题： - -- `unit` 什么时候进入 `initialization` -- `finalization` 在什么时候触发 -- `unit` 里的常量、变量和 `findfunction("UnitName")` 到底暴露哪些成员 -- `tslfilename()` 返回什么 -- `NameSpace "..."`、`tsl.conf` 和 `-LIBPATH` 怎样影响 `.tsf` 查找 -- `syssettsllibpath()` / `sysgettsllibpath()` 怎样在运行时改查找路径 - -## Agent 命名空间/Libpath 判断流程 - -1. 先判断任务是单元命名空间访问、`-LIBPATH` 查找，还是配置文件查找。 -2. 路径和查找顺序只写平台中立规则，不写某个开发机或容器路径。 -3. `-LIBPATH` 只作为运行时部署/查找规则，不写进普通语法示例。 -4. 未验证的路径替换和父目录继承不要当成稳定规则。 -5. 没有已验证代码块时不要发明命名空间/Libpath 写法。 - -## 必须记住的规则 - -- 完整 `unit` 形态可以包含 `interface`、`implementation`、`initialization`、`finalization`，并以 `end.` 结束。 -- `initialization` 在 `unit` 第一次被实际使用时触发，不是只因为顶层写了 `uses` 就立刻执行。 -- `finalization` 会在脚本结束前触发。 -- 直接写 `DemoUnit.Member` 时，当前解释器能读到 `interface` 和 `implementation` 里的常量、变量。 -- `findfunction("DemoUnit")` 拿到的是 `unit` 对象入口，但当前只验证到它稳定暴露 `interface` 成员；`implementation` 变量和常量没有从这个对象读出来。 -- `DemoUnit.VarName := value` 这种限定赋值当前会编译失败；如果要改 `unit` 状态，应导出函数或方法来改。 -- `tslfilename()` 在命令行解释器里返回当前执行脚本的完整路径。 -- `NameSpace "DemoNS";` 会选择 `Hello@DemoNS.tsf` 这类命名空间函数文件。 -- `tsl.conf` 的 `[system] Namespace=...` 可以设置默认命名空间；脚本里的 `NameSpace "..."` 会覆盖配置值。 -- 当全局 `Hello.tsf` 和 `Hello@StmtNS.tsf` 同时存在时，启用 `StmtNS` 后会优先命中命名空间版本。 -- `-LIBPATH` 必须跟在脚本文件名后面；目录项必须以 `/` 或 `\` 结尾；多路径分隔符当前实测是分号 `;`。 -- 当多个 `-LIBPATH` 目录都存在同名 `.tsf` 时，解释器按路径从前到后查找，先命中的目录优先。 -- `tsl.conf` 里的绝对 `Libpath=` 可以生效；`Libpath={$P}...` 在当前解释器下没有拿到正向结果。 -- `syssettsllibpath()` / `sysgettsllibpath()` 可以在运行时修改和读取查找路径，路径规则与 `-LIBPATH` 相同。 -- `InheritParent=1` 目前没有拿到稳定正例，因此不写成正式规则。 - -## 已验证语法与行为 - -### `unit` 生命周期 - -代码块身份：配置片段 / 概念骨架 - -```text -// DemoUnit.tsf -unit DemoUnit; -interface -const UnitValue = 7; -var UnitCounter; -function Ping(); -implementation -var PrivateCounter; -function Ping(); -begin - PrivateCounter := PrivateCounter + 1; - UnitCounter := UnitCounter + 10; - return PrivateCounter; -end; -initialization - WriteLn("INIT"); - UnitCounter := 1; - PrivateCounter := 100; -finalization - WriteLn("FINAL"); -end. - -// main.tsl -program test; -uses DemoUnit; -begin - WriteLn("BEFORE"); - WriteLn(DemoUnit.UnitValue); - WriteLn(DemoUnit.UnitCounter); - WriteLn(Ping()); - WriteLn(DemoUnit.UnitCounter); -end. -``` - -已验证运行结果： - -- 输出顺序是 `BEFORE`、`INIT`、`7`、`1`、`101`、`11`、`FINAL`。 -- 这说明顶层写了 `uses DemoUnit;` 之后，`initialization` 不是立刻执行，而是在第一次真正读 `DemoUnit` 成员时触发。 -- `finalization` 在脚本主体输出结束后触发。 - -代码块身份：已验证输出片段 - -```text -BEFORE -INIT -7 -1 -101 -11 -FINAL -``` - -### `unit` 成员的读取边界 - -直接限定读取： - -代码块身份：配置片段 / 概念骨架 - -```text -// DemoUnit.tsf -unit DemoUnit; -interface -const PublicConst = 1; -var PublicVar; -function PublicFunc(); -implementation -const ImplConst = 2; -var ImplVar; -function PublicFunc(); -begin - return 10; -end; -function ImplFunc(); -begin - return 20; -end; -initialization - PublicVar := 3; - ImplVar := 4; -end. - -// main.tsl -uses DemoUnit; -WriteLn(DemoUnit.PublicConst); -WriteLn(DemoUnit.PublicVar); -WriteLn(DemoUnit.ImplConst); -WriteLn(DemoUnit.ImplVar); -WriteLn(PublicFunc()); -WriteLn(ImplFunc()); -``` - -已验证运行结果： - -- `DemoUnit.PublicConst` 输出 `1`。 -- `DemoUnit.PublicVar` 输出 `3`。 -- `DemoUnit.ImplConst` 输出 `2`。 -- `DemoUnit.ImplVar` 输出 `4`。 -- `PublicFunc()` 输出 `10`。 -- `ImplFunc()` 仍然报 `compile error or not found`。 -- 当前解释器的真实边界是：实现段函数仍私有，但实现段常量和变量可以通过 `DemoUnit.Member` 直接读取。 - -`findfunction("UnitName")` 拿到的 `unit` 对象： - -代码块身份：配置片段 / 概念骨架 - -```text -// DemoUnit.tsf -unit DemoUnit; -interface -const PublicConst = 1; -var PublicVar; -function Ping(); -implementation -const ImplConst = 2; -var ImplVar; -function Ping(); -begin - return 11; -end; -initialization - PublicVar := 3; - ImplVar := 4; -end. - -// main.tsl -uses DemoUnit; -u := findfunction("DemoUnit"); -WriteLn(u.PublicConst); -WriteLn(u.PublicVar); -WriteLn(u.Ping()); -WriteLn(u.ImplConst); -``` - -已验证运行结果： - -- `u.PublicConst` 输出 `1`。 -- `u.PublicVar` 输出 `3`。 -- `u.Ping()` 输出 `11`。 -- `u.ImplConst` 报对象属性或方法不存在。 -- 当前解释器下，`findfunction("DemoUnit")` 拿到的对象入口只稳定暴露 `interface` 成员。 - -限定赋值失败： - -代码块身份：反例 / 不可照写 - -```text -uses DemoUnit; -DemoUnit.UnitCounter := 13; -``` - -已验证结果： - -- 上面这段会编译失败，报错核心是 `left side can not be assign to`。 - -### `TslFileName` - -代码块身份：已验证可执行示例 - -```tsl -WriteLn(tslfilename()); -``` - -已验证结果： - -- 在命令行解释器里，这一行会输出当前执行 `.tsl` 文件的完整路径。 -- 当前已验证的是“主脚本路径”；不要把 `.tsf` 被调用场景的返回值提前写成已验证事实。 - -### `NameSpace` 与默认命名空间 - -把默认命名空间、脚本覆盖、以及“全局函数与命名空间函数同名”的三组结论压成同一套最小实验： - -代码块身份：配置片段 / 概念骨架 - -```text -// tsl.conf -[system] -Namespace=ConfNS -Libpath=D:\path\to\lib\ - -// 同一目录下准备三份函数文件 -// Hello.tsf -function Hello(); -begin - return 10; -end; - -// Hello@ConfNS.tsf -function Hello(); -begin - return 20; -end; - -// Hello@StmtNS.tsf -function Hello(); -begin - return 30; -end; - -// main_conf.tsl -program test; -begin - WriteLn(Hello()); -end. - -// main_stmt.tsl -program test; -begin - NameSpace "StmtNS"; - WriteLn(Hello()); -end. -``` - -已验证运行结果： - -- `main_conf.tsl` 输出 `20`，说明 `tsl.conf` 里的 `Namespace=ConfNS` 会默认命中 `Hello@ConfNS.tsf`。 -- `main_stmt.tsl` 输出 `30`，说明脚本里的 `NameSpace "StmtNS";` 会覆盖 `tsl.conf` 里的 `Namespace=ConfNS`。 -- 在同一目录保留 `Hello.tsf` 后，不写 `NameSpace` 且不设置 `Namespace` 时，`Hello()` 输出 `10`。 -- 如果只保留 `Hello@StmtNS.tsf` 而没有全局 `Hello.tsf`，又没有启用命名空间，`Hello()` 会报找不到函数。 - -### `-LIBPATH` - -查找顺序： - -代码块身份：配置片段 / 概念骨架 - -```text -// libA/Hello.tsf -function Hello(); -begin - return 101; -end; - -// libB/Hello.tsf -function Hello(); -begin - return 202; -end; - -// main.tsl -program test; -begin - WriteLn(Hello()); -end. - -// command A -tsl .\main.tsl -LIBPATH "D:\libA\;D:\libB\" - -// command B -tsl .\main.tsl -LIBPATH "D:\libB\;D:\libA\" -``` - -已验证运行结果： - -- 命令 A 输出 `101`。 -- 命令 B 输出 `202`。 -- 当前解释器按 `-LIBPATH` 从前到后查找，先命中的目录优先。 - -位置与分隔符边界： - -代码块身份：配置片段 / 概念骨架 - -```text -tsl -LIBPATH "D:\libA\" .\main.tsl -tsl .\main.tsl -LIBPATH "D:\libA" -tsl .\main.tsl -LIBPATH "D:\libA\,D:\libB\" -``` - -已验证结果： - -- 把 `-LIBPATH` 放在脚本文件名前面时，解释器不会执行脚本，而是回到 usage 提示。 -- 路径项不带结尾 `/` 或 `\` 时，函数找不到。 -- 逗号分隔多路径没有跑通；当前实测有效的是分号 `;`。 - -### `syssettsllibpath()` 与 `sysgettsllibpath()` - -代码块身份：配置片段 / 概念骨架 - -```text -program test; -begin - WriteLn(syssettsllibpath("C:/path/to/libA/;C:/path/to/libB/")); - WriteLn(sysgettsllibpath()); - WriteLn(call("FnA")); - WriteLn(call("FnB")); -end. -``` - -已验证运行结果： - -- `syssettsllibpath(".../libA/;.../libB/")` 之后，`call("FnA")` 和 `call("FnB")` 都能找到对应函数。 -- `sysgettsllibpath()` 返回设置后的完整路径串。 -- 当前实测里，逗号分隔没有跑通；路径项不带结尾 `/` 也没有跑通。 - -### `tsl.conf` 的 `Libpath=` - -代码块身份：配置片段 / 概念骨架 - -```text -[system] -Libpath=D:\path\to\funcext\ -``` - -已验证结果： - -- 当前目录 `tsl.conf` 设为绝对 `Libpath=` 时，脚本可以找到该目录下的 `.tsf`。 -- 当前解释器下，`Libpath={$P}funcext/` 没有拿到正向结果。 -- 当前解释器下，也没有拿到 `InheritParent=1` 的稳定正例，因此不要把这两条当成可依赖规则。 - -`Libpath=` 的正向与负向对照： - -代码块身份：配置片段 / 概念骨架 - -```text -// case A: 绝对 Libpath -// tsl.conf -[system] -Libpath=D:/abs/path/to/funcext/ - -// funcext/Hello.tsf -function Hello(); -begin - return 123; -end; - -// main.tsl -program test; -begin - WriteLn(Hello()); -end. - -// case B: {$P} Libpath -// tsl.conf -[system] -Libpath={$P}funcext/ - -// case B 的 main.tsl 与 case A 相同 -// case B 的 funcext/Hello.tsf 只把返回值改成 456 -``` - -已验证结果： - -- case A 输出 `123` -- case B 仍报 `function:Hello compile error or not found` -- 因此当前解释器下，不能把 `{$P}` 替换写法当成已经稳定可依赖的规则 - -`InheritParent=1` 的最小负例： - -代码块身份：反例 / 不可照写 - -```text -// parent/tsl.conf -[system] -Namespace=ParentNS -InheritParent=1 - -// parent/sub/Hello@ParentNS.tsf -function Hello(); -begin - return 314; -end; - -// parent/sub/main.tsl -program test; -begin - WriteLn(Hello()); -end. -``` - -已验证结果： - -- 在当前解释器里，这组父目录配置 + 子目录脚本的最小样例仍报 `function:Hello compile error or not found` -- 因此 `InheritParent=1` 现在还不能升级成正式正向结论 - -## 常见误写 - -- 把 `DemoUnit.VarName := value` 当成可用的限定赋值。 -- 以为 `implementation` 里的常量和变量一定都不能从 `DemoUnit.Member` 读到。 -- 以为 `findfunction("DemoUnit")` 暴露的成员范围和 `DemoUnit.Member` 完全相同。 -- 把脚本内的 `NameSpace "..."` 当成和 `tsl.conf` 里的 `Namespace=...` 叠加，而不是覆盖。 -- 把 `-LIBPATH` 放在脚本文件名前面。 -- 用逗号分隔 `-LIBPATH` 或 `syssettsllibpath()` 的多路径。 -- 忘了给 `-LIBPATH` 或 `syssettsllibpath()` 的目录项补结尾 `/` 或 `\`。 -- 把 `Libpath={$P}...` 和 `InheritParent=1` 直接当成当前解释器已经稳定可依赖的规则。 - -## 跳转指引 - -- 回看 `unit` / `uses` 主线：见 [10_units_and_scope.md](10_units_and_scope.md) -- 查看对象反射与运行时对象：见 [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) -- 回看函数文件与顶层主体：见 [03_core_model.md](03_core_model.md) diff --git a/docs/tsl/syntax/23_fmarray.md b/docs/tsl/syntax/23_fmarray.md new file mode 100644 index 00000000..b04ca4ca --- /dev/null +++ b/docs/tsl/syntax/23_fmarray.md @@ -0,0 +1,532 @@ +# TSL FMArray + +文档类型：语法深水专题 +是否可直接用于生成代码：是 +是否含可直接照写示例：是 +是否含不可照写反例：是 +遇到不确定时：先按本页候选页继续判断；[22_matrix_deep_dive.md](22_matrix_deep_dive.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[14_ts_sql.md](14_ts_sql.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只讲 `FMArray` 文档主干能力：怎样构造 `FMArray`、怎样判断类型、怎样和 `Array` 互转、怎样读取尺寸、做基础运算、做多维转置与维度交换、做矩阵连接、参与 `select/mselect`，以及 `insert/delete/update` 语法边界。 + +## 本篇职责 + +回答“什么时候该用 `FMArray` 而不是普通 `array`，以及文档明确 `FMArray` 写法有哪些”。 + +## 智能体 FMArray 判断流程 + +1. 先判断是否确实需要 `FMArray`，普通数组能解决时先用普通数组。 +2. 构造、类型判断、尺寸读取、转置、连接和 TS-SQL 参与只照本页文档明确形态写。 +3. `insert`、`delete`、`update` 的收尾形式分别判断，不要互相套用。 +4. FMArray 错误边界按本页反例处理，不要凭普通数组经验修写法。 +5. 没有对应代码块时不要发明 FMArray 写法。 + +## 核心规则 + +- `fmarray[...]` 可以直接构造 `FMArray` 常量。 +- `dataType(v)` 对 `FMArray` 返回 `27`。 +- `dataType(v, 1)` 可以读出 `FMArray` 单元格类型；本页文档类型包括 `0` 整型、`1` 浮点、`20` 64 位整型。 +- FMArray 相关函数的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md) 和 [../reference/catalog/math.md](../reference/catalog/math.md)；本页只保留 FMArray 行为示例和返回形态边界。 +- `ifFmarray(v)` 可直接判断值是否为 `FMArray`。 +- `mInit`、`mInitDiag`、`mRand` 都可直接生成 `FMArray`。 +- `arrayToFm` 和 `matrixToArray` 可在 `Array` / `FMArray` 间互转。 +- `msize`、`mrows`、`mcols` 都支持 `FMArray`；对三维 `FMArray`，`msize` 会返回全部维度长度。 +- `FMArray` 支持和标量、`FMArray`、`Array` 做基础算符运算。 +- `union2` 支持 `FMArray` / `Array` 混合运算；结果类型跟随左值。 +- 对超过二维的 `FMArray`，反引号转置会把全部维度倒置；`mswap` 可只交换指定维度。 +- `union` 可做按行连接且不去重，但列结构必须兼容。 +- `|` 和 `:|` 都可做矩阵并右方（按列连接）；行数不一致时会用 `0` 补齐，并且两者表现一致。 +- 对 `FMArray` 做普通 `select` 不会保留 `FMArray` 类型；`mselect` 也不会返回 `dataType=27`。 +- `insert into a array(...)`、`delete from a where ...;`、`update a set ... where ... end;` 都能作用于 `FMArray`，但三者的收尾形式并不完全相同。 + +## 可直接照写示例 + +### 常量构造与类型判断 + +代码块身份：可直接照写示例 + +```tsl +f1 := fmarray[1, 2, 3]; +f2 := fmarray[[1, 2], [3, 4]]; +f3 := fmarray[1.0, 2.0, 3.5]; +writeLn(dataType(f1)); +writeLn(dataType(f1, 1)); +writeLn(dataType(f3, 1)); +writeLn(ifFmarray(f1)); +writeLn(length(f1)); +writeLn(f1[0], ',', f1[1], ',', f1[2]); +writeLn(mrows(f2)); +writeLn(mcols(f2)); +writeLn(f2[0,0], ',', f2[0,1], ',', f2[1,0], ',', f2[1,1]); +``` + +结果说明： + +- `dataType(f1)` 返回 `27` +- `dataType(f1, 1)` 返回 `0` +- `dataType(f3, 1)` 返回 `1` +- `ifFmarray(f1)` 返回 `1` +- `length(f1)` 返回 `3` +- `f1` 的三个元素依次是 `1`、`2`、`3` +- `f2` 的行数是 `2`、列数是 `2` +- `f2` 四个单元依次是 `1`、`2`、`3`、`4` + +代码块身份：输出片段 + +```text +27 +0 +1 +1 +``` + +### `mInit`、`mInitDiag`、`mRand` + +代码块身份：可直接照写示例 + +```tsl +fm1 := mInit(5, 3); +fm2 := mInit(array(3, 2), 1L); +fd1 := mInitDiag(3, 3, 1); +fr1 := mRand(2, 3); +writeLn(dataType(fm1, 1)); +writeLn(length(fm1)); +writeLn(fm1[0], ',', fm1[1], ',', fm1[2], ',', fm1[3], ',', fm1[4]); +writeLn(dataType(fm2, 1)); +writeLn(mrows(fm2)); +writeLn(mcols(fm2)); +writeLn(fd1[0,0], ',', fd1[0,1], ',', fd1[1,0], ',', fd1[1,1], ',', fd1[2,2]); +writeLn(mrows(fr1)); +writeLn(mcols(fr1)); +``` + +结果说明： + +- `mInit(5, 3)` 生成长度为 `5` 的整型 `FMArray`，五个元素都是 `3` +- `dataType(fm1, 1)` 返回 `0` +- `mInit(array(3, 2), 1L)` 的单元格类型是 `20` +- `fm2` 的行数是 `3`、列数是 `2` +- `mInitDiag(3, 3, 1)` 的 `(0,0)`、`(1,1)`、`(2,2)` 为 `1`，而 `(0,1)`、`(1,0)` 为 `0` +- `mRand(2, 3)` 的行数是 `2`、列数是 `3` + +### `arrayToFm`、`matrixToArray` 与单元格类型转换 + +代码块身份：可直接照写示例 + +```tsl +a1 := array(1, 2, 3.5); +f1 := arrayToFm(a1, 0); +f2 := arrayToFm(a1, 0.0); +f3 := int64(fmarray[1, 2, 3]); +a2 := matrixToArray(fmarray[[1, 2], [3, 8]]); +writeLn(dataType(f1, 1)); +writeLn(f1[0], ',', f1[1], ',', f1[2]); +writeLn(dataType(f2, 1)); +writeLn(f2[0], ',', f2[1], ',', f2[2]); +writeLn(dataType(f3, 1)); +writeLn(f3[0], ',', f3[1], ',', f3[2]); +writeLn(mrows(a2)); +writeLn(mcols(a2)); +writeLn(a2[0][0], ',', a2[0][1], ',', a2[1][0], ',', a2[1][1]); +``` + +结果说明： + +- `arrayToFm(a1, 0)` 的单元格类型是 `0`，结果是 `1,2,3` +- `arrayToFm(a1, 0.0)` 的单元格类型是 `1`，结果是 `1,2,3.5` +- `int64(fmarray[1, 2, 3])` 的单元格类型是 `20` +- `matrixToArray(fmarray[[1, 2], [3, 8]])` 返回一个 `2 x 2` 的 `Array`，内容是 `(1,2)`、`(3,8)` + +### 尺寸与重构 + +二维和三维尺寸： + +代码块身份：可直接照写示例 + +```tsl +f3 := fmarray[[[1, 1], [2, 2], [3, 3]], [[2, 2], [3, 3], [4, 4]]]; +s := msize(f3); +writeLn(length(s)); +writeLn(s[0], ',', s[1], ',', s[2]); +``` + +结果说明： + +- `msize(f3)` 的长度是 `3` +- 三个维度依次是 `2`、`3`、`2` + +`reshape` 会保持 `FMArray` 类型： + +代码块身份：可直接照写示例 + +```tsl +f1 := fmarray[[1, 2], [3, 4], [5, 5]]; +r1 := reshape(f1, 6); +writeLn(dataType(r1)); +writeLn(length(r1)); +writeLn(r1[0], ',', r1[1], ',', r1[2], ',', r1[3], ',', r1[4], ',', r1[5]); +``` + +结果说明： + +- `dataType(r1)` 仍然是 `27` +- `r1` 的长度是 `6` +- 元素依次是 `1`、`2`、`3`、`4`、`5`、`5` + +### 标量运算与基础算符 + +代码块身份：可直接照写示例 + +```tsl +f1 := fmarray[1, 2, 3]; +f2 := fmarray[2, 3, 4]; +a1 := array(2, 3, 4); +s0 := f1 + 1; +s1 := f1 + f2; +s2 := f1 + a1; +writeLn(dataType(s0)); +writeLn(s0[0], ',', s0[1], ',', s0[2]); +writeLn(dataType(s1)); +writeLn(s1[0], ',', s1[1], ',', s1[2]); +writeLn(dataType(s2)); +writeLn(s2[0], ',', s2[1], ',', s2[2]); +``` + +结果说明： + +- `f1 + 1` 的 `dataType` 是 `27`，结果是 `2,3,4` +- `f1 + f2` 的 `dataType` 是 `27`，结果是 `3,5,7` +- `f1 + array(2, 3, 4)` 的 `dataType` 仍是 `27`，结果也是 `3,5,7` + +### `union2` 与左值类型 + +代码块身份：可直接照写示例 + +```tsl +f1 := fmarray[1, 2, 0, 4, 5]; +a1 := array(1, 0, 7.2); +u1 := f1 union2 a1; +u2 := a1 union2 f1; +writeLn(dataType(u1)); +writeLn(dataType(u1, 1)); +writeLn(length(u1)); +writeLn(u1[0], ',', u1[1], ',', u1[2], ',', u1[3], ',', u1[4], ',', u1[5]); +writeLn(dataType(u2)); +writeLn(length(u2)); +writeLn(u2[0], ',', u2[1], ',', u2[2], ',', u2[3], ',', u2[4], ',', u2[5]); +``` + +结果说明： + +- `union2` 的结果 `dataType` 是 `27` +- `f1 union2 array(1, 0, 7.2)` 的单元格类型会提升为 `1` 浮点型 +- `f1 union2 array(1, 0, 7.2)` 的长度是 `6`，结果是 `1,2,0,4,5,7.2` +- `array(1, 0, 7.2) union2 f1` 的 `dataType` 是 `5` +- `array(1, 0, 7.2) union2 f1` 的长度也是 `6`，结果是 `1,0,7.2,2,4,5` + +### 多维转置与维度交换 + +三维 `FMArray` 上，反引号转置会把全部维度倒置： + +代码块身份：可直接照写示例 + +```tsl +f3 := fmarray[[[1], [2]], [[1], [0]], [[3], [-8]]]; +t := `f3; +s := msize(t); +writeLn(dataType(t)); +writeLn(length(s)); +writeLn(s[0], ',', s[1], ',', s[2]); +writeLn(t[0,0,0], ',', t[0,0,1], ',', t[0,0,2], ';', t[0,1,0], ',', t[0,1,1], ',', t[0,1,2]); +``` + +结果说明： + +- 原矩阵尺寸是 `3,2,1`，转置后尺寸是 `1,2,3` +- 结果 `dataType` 仍是 `27` +- 转置后的内容是 `[[[1,1,3],[2,0,-8]]]` + +只交换指定维度时，使用 `mswap`： + +代码块身份：可直接照写示例 + +```tsl +f3 := fmarray[[[1], [2]], [[1], [0]], [[3], [-8]]]; +t := mswap(f3, 0, 1); +s := msize(t); +writeLn(dataType(t)); +writeLn(length(s)); +writeLn(s[0], ',', s[1], ',', s[2]); +writeLn(t[0,0,0], ',', t[0,1,0], ',', t[0,2,0], ';', t[1,0,0], ',', t[1,1,0], ',', t[1,2,0]); +``` + +结果说明： + +- `mswap(f3, 0, 1)` 后尺寸是 `2,3,1` +- 结果 `dataType` 仍是 `27` +- 结果内容是 `[[[1],[1],[3]],[[2],[0],[-8]]]` + +### 矩阵连接 / 矩阵并右方：`union`、`|`、`:|` + +`union` 会按行拼接，不做去重： + +代码块身份：可直接照写示例 + +```tsl +t1 := fmarray[[1, 2], [3, 4], [5, 5]]; +t2 := fmarray[[7, 8]]; +u := t1 union t2; +writeLn(dataType(u)); +writeLn(mrows(u)); +writeLn(mcols(u)); +writeLn(u[0,0], ',', u[0,1], ';', u[1,0], ',', u[1,1], ';', u[2,0], ',', u[2,1], ';', u[3,0], ',', u[3,1]); +``` + +结果说明： + +- `union` 的结果 `dataType` 是 `27` +- `t1 union t2` 的行数是 `4`、列数是 `2` +- 拼接后四行依次是 `(1,2)`、`(3,4)`、`(5,5)`、`(7,8)` + +`|` 和 `:|` 会执行矩阵并右方，也就是按列拼接： + +代码块身份：可直接照写示例 + +```tsl +t1 := fmarray[[1, 2], [3, 4], [5, 5]]; +t2 := fmarray[[3, 4], [7, 8], [6, 9]]; +u1 := t1 | t2; +u2 := t1 :| t2; +writeLn(dataType(u1)); +writeLn(mrows(u1)); +writeLn(mcols(u1)); +writeLn(u1[0,0], ',', u1[0,1], ',', u1[0,2], ',', u1[0,3]); +writeLn(u1[1,0], ',', u1[1,1], ',', u1[1,2], ',', u1[1,3]); +writeLn(u1[2,0], ',', u1[2,1], ',', u1[2,2], ',', u1[2,3]); +writeLn(u2[0,0], ',', u2[0,1], ',', u2[0,2], ',', u2[0,3]); +writeLn(u2[1,0], ',', u2[1,1], ',', u2[1,2], ',', u2[1,3]); +writeLn(u2[2,0], ',', u2[2,1], ',', u2[2,2], ',', u2[2,3]); +``` + +代码块身份：输出片段 + +```text +27 +3 +4 +1,2,3,4 +3,4,7,8 +5,5,6,9 +1,2,3,4 +3,4,7,8 +5,5,6,9 +``` + +结果说明： + +- `|` 的结果 `dataType` 是 `27` +- `t1 | t2` 和 `t1 :| t2` 的行数都是 `3`、列数都是 `4` +- 两种写法的结果都依次是 `(1,2,3,4)`、`(3,4,7,8)`、`(5,5,6,9)` + +行数不一致时，`|` 和 `:|` 在 `FMArray` 上表现一致，缺失行会用 `0` 补齐。 + +代码块身份：可直接照写示例 + +```tsl +m1 := fmarray[[1, 2], [3, 4], [5, 5]] | fmarray[[3, 4]]; +m2 := fmarray[[3, 4]] | fmarray[[1, 2], [3, 4], [5, 5]]; +writeLn(m1[0,0], ',', m1[0,1], ',', m1[0,2], ',', m1[0,3]); +writeLn(m1[1,0], ',', m1[1,1], ',', m1[1,2], ',', m1[1,3]); +writeLn(m1[2,0], ',', m1[2,1], ',', m1[2,2], ',', m1[2,3]); +writeLn(m2[0,0], ',', m2[0,1], ',', m2[0,2], ',', m2[0,3]); +writeLn(m2[1,0], ',', m2[1,1], ',', m2[1,2], ',', m2[1,3]); +writeLn(m2[2,0], ',', m2[2,1], ',', m2[2,2], ',', m2[2,3]); +``` + +代码块身份：输出片段 + +```text +1,2,3,4 +3,4,0,0 +5,5,0,0 +3,4,1,2 +0,0,3,4 +0,0,5,5 +``` + +- `fmarray[[1, 2], [3, 4], [5, 5]] | fmarray[[3, 4]]` 的结果三行依次是 `(1,2,3,4)`、`(3,4,0,0)`、`(5,5,0,0)` +- `fmarray[[3, 4]] | fmarray[[1, 2], [3, 4], [5, 5]]` 的结果三行依次是 `(3,4,1,2)`、`(0,0,3,4)`、`(0,0,5,5)` +- 把上面两条里的 `|` 改成 `:|`，结果一致 + +### 排序 + +一维排序： + +代码块身份：可直接照写示例 + +```tsl +s1 := fmarray[10, 2, -3, 8]; +sortArray(s1); +writeLn(s1[0], ',', s1[1], ',', s1[2], ',', s1[3]); +``` + +结果说明： + +- 排序后结果是 `-3,2,8,10` + +二维按字段排序： + +代码块身份：可直接照写示例 + +```tsl +f1 := fmarray[[11, 12], [31, 4], [5, 5]]; +sortTableByField(f1, 0, 1); +writeLn(f1[0,0], ',', f1[0,1], ';', f1[1,0], ',', f1[1,1], ';', f1[2,0], ',', f1[2,1]); +``` + +结果说明： + +- 排序后依次是 `(5,5)`、`(11,12)`、`(31,4)` + +### TS-SQL 对 `FMArray` 的支持 + +代码块身份：可直接照写示例 + +```tsl +q1 := select * from fmarray[[1, 2], [0, 4], [1, 2], [5, 6]] end; +q2 := mselect * from fmarray[[1, 2], [0, 4], [1, 2], [5, 6]] end; +writeLn(dataType(q1)); +writeLn(mrows(q1)); +writeLn(dataType(q2)); +writeLn(mrows(q2)); +writeLn(mcols(q2)); +``` + +结果说明： + +- 普通 `select` 的返回 `dataType` 是 `5` +- `q1` 的行数是 `4` +- `mselect` 的返回 `dataType` 是 `17` +- `q2` 的行数是 `4`、列数是 `2` +- 说明对 `FMArray` 做 TS-SQL 查询时，结果不会保留 `dataType=27` + +### `insert` / `delete` / `update` + +`insert`： + +代码块身份：可直接照写示例 + +```tsl +a := mInit(2, 3, 1.0); +insert into a array(9); +writeLn(mrows(a)); +writeLn(mcols(a)); +writeLn(a[2,0], ',', a[2,1], ',', a[2,2]); +``` + +结果说明： + +- 插入后行数是 `3` +- 列数仍是 `3` +- 新插入的第三行是 `9,9,9` + +`delete`： + +代码块身份：可直接照写示例 + +```tsl +d := fmarray[[1, 2], [0, 4], [5, 6]]; +delete from d where [1] = 4; +writeLn(mrows(d)); +writeLn(d[0,0], ',', d[0,1], ';', d[1,0], ',', d[1,1]); +``` + +结果说明： + +- 删除后行数是 `2` +- 保留的两行是 `(1,2)`、`(5,6)` + +`update`： + +代码块身份：可直接照写示例 + +```tsl +u := fmarray[[1, 2], [0, 4], [5, 6]]; +update u set [0] = 100 where [1] = 4 end; +writeLn(mrows(u)); +writeLn(u[0,0], ',', u[0,1], ';', u[1,0], ',', u[1,1], ';', u[2,0], ',', u[2,1]); +``` + +结果说明： + +- 更新后行数仍是 `3` +- 结果三行依次是 `(1,2)`、`(100,4)`、`(5,6)` + +这三种写法的收尾形式为： + +- `insert into a array(9);` +- `delete from d where [1] = 4;` +- `update u set [0] = 100 where [1] = 4 end;` + +## 本页不生成的范围 + +- `mInitDiag` 更高维行为 +- `mRand` 的随机分布参数变体 +- `union` / `|` / `:|` 与普通 `array` 的更多混合边界 +- `left join` / `right join` / 更复杂 SQL 写回 +- CopyOnWrite 的内存级行为 + +这些不作为本页可生成事实。 + +## 默认生成模板 + +需要 `FMArray` 常量时，优先从这个最短模板开始： + +代码块身份：可直接照写示例 + +```tsl +f := fmarray[1, 2, 3]; +``` + +## 禁止项 + +- 在一个 `FMArray` 常量里混用不同单元格类型。 +- 把 `FMArray` 当成支持字符串下标的 `array`。 +- 以为对 `FMArray` 做普通 `select` 后，结果还是 `dataType=27`。 +- 把 `delete` 和 `update` 的结尾形式写成同一种。 +- 以为 `union` 可以忽略列结构差异。 +- 以为 `array union2 fmarray` 还会返回 `FMArray`。 + +代码块身份：反例 / 不可照写 + +```text +f := fmarray[1, 2.0, 3]; +``` + +上面这种写法不作为可写事实，会编译失败，错误信息包含 `fmarray must be same type`。 + +代码块身份：反例 / 不可照写 + +```text +f := fmarray[1, 2, 3]; +writeLn(f["A"]); +``` + +上面这种写法不作为可写事实，会运行报错，错误信息包含 `fmarray index type error`。 + +代码块身份：反例 / 不可照写 + +```text +delete from d where [1] = 4 end; +``` + +这类写法不要直接当成默认模板。`delete ... end;` 会报 `Statement missing terminator`；文档明确写法是 `delete ...;`。 + +代码块身份：反例 / 不可照写 + +```text +t1 := fmarray[[1, 2], [3, 4]]; +t2 := fmarray[[7, 8, 9]]; +u := t1 union t2; +``` + +上面这种写法会运行报错，错误信息包含 `union dim dismatch`。本页明确的 `union` 只适用于列结构兼容的 `FMArray`。 diff --git a/docs/tsl/syntax/23_object_runtime_and_introspection.md b/docs/tsl/syntax/23_object_runtime_and_introspection.md deleted file mode 100644 index baef551c..00000000 --- a/docs/tsl/syntax/23_object_runtime_and_introspection.md +++ /dev/null @@ -1,413 +0,0 @@ -# Object Runtime And Introspection - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：否 -遇到不确定时跳转到：[09_objects_and_classes.md](09_objects_and_classes.md)、[24_builtin_runtime_objects.md](24_builtin_runtime_objects.md)、[32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) - -手册位置：第 23 篇，共 32 篇。上一篇：[22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md)。下一篇：[24_builtin_runtime_objects.md](24_builtin_runtime_objects.md)。 - -这一篇收拢对象模型里不适合继续堆在基础类主线里的运行时内容：类信息、函数句柄、对象状态、引用计数、运行时对象枚举。 - -## 这一篇解决什么问题 - -回答“类已经会声明、继承、构造之后，怎样检查类信息、函数信息和对象运行时状态”。 - -## Agent 对象运行时/反射判断流程 - -1. 先判断要做类查找、函数查找、对象检查，还是运行时成员访问。 -2. 反射入口优先照 `FindClass`、`FindFunction` 等已验证示例写。 -3. 对象模型本身回看 `09_objects_and_classes.md`，不要在运行时页发明类声明语法。 -4. 函数值调用边界回看函数页，避免把函数指针直接当普通函数调用。 -5. 没有已验证代码块时不要发明对象运行时/反射写法。 - -## 必须记住的规则 - -- 对象值当前可以用 `ifObj(...)` 做显式判定。 -- `class(Name)` 和 `FindClass("Name")` 当前都可以拿到类类型。 -- `obj is classType` 当前已验证可直接拿类类型变量来做实例判定。 -- `FindClass("ParentName", obj)` 当前已验证可以把实例对象降成指定父类视图。 -- `obj.ClassInfo(1)` 当前已验证会返回类类型，并且这个类类型可以继续交给 `CreateObject(...)`。 -- `obj.ClassInfo()` 当前至少已验证可以直接读出 `["classname"]`。 -- `objectstate(self)` 在构造函数内部的最小已验证结果是 `1`；构造结束后对实例再取 `objectstate(obj)` 的最小已验证结果是 `2`。 -- `tslassigning` 在属性写入函数里输出 `1`，在属性读取函数里输出 `0`。 -- `FindFunction("MethodName", obj)` 当前已验证可以拿到实例方法句柄。 -- `FindFunction("MethodName", class(A))` 当前已验证可以拿到类方法句柄。 -- `ThisFunction(obj.Method)` 和 `ThisFunction(class(A).Method)` 当前也已验证可用。 -- 当前最稳的句柄调用方式是 `f.do(...)`。 -- `FindOverLoad(argc, "Name", obj)` 当前已验证可以按参数个数取到对应重载方法。 -- `FunctionInfo` 当前至少已验证可以读出 `functionname`、`returntype`、`classname` 这几个字段。 -- `TSLObjects(1)` 当前已验证会按类名分组返回对象信息，并且分组项里的 `"obj"` 字段可以重新拿到可调用对象。 -- 对象赋值会延长对象存活；当前最小样例里，只有最后一个引用清空后才会触发 `destroy()`。 - -## 已验证语法 - -对象值的最小显式判定： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - obj := CreateObject("TStringList"); - WriteLn(ifObj(obj)); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明 `CreateObject(...)` 得到的对象值当前可以用 `ifObj(...)` 判定 - -代码块身份：已验证输出片段 - -```text -1 -``` - -`FindClass(...)` 与类类型变量： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - class function FucA(); - begin - return "ClassA"; - end; -end; -begin - classA := FindClass("A"); - obj := new A(); - WriteLn(classA.FucA()); - WriteLn(obj is classA); -end. -``` - -已验证运行结果： - -- 依次输出 `ClassA`、`1` -- 说明 `FindClass("A")` 当前可以拿到类类型 -- 说明类类型变量可以直接调用类方法 -- 也说明 `obj is classA` 这种“实例对类类型变量做判定”的写法当前可用 - -`FindClass("Parent", obj)` 的父类视图： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type ClassA = class - function Fuc(); virtual; - begin - return "ClassA"; - end; -end; -type ClassB = class(ClassA) - function Fuc(); override; - begin - return "ClassB"; - end; -end; -begin - objb := new ClassB(); - obj := FindClass("ClassA", objb); - WriteLn(obj.Fuc()); -end. -``` - -已验证运行结果： - -- 输出 `ClassA` -- 说明 `FindClass("ClassA", objb)` 当前可以把子类实例降成父类视图 -- 也说明之后的方法分派会按父类视图执行 - -`ClassInfo(1)` 返回类类型： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - value; -end; -begin - obj := new A(); - cls := obj.ClassInfo(1); - obj2 := CreateObject(cls); - WriteLn(obj2 is class(A)); -end. -``` - -已验证运行结果： - -- 输出 `1` -- 说明 `obj.ClassInfo(1)` 当前可以返回类类型 -- 也说明这个类类型可以继续交给 `CreateObject(...)` - -`ClassInfo()` 返回的映射字段： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class -end; -begin - obj := new A(); - info := obj.ClassInfo(); - WriteLn(info["classname"]); -end. -``` - -已验证运行结果： - -- 输出 `a` -- 说明 `ClassInfo()` 当前至少可以直接读出 `["classname"]` -- 当前这个最小例子里，类名表现为小写标识符 - -`objectstate(...)`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type ca = class - static sca; - function create(n); - begin - sca := self; - WriteLn(objectstate(self)); - end; -end; -begin - oa := new ca("abc"); - WriteLn(objectstate(oa)); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`2` -- 说明当前最小样例里，构造函数内部对象状态是 `1` -- 构造结束后，再对实例取 `objectstate(...)` 会得到 `2` - -`tslassigning`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type ca = class - value; - property c read getc write setc; - function setc(v); - begin - WriteLn(tslassigning); - value := v; - end; - function getc(); - begin - WriteLn(tslassigning); - return value; - end; -end; -begin - o := new ca(); - o.c := 3; - WriteLn(o.c); -end. -``` - -已验证运行结果： - -- 依次输出 `1`、`0`、`3` -- 说明属性写入函数里 `tslassigning` 为 `1` -- 属性读取函数里 `tslassigning` 为 `0` - -`FindFunction(...)` 查找实例方法和类方法： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - function Add(x, y); - begin - return x + y; - end; - class function AddClass(x, y); - begin - return x + y; - end; -end; -begin - obj := new A(); - f1 := FindFunction("Add", obj); - f2 := FindFunction("AddClass", class(A)); - WriteLn(f1.do(3, 4)); - WriteLn(f2.do(5, 6)); -end. -``` - -已验证运行结果： - -- 依次输出 `7`、`11` -- 说明 `FindFunction(..., obj)` 当前能拿到实例方法句柄 -- 说明 `FindFunction(..., class(A))` 当前能拿到类方法句柄 -- 也说明句柄调用方式 `f.do(...)` 当前稳定可用 - -`ThisFunction(...)` 也可以直接拿方法句柄： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - function Add(x, y); - begin - return x + y; - end; - class function AddClass(x, y); - begin - return x + y; - end; -end; -begin - obj := new A(); - f1 := ThisFunction(obj.Add); - f2 := ThisFunction(class(A).AddClass); - WriteLn(f1.do(3, 4)); - WriteLn(f2.do(5, 6)); -end. -``` - -已验证运行结果： - -- 依次输出 `7`、`11` -- 说明 `ThisFunction(...)` 当前也可以稳定得到实例方法和类方法句柄 - -`FindOverLoad(...)`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TestClass = class - function fun(p1, p2); overload; - begin - return p1 + p2; - end; - function fun(p1); overload; - begin - return p1 + 10; - end; -end; -begin - t := FindOverLoad(2, "fun", CreateObject("TestClass")); - WriteLn(t.do(1, 2)); -end. -``` - -已验证运行结果： - -- 输出 `3` -- 说明 `FindOverLoad(2, "fun", obj)` 当前可以按参数个数拿到对应重载方法 - -`FunctionInfo` 的最小已验证字段： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type A = class - class function Add(a: lhs; b: rhs): sum_t; - begin - return a + b; - end; -end; -begin - f := ThisFunction(class(A).Add); - info := f.FunctionInfo; - WriteLn(info["functionname"]); - WriteLn(info["returntype"]); - WriteLn(info["classname"]); -end. -``` - -已验证运行结果： - -- 依次输出 `add`、`sum_t`、`a` -- 说明 `FunctionInfo["functionname"]`、`["returntype"]`、`["classname"]` 当前都可直接读取 -- 当前这个最小例子里，返回的函数名和类名表现为小写标识符 - -`TSLObjects(1)`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TestClass01 = class - value; - function create(_value); - begin - value := _value; - end; - class function add(x, y); - begin - return x + y; - end; -end; -begin - objA := new TestClass01(100); - objB := new TestClass01(101); - objsInfo := TSLObjects(1); - WriteLn(length(objsInfo["TestClass01"])); - newObjA := objsInfo["TestClass01"][0, "obj"]; - WriteLn(newObjA is class(TestClass01)); - WriteLn(newObjA.add(1, 2)); -end. -``` - -已验证运行结果： - -- 依次输出 `2`、`1`、`3` -- 说明 `TSLObjects(1)` 当前可以按类名拿到对象分组 -- 分组项里的 `"obj"` 字段当前可以重新拿到可调用对象 - -引用计数的最小行为： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type T1 = class - function destroy(); - begin - WriteLn("destroy"); - end; -end; -begin - o1 := new T1(); - o2 := o1; - o1 := 0; - WriteLn("O1 to Zero"); - o2 := 0; - WriteLn("O2 to Zero"); -end. -``` - -已验证运行结果： - -- 依次输出 `O1 to Zero`、`destroy`、`O2 to Zero` -- 说明只清空第一个别名时对象还不会释放 -- 最后一个引用清空后才会触发 `destroy()` - -## 跳转指引 - -- 回看类的基础语法：见 [09_objects_and_classes.md](09_objects_and_classes.md) -- 回看函数值与基础调用：见 [06_functions_and_calls.md](06_functions_and_calls.md) -- 看运行时内置对象：见 [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) -- 看对象算符重载：见 [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) diff --git a/docs/tsl/syntax/24_builtin_runtime_objects.md b/docs/tsl/syntax/24_builtin_runtime_objects.md deleted file mode 100644 index 5dc7d7b1..00000000 --- a/docs/tsl/syntax/24_builtin_runtime_objects.md +++ /dev/null @@ -1,183 +0,0 @@ -# Builtin Runtime Objects - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：否 -遇到不确定时跳转到：[23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md)、[30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 24 篇，共 32 篇。上一篇：[23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md)。下一篇：[25_set_operations.md](25_set_operations.md)。 - -这一篇只收当前解释器下已经实际跑通的运行时内置对象最小模型。这里讲的是语言运行时对象，不是金融业务 API。 - -## 这一篇解决什么问题 - -回答“写普通 TSL/TSF 脚本时，哪些内置对象可以直接创建，最小可用接口是什么，哪些对象其实依赖特定运行上下文”。 - -## Agent 内置运行时对象判断流程 - -1. 先判断要访问哪个内置运行时对象，以及它是不是语言对象而非业务 API。 -2. 只照本页已验证的最小读写路径使用内置对象。 -3. 不要把金融业务上下文对象和语言运行时对象混在一起。 -4. 需要系统参数或 `with` 后缀时跳转到运行时上下文页。 -5. 没有已验证代码块时不要发明内置运行时对象写法。 - -## 必须记住的规则 - -- 当前 CLI 里，`TStringList` 已验证可以直接 `CreateObject("TStringList")` 创建。 -- `TStringList` 当前已验证支持数字下标、字符串键下标、`Count` 和 `Add(...)`。 -- 流对象应先按 `TStream` 家族理解；当前 CLI 里最小可靠入口是 `TMemoryStream` 这种具体类型。 -- 当前 CLI 里，直接 `CreateObject("TStream")` 会失败，错误信息包含 `function:tstream compile error or not found`。 -- `TMemoryStream` 当前已验证支持 `Write(...)`、`Read(...)`、`Position`、`Size`。 -- `TCipher` 当前不是“无参即可创建”的对象；`CreateObject("TCipher")` 会失败。 -- `TCipher` 当前已验证可用的最小写法是 `CreateObject("TCipher", 2)`，然后设置 `Password` 再做 `Encrypt(...)` / `Decrypt(...)`。 -- `TWebRequest` 和 `TWebResponse` 在当前 CLI 环境里没有通过直接 `CreateObject(...)` 的最小样例。 -- 因此，WEB 请求 / 响应对象不要直接写进普通命令行脚本模板；它们应视为特定运行上下文对象。 - -## 已验证语法 - -### `TStringList` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - obj := CreateObject("TStringList"); - obj.CommaText := "A=aaa,B=bbb,C=222"; - WriteLn(obj[1]); - WriteLn(obj["B"]); - WriteLn(obj.Count); - obj.Add("D=444"); - WriteLn(obj.Count); -end. -``` - -已验证运行结果： - -- 依次输出 `B=bbb`、`bbb`、`3`、`4` -- 说明当前既可以按数字下标取整行，也可以按键名取 `Name=Value` 里的值 - -代码块身份：已验证输出片段 - -```text -B=bbb -bbb -3 -4 -``` - -### `TStream` 家族的最小可靠入口：`TMemoryStream` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - mem := CreateObject("TMemoryStream"); - buffer := "ABC"; - mem.Write(buffer, 3); - mem.Position := 0; - outbuf := "xxx"; - mem.Read(outbuf, 3); - WriteLn(outbuf); - WriteLn(mem.Size); - try - base := CreateObject("TStream"); - WriteLn(ifObj(base)); - except - WriteLn("TStreamError"); - WriteLn(ExceptObject.ErrInfo); - end; -end. -``` - -已验证运行结果： - -- 前两行输出 `ABC`、`3` -- 后两行输出 `TStreamError`，以及包含 `function:tstream compile error or not found` 的错误信息 -- 说明当前 CLI 里应优先使用 `TMemoryStream` 这类具体流对象，不要把裸 `TStream` 当成可直接创建对象 - -### `TCipher` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - try - bad := CreateObject("TCipher"); - WriteLn("NoArg"); - WriteLn(ifObj(bad)); - except - WriteLn("NoArgError"); - WriteLn(ExceptObject.ErrInfo); - end; - - cipher := CreateObject("TCipher", 2); - cipher.Password := "Tinysoft"; - enc := cipher.Encrypt("abc"); - WriteLn(enc <> "abc"); - WriteLn(cipher.Decrypt(enc)); -end. -``` - -已验证运行结果： - -- 前两行输出 `NoArgError`，以及包含 `New Class tcipher Error.` 的错误信息 -- 后两行输出 `1`、`abc` -- 说明 `TCipher` 当前必须按“带模式参数创建”来写，随后可稳定走 `Password -> Encrypt -> Decrypt` - -### `TWebRequest` / `TWebResponse` 的 CLI 边界 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - try - req := CreateObject("TWebRequest"); - WriteLn("ReqOk"); - WriteLn(ifObj(req)); - except - WriteLn("ReqError"); - WriteLn(ExceptObject.ErrInfo); - end; - - try - resp := CreateObject("TWebResponse"); - WriteLn("RespOk"); - WriteLn(ifObj(resp)); - except - WriteLn("RespError"); - WriteLn(ExceptObject.ErrInfo); - end; -end. -``` - -已验证运行结果： - -- 先输出 `ReqError`，随后错误信息包含 `function:twebrequest compile error or not found` -- 再输出 `RespError`，随后错误信息包含 `function:twebresponse compile error or not found` -- 说明当前 CLI 环境下，WEB 请求 / 响应对象不能直接按普通 `CreateObject(...)` 脚本对象来写 - -## 暂不在本页展开的对象 - -- `TFileStream` -- `TIniFile` -- `TMemIniFile` -- `THashedStringList` -- `TRSA` -- `FTP` / `SMTP` / `POP3` -- `MailMsg` / `MessagePart` -- `TCookie` / `TCookieCollection` -- `TSessionMan` / `TSession` - -这些对象旧资料里都出现过，但当前这一篇先只保留“新 session 最容易直接用到”的最小主干。需要把其中某个对象升级进主线正文时，应先补最小脚本再写结论。 - -## 跳转指引 - -- 回看对象主线：见 [09_objects_and_classes.md](09_objects_and_classes.md) -- 看对象运行时反射：见 [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) -- 看运行时服务与缓存：见 [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) -- 看对象重载与遍历：见 [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) diff --git a/docs/tsl/syntax/24_object_overloads_and_iteration.md b/docs/tsl/syntax/24_object_overloads_and_iteration.md new file mode 100644 index 00000000..543c1647 --- /dev/null +++ b/docs/tsl/syntax/24_object_overloads_and_iteration.md @@ -0,0 +1,325 @@ +# TSL 对象重载与迭代 + +文档类型：语法深水专题 +是否可直接用于生成代码：仅部分 +是否含可直接照写示例：是 +是否含不可照写反例：否 +遇到不确定时：先按本页候选页继续判断；[08_objects_and_classes.md](08_objects_and_classes.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[17_types_and_conversions.md](17_types_and_conversions.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md) + +这一篇只讲对象直接参与语言级操作的文档能力：基础算符重载、`[]` 重载、`for in` 重载，以及 `mrows` / `mcols` / `msize` 这类矩阵关键字重载。 + +## 本篇职责 + +回答“当类不只是普通对象，而要直接参与 `obj + x`、`obj[index]`、`for v in obj`、`mrows(obj)` 这类语言级操作时，支持哪些文档明确写法”。 + +## 智能体对象重载/迭代判断流程 + +1. 先判断要重载二元算符、下标、`for in`，还是矩阵尺寸函数。 +2. 对象重载只照本页明确的 `operator` 签名写，不要从未写入文档资料扩展未知重载。 +3. 普通对象模型先回看 `08_objects_and_classes.md`，不要在重载页发明类基础语法。 +4. 未列入本页主干的重载族不要写成语法事实。 +5. 没有对应代码块时不要发明对象重载/迭代写法。 + +## 核心规则 + +- 对象二元算符重载的最小可靠形态是成员方法 `function operator + (data);` 这一类写法。 +- 比较算符可写成 `function operator < (data, isLeft);`，用 `isLeft` 区分对象在左边还是右边。 +- 对象 `[]` 读取有两种文档明确写法：`function operator[](index);` 和 `function operator[0](index, s1);`。 +- 对象 `[]` 写入的文档明确写法是 `function operator[1](index, v);`。 +- `function operator for(flag);` 可以重载 `for in`。 +- 在 `operator for(flag)` 里，`flag .& 2` 可用来区分“一个循环变量”还是“两个循环变量”，`flag .& 1` 可用来区分“第一次进入”还是“继续迭代”。 +- `mrows` / `mcols` / `msize` 可以在类里先声明 `function operator mrows(n);` 这类签名，再在类外实现 `function operator ClassName.mrows(n);`。 +- 可用形态包括 `mrows(obj)`、`mcols(obj)`、`msize(obj)` 这类关键字调用，以及 `obj.mcols(1)` 这类对象方法式调用。 +- `function operator++(v);` 和 `function operator += (v);` 也可用。 +- 不要把未写入文档资料里的裸 `function operator;` / `function operator1;`，或未列入本页的 `mcell` / `mrow` / `mcol` / `::` / `:.` 重载，直接当成语法事实。 + +## 可直接照写示例 + +### 二元算符重载 + +代码块身份：可直接照写示例 + +```tsl +t1 := new TComplex(); +t1.vReal := 10; +t1.vImaginary := 100; +t2 := t1 + 10; +writeLn(t2.vReal); +writeLn(t1 < 5); +writeLn(t1 < 300); +writeLn(5 < t1); + +type TComplex = class +public + vReal; + vImaginary; + function operator + (data); + begin + r := new TComplex(); + if ifNumber(data) then + begin + r.vReal := vReal + data; + end + else + begin + r.vReal := vReal + data.vReal; + r.vImaginary := vImaginary + data.vImaginary; + end + return r; + end; + function operator < (data, isLeft); + begin + if ifNumber(data) then + begin + v := vReal < data; + end + else + begin + v := (vReal ^ 2 + vImaginary ^ 2) < data.vReal ^ 2 + data.vImaginary ^ 2; + end + if not isLeft then v := not v; + return v; + end; +end; +``` + +结果说明： + +- 依次输出 `20`、`0`、`1`、`1` +- 说明 `obj + value` 可以通过成员 `operator +` 接管 +- 说明带 `isLeft` 的比较算符可以同时处理 `obj < value` 和 `value < obj` + +代码块身份：输出片段 + +```text +20 +0 +1 +1 +``` + +### `[]` 重载：`operator[]` / `operator[1]` + +代码块身份：可直接照写示例 + +```tsl +t := array(1, 2, 3, 4, 5); +b := new bb(t); +writeLn(b[2]); +b[3] := 999; +writeLn(b.data[3]); + +type bb = class +public + data; + function create(v); + begin + data := v; + end; + function operator[](index); + begin + return data[index]; + end; + function operator[1](index, v); + begin + data[index] := v; + end; +end; +``` + +结果说明： + +- 依次输出 `3`、`999` +- 说明 `operator[]` 和 `operator[1]` 可以完成单层下标读取和写入 + +### `[]` 重载：`operator[0]` / `operator[1]` + +沿用上一段的 `bb` 类与测试主体，只把读取签名从 `function operator[](index);` 改成 `function operator[0](index, s1);`： + +代码块身份：配置片段 / 概念骨架 + +```tsl +type bb = class +public + // 其余字段、create()、operator[1] 和测试主体同上一段 + function operator[0](index, s1); + begin + return data[index]; + end; +end; +``` + +结果说明： + +- 依次输出 `3`、`999` +- 说明 `operator[0]` / `operator[1]` 这组写法在单层下标场景同样可用 + +### `for in` 重载 + +代码块身份：可直接照写示例 + +```tsl +box := new Box(array("A", "B", "C")); +for v in box do + writeLn(v); +for i, v in box do + writeLn(i$":"$v); + +type Box = class +public + data; + findex; + function create(v); + begin + data := v; + end; + function operator for(flag); + begin + use_pair := flag .& 2; + again := flag .& 1; + if not again then + begin + findex := 0; + end + else if findex < length(data) - 1 then + begin + findex++; + end + else + begin + return nil; + end + + if use_pair then + return array(findex, data[findex]); + return data[findex]; + end; +end; +``` + +结果说明： + +- 单变量循环依次输出 `A`、`B`、`C` +- 双变量循环依次输出 `0:A`、`1:B`、`2:C` +- 说明 `operator for(flag)` 可以重载 `for in` +- 也说明同一个对象可以按返回值形态同时支持“单变量遍历”和“索引 + 值遍历” + +### `mrows` / `mcols` / `msize` 重载 + +代码块身份：可直接照写示例 + +```tsl +g := new GridWrap(); +writeLn(mrows(g)); +writeLn(mcols(g)); +sz := msize(g); +writeLn(sz[0]); +writeLn(sz[1]); +cols := g.mcols(1); +writeLn(cols[0]); +writeLn(cols[1]); +writeLn(cols[2]); + +type GridWrap = class +public + data; + function create(); + begin + data := array( + ("A": 1, "B": 2, "C": 3), + ("A": 4, "B": 5, "C": 6) + ); + end; + function operator mrows(n); + function operator mcols(n); + function operator msize(n); +end; + +function operator GridWrap.mrows(n); +begin + _n := ifNil(n) ? 0 : n; + return mrows(data, _n); +end; + +function operator GridWrap.mcols(n); +begin + _n := ifNil(n) ? 0 : n; + return mcols(data, _n); +end; + +function operator GridWrap.msize(n); +begin + _n := ifNil(n) ? 0 : n; + return msize(data, _n); +end; +``` + +结果说明： + +- 依次输出 `2`、`3`、`2`、`3`、`A`、`B`、`C` +- 说明 `mrows(obj)`、`mcols(obj)`、`msize(obj)` 都可由对象重载接管 +- 说明对象方法式调用 `obj.mcols(1)` 也可继续取得列下标列表 + +### `++` 与 `+=` + +代码块身份：可直接照写示例 + +```tsl +b := new bb(10); +++b; +writeLn(b.data); +c := b++; +writeLn(c.data); +writeLn(b.data); +b += 5; +writeLn(b.data); + +type bb = class +public + data; + function create(v); + begin + data := v; + end; + function operator++(v); + begin + if v = 0 then + begin + r := new bb(); + r.data := data; + r.data++; + return r; + end + else + data++; + end; + function operator += (v); + begin + data += v; + end; +end; +``` + +结果说明： + +- 依次输出 `11`、`11`、`12`、`17` +- 说明前置 `++` 会直接修改对象状态 +- 说明这个最小样例里，后置 `b++` 返回的是递增前快照 +- 说明 `operator += (v)` 可以接管 `b += 5` + +## 本页不生成的范围 + +- `::` / `:.` 遍历重载 +- `mcell` / `mrow` / `mcol` / `mIndexCount` / `mIndex` +- 多级 `[]` 下标重载 +- 右侧算术如 `value + obj` +- 对基础二进制函数的大规模重载族 + +这些名称只作为边界提示，不作为本页可生成模板。 + +## 禁止项 + +- 不要从本页 `operator` 示例外推未写入文档的重载族。 +- 不要把 `mcell` / `mrow` / `mcol` / `::` / `:.` 直接写成可用语法。 +- 不要把多级 `[]` 下标重载或 `value + obj` 这类右侧算术写成文档事实。 +- 不要在本页发明普通类语法；基础对象模型回 [08_objects_and_classes.md](08_objects_and_classes.md)。 diff --git a/docs/tsl/syntax/25_set_operations.md b/docs/tsl/syntax/25_set_operations.md deleted file mode 100644 index 8ca95afa..00000000 --- a/docs/tsl/syntax/25_set_operations.md +++ /dev/null @@ -1,184 +0,0 @@ -# Set Operations - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[14_resultset_and_filters.md](14_resultset_and_filters.md)、[13_matrix_and_collections.md](13_matrix_and_collections.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 25 篇，共 32 篇。上一篇：[24_builtin_runtime_objects.md](24_builtin_runtime_objects.md)。下一篇：[26_matrix_deep_dive.md](26_matrix_deep_dive.md)。 - -这一篇只讲集合运算本身：`in`、`sqlin`、`union2`、`intersect`、`minus`、`outersect`。它和 [14_resultset_and_filters.md](14_resultset_and_filters.md) 的分工很明确: 这一篇讲“去重后的集合关系”，过滤页讲“按原结果集逐行保留或排除”。 - -## 这一篇解决什么问题 - -回答“某个元素是否在数组里、某组元素是否构成子集、某一行是否存在于结果集中，以及两个结果集如何做并集、交集、差集和对称差集”。 - -## Agent 集合运算判断流程 - -1. 先判断要写 `in`、`sqlin`、否定集合判断，还是结果集集合操作。 -2. 基础成员判断优先照表达式页和本页已验证示例写。 -3. `not in` 与 `not sqlin` 是已验证否定写法，不要改成未验证组合。 -4. 复杂查询或矩阵数据跳转到 TS-SQL / 矩阵页面。 -5. 没有已验证代码块时不要发明集合运算写法。 - -## 必须记住的规则 - -- `in` / `not in` 处理的是元素存在关系，以及左侧为数组时的子集关系。 -- `sqlin` / `not sqlin` 处理的是行存在关系；左侧要当成一整行去匹配右侧结果集。 -- `union2`、`intersect`、`minus`、`outersect` 都按“行”运算，而不是按单元格逐个运算。 -- 当前解释器支持 `not in` 和 `not sqlin` 这种否定写法。 -- 集合运算结果会折叠重复行；如果需求是保留重复记录，不要用这一篇的算符，改看 [14_resultset_and_filters.md](14_resultset_and_filters.md)。 -- 当数据本身就是一维数组时，按行集合运算和按元素集合运算是一致的。 - -## 已验证语法 - -### `in` 与 `not in` - -`in` 既可以判断单个元素是否存在，也可以判断左侧数组是否是右侧结果集的子集： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(1 in array(1, 2, 2)); - WriteLn(1 in array(0, 2)); - WriteLn(1 in array((1), (2))); - WriteLn(array(1, 2) in array(1, 2, 3, 4)); - WriteLn(array(1, 3) in array((1, 2), (3, 4))); - WriteLn(array(1, 2) in array(1)); - WriteLn(1 not in array(0, 2)); -end. -``` - -已验证运行结果： - -- `1 in array(1, 2, 2)` 输出 `1` -- `1 in array(0, 2)` 输出 `0` -- `1 in array((1), (2))` 输出 `1` -- `array(1, 2) in array(1, 2, 3, 4)` 输出 `1` -- `array(1, 3) in array((1, 2), (3, 4))` 输出 `1` -- `array(1, 2) in array(1)` 输出 `0` -- `1 not in array(0, 2)` 输出 `1` - -代码块身份：已验证输出片段 - -```text -1 -0 -1 -1 -``` - -### `sqlin` 与 `not sqlin` - -`sqlin` 改成按整行判断左侧是否存在于右侧结果集中： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - WriteLn(1 sqlin array(1, 2)); - WriteLn(array(1, 2) sqlin array(1, 2, 3)); - WriteLn(array(1, 2) sqlin array((1, 2), (3, 4))); - WriteLn(array(5, 6) not sqlin array((1, 2), (3, 4))); -end. -``` - -已验证运行结果： - -- `1 sqlin array(1, 2)` 输出 `1` -- `array(1, 2) sqlin array(1, 2, 3)` 输出 `0` -- `array(1, 2) sqlin array((1, 2), (3, 4))` 输出 `1` -- `array(5, 6) not sqlin array((1, 2), (3, 4))` 输出 `1` - -可以把两者的差异直接记成一句话： - -- `in` 看元素或子集 -- `sqlin` 看整行 - -### 行集合的并、交、差、对称差 - -下面这组最小例子同时验证了“按行运算”和“结果会折叠重复行”： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - A := array((1, 2), (1, 2), (2, 3)); - B := array((1, 2), (3, 4)); - U := A union2 B; - I := A intersect B; - M := A minus B; - O := A outersect B; -end. -``` - -已验证运行结果： - -- `A union2 B` 共有三行：`(1,2)`、`(2,3)`、`(3,4)` -- `A intersect B` 只有一行：`(1,2)` -- `A minus B` 只有一行：`(2,3)` -- `A outersect B` 有两行：`(2,3)`、`(3,4)` -- `A` 原本有两行相同的 `(1,2)`，但 `union2` / `intersect` 的结果都只保留一份，说明集合运算会折叠重复行 - -如果你需要看更大的四列结果集例子，当前解释器下也已经实测过： - -- `array((1,2,3,4),(2,3,4,5),(1,1,1,1)) union2 array((1,2,3,4),(3,4,5,6),(2,2,2,2))` - 返回 `array((1,2,3,4),(2,3,4,5),(1,1,1,1),(3,4,5,6),(2,2,2,2))` -- 同一组输入下： - `intersect` 返回 `array((1,2,3,4))` -- 同一组输入下： - `minus` 返回 `array((2,3,4,5),(1,1,1,1))` -- 同一组输入下： - `outersect` 返回 `array((2,3,4,5),(1,1,1,1),(3,4,5,6),(2,2,2,2))` - -## 和过滤运算的区别 - -- 集合运算先把数据当成“行集合”来看，再做包含、并交差。 -- 过滤运算先保留“原结果集里的每一条命中记录”；因此重复行会保留下来。 -- 你要的是“集合关系”，看这一篇。 -- 你要的是“从原表里筛出哪些行”，看 [14_resultset_and_filters.md](14_resultset_and_filters.md)。 - -## 最小可编译示例 - -如果你只想先记住最短写法，从这里开始： - -代码块身份：已验证可执行示例 - -```tsl -Matched := 1 in array(1, 2, 3); -``` - -## 常见误写 - -- 把 `in` 和 `sqlin` 当成同一个概念。 -- 期待 `union2` 保留重复行。 -- 用集合运算去做“保留原始重复记录”的过滤任务。 -- 把二维结果集默认当成“按元素逐个比较”的集合运算。 - -代码块身份：反例 / 不可照写 - -```text -Matched := array(1, 2) in array((1, 2), (3, 4)); -``` - -上面这类写法不要直接理解成“左边这一整行是否存在于右边”。当前手册里，整行存在判断统一写成 `sqlin`，避免把 `in` 的子集语义和行匹配语义混在一起。 - -代码块身份：反例 / 不可照写 - -```text -OnlyLeft := A minus B; -``` - -如果你的任务要求保留 `A` 里重复出现的命中次数，上面这种集合差集就不是合适工具，因为它会把结果当成集合而不是原始记录流。 - -## 跳转指引 - -- 回看表达式和逻辑运算：见 [07_expressions_and_operators.md](07_expressions_and_operators.md) -- 看数组、嵌套数组和子矩阵：见 [13_matrix_and_collections.md](13_matrix_and_collections.md) -- 看结果集过滤：见 [14_resultset_and_filters.md](14_resultset_and_filters.md) -- 进入矩阵深水专题：见 [26_matrix_deep_dive.md](26_matrix_deep_dive.md) diff --git a/docs/tsl/syntax/26_matrix_deep_dive.md b/docs/tsl/syntax/26_matrix_deep_dive.md deleted file mode 100644 index 33a449be..00000000 --- a/docs/tsl/syntax/26_matrix_deep_dive.md +++ /dev/null @@ -1,194 +0,0 @@ -# Matrix Deep Dive - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[13_matrix_and_collections.md](13_matrix_and_collections.md)、[27_fmarray.md](27_fmarray.md)、[25_set_operations.md](25_set_operations.md) - -手册位置：第 26 篇，共 32 篇。上一篇：[25_set_operations.md](25_set_operations.md)。下一篇：[27_fmarray.md](27_fmarray.md)。 - -这一篇开始讲真正的矩阵语法主干：矩阵初始化、数列构造，以及怎样读取矩阵的行列大小和索引。它和 [13_matrix_and_collections.md](13_matrix_and_collections.md) 的分工是：`13` 只讲数组与矩阵样数据，这一篇开始讲矩阵专用构造与大小接口。 - -## 这一篇解决什么问题 - -回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，以及怎样拿到矩阵的行数、列数、行索引和列索引”。 - -## Agent 矩阵深水判断流程 - -1. 先判断要读矩阵尺寸、列索引、矩阵选择，还是矩阵与数组转换。 -2. 基础数组和矩阵样比较先回看 `13_matrix_and_collections.md`。 -3. `MRows` / `MCols` / `MSize` 等函数只照已验证返回形态写。 -4. 不要把列索引数组误当成单个数字。 -5. 没有已验证代码块时不要发明矩阵深水写法。 - -## 必须记住的规则 - -- `Zeros(...)`、`Ones(...)`、`Rand(...)`、`Nils(...)`、`Eye(...)` 都可以直接用于矩阵初始化。 -- `Zeros(3)`、`Ones(3)`、`Nils(2)` 这类单参数写法可以直接生成一维结果。 -- `Zeros(2, 3)`、`Rand(2, 3)` 这类双参数写法可以直接生成二维矩阵。 -- `Zeros(2, array("A", "B"))` 这种写法可以直接生成带列名的二维结果。 -- `Eye(3)` 生成的是 `3 x 3` 单位矩阵，不是一维数组。 -- `->` 用来生成数列；默认步长是 `1`，也可以显式传入步长和索引数组。 -- `MSize(A)` 返回 `array(行数, 列数)`。 -- `MSize(A, 1)` 返回行索引数组和列索引数组。 -- `MRows(A)` / `MCols(A)` 默认返回数量；第二个参数写成 `1` 时返回索引数组。 - -## 已验证语法 - -### 矩阵初始化 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - Z1 := Zeros(3); - Z2 := Zeros(2, 3); - O1 := Ones(3); - N1 := Nils(2); - E1 := Eye(3); - R1 := Rand(2, 3); - T1 := Zeros(2, array("A", "B")); - WriteLn(Length(Z1)); - WriteLn(MRows(Z2)); - WriteLn(MCols(Z2)); -end. -``` - -已验证运行结果： - -- `Zeros(3)` 的长度是 `3`，前三个元素依次是 `0`、`0`、`0` -- `Zeros(2, 3)` 的行数是 `2`、列数是 `3`，第一行前三个元素是 `0`、`0`、`0` -- `Ones(3)` 的前三个元素依次是 `1`、`1`、`1` -- `Nils(2)` 已验证可直接生成长度为 `2` 的结果 -- `Eye(3)` 的行数是 `3`、列数是 `3`，并且 `(0,0)`、`(1,1)`、`(2,2)` 为 `1`，`(0,1)`、`(1,0)` 为 `0` -- `Rand(2, 3)` 的行数是 `2`、列数是 `3` -- `Zeros(2, array("A", "B"))` 的行数是 `2`、列数是 `2`，并且 `T1[0]["A"]`、`T1[0]["B"]`、`T1[1]["A"]`、`T1[1]["B"]` 都是 `0` - -代码块身份：已验证输出片段 - -```text -3 -2 -3 -``` - -### `->` 数列数组初始化 - -默认步长为 `1`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - S1 := 1 -> 5; -end. -``` - -已验证运行结果： - -- `S1` 是 `array(1, 2, 3, 4, 5)` - -显式指定步长： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - S2 := array(2.5, 0.5) -> 5; -end. -``` - -已验证运行结果： - -- `S2` 的长度是 `6` -- 六个元素依次是 `2.5`、`3`、`3.5`、`4`、`4.5`、`5` - -显式指定索引数组： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - S3 := array(0, 1, array("A", "B", "C", "D", "E", "F")) -> 5; -end. -``` - -已验证运行结果： - -- `S3` 的长度是 `6` -- `S3["A"]` 到 `S3["F"]` 依次是 `0`、`1`、`2`、`3`、`4`、`5` - -### `MSize`、`MRows`、`MCols` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - A := array( - ("A": 1, "B": 2), - ("A": 11, "B": 22), - ("A": 21, "B": 32) - ); - SizeInfo := MSize(A); - SizeIndex := MSize(A, 1); - RowCount := MRows(A); - RowIndex := MRows(A, 1); - ColCount := MCols(A); - ColIndex := MCols(A, 1); -end. -``` - -已验证运行结果： - -- `MSize(A)` 返回 `array(3, 2)` -- `MSize(A, 1)` 的第一项是 `array(0, 1, 2)`，第二项是 `array("A", "B")` -- `MRows(A)` 返回 `3` -- `MRows(A, 1)` 返回 `array(0, 1, 2)` -- `MCols(A)` 返回 `2` -- `MCols(A, 1)` 返回 `array("A", "B")` - -## 最小可编译示例 - -如果你只想先记住最短矩阵构造，从这个开始： - -代码块身份：已验证可执行示例 - -```tsl -M := Zeros(2, 3); -``` - -## 常见误写 - -- 把 `Eye(3)` 当成一维数组。 -- 以为 `MRows(A, 1)` 和 `MCols(A, 1)` 返回的还是数量。 -- 写带步长的 `->` 时，漏掉外层 `array(...)`。 -- 还在普通数组页里硬塞矩阵专用大小接口。 - -代码块身份：反例 / 不可照写 - -```text -S := 2.5, 0.5 -> 5; -``` - -上面这种写法不对。显式步长模式需要写成 `array(2.5, 0.5) -> 5`。 - -代码块身份：反例 / 不可照写 - -```text -Cols := MCols(A, 1); -``` - -不要把上面这一句的返回值当成数字 `2`。当前解释器下，`MCols(A, 1)` 返回的是列索引数组，例如 `array("A", "B")`。 - -## 跳转指引 - -- 回看数组与嵌套数组：见 [13_matrix_and_collections.md](13_matrix_and_collections.md) -- 看结果集过滤：见 [14_resultset_and_filters.md](14_resultset_and_filters.md) -- 看集合运算：见 [25_set_operations.md](25_set_operations.md) -- 进入 `FMArray`：见 [27_fmarray.md](27_fmarray.md) diff --git a/docs/tsl/syntax/27_fmarray.md b/docs/tsl/syntax/27_fmarray.md deleted file mode 100644 index a7051162..00000000 --- a/docs/tsl/syntax/27_fmarray.md +++ /dev/null @@ -1,552 +0,0 @@ -# FMArray - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[26_matrix_deep_dive.md](26_matrix_deep_dive.md)、[13_matrix_and_collections.md](13_matrix_and_collections.md)、[28_ts_sql_core.md](28_ts_sql_core.md) - -手册位置：第 27 篇，共 32 篇。上一篇：[26_matrix_deep_dive.md](26_matrix_deep_dive.md)。下一篇：[28_ts_sql_core.md](28_ts_sql_core.md)。 - -这一篇只讲当前解释器下已经实际跑通的 `FMArray` 主干能力：怎样构造 `FMArray`、怎样判断类型、怎样和 `Array` 互转、怎样读取尺寸、做基础运算、做多维转置与维度交换、做矩阵连接、参与 `select/mselect`，以及当前可用的 `insert/delete/update` 语法边界。 - -## 这一篇解决什么问题 - -回答“什么时候该用 `FMArray` 而不是普通 `array`，以及当前解释器里最可靠的 `FMArray` 写法到底有哪些”。 - -## Agent FMArray 判断流程 - -1. 先判断是否确实需要 `FMArray`，普通数组能解决时先用普通数组。 -2. 构造、类型判断、尺寸读取、转置、连接和 TS-SQL 参与只照本页已验证形态写。 -3. `insert`、`delete`、`update` 的收尾形式分别判断，不要互相套用。 -4. FMArray 错误边界按本页反例处理，不要凭普通数组经验修写法。 -5. 没有已验证代码块时不要发明 FMArray 写法。 - -## 必须记住的规则 - -- `fmarray[...]` 可以直接构造 `FMArray` 常量。 -- `datatype(v)` 对 `FMArray` 返回 `27`。 -- `datatype(v, 1)` 可以读出 `FMArray` 单元格类型；当前已验证到 `0` 整型、`1` 浮点、`20` 64 位整型。 -- `ifFMArray(v)` 可直接判断值是否为 `FMArray`。 -- `MInit`、`MInitDiag`、`MRand` 都可直接生成 `FMArray`。 -- `ArrayToFM` 和 `MatrixToArray` 可在 `Array` / `FMArray` 间互转。 -- `MSize`、`MRows`、`MCols` 都支持 `FMArray`；对三维 `FMArray`，`MSize` 已验证会返回全部维度长度。 -- `FMArray` 已验证支持和标量、`FMArray`、`Array` 做基础算符运算。 -- `union2` 已验证支持 `FMArray` / `Array` 混合运算；结果类型跟随左值。 -- 对超过二维的 `FMArray`，反引号转置会把全部维度倒置；`mswap` 可只交换指定维度。 -- `union` 可做按行连接且不去重，但列结构必须兼容。 -- `|` 和 `:|` 都可做按列连接；当前已验证到行数不一致时会用 `0` 补齐，并且两者表现一致。 -- 对 `FMArray` 做普通 `select` 不会保留 `FMArray` 类型；`mselect` 也不会返回 `datatype=27`。 -- 当前实测里，`insert into a array(...)`、`delete from a where ...;`、`update a set ... where ... end;` 都能作用于 `FMArray`，但三者的收尾形式并不完全相同。 - -## 已验证语法 - -### 常量构造与类型判断 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f1 := fmarray[1, 2, 3]; - f2 := fmarray[[1, 2], [3, 4]]; - f3 := fmarray[1.0, 2.0, 3.5]; - WriteLn(datatype(f1)); - WriteLn(datatype(f1, 1)); - WriteLn(datatype(f3, 1)); - WriteLn(ifFMarray(f1)); - WriteLn(length(f1)); - WriteLn(f1[0], ',', f1[1], ',', f1[2]); - WriteLn(mrows(f2)); - WriteLn(mcols(f2)); - WriteLn(f2[0,0], ',', f2[0,1], ',', f2[1,0], ',', f2[1,1]); -end. -``` - -已验证运行结果： - -- `datatype(f1)` 返回 `27` -- `datatype(f1, 1)` 返回 `0` -- `datatype(f3, 1)` 返回 `1` -- `ifFMarray(f1)` 返回 `1` -- `length(f1)` 返回 `3` -- `f1` 的三个元素依次是 `1`、`2`、`3` -- `f2` 的行数是 `2`、列数是 `2` -- `f2` 四个单元依次是 `1`、`2`、`3`、`4` - -代码块身份：已验证输出片段 - -```text -27 -0 -1 -1 -``` - -### `MInit`、`MInitDiag`、`MRand` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - fm1 := MInit(5, 3); - fm2 := MInit(array(3, 2), 1L); - fd1 := MInitDiag(3, 3, 1); - fr1 := MRand(2, 3); - WriteLn(datatype(fm1, 1)); - WriteLn(length(fm1)); - WriteLn(fm1[0], ',', fm1[1], ',', fm1[2], ',', fm1[3], ',', fm1[4]); - WriteLn(datatype(fm2, 1)); - WriteLn(mrows(fm2)); - WriteLn(mcols(fm2)); - WriteLn(fd1[0,0], ',', fd1[0,1], ',', fd1[1,0], ',', fd1[1,1], ',', fd1[2,2]); - WriteLn(mrows(fr1)); - WriteLn(mcols(fr1)); -end. -``` - -已验证运行结果： - -- `MInit(5, 3)` 生成长度为 `5` 的整型 `FMArray`，五个元素都是 `3` -- `datatype(fm1, 1)` 返回 `0` -- `MInit(array(3, 2), 1L)` 的单元格类型是 `20` -- `fm2` 的行数是 `3`、列数是 `2` -- `MInitDiag(3, 3, 1)` 的 `(0,0)`、`(1,1)`、`(2,2)` 为 `1`，而 `(0,1)`、`(1,0)` 为 `0` -- `MRand(2, 3)` 的行数是 `2`、列数是 `3` - -### `ArrayToFM`、`MatrixToArray` 与单元格类型转换 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a1 := array(1, 2, 3.5); - f1 := ArrayToFM(a1, 0); - f2 := ArrayToFM(a1, 0.0); - f3 := int64(fmarray[1, 2, 3]); - a2 := MatrixToArray(fmarray[[1, 2], [3, 8]]); - WriteLn(datatype(f1, 1)); - WriteLn(f1[0], ',', f1[1], ',', f1[2]); - WriteLn(datatype(f2, 1)); - WriteLn(f2[0], ',', f2[1], ',', f2[2]); - WriteLn(datatype(f3, 1)); - WriteLn(f3[0], ',', f3[1], ',', f3[2]); - WriteLn(mrows(a2)); - WriteLn(mcols(a2)); - WriteLn(a2[0][0], ',', a2[0][1], ',', a2[1][0], ',', a2[1][1]); -end. -``` - -已验证运行结果： - -- `ArrayToFM(a1, 0)` 的单元格类型是 `0`，结果是 `1,2,3` -- `ArrayToFM(a1, 0.0)` 的单元格类型是 `1`，结果是 `1,2,3.5` -- `int64(fmarray[1, 2, 3])` 的单元格类型是 `20` -- `MatrixToArray(fmarray[[1, 2], [3, 8]])` 返回一个 `2 x 2` 的 `Array`，内容是 `(1,2)`、`(3,8)` - -### 尺寸与重构 - -二维和三维尺寸： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f3 := fmarray[[[1, 1], [2, 2], [3, 3]], [[2, 2], [3, 3], [4, 4]]]; - s := MSize(f3); - WriteLn(length(s)); - WriteLn(s[0], ',', s[1], ',', s[2]); -end. -``` - -已验证运行结果： - -- `MSize(f3)` 的长度是 `3` -- 三个维度依次是 `2`、`3`、`2` - -`reshape` 会保持 `FMArray` 类型： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f1 := fmarray[[1, 2], [3, 4], [5, 5]]; - r1 := reshape(f1, 6); - WriteLn(datatype(r1)); - WriteLn(length(r1)); - WriteLn(r1[0], ',', r1[1], ',', r1[2], ',', r1[3], ',', r1[4], ',', r1[5]); -end. -``` - -已验证运行结果： - -- `datatype(r1)` 仍然是 `27` -- `r1` 的长度是 `6` -- 元素依次是 `1`、`2`、`3`、`4`、`5`、`5` - -### 标量运算与基础算符 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f1 := fmarray[1, 2, 3]; - f2 := fmarray[2, 3, 4]; - a1 := array(2, 3, 4); - s0 := f1 + 1; - s1 := f1 + f2; - s2 := f1 + a1; - WriteLn(datatype(s0)); - WriteLn(s0[0], ',', s0[1], ',', s0[2]); - WriteLn(datatype(s1)); - WriteLn(s1[0], ',', s1[1], ',', s1[2]); - WriteLn(datatype(s2)); - WriteLn(s2[0], ',', s2[1], ',', s2[2]); -end. -``` - -已验证运行结果： - -- `f1 + 1` 的 `datatype` 是 `27`，结果是 `2,3,4` -- `f1 + f2` 的 `datatype` 是 `27`，结果是 `3,5,7` -- `f1 + array(2, 3, 4)` 的 `datatype` 仍是 `27`，结果也是 `3,5,7` - -### `union2` 与左值类型 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f1 := fmarray[1, 2, 0, 4, 5]; - a1 := array(1, 0, 7.2); - u1 := f1 union2 a1; - u2 := a1 union2 f1; - WriteLn(datatype(u1)); - WriteLn(datatype(u1, 1)); - WriteLn(length(u1)); - WriteLn(u1[0], ',', u1[1], ',', u1[2], ',', u1[3], ',', u1[4], ',', u1[5]); - WriteLn(datatype(u2)); - WriteLn(length(u2)); - WriteLn(u2[0], ',', u2[1], ',', u2[2], ',', u2[3], ',', u2[4], ',', u2[5]); -end. -``` - -已验证运行结果： - -- `union2` 的结果 `datatype` 是 `27` -- `f1 union2 array(1, 0, 7.2)` 的单元格类型会提升为 `1` 浮点型 -- `f1 union2 array(1, 0, 7.2)` 的长度是 `6`，结果是 `1,2,0,4,5,7.2` -- `array(1, 0, 7.2) union2 f1` 的 `datatype` 是 `5` -- `array(1, 0, 7.2) union2 f1` 的长度也是 `6`，结果是 `1,0,7.2,2,4,5` - -### 多维转置与维度交换 - -三维 `FMArray` 上，反引号转置会把全部维度倒置： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f3 := fmarray[[[1], [2]], [[1], [0]], [[3], [-8]]]; - t := `f3; - s := MSize(t); - WriteLn(datatype(t)); - WriteLn(length(s)); - WriteLn(s[0], ',', s[1], ',', s[2]); - WriteLn(t[0,0,0], ',', t[0,0,1], ',', t[0,0,2], ';', t[0,1,0], ',', t[0,1,1], ',', t[0,1,2]); -end. -``` - -已验证运行结果： - -- 原矩阵尺寸是 `3,2,1`，转置后尺寸是 `1,2,3` -- 结果 `datatype` 仍是 `27` -- 转置后的内容是 `[[[1,1,3],[2,0,-8]]]` - -只交换指定维度时，使用 `mswap`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f3 := fmarray[[[1], [2]], [[1], [0]], [[3], [-8]]]; - t := mswap(f3, 0, 1); - s := MSize(t); - WriteLn(datatype(t)); - WriteLn(length(s)); - WriteLn(s[0], ',', s[1], ',', s[2]); - WriteLn(t[0,0,0], ',', t[0,1,0], ',', t[0,2,0], ';', t[1,0,0], ',', t[1,1,0], ',', t[1,2,0]); -end. -``` - -已验证运行结果： - -- `mswap(f3, 0, 1)` 后尺寸是 `2,3,1` -- 结果 `datatype` 仍是 `27` -- 结果内容是 `[[[1],[1],[3]],[[2],[0],[-8]]]` - -### 矩阵连接：`union`、`|`、`:|` - -`union` 会按行拼接，不做去重： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - t1 := fmarray[[1, 2], [3, 4], [5, 5]]; - t2 := fmarray[[7, 8]]; - u := t1 union t2; - WriteLn(datatype(u)); - WriteLn(mrows(u)); - WriteLn(mcols(u)); - WriteLn(u[0,0], ',', u[0,1], ';', u[1,0], ',', u[1,1], ';', u[2,0], ',', u[2,1], ';', u[3,0], ',', u[3,1]); -end. -``` - -已验证运行结果： - -- `union` 的结果 `datatype` 是 `27` -- `t1 union t2` 的行数是 `4`、列数是 `2` -- 拼接后四行依次是 `(1,2)`、`(3,4)`、`(5,5)`、`(7,8)` - -`|` 和 `:|` 会按列拼接： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - t1 := fmarray[[1, 2], [3, 4], [5, 5]]; - t2 := fmarray[[3, 4], [7, 8], [6, 9]]; - u1 := t1 | t2; - u2 := t1 :| t2; - WriteLn(datatype(u1)); - WriteLn(mrows(u1)); - WriteLn(mcols(u1)); - WriteLn(u1[0,0], ',', u1[0,1], ',', u1[0,2], ',', u1[0,3]); - WriteLn(u1[1,0], ',', u1[1,1], ',', u1[1,2], ',', u1[1,3]); - WriteLn(u1[2,0], ',', u1[2,1], ',', u1[2,2], ',', u1[2,3]); - WriteLn(u2[0,0], ',', u2[0,1], ',', u2[0,2], ',', u2[0,3]); - WriteLn(u2[1,0], ',', u2[1,1], ',', u2[1,2], ',', u2[1,3]); - WriteLn(u2[2,0], ',', u2[2,1], ',', u2[2,2], ',', u2[2,3]); -end. -``` - -已验证运行结果： - -- `|` 的结果 `datatype` 是 `27` -- `t1 | t2` 和 `t1 :| t2` 的行数都是 `3`、列数都是 `4` -- 两种写法的结果都依次是 `(1,2,3,4)`、`(3,4,7,8)`、`(5,5,6,9)` - -当前还额外验证到：行数不一致时，`|` 和 `:|` 在 `FMArray` 上表现一致，缺失行会用 `0` 补齐。 - -- `fmarray[[1, 2], [3, 4], [5, 5]] | fmarray[[3, 4]]` 的结果三行依次是 `(1,2,3,4)`、`(3,4,0,0)`、`(5,5,0,0)` -- `fmarray[[3, 4]] | fmarray[[1, 2], [3, 4], [5, 5]]` 的结果三行依次是 `(3,4,1,2)`、`(0,0,3,4)`、`(0,0,5,5)` -- 把上面两条里的 `|` 改成 `:|`，结果一致 - -### 排序 - -一维排序： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - s1 := fmarray[10, 2, -3, 8]; - sortarray(s1); - WriteLn(s1[0], ',', s1[1], ',', s1[2], ',', s1[3]); -end. -``` - -已验证运行结果： - -- 排序后结果是 `-3,2,8,10` - -二维按字段排序： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - f1 := fmarray[[11, 12], [31, 4], [5, 5]]; - SortTableByField(f1, 0, 1); - WriteLn(f1[0,0], ',', f1[0,1], ';', f1[1,0], ',', f1[1,1], ';', f1[2,0], ',', f1[2,1]); -end. -``` - -已验证运行结果： - -- 排序后依次是 `(5,5)`、`(11,12)`、`(31,4)` - -### TS-SQL 对 `FMArray` 的支持 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - q1 := select * from fmarray[[1, 2], [0, 4], [1, 2], [5, 6]] end; - q2 := mselect * from fmarray[[1, 2], [0, 4], [1, 2], [5, 6]] end; - WriteLn(datatype(q1)); - WriteLn(mrows(q1)); - WriteLn(datatype(q2)); - WriteLn(mrows(q2)); - WriteLn(mcols(q2)); -end. -``` - -已验证运行结果： - -- 普通 `select` 的返回 `datatype` 是 `5` -- `q1` 的行数是 `4` -- `mselect` 的返回 `datatype` 是 `17` -- `q2` 的行数是 `4`、列数是 `2` -- 说明当前解释器下，对 `FMArray` 做 TS-SQL 查询时，结果不会保留 `datatype=27` - -### `insert` / `delete` / `update` - -`insert`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a := MInit(2, 3, 1.0); - insert into a array(9); - WriteLn(mrows(a)); - WriteLn(mcols(a)); - WriteLn(a[2,0], ',', a[2,1], ',', a[2,2]); -end. -``` - -已验证运行结果： - -- 插入后行数是 `3` -- 列数仍是 `3` -- 新插入的第三行是 `9,9,9` - -`delete`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - d := fmarray[[1, 2], [0, 4], [5, 6]]; - delete from d where [1] = 4; - WriteLn(mrows(d)); - WriteLn(d[0,0], ',', d[0,1], ';', d[1,0], ',', d[1,1]); -end. -``` - -已验证运行结果： - -- 删除后行数是 `2` -- 保留的两行是 `(1,2)`、`(5,6)` - -`update`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - u := fmarray[[1, 2], [0, 4], [5, 6]]; - update u set [0] = 100 where [1] = 4 end; - WriteLn(mrows(u)); - WriteLn(u[0,0], ',', u[0,1], ';', u[1,0], ',', u[1,1], ';', u[2,0], ',', u[2,1]); -end. -``` - -已验证运行结果： - -- 更新后行数仍是 `3` -- 结果三行依次是 `(1,2)`、`(100,4)`、`(5,6)` - -当前解释器下，这三种写法的收尾形式已验证为： - -- `insert into a array(9);` -- `delete from d where [1] = 4;` -- `update u set [0] = 100 where [1] = 4 end;` - -## 暂不在本页展开的部分 - -- `MInitDiag` 更高维行为 -- `MRand` 的随机分布参数变体 -- `union` / `|` / `:|` 与普通 `array` 的更多混合边界 -- `left join` / `right join` / 更复杂 SQL 写回 -- CopyOnWrite 的内存级行为 - -这些都要等单独补最小验证后，再进入主线正文。 - -## 最小可编译示例 - -如果你只想先记住最短 `FMArray` 骨架，从这个开始： - -代码块身份：已验证可执行示例 - -```tsl -f := fmarray[1, 2, 3]; -``` - -## 常见误写 - -- 在一个 `FMArray` 常量里混用不同单元格类型。 -- 把 `FMArray` 当成支持字符串下标的 `array`。 -- 以为对 `FMArray` 做普通 `select` 后，结果还是 `datatype=27`。 -- 把 `delete` 和 `update` 的结尾形式写成同一种。 -- 以为 `union` 可以忽略列结构差异。 -- 以为 `array union2 fmarray` 还会返回 `FMArray`。 - -代码块身份：反例 / 不可照写 - -```text -f := fmarray[1, 2.0, 3]; -``` - -上面这种写法在当前解释器里会编译失败，错误信息包含 `fmarray must be same type`。 - -代码块身份：反例 / 不可照写 - -```text -f := fmarray[1, 2, 3]; -WriteLn(f["A"]); -``` - -上面这种写法在当前解释器里会运行报错，错误信息包含 `fmarray index type error`。 - -代码块身份：反例 / 不可照写 - -```text -delete from d where [1] = 4 end; -``` - -这类写法不要直接当成当前默认模板。当前已验证结果显示，`delete ... end;` 会报 `Statement missing terminator`；已验证可用的是 `delete ...;`。 - -代码块身份：反例 / 不可照写 - -```text -t1 := fmarray[[1, 2], [3, 4]]; -t2 := fmarray[[7, 8, 9]]; -u := t1 union t2; -``` - -上面这种写法会运行报错，错误信息包含 `union dim dismatch`。当前已验证的 `union` 只适用于列结构兼容的 `FMArray`。 - -## 跳转指引 - -- 回看矩阵基础：见 [26_matrix_deep_dive.md](26_matrix_deep_dive.md) -- 看 TS-SQL 基础：见 [28_ts_sql_core.md](28_ts_sql_core.md) -- 看 TS-SQL 进阶：见 [29_ts_sql_advanced.md](29_ts_sql_advanced.md) diff --git a/docs/tsl/syntax/28_ts_sql_core.md b/docs/tsl/syntax/28_ts_sql_core.md deleted file mode 100644 index 1316e6b7..00000000 --- a/docs/tsl/syntax/28_ts_sql_core.md +++ /dev/null @@ -1,243 +0,0 @@ -# TS-SQL Core - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[15_ts_sql.md](15_ts_sql.md)、[29_ts_sql_advanced.md](29_ts_sql_advanced.md)、[14_resultset_and_filters.md](14_resultset_and_filters.md) - -手册位置：第 28 篇，共 32 篇。上一篇：[27_fmarray.md](27_fmarray.md)。下一篇：[29_ts_sql_advanced.md](29_ts_sql_advanced.md)。 - -这一篇先收 TS-SQL 最基础、最稳定的一层：如何在内存数组上写 `select` 查询，怎样理解 `select` / `sselect` / `vselect` / `mselect` 的返回形态，以及 `where`、`group by`、`order by`、`ThisRow`、`ThisRowIndex` 这些查询骨架怎么写。 - -## 这一篇解决什么问题 - -回答“第一次写 TS-SQL 时，怎样在不碰 join、数据库表和对象化写回接口的前提下，稳定写出最小查询”。 - -## Agent TS-SQL Core 判断流程 - -1. 先判断要写 `select`、`sselect`、`vselect` 还是 `mselect`。 -2. 内存数组查询优先从 `select ... from T end` 最小骨架起手。 -3. 二维结果集字段访问用 `["字段名"]`，一维数组优先用 `ThisRow` 和 `ThisRowIndex`。 -4. join 和进阶聚合跳转到 `29_ts_sql_advanced.md`，不要在核心页发明写法。 -5. 没有已验证代码块时不要发明 TS-SQL Core 写法。 - -## 必须记住的规则 - -- TS-SQL 查询以 `select`、`sselect`、`vselect` 或 `mselect` 开始，以 `end` 结束。 -- `from` 后面可以直接跟内存数组结果集。 -- 在二维结果集里访问字段，当前稳定写法是 `["字段名"]`。 -- 普通 `select` 默认返回二维数组结果。 -- `sselect` 返回一维数组。 -- `vselect` 直接返回单个值，最适合聚集结果。 -- `mselect` 返回 `Matrix`；当前这一篇只把“返回矩阵且可读取行列信息”提升为已验证规则。 -- `where`、`group by`、`order by` 可以直接接在 `from` 后面继续使用。 -- 对一维数组做 TS-SQL 查询时，优先使用 `ThisRow` 和 `ThisRowIndex`，不要默认把 `[0]` 当成可靠列访问写法。 - -## 已验证语法 - -### 最基础的 `select` - -`select` 在内存数组上可直接返回二维结果： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1), - ("A": 1, "B": 2) - ); - R := select ["A"], ["B"] from T end; - WriteLn(Length(R)); -end. -``` - -已验证运行结果： - -- `R` 的长度是 `3` -- 三行依次是 `(1,3)`、`(2,1)`、`(1,2)` -- 说明 `select ["A"], ["B"] from T end` 会按原顺序返回二维结果集 - -代码块身份：已验证输出片段 - -```text -3 -``` - -`select *` 也已验证可用： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1) - ); - R := select * from T end; -end. -``` - -已验证运行结果： - -- `R` 的长度是 `2` -- 两行依次是 `(1,3)`、`(2,1)` - -### `sselect`、`vselect`、`mselect` - -四种查询入口的差异可以先记这一组： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1), - ("A": 1, "B": 2) - ); - S := sselect ["A"] from T end; - V := vselect sumof(["B"]) from T end; - M := mselect * from T end; - C := MCols(M, 1); -end. -``` - -已验证运行结果： - -- `sselect ["A"] from T end` 返回一维数组 `array(1, 2, 1)` -- `vselect sumof(["B"]) from T end` 返回单值 `6` -- `mselect * from T end` 的行数是 `3`、列数是 `2` -- `MCols(M, 1)` 返回列索引 `array("A", "B")` - -当前这篇只把 `mselect` 的“返回 Matrix 且保留行列信息”提升为已验证主干；直接单元格读取规则后续再单独补验证。 - -### `where` 和 `order by` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1), - ("A": 1, "B": 2) - ); - R := select * from T where ["B"] > 1 order by ["B"] end; -end. -``` - -已验证运行结果： - -- `R` 的长度是 `2` -- 两行依次是 `(1,2)`、`(1,3)` -- 说明 `where ["B"] > 1` 会先筛选，再按 `order by ["B"]` 的升序返回 - -### `group by` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1), - ("A": 1, "B": 2) - ); - G := select ["A"], sumof(["B"]) as "SumB" - from T - group by ["A"] - order by ["A"] - end; -end. -``` - -已验证运行结果： - -- `G` 的长度是 `2` -- 第一行是 `(1,5)` -- 第二行是 `(2,1)` -- 说明 `group by ["A"]` 后可以直接接聚集函数，并用 `as "SumB"` 指定返回列名 - -### 一维数组上的 `ThisRow` 与 `ThisRowIndex` - -处理一维数组时，当前最可靠的入口是 `ThisRow` 和 `ThisRowIndex`： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - X := array(10, 20, 30); - Y := sselect ThisRow from X end; - Z := sselect ThisRowIndex from X end; - R := select ThisRow as "Value", ThisRowIndex as "Idx" - from X - where ThisRow > 15 - order by ThisRow - end; -end. -``` - -已验证运行结果： - -- `sselect ThisRow from X end` 返回 `array(10, 20, 30)` -- `sselect ThisRowIndex from X end` 返回 `array(0, 1, 2)` -- 上面的 `select ... from X where ThisRow > 15 order by ThisRow end` 返回两行：`(1,20)`、`(2,30)` - -## 暂不在本页展开的部分 - -- `join` / `with on` -- `ThisGroup` -- `RefMaxOf` / `RefMinOf` -- `insert` / `update` / `delete` -- 面向 SQL 数据源的查询与写回 - -这些内容继续留给 [29_ts_sql_advanced.md](29_ts_sql_advanced.md) 或更深专题，不在这一篇提前写死。 - -## 最小可编译示例 - -如果你只想先记住最短 TS-SQL 骨架，从这个开始： - -代码块身份：已验证可执行示例 - -```tsl -R := select * from T end; -``` - -## 常见误写 - -- 把 `select` 当成普通函数调用，忘了以 `end` 收尾。 -- 在二维结果集里直接写 `A` 而不是 `["A"]`。 -- 需要一维结果时还在用普通 `select`。 -- 处理一维数组时直接把 `[0]` 当成稳定列访问。 -- 把 `vselect` 用在本来应该返回多行结果的场景里。 - -代码块身份：反例 / 不可照写 - -```text -R := select A from T end; -``` - -上面这种写法不要当成当前手册的可靠规则。二维结果集字段访问，当前只把 `["A"]` 这种写法提升为已验证主干。 - -代码块身份：反例 / 不可照写 - -```text -R := select [0] from X end; -``` - -当前已验证结果显示，这种对一维数组直接用 `[0]` 的写法虽然返回了长度为 `3` 的结果，但取到的值是 `nil`，不能当成可靠入口。对一维数组应改用 `ThisRow` 和 `ThisRowIndex`。 - -## 跳转指引 - -- 回看结果集过滤：见 [14_resultset_and_filters.md](14_resultset_and_filters.md) -- 回看集合与矩阵页：见 [25_set_operations.md](25_set_operations.md) 和 [26_matrix_deep_dive.md](26_matrix_deep_dive.md) -- 进入 TS-SQL 进阶：见 [29_ts_sql_advanced.md](29_ts_sql_advanced.md) diff --git a/docs/tsl/syntax/29_ts_sql_advanced.md b/docs/tsl/syntax/29_ts_sql_advanced.md deleted file mode 100644 index 2114cc82..00000000 --- a/docs/tsl/syntax/29_ts_sql_advanced.md +++ /dev/null @@ -1,206 +0,0 @@ -# TS-SQL Advanced - -文档类型：语法主线 -是否可直接用于生成代码：是 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[28_ts_sql_core.md](28_ts_sql_core.md)、[15_ts_sql.md](15_ts_sql.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 29 篇，共 32 篇。上一篇：[28_ts_sql_core.md](28_ts_sql_core.md)。下一篇：[30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md)。 - -这一篇只收当前已经实测通过的 TS-SQL 进阶查询能力：多表 `join`、分组子查询 `ThisGroup`、排序后的原始行下标 `ThisRowIndex`，以及 `RefMaxOf` / `RefMinOf` 这类“取极值所在行的另一列”的写法。 - -## 这一篇解决什么问题 - -回答“基础 `select` 已经会写以后，怎样继续处理多表联接、分组后组内再查、以及极值对应行的引用值”。 - -## Agent TS-SQL Advanced 判断流程 - -1. 先确认核心 `select ... from ... end` 已能表达基础查询，再进入进阶语法。 -2. 多表 join、`ThisGroup`、`ThisRowIndex` 和极值引用只照本页已验证示例写。 -3. 字段访问和返回形态仍遵守核心 TS-SQL 页规则。 -4. 不要把数据库 SQL 方言直接迁移到 TS-SQL。 -5. 没有已验证代码块时不要发明 TS-SQL Advanced 写法。 - -## 必须记住的规则 - -- 多表 `join` 时，字段访问应写成 `[表序号].["字段名"]`。 -- `ThisGroup` 不是普通值，而是分组后的子结果集；要通过子 `select` / `vselect` 的 `from ThisGroup` 来访问。 -- `ThisRowIndex` 在 `order by` 之后仍可返回原始行位置，而不是排序后的序号。 -- `RefMaxOf(...)` 和 `RefMinOf(...)` 在当前最小例子里可与 `MaxOf(...)` / `MinOf(...)` 配合，取极值所在行的另一列值。 -- 这一篇当前只提升“高级查询”部分；对象化写回接口和更深的时间序列查询仍然暂缓。 - -## 已验证语法 - -### `join` - -最小内存表联接： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - A := array( - ("ID": 1, "V1": 10), - ("ID": 2, "V1": 20) - ); - B := array( - ("ID": 1, "V2": 100), - ("ID": 3, "V2": 300) - ); - R := select [1].["ID"], [1].["V1"], [2].["V2"] - from A join B on [1].["ID"] = [2].["ID"] - end; - WriteLn(Length(R)); - WriteLn(R[0]["ID"]); - WriteLn(R[0]["V1"]); - WriteLn(R[0]["V2"]); -end. -``` - -已验证运行结果： - -- `R` 的长度是 `1` -- 唯一一行是 `(1,10,100)` -- 说明当前解释器接受 `from A join B on ...`，并接受 `[1].["字段"]`、`[2].["字段"]` 这种多表字段访问 - -代码块身份：已验证输出片段 - -```text -1 -1 -10 -100 -``` - -### `ThisGroup` - -分组后可在组内继续做子查询： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3, "Name": "x"), - ("A": 2, "B": 1, "Name": "y"), - ("A": 1, "B": 2, "Name": "z") - ); - G := select ["A"], maxb := maxof(["B"]) as "MaxB", - vselect ["Name"] from ThisGroup where ["B"] = maxb end as "TopName" - from T - group by ["A"] - order by ["A"] - end; -end. -``` - -已验证运行结果： - -- `G` 的长度是 `2` -- 第一行是 `(1,3,"x")` -- 第二行是 `(2,1,"y")` -- 说明 `ThisGroup` 可以在分组上下文里作为子结果集继续 `vselect` - -### `ThisRowIndex` 在排序后仍指向原始位置 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - T := array( - ("A": 1, "B": 3), - ("A": 2, "B": 1), - ("A": 1, "B": 2) - ); - R := select ThisRowIndex as "Idx", ["B"] - from T - order by ["B"] - end; -end. -``` - -已验证运行结果： - -- `R` 的三行依次是 `(1,1)`、`(2,2)`、`(0,3)` -- 说明 `order by ["B"]` 之后，`ThisRowIndex` 仍返回原表中的原始下标 - -### `RefMaxOf` 与 `RefMinOf` - -当前最小样例里，`RefMaxOf` / `RefMinOf` 可以和对应的极值聚集一起使用： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - A := array((6, 20), (5, 20), (9, 2), (2, 20), (7, 18)); - R1 := select maxof([0]) as "MaxA", refmaxof([1]) as "RefB" from A end; - R2 := select minof([0]) as "MinA", refminof([1]) as "RefB" from A end; -end. -``` - -已验证运行结果： - -- `R1` 只有一行，结果是 `(9,2)` -- `R2` 只有一行，结果是 `(2,20)` -- 说明在这个最小例子里，`refmaxof([1])` 取到了 `[0]` 最大值所在行的 `[1]`，`refminof([1])` 取到了 `[0]` 最小值所在行的 `[1]` - -## 暂不在本页展开的部分 - -- `with on` -- `left join` / `right join` / `full join` -- `RefsOf` -- `TSQLInsert` -- `TSQLSetValue` -- `TSQLBatchInsert` -- `TSQLEdit` / `TSQLPost` / `TSQLFinal` -- 更深的时间序列聚集与缓存选项 - -这些内容要等单独补最小验证后，再进入主线正文。 - -## 最小可编译示例 - -如果你只想先记住最短的高级查询骨架，从这个开始： - -代码块身份：已验证可执行示例 - -```tsl -R := select [1].["ID"], [2].["V2"] - from A join B on [1].["ID"] = [2].["ID"] - end; -``` - -## 常见误写 - -- 多表联接时继续写成 `["ID"]`，没有加表序号。 -- 把 `ThisGroup` 当成普通字段或普通变量。 -- 把排序后的 `ThisRowIndex` 误当成排序序号。 -- 在还没验证的情况下，把 `with on`、写回接口和时间序列缓存写进默认模板。 - -代码块身份：反例 / 不可照写 - -```text -R := select ["ID"], ["V1"], ["V2"] - from A join B on ["ID"] = ["ID"] - end; -``` - -上面这种写法不要当成当前手册的可靠规则。多表查询里，当前只把 `[1].["字段"]`、`[2].["字段"]` 这种带表序号的访问方式提升为已验证主干。 - -代码块身份：反例 / 不可照写 - -```text -Value := ThisGroup; -``` - -不要把 `ThisGroup` 当成普通值直接使用。当前可靠入口是 `select ... from ThisGroup end` 或 `vselect ... from ThisGroup end`。 - -## 跳转指引 - -- 回看 TS-SQL 基础：见 [28_ts_sql_core.md](28_ts_sql_core.md) -- 回看 TS-SQL 总入口：见 [15_ts_sql.md](15_ts_sql.md) -- 看运行时与全局缓存：见 [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) diff --git a/docs/tsl/syntax/30_runtime_services_and_global_cache.md b/docs/tsl/syntax/30_runtime_services_and_global_cache.md deleted file mode 100644 index 2369d850..00000000 --- a/docs/tsl/syntax/30_runtime_services_and_global_cache.md +++ /dev/null @@ -1,219 +0,0 @@ -# Runtime Services And Global Cache - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[16_debug_and_profiler.md](16_debug_and_profiler.md)、[24_builtin_runtime_objects.md](24_builtin_runtime_objects.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 30 篇，共 32 篇。上一篇：[29_ts_sql_advanced.md](29_ts_sql_advanced.md)。下一篇：[31_complex_and_weakref.md](31_complex_and_weakref.md)。 - -这一篇只讲当前解释器下已经实际跑通的运行时服务主干：`#` 网格调用、`timeout` 后缀，以及全局缓存的最小可用函数组。 - -## 这一篇解决什么问题 - -回答“网格调用现在怎样写，全局缓存最稳的读写方式是什么，以及什么时候缓存值会失效或脱离缓存身份”。 - -## Agent 运行时服务/全局缓存判断流程 - -1. 先判断要用 `#` 网格调用、`timeout` 后缀，还是全局缓存函数。 -2. 运行时服务只照本页已验证最小路径写，不要猜测隐藏参数。 -3. 全局缓存读写要成对出现，并明确 key/value 生命周期。 -4. 普通函数调用回到函数页，不要把运行时服务写成普通语法糖。 -5. 没有已验证代码块时不要发明运行时服务/全局缓存写法。 - -## 必须记住的规则 - -- 网格调用的最小写法是 `r := #Func(args);`。 -- 网格调用返回的不是最终值；当前已验证可以用 `dupvalue(r)` 取回结果。 -- `timeout N` 后缀当前已验证可直接接在网格调用后面。 -- `SetGlobalCache(name, value)` 当前已验证返回 `1` 表示设置成功。 -- `GetGlobalCache(name, outVar)` 当前已验证返回 `1` 表示取出成功。 -- 从全局缓存取出的值，`ifcache(v)` 当前会返回 `1`。 -- 一旦对取出的缓存值做本地写入，它会立刻实例化；写入后 `ifcache(v)` 返回 `0`。 -- `CheckGlobalCacheExpired(v)` 对当前版本的缓存返回 `0`；同名缓存被重置后，旧引用会变成过期状态并返回 `1`。 -- 当前已验证：全局缓存取出的值可以直接参与 `select`。 - -## 已验证语法 - -### `#` 网格调用与 `dupvalue` - -代码块身份：已验证可执行示例 - -```tsl -program test; -function AddOne(v); -begin - return v + 1; -end; -begin - WriteLn(dupvalue(#AddOne(5))); -end. -``` - -已验证运行结果： - -- `#AddOne(5)` 可以执行 -- `dupvalue(r)` 返回最终结果 `6` - -代码块身份：已验证输出片段 - -```text -6 -``` - -### 网格调用的 `timeout` - -代码块身份：已验证可执行示例 - -```tsl -program test; -function AddOne(v); -begin - return v + 1; -end; -begin - WriteLn(dupvalue(#AddOne(5) timeout 3000)); -end. -``` - -已验证运行结果： - -- `timeout 3000` 这种后缀写法可以通过并正常执行 -- 上例输出 `6` - -### `SetGlobalCache`、`GetGlobalCache` 与 `ifcache` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - v1 := array(1, 2, 3); - WriteLn(SetGlobalCache("PB_TEST_GC_BASIC", v1)); - WriteLn(GetGlobalCache("PB_TEST_GC_BASIC", v2)); - WriteLn(ifcache(v2)); - WriteLn(length(v2)); - WriteLn(v2[0], ',', v2[1], ',', v2[2]); -end. -``` - -已验证运行结果： - -- `SetGlobalCache("PB_TEST_GC_BASIC", v1)` 返回 `1` -- `GetGlobalCache("PB_TEST_GC_BASIC", v2)` 返回 `1` -- 取出的 `v2` 上 `ifcache(v2)` 返回 `1` -- `v2` 长度是 `3`，内容是 `1,2,3` - -### `CheckGlobalCacheExpired` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - SetGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3)); - GetGlobalCache("PB_TEST_GC_EXPIRE", v); - WriteLn(CheckGlobalCacheExpired(v)); - SetGlobalCache("PB_TEST_GC_EXPIRE", array(1, 2, 3, 4)); - WriteLn(CheckGlobalCacheExpired(v)); -end. -``` - -已验证运行结果： - -- 刚取出的缓存引用上，`CheckGlobalCacheExpired(v)` 返回 `0` -- 同名缓存被重新设置后，旧引用上的 `CheckGlobalCacheExpired(v)` 返回 `1` - -### 写入后会实例化 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - SetGlobalCache("PB_TEST_GC_DETACH", array(1, 2, 3)); - GetGlobalCache("PB_TEST_GC_DETACH", v); - WriteLn(ifcache(v)); - v[0] := 100; - WriteLn(ifcache(v)); - WriteLn(v[0], ',', v[1], ',', v[2]); -end. -``` - -已验证运行结果： - -- 刚取出时 `ifcache(v)` 返回 `1` -- 对 `v[0]` 赋值后，`ifcache(v)` 立即返回 `0` -- 写入后的本地值内容是 `100,2,3` - -### 全局缓存参与 `select` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - src := array((1, 2), (3, 4), (2, 1)); - SetGlobalCache("PB_TEST_GC_SELECT", src); - GetGlobalCache("PB_TEST_GC_SELECT", v); - q := select * from v order by [0] desc end; - WriteLn(datatype(q)); - WriteLn(mrows(q)); - WriteLn(q[0][0], ',', q[0][1], ';', q[1][0], ',', q[1][1], ';', q[2][0], ',', q[2][1]); -end. -``` - -已验证运行结果： - -- 对缓存值做 `select` 可以正常执行 -- 返回结果的 `datatype` 是 `5` -- 行数是 `3` -- 排序后内容依次是 `(3,4)`、`(2,1)`、`(1,2)` - -## 暂不在本页展开的部分 - -- 网格调用里的 `with array(...)` 系统参数传递 -- 网格超时触发错误时的完整边界 -- `GetGlobalCacheInfo`、`ListGlobalCache`、`ListGlobalCacheRemoved` -- 初始化 TSL、监控线程、回收策略与兼容旧系统方案 - -## 最小可编译示例 - -如果你只想先记住最短骨架，从下面这个网格调用模板起步： - -代码块身份：已验证可执行示例 - -```tsl -program test; -function AddOne(v); -begin - return v + 1; -end; -begin - WriteLn(dupvalue(#AddOne(5))); -end. -``` - -需要缓存时，再从 `SetGlobalCache` / `GetGlobalCache` 那一节开始。 - -## 常见误写 - -- 把网格句柄直接当最终值用，而不做 `dupvalue(...)`。 -- 以为从全局缓存取出的值，本地写入后仍然保持缓存身份。 -- 以为旧缓存引用在同名缓存被重置后还会继续视为“未过期”。 - -代码块身份：反例 / 不可照写 - -```text -r := #AddOne(5); -WriteLn(r); -``` - -上面这种写法不要直接当成“已经拿到计算结果”。当前已验证的稳定取值方式是 `dupvalue(r)`。 - -## 跳转指引 - -- 回看调试与 profiler：见 [16_debug_and_profiler.md](16_debug_and_profiler.md) -- 回看运行时环境参数：见 [11_runtime_context_and_with.md](11_runtime_context_and_with.md) -- 回看语法主入口：见 [index.md](index.md) diff --git a/docs/tsl/syntax/31_complex_and_weakref.md b/docs/tsl/syntax/31_complex_and_weakref.md deleted file mode 100644 index a4f97bc0..00000000 --- a/docs/tsl/syntax/31_complex_and_weakref.md +++ /dev/null @@ -1,345 +0,0 @@ -# Complex And WeakRef - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：是 -遇到不确定时跳转到：[09_objects_and_classes.md](09_objects_and_classes.md)、[32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md)、[12_pitfalls.md](12_pitfalls.md) - -手册位置：第 31 篇，共 32 篇。上一篇：[30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md)。下一篇：[32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md)。 - -这一篇只讲当前解释器下已经实际跑通的两组新一代语言能力：复数，以及弱引用 / 自动弱引用里当前真正可靠的最小写法。 - -## 这一篇解决什么问题 - -回答“复数现在到底怎样写，弱引用到底有哪些语法真的能用，哪些历史资料里的写法今天不能直接照抄”。 - -## Agent 复数/弱引用判断流程 - -1. 先判断任务需要复数，还是弱引用/自动弱引用。 -2. 复数字面量和比较只照本页已验证示例写。 -3. 访问弱引用前先做 `checkweakref(...)` 判定，不要假设失效弱引用安全返回 nil。 -4. 类内 `WeakRef;` / `AutoRef;` 段落式写法属于反例，不要照写。 -5. 没有已验证代码块时不要发明复数/弱引用写法。 - -## 必须记住的规则 - -- 复数字面量可以直接写成 `a + bj`，也可以用 `complex(a, b)` 构造。 -- `datatype(z)` 对复数返回 `41`，`ifcomplex(z)` 对复数返回 `1`。 -- `real`、`imag`、`conj`、`abs` 当前都已验证可用。 -- 当前解释器里，实数 `x` 与复数 `x + 0j` 的相等比较结果为真。 -- `complex(array(...), imag)` 会返回 `Array`；`complex(fmarray..., imag)` 会返回 `FMArray`，并且其单元格类型是 `41`。 -- 弱引用能力的条件编译宏当前已验证是 `weakptr`；自动弱引用相关宏是 `AutoWeak`。 -- `weakref(obj)` 可以创建弱引用；对象仍存活时，`weakref_get(w)` 可以拿回强引用。 -- `checkweakref(w)` 当前已验证：对象仍存活时返回 `1`，对象已释放后返回 `-1`。 -- 对已经失效的弱引用直接调用 `weakref_get(w)`，当前解释器里会运行报错，不要把它当成“安全返回 nil”的接口。 -- 类成员上的 `[WeakRef] field;` 和 `[AutoRef] field;` 当前已验证可以通过。 -- `[WeakRef]` 成员不会阻止对象析构；强引用释放后，对象会正常销毁。 -- 历史资料里的类内段落式 `WeakRef;` / `AutoRef;` 在当前解释器里没有通过，错误信息包含 `invalid class definition`。 - -## 已验证语法 - -### 复数常量、类型与基础读取 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - z1 := 4 + 3j; - z2 := complex(5, -2); - WriteLn(datatype(z1)); - WriteLn(ifcomplex(z1)); - WriteLn(real(z1)); - WriteLn(imag(z1)); - WriteLn(z2); -end. -``` - -已验证运行结果： - -- `datatype(4 + 3j)` 返回 `41` -- `ifcomplex(4 + 3j)` 返回 `1` -- `real(4 + 3j)` 返回 `4` -- `imag(4 + 3j)` 返回 `3` -- `complex(5, -2)` 打印结果是 `5-2j` - -代码块身份：已验证输出片段 - -```text -41 -1 -4 -3 -``` - -### 共轭、模与等值比较 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - z := 4 + 3j; - c := conj(z); - WriteLn(abs(z)); - WriteLn(real(c)); - WriteLn(imag(c)); - if 3.15 = 3.15 + 0j then - WriteLn(1); - else - WriteLn(0); -end. -``` - -已验证运行结果： - -- `abs(4 + 3j)` 返回 `5` -- `conj(4 + 3j)` 的实部是 `4`、虚部是 `-3` -- `3.15 = 3.15 + 0j` 当前比较结果为真 - -### 复数 `Array` 与复数 `FMArray` - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - a := complex(array(1, 2, 3), 5.5); - f := complex(fmarray[1, 2, 3], 5.5); - WriteLn(datatype(a)); - WriteLn(length(a)); - WriteLn(a[0], ',', a[1], ',', a[2]); - WriteLn(datatype(f)); - WriteLn(datatype(f, 1)); - WriteLn(length(f)); - WriteLn(f[0], ',', f[1], ',', f[2]); -end. -``` - -已验证运行结果： - -- `complex(array(1, 2, 3), 5.5)` 的 `datatype` 是 `5` -- 上述复数数组长度是 `3`，三个元素依次是 `1+5.5j`、`2+5.5j`、`3+5.5j` -- `complex(fmarray[1, 2, 3], 5.5)` 的 `datatype` 是 `27` -- 上述复数 `FMArray` 的单元格类型 `datatype(f, 1)` 是 `41` -- 该 `FMArray` 长度是 `3`，三个元素依次是 `1+5.5j`、`2+5.5j`、`3+5.5j` - -### 弱引用能力的条件编译判定 - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin -{$IFDEF weakptr} - WriteLn('weakptr'); -{$ELSE} - WriteLn('Noweakptr'); -{$ENDIF} -{$IFDEF AutoWeak} - WriteLn('AutoWeak'); -{$ELSE} - WriteLn('NoAutoWeak'); -{$ENDIF} -end. -``` - -已验证运行结果： - -- 当前解释器会输出 `weakptr` -- 当前解释器也会输出 `AutoWeak` -- 说明这代解释器里，弱引用能力的条件编译开关应写成 `weakptr`，自动弱引用能力的开关应写成 `AutoWeak` - -### `weakref`、`weakref_get` 与 `checkweakref` - -对象仍然存活时： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TNode = class - name; - function create(v); - begin - name := v; - end; -end; -begin - a := new TNode('A'); - w := weakref(a); - WriteLn(checkweakref(w)); - s := weakref_get(w); - WriteLn(s.name); -end. -``` - -已验证运行结果： - -- `checkweakref(w)` 返回 `1` -- `weakref_get(w)` 能拿回强引用 -- 通过拿回的强引用可继续访问对象成员，此处输出 `A` - -沿用同一个 `TNode`，只把主体改成下面这样： - -代码块身份：配置片段 / 概念骨架 - -```tsl -program test; -begin - a := new TNode('A'); - w := weakref(a); - WriteLn(checkweakref(w)); - a := nil; - WriteLn(checkweakref(w)); -end. -``` - -已验证运行结果： - -- 创建后 `checkweakref(w)` 返回 `1` -- 把最后一个强引用设为 `nil` 后，`checkweakref(w)` 返回 `-1` - -当前还额外验证到： - -代码块身份：反例 / 不可照写 - -```text -a := new TNode('A'); -w := weakref(a); -a := nil; -t := weakref_get(w); -``` - -上面这种写法在当前解释器里会运行报错，因此访问弱引用前应先做 `checkweakref(w)` 判定。 - -### `[WeakRef]` 与 `[AutoRef]` 成员标记 - -成员级标记当前可以直接写在类里： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TChild = class -public - [WeakRef] owner1; - [AutoRef] owner2; -end; -begin - WriteLn(1); -end. -``` - -已验证运行结果： - -- 上述写法可以正常执行，并输出 `1` -- 说明 `[WeakRef] field;` 和 `[AutoRef] field;` 当前都能通过 - -`[WeakRef]` 成员不会阻止对象析构： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TA = class -public - function destroy(); - begin - WriteLn('Destroy'); - end; -end; - -type TB = class -public - [WeakRef] owner; - function Bind(v); - begin - owner := v; - end; -end; -begin - a := new TA(); - b := new TB(); - b.Bind(a); - a := nil; - WriteLn('AfterNil'); -end. -``` - -已验证运行结果： - -- 输出顺序是 `Destroy`、`AfterNil` -- 说明 `TB.owner` 作为 `[WeakRef]` 成员，不会把 `TA` 实例继续强持有 - -## 暂不在本页展开的部分 - -- 复数统计函数、分解函数与更大函数族 -- `MakeWeakRef`、`MakeStrongRef`、`weakref_check` 等别名接口 -- `property write` 传播自动弱引用的更复杂规则 -- 循环引用场景里的完整模式化写法 - -## 最小可编译示例 - -复数最短骨架： - -代码块身份：已验证可执行示例 - -```tsl -program test; -begin - z := 4 + 3j; - WriteLn(real(z)); - WriteLn(imag(z)); -end. -``` - -弱引用最短骨架： - -代码块身份：已验证可执行示例 - -```tsl -program test; -type TNode = class - name; - function create(v); - begin - name := v; - end; -end; -begin - a := new TNode('A'); - w := weakref(a); - WriteLn(checkweakref(w)); -end. -``` - -## 常见误写 - -- 把弱引用能力的条件编译宏写成 `WeakRef`。 -- 以为 `weakref_get(deadWeakRef)` 会像普通可空访问那样安全返回 `nil`。 -- 以为历史资料里的类内段落式 `WeakRef;` / `AutoRef;` 现在也能直接通过。 -- 以为 `[WeakRef]` 成员会继续强持有对象。 - -代码块身份：反例 / 不可照写 - -```text -type TChild = class -public - owner0; - [WeakRef] owner1; - WeakRef; - owner2; - AutoRef; - owner3; -end; -``` - -上面这种把 `WeakRef;` / `AutoRef;` 当作类内段落切换的写法，在当前解释器里会编译失败，错误信息包含 `invalid class definition`。 - -## 跳转指引 - -- 回看语法主入口：见 [index.md](index.md) -- 回看对象主线：见 [09_objects_and_classes.md](09_objects_and_classes.md) -- 看对象重载：见 [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) diff --git a/docs/tsl/syntax/32_object_overloads_and_iteration.md b/docs/tsl/syntax/32_object_overloads_and_iteration.md deleted file mode 100644 index 4c751db0..00000000 --- a/docs/tsl/syntax/32_object_overloads_and_iteration.md +++ /dev/null @@ -1,320 +0,0 @@ -# Object Overloads And Iteration - -文档类型：语法主线 -是否可直接用于生成代码：仅部分 -是否含已验证可执行示例：是 -是否含已验证反例：否 -遇到不确定时跳转到：[09_objects_and_classes.md](09_objects_and_classes.md)、[23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md)、[31_complex_and_weakref.md](31_complex_and_weakref.md) - -手册位置：第 32 篇，共 32 篇。上一篇：[31_complex_and_weakref.md](31_complex_and_weakref.md)。这一篇是当前 syntax 深水专题的最后一篇。 - -这一篇收拢“对象像数组、像容器、像可遍历值”这一组新一代能力：基础算符重载、`[]` 重载、`for in` 重载，以及 `mrows` / `mcols` / `msize` 这类矩阵关键字重载。 - -## 这一篇解决什么问题 - -回答“当类不只是普通对象，而要直接参与 `obj + x`、`obj[index]`、`for v in obj`、`mrows(obj)` 这类语言级操作时，当前解释器到底支持哪些真实写法”。 - -## Agent 对象重载/迭代判断流程 - -1. 先判断要重载二元算符、下标、`for in`，还是矩阵尺寸函数。 -2. 对象重载只照本页已验证的 `operator` 签名写，不要从历史资料扩展未知重载。 -3. 普通对象模型先回看 `09_objects_and_classes.md`，不要在重载页发明类基础语法。 -4. 未列入本页主干的重载族先视为未验证。 -5. 没有已验证代码块时不要发明对象重载/迭代写法。 - -## 必须记住的规则 - -- 对象二元算符重载当前最小可靠形态是成员方法 `function operator + (data);` 这一类写法。 -- 比较算符当前已验证可写成 `function operator < (data, isLeft);`，用 `isLeft` 区分对象在左边还是右边。 -- 对象 `[]` 读取当前已验证两种写法：`function operator[](index);` 和 `function operator[0](index, s1);`。 -- 对象 `[]` 写入当前已验证写法是 `function operator[1](index, v);`。 -- `function operator for(flag);` 当前已验证可以重载 `for in`。 -- 在 `operator for(flag)` 里，`flag .& 2` 可用来区分“一个循环变量”还是“两个循环变量”，`flag .& 1` 可用来区分“第一次进入”还是“继续迭代”。 -- `mrows` / `mcols` / `msize` 当前已验证可以在类里先声明 `function operator mrows(n);` 这类签名，再在类外实现 `function operator ClassName.mrows(n);`。 -- 当前已验证可用的是 `mrows(obj)`、`mcols(obj)`、`msize(obj)` 这类关键字调用，以及 `obj.mcols(1)` 这类对象方法式调用。 -- `function operator++(v);` 和 `function operator += (v);` 当前也已验证可用。 -- 不要把历史资料里的裸 `function operator;` / `function operator1;` 或尚未验证的 `mcell` / `mrow` / `mcol` / `::` / `:.` 重载，直接当成当前解释器事实。 - -## 已验证语法 - -### 二元算符重载 - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Tcomplex = class - vReal; - vImaginary; - function operator + (data); - begin - r := new Tcomplex(); - if ifnumber(data) then - r.vReal := vReal + data - else - begin - r.vReal := vReal + data.vReal; - r.vImaginary := vImaginary + data.vImaginary; - end; - return r; - end; - function operator < (data, isLeft); - begin - if ifnumber(data) then - v := vReal < data - else - v := (vReal ^ 2 + vImaginary ^ 2) < data.vReal ^ 2 + data.vImaginary ^ 2; - if not isLeft then v := not v; - return v; - end; -end; -begin - t1 := new TComplex(); - t1.vReal := 10; - t1.vImaginary := 100; - t2 := t1 + 10; - WriteLn(t2.vReal); - WriteLn(t1 < 5); - WriteLn(t1 < 300); - WriteLn(5 < t1); -end. -``` - -已验证运行结果： - -- 依次输出 `20`、`0`、`1`、`1` -- 说明 `obj + value` 当前可以通过成员 `operator +` 接管 -- 说明带 `isLeft` 的比较算符当前可以同时处理 `obj < value` 和 `value < obj` - -代码块身份：已验证输出片段 - -```text -20 -0 -1 -1 -``` - -### `[]` 重载：`operator[]` / `operator[1]` - -代码块身份：已验证可执行示例 - -```tsl -program test; -type bb = class - data; - function create(v); - begin - data := v; - end; - function operator[](index); - begin - return data[index]; - end; - function operator[1](index, v); - begin - data[index] := v; - end; -end; -begin - t := array(1, 2, 3, 4, 5); - b := new bb(t); - WriteLn(b[2]); - b[3] := 999; - WriteLn(b.data[3]); -end. -``` - -已验证运行结果： - -- 依次输出 `3`、`999` -- 说明当前解释器下，`operator[]` 和 `operator[1]` 可以完成单层下标读取和写入 - -### `[]` 重载：`operator[0]` / `operator[1]` - -沿用上一段的 `bb` 类与测试主体，只把读取签名从 `function operator[](index);` 改成 `function operator[0](index, s1);`： - -代码块身份：配置片段 / 概念骨架 - -```tsl -type bb = class - // 其余字段、Create()、operator[1] 和测试主体同上一段 - function operator[0](index, s1); - begin - return data[index]; - end; -end; -``` - -已验证运行结果： - -- 依次输出 `3`、`999` -- 说明 `operator[0]` / `operator[1]` 这组写法在单层下标场景同样可用 - -### `for in` 重载 - -代码块身份：已验证可执行示例 - -```tsl -program test; -type Box = class - data; - findex; - function create(v); - begin - data := v; - end; - function operator for(flag); - begin - use_pair := flag .& 2; - again := flag .& 1; - if not again then - findex := 0 - else if findex < length(data) - 1 then - findex++ - else - return nil; - - if use_pair then - return array(findex, data[findex]); - return data[findex]; - end; -end; -begin - box := new Box(array("A", "B", "C")); - for v in box do - WriteLn(v); - for i, v in box do - WriteLn(i$":"$v); -end. -``` - -已验证运行结果： - -- 单变量循环依次输出 `A`、`B`、`C` -- 双变量循环依次输出 `0:A`、`1:B`、`2:C` -- 说明 `operator for(flag)` 当前确实可以重载 `for in` -- 也说明同一个对象可以按返回值形态同时支持“单变量遍历”和“索引 + 值遍历” - -### `mrows` / `mcols` / `msize` 重载 - -代码块身份：已验证可执行示例 - -```tsl -program test; -type GridWrap = class - data; - function create(); - begin - data := array( - ("A": 1, "B": 2, "C": 3), - ("A": 4, "B": 5, "C": 6) - ); - end; - function operator mrows(n); - function operator mcols(n); - function operator msize(n); -end; - -function operator GridWrap.mrows(n); -begin - _n := ifnil(n) ? 0 : n; - return mrows(data, _n); -end; - -function operator GridWrap.mcols(n); -begin - _n := ifnil(n) ? 0 : n; - return mcols(data, _n); -end; - -function operator GridWrap.msize(n); -begin - _n := ifnil(n) ? 0 : n; - return msize(data, _n); -end; - -begin - g := new GridWrap(); - WriteLn(mrows(g)); - WriteLn(mcols(g)); - sz := msize(g); - WriteLn(sz[0]); - WriteLn(sz[1]); - cols := g.mcols(1); - WriteLn(cols[0]); - WriteLn(cols[1]); - WriteLn(cols[2]); -end. -``` - -已验证运行结果： - -- 依次输出 `2`、`3`、`2`、`3`、`A`、`B`、`C` -- 说明 `mrows(obj)`、`mcols(obj)`、`msize(obj)` 当前都可由对象重载接管 -- 说明对象方法式调用 `obj.mcols(1)` 也可继续取得列下标列表 - -### `++` 与 `+=` - -代码块身份：已验证可执行示例 - -```tsl -program test; -type bb = class - data; - function create(v); - begin - data := v; - end; - function operator++(v); - begin - if v = 0 then - begin - r := new bb(); - r.data := data; - r.data++; - return r; - end - else - data++; - end; - function operator += (v); - begin - data += v; - end; -end; -begin - b := new bb(10); - ++b; - WriteLn(b.data); - c := b++; - WriteLn(c.data); - WriteLn(b.data); - b += 5; - WriteLn(b.data); -end. -``` - -已验证运行结果： - -- 依次输出 `11`、`11`、`12`、`17` -- 说明前置 `++` 会直接修改对象状态 -- 说明这个最小样例里，后置 `b++` 返回的是递增前快照 -- 说明 `operator += (v)` 当前可以接管 `b += 5` - -## 暂不在本页展开的部分 - -- `::` / `:.` 遍历重载 -- `mcell` / `mrow` / `mcol` / `mIndexCount` / `mIndex` -- 多级 `[]` 下标重载 -- 右侧算术如 `value + obj` -- 对基础二进制函数的大规模重载族 - -这些旧资料里都有更深示例，但当前这一篇先只保留已经单独跑通的容器化主干。 - -## 跳转指引 - -- 回看对象模型：见 [09_objects_and_classes.md](09_objects_and_classes.md) -- 回看语法主入口：见 [index.md](index.md) -- 回看对象运行时反射：见 [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) -- 回看复数与弱引用：见 [31_complex_and_weakref.md](31_complex_and_weakref.md) diff --git a/docs/tsl/syntax/coverage_map.md b/docs/tsl/syntax/coverage_map.md deleted file mode 100644 index a4ea96b0..00000000 --- a/docs/tsl/syntax/coverage_map.md +++ /dev/null @@ -1,39 +0,0 @@ -# Coverage Map - -文档类型：检索页 -是否可直接用于生成代码：否 -是否含已验证可执行示例：否 -是否含已验证反例：否 -遇到不确定时跳转到：[index.md](index.md)（优先）、[02_quickstart.md](02_quickstart.md)、[12_pitfalls.md](12_pitfalls.md) - -这一页只回答一个问题：旧 8 章语法手册里的语言章节，现在在新的正式语法手册里分别落到哪里。 - -## 怎么使用这页 - -- 想系统读手册，先按 `01` 到 `16` 主线走。 -- 想补齐深水专题，再按需进入 `18` 到 `32`。 -- 想知道旧书某一章今天应该拆到哪里看，直接查下面的映射表。 - -## 8 章吸收总表 - -| 旧章节 | 主线页 | 专题页 | 说明 | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -| `01_language_basics.md` | [01_introduction.md](01_introduction.md), [03_core_model.md](03_core_model.md), [04_values_and_literals.md](04_values_and_literals.md), [05_variables_and_constants.md](05_variables_and_constants.md), [07_expressions_and_operators.md](07_expressions_and_operators.md), [11_runtime_context_and_with.md](11_runtime_context_and_with.md), [13_matrix_and_collections.md](13_matrix_and_collections.md) | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md), [19_types_and_conversions.md](19_types_and_conversions.md), [20_strings_and_text.md](20_strings_and_text.md) | 语言基础主干在主线，词法 / 类型 / 字符串边界放进深水专题 | -| `02_control_flow.md` | [08_control_flow.md](08_control_flow.md) | [16_debug_and_profiler.md](16_debug_and_profiler.md) | 控制流在主线，调试与 profiler 单列专题 | -| `03_functions.md` | [06_functions_and_calls.md](06_functions_and_calls.md) | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | 普通函数在主线，`external` / 动态库 / 线程放进专题 | -| `04_modules_and_namespace.md` | [10_units_and_scope.md](10_units_and_scope.md) | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | `unit` / `uses` 在主线，运行时查找路径与 `Libpath` 放进专题 | -| `05_object_model.md` | [09_objects_and_classes.md](09_objects_and_classes.md) | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md), [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md), [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 类基础语法在主线，运行时 / 内置对象 / 重载能力拆到专题 | -| `06_extended_syntax.md` | [13_matrix_and_collections.md](13_matrix_and_collections.md), [14_resultset_and_filters.md](14_resultset_and_filters.md), [15_ts_sql.md](15_ts_sql.md) | [25_set_operations.md](25_set_operations.md), [26_matrix_deep_dive.md](26_matrix_deep_dive.md), [27_fmarray.md](27_fmarray.md), [28_ts_sql_core.md](28_ts_sql_core.md), [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | 主线先建立数组 / 结果集 / TS-SQL 入口，集合 / 矩阵 / FMArray / TS-SQL 深水内容进入专题 | -| `07_debug_and_profiler.md` | [16_debug_and_profiler.md](16_debug_and_profiler.md) | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | 调试入口在主线，运行时服务与全局缓存单列专题 | -| `08_new_generation.md` | [07_expressions_and_operators.md](07_expressions_and_operators.md), [09_objects_and_classes.md](09_objects_and_classes.md) | [31_complex_and_weakref.md](31_complex_and_weakref.md), [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 较新语法相关内容已分散吸收到表达式 / 对象主线，复数 / 弱引用 / 对象重载保留在专题 | - -## 读取原则 - -- 新 session 不需要再回旧 8 章语法手册建立语言主干。 -- `01` 到 `16` 负责从介绍到进阶的顺序阅读。 -- `18` 到 `32` 负责把旧 8 章里剩余的深水内容补齐。 -- 当前正式手册没有 `17_xxx.md`；主线是 `01-16`，深水专题是 `18-32`。 - -## 跳转 - -- 回到语法入口：见 [index.md](index.md) diff --git a/docs/tsl/syntax/index.md b/docs/tsl/syntax/index.md index 447c5763..1d2cf264 100644 --- a/docs/tsl/syntax/index.md +++ b/docs/tsl/syntax/index.md @@ -1,148 +1,66 @@ -# Syntax Index +# TSL 语法入口 文档类型：检索页 是否可直接用于生成代码：否 -是否含已验证可执行示例：否 -是否含已验证反例：否 -遇到不确定时跳转到：[02_quickstart.md](02_quickstart.md)（优先）、[03_core_model.md](03_core_model.md)、[07_expressions_and_operators.md](07_expressions_and_operators.md)、[09_objects_and_classes.md](09_objects_and_classes.md)、[12_pitfalls.md](12_pitfalls.md) +是否含可直接照写示例：否 +是否含不可照写反例：否 +遇到不确定时：先按本文“按任务跳转”做语法层分流；写最短骨架看 [01_quickstart.md](01_quickstart.md)，判断文件模型看 [02_core_model.md](02_core_model.md)，判断表达式看 [06_expressions_and_operators.md](06_expressions_and_operators.md)，判断类/对象看 [08_objects_and_classes.md](08_objects_and_classes.md)，核对反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)。 -这里是 TSL 语法手册入口。只处理“agent 应该怎样识别并生成语言写法”，不处理金融业务语义。本文档不是人类教程；它给 agent 提供判断顺序、关键词分流和可靠示例入口。 +本页只做语法层路由。生成代码时不要顺序读完整套语法文档；先判断任务命中哪一类，再进入最小专题页。 -## 元数据读法 +## 元数据与代码块身份 -- 页头里的 `是否可直接用于生成代码` 是页面级粗判断；真正落代码时，优先看每个代码块自己的 `代码块身份`。 -- `是否可直接用于生成代码` 有三种值：`是`、`否`、`仅部分`；其中 `仅部分` 表示这一页同时含有可直接参考的代码块，以及依赖多文件、查找路径或运行时环境的代码块。 -- `是否含已验证可执行示例` 只表示这一页存在已跑通的正向代码示例。 -- `是否含已验证反例` 只表示这一页存在已经确认不能照写的负例。 -- `代码块身份` 固定只用四种值：`已验证可执行示例`、`已验证输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。 -- 如果代码块后面还有用途或限制说明，会单独写成 `代码块说明`，不继续混进 `代码块身份`。 -- 如果页头里的 `遇到不确定时跳转到` 给出多个目标，默认第一项是优先入口，后面的目标用于分流或补证。 +- 页头 `是否可直接用于生成代码` 只做页面级粗判断；落代码时以块级 `代码块身份` 为准。 +- `代码块身份` 固定只用四种值：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。 +- 普通语法专题页的 `遇到不确定时` 先按候选页继续判断，仍不命中再回本语法入口页；本页例外，必须先按“按任务跳转”分流。 -## 这本手册怎么读 +## 智能体语法判断流程 -- 默认先走“Agent 判断流程”和“按任务跳转”，不要先顺序读完整套。 -- 只有刻意系统学习时，才按下面的“推荐读法”顺序进入。 -- 当前这套正式语法手册不再只覆盖主线入门，而是负责完整吸收旧 8 个语言章节。 - -## Agent 判断流程 - -1. 先识别用户是否已经给出 `.tsl` / `.tsf` 后缀；给出后缀时，后缀就是判断依据。 -2. 未给后缀时，再按交付目标判断：可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。 -3. 如果是 `.tsl`，按可执行脚本处理：先写语句区，语句按顺序执行；需要函数/类时，把声明区放在语句区之后。 -4. 如果是 `.tsf`，按模块/函数扩展处理：生成可部署到解释器 `funcext` 的声明；部署后脚本可以直接调用暴露的顶层函数。 -5. 再识别关键词属于值/变量、函数、类、unit、表达式、控制流、运行时、TS-SQL 或其他专题。 -6. 只进入关键词命中的最小页面；写代码前优先复制已验证可执行示例的结构，不要从多个页面拼接未经验证的新骨架。 -7. 遇到反例、解释器差异或资料冲突时，先按 [12_pitfalls.md](12_pitfalls.md) 和对应专题页收口；仍无结论时不要发明语法。 - -## 如果你马上要写 TSL - -1. [02_quickstart.md](02_quickstart.md)（先看语言核心事实速查和最短骨架） -2. [03_core_model.md](03_core_model.md) -3. [06_functions_and_calls.md](06_functions_and_calls.md) -4. [12_pitfalls.md](12_pitfalls.md) -5. 涉及较新写法时，按主题跳到对应专题页 - -## 推荐读法 - -1. [01_introduction.md](01_introduction.md) -2. [02_quickstart.md](02_quickstart.md) -3. [03_core_model.md](03_core_model.md) -4. [04_values_and_literals.md](04_values_and_literals.md) -5. [05_variables_and_constants.md](05_variables_and_constants.md) -6. [06_functions_and_calls.md](06_functions_and_calls.md) -7. [07_expressions_and_operators.md](07_expressions_and_operators.md) -8. [08_control_flow.md](08_control_flow.md) -9. [09_objects_and_classes.md](09_objects_and_classes.md) -10. [10_units_and_scope.md](10_units_and_scope.md) -11. [11_runtime_context_and_with.md](11_runtime_context_and_with.md) -12. [12_pitfalls.md](12_pitfalls.md) -13. [13_matrix_and_collections.md](13_matrix_and_collections.md) -14. [14_resultset_and_filters.md](14_resultset_and_filters.md) -15. [15_ts_sql.md](15_ts_sql.md) -16. [16_debug_and_profiler.md](16_debug_and_profiler.md) - 这条顺序对应“先建立整体读法，再写值、变量、函数、表达式、流程，随后进入类、unit、运行时边界，再按需进入进阶专题”。 - -编号说明：主线 `01-16`，深水 `18-32`，无 `17` 号正文页；历史 `17` 号位保留为空。 - -## 深水专题 - -以下专题默认不要预读。只有主线页不够、或者任务已经明确命中对应场景时，再进入。 - -| 专题 | 什么时候进入 | -| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | -| [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) | 只有涉及注释规则、条件编译、编译选项或词法边界时才读 | -| [19_types_and_conversions.md](19_types_and_conversions.md) | 只有涉及显式类型、转换规则或类型兼容问题时才读 | -| [20_strings_and_text.md](20_strings_and_text.md) | 只有涉及字符串处理、编码或文本细节时才读 | -| [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | 只有涉及 `external`、DLL、线程或外部调用时才读 | -| [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | 只有涉及 `namespace`、`Libpath`、unit 运行时或查找路径时才读 | -| [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) | 只有涉及对象运行时、自省或反射能力时才读 | -| [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) | 只有涉及内置运行时对象时才读 | -| [25_set_operations.md](25_set_operations.md) | 只有涉及集合运算专题时才读 | -| [26_matrix_deep_dive.md](26_matrix_deep_dive.md) | 只有涉及矩阵运算且 [13_matrix_and_collections.md](13_matrix_and_collections.md) 不够用时才读 | -| [27_fmarray.md](27_fmarray.md) | 只有涉及 `FMArray` 专题时才读 | -| [28_ts_sql_core.md](28_ts_sql_core.md) | 只有开始写 TS-SQL 核心语法时才读 | -| [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | 只有 TS-SQL 基础页不够、问题进入进阶能力时才读 | -| [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | 只有涉及网格计算、运行时服务或全局缓存时才读 | -| [31_complex_and_weakref.md](31_complex_and_weakref.md) | 只有涉及复数或弱引用时才读 | -| [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 只有涉及对象算符重载或遍历重载时才读 | - -这组页面承担旧 8 章里没有被主线正文完整吃掉的深水内容，目标是让新 session 只靠 `docs/tsl/syntax/` 就能覆盖旧语法章节，但默认首跳仍应先走主线页。 +1. 先判断文件模型；完整规则看 [02_core_model.md](02_core_model.md)。 +2. 用户已给 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，入口流程或一次性脚本初判为 `.tsl`，可复用交付物初判为 `.tsf`。 +3. 文件模型会影响正确性且目标不明确时，先向用户确认。 +4. 识别关键词属于值/变量、函数、类、unit、表达式、控制流、运行时、TS-SQL 或进阶专题。 +5. 只进入命中的最小页面；写代码前优先参考该页的可直接照写示例。 +6. 命中反例或负向边界时，先看 [11_pitfalls.md](11_pitfalls.md) 和对应专题页；仍无结论时不要发明语法。 ## 按任务跳转 -| 当前任务 | 先读哪里 | -| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -| 先建立整体读法 | [01_introduction.md](01_introduction.md) | -| 写最短骨架 | [02_quickstart.md](02_quickstart.md) | -| 判断顶层模型 / 文件模型 | [03_core_model.md](03_core_model.md) | -| 写值、数组、字符串 | [04_values_and_literals.md](04_values_and_literals.md) | -| 写变量、常量、显式声明 | [05_variables_and_constants.md](05_variables_and_constants.md) | -| 写 `function` / `procedure`、参数修饰、默认参数、命名参数、变参、`external` | [06_functions_and_calls.md](06_functions_and_calls.md) | -| 写赋值、比较、`if` 表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) | -| 写 `?.` 等较新表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) | -| 写条件、循环、异常控制 | [08_control_flow.md](08_control_flow.md) | -| 写类、继承、property、静态字段 | [09_objects_and_classes.md](09_objects_and_classes.md) | -| 写 `unit` / `uses` | [10_units_and_scope.md](10_units_and_scope.md) | -| 写运行时环境参数、`SysParams[...]`、`#Func() with array(...)` | [11_runtime_context_and_with.md](11_runtime_context_and_with.md) | -| 先避开高频误写 | [12_pitfalls.md](12_pitfalls.md) | -| 写数组扩展、键表、矩阵样数据 | [13_matrix_and_collections.md](13_matrix_and_collections.md) | -| 写结果集过滤专题 | [14_resultset_and_filters.md](14_resultset_and_filters.md) | -| 写 TS-SQL 专题 | [15_ts_sql.md](15_ts_sql.md) | -| 看调试与 profiler 专题 | [16_debug_and_profiler.md](16_debug_and_profiler.md) | -| 看词法、注释、编译选项 | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) | -| 看类型与转换 | [19_types_and_conversions.md](19_types_and_conversions.md) | -| 看字符串与编码专题 | [20_strings_and_text.md](20_strings_and_text.md) | -| 看 `external`、DLL 与多线程 | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | -| 看 `namespace`、单元运行时、`Libpath`、查找路径 | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | -| 看对象运行时和反射 | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) | -| 看运行时内置对象 | [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) | -| 看集合运算 | [25_set_operations.md](25_set_operations.md) | -| 看矩阵深水专题 | [26_matrix_deep_dive.md](26_matrix_deep_dive.md) | -| 看 `FMArray` | [27_fmarray.md](27_fmarray.md) | -| 看 TS-SQL 基础 | [28_ts_sql_core.md](28_ts_sql_core.md) | -| 看 TS-SQL 进阶 | [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | -| 看网格计算与全局缓存 | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | -| 看复数与弱引用 | [31_complex_and_weakref.md](31_complex_and_weakref.md) | -| 看对象算符与遍历重载 | [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | -| 看较新表达式或表达式边界 | [07_expressions_and_operators.md](07_expressions_and_operators.md) | -| 看较新对象能力或类边界 | [09_objects_and_classes.md](09_objects_and_classes.md) | -| 看资料冲突 / 解释器差异 | 先留在当前页，对照上面的主线与深水进入条件后，再按主题进入相应页面 | -| 看高频误写 / 反例 / 负向边界 | [12_pitfalls.md](12_pitfalls.md) | -| 看正式语法手册当前覆盖范围与成熟度 | [coverage_map.md](coverage_map.md) | +| 任务 | 先读哪里 | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | +| 写最短骨架 / 语言核心事实 | [01_quickstart.md](01_quickstart.md) | +| 判断 `.tsl` / `.tsf`、顶层语句区、声明区、文件模型 | [02_core_model.md](02_core_model.md) | +| 写值、数组、字符串、字符串编码边界 | [03_values_and_literals.md](03_values_and_literals.md) | +| 写变量、常量、显式声明 | [04_variables_and_constants.md](04_variables_and_constants.md) | +| 写 `function` / `procedure`、参数、默认参数、命名参数、变参 | [05_functions_and_calls.md](05_functions_and_calls.md) | +| 写赋值、比较、条件表达式、较新表达式、运算符边界 | [06_expressions_and_operators.md](06_expressions_and_operators.md) | +| 写条件、循环、异常控制 | [07_control_flow.md](07_control_flow.md) | +| 写类、继承、property、静态字段、较新对象能力或类边界 | [08_objects_and_classes.md](08_objects_and_classes.md) | +| 写 `unit` / `uses` | [09_units_and_scope.md](09_units_and_scope.md) | +| 写运行时环境参数、`sysParams[...]`、`with array(...)`、网格调用或全局缓存 | [10_runtime_context_and_with.md](10_runtime_context_and_with.md) | +| 核对高频误写 / 反例 / 负向边界 | [11_pitfalls.md](11_pitfalls.md) | +| 写数组扩展、键表、集合运算、矩阵样数据 | [12_matrix_and_collections.md](12_matrix_and_collections.md) | +| 写结果集过滤专题 | [13_resultset_and_filters.md](13_resultset_and_filters.md) | +| 写 TS-SQL 专题 | [14_ts_sql.md](14_ts_sql.md) | +| 看调试与性能分析器专题 | [15_debug_and_profiler.md](15_debug_and_profiler.md) | +| 看注释、条件编译、编译选项或词法边界 | [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md) | +| 看显式类型、转换规则、复数 | [17_types_and_conversions.md](17_types_and_conversions.md) | +| 看 `external`、DLL 与多线程 | [18_external_calls_and_threads.md](18_external_calls_and_threads.md) | +| 看 `namespace`、`Libpath`、unit 运行时、查找路径 | [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md) | +| 看对象运行时、自省、反射、弱引用 | [20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md) | +| 看运行时内置对象 | [21_builtin_runtime_objects.md](21_builtin_runtime_objects.md) | +| 看矩阵进阶专题 | [22_matrix_deep_dive.md](22_matrix_deep_dive.md) | +| 看 `FMArray` | [23_fmarray.md](23_fmarray.md) | +| 看对象算符重载或遍历重载 | [24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md) | -## 旧 8 章在正式手册中的落点 +## 入口禁止项 -- `01_language_basics.md`：主线落在 `01` `03` `04` `05` `07` `11` `13`，深水落在 `18` `19` `20` -- `02_control_flow.md`：主线落在 `08`，调试与性能补充落在 `16` -- `03_functions.md`：主线落在 `06`，系统交互补充落在 `21` -- `04_modules_and_namespace.md`：主线落在 `10`，单元运行时与查找路径补充落在 `22` -- `05_object_model.md`：主线落在 `09`，运行时 / 内置对象 / 重载补充落在 `23` `24` `32` -- `06_extended_syntax.md`：主线入口在 `13` `14` `15`，深水落在 `25` `26` `27` `28` `29` -- `07_debug_and_profiler.md`：入口在 `16`，服务层运行时补充落在 `30` -- `08_new_generation.md`：表达式与对象主线落在 `07` `09`，复数 / 弱引用 / 对象重载落在 `31` `32` +- 不要跳过“智能体语法判断流程”和“按任务跳转”直接顺序读完整套。 +- 不要把本入口页当成可直接生成代码的语法事实页。 +- 不要从多个专题页拼接未写入文档的新骨架；生成前优先使用单页里的可直接照写示例。 +- 不要把数据仓库函数查询、模块集成或项目执行问题留在语法层处理。 ## 切换到别的层 -- 业务问题：见 [../finance/index.md](../finance/index.md) +- 数据仓库金融函数：见 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md) - 模块 / 集成 / 互操作：见 [../modules/index.md](../modules/index.md) - 函数库查找：见 [../reference/index.md](../reference/index.md) diff --git a/docs/tsl/toolchain.md b/docs/tsl/toolchain.md index e4315dc9..42e2141f 100644 --- a/docs/tsl/toolchain.md +++ b/docs/tsl/toolchain.md @@ -2,28 +2,28 @@ 文档类型：模板页 是否可直接用于生成代码：否 -是否含已验证可执行示例：否 -是否含已验证反例：否 -遇到不确定时跳转到：项目自身文档、`scripts/*` 入口脚本、CI 配置 +是否含可直接照写示例：否 +是否含不可照写反例：否 +遇到不确定时：项目自身文档、`scripts/*` 入口脚本、CI 配置 这里处理项目执行类问题，不处理通用 TSL 语法事实。 -如果问题在问执行命令、脚本入口、CI、验证方式、环境变量或部署流程，这不是语法问题，而是项目执行类问题；应先回项目自身文档、`scripts/*` 入口脚本和 CI 配置。默认检索 TSL 语法、代码写法或真实执行命令时，应忽略本页。本页只是一份待补齐模板，不提供真实可执行命令。 +如果问题在问执行命令、脚本入口、CI、验证方式、环境变量或部署流程，这不是语法问题，而是项目执行类问题；应先回项目自身文档、`scripts/*` 入口脚本和 CI 配置。默认检索 TSL 语法、代码写法或真实执行命令时，应忽略本页。本页只是一份占位模板，不提供真实可执行命令。 ## 模板说明 - 本文件提供一份通用占位模板，不是通用执行手册。 -- 只有在当前项目已经把工具链、执行入口和验证命令补齐后，才可以把它当成执行依据。 -- 如果这页里仍然出现 `<...>` 形式的占位符，说明当前项目还没有补齐真实信息，应回到项目自身文档或脚本入口。 +- 只有在本项目已经写明工具链、执行入口和验证命令后，才可以把它当成执行依据。 +- 如果这页里仍然出现 `<...>` 形式的占位符，说明本项目还没有写明真实信息，应回到项目自身文档或脚本入口。 - 以下命令片段全部属于模板占位，不是真实 CLI 示例，也不应被 AI 直接复制执行。 ## 为什么不可直接执行 -- 占位符没有绑定到当前项目的真实解释器、路径、环境变量和脚本入口。 +- 占位符没有绑定到本项目的真实解释器、路径、环境变量和脚本入口。 - 同一条模板命令在不同项目里可能对应不同的安装方式、权限模型和验证流程。 - 如果直接照抄本页内容，最常见的错误是路径不存在、可执行入口错误、凭证缺失或验证层级不匹配。 -## 项目补齐项 +## 项目填写项 ### 解释器/编译器（必填） @@ -81,11 +81,11 @@ Windows: - 凭证、许可证等敏感信息应通过环境变量或 CI secrets 注入；文档只写变量名或获取方式，不写明文值。 -### 验证命令（必须补齐） +### 验证命令（必须填写） -- 至少补齐一个最小冒烟命令。 -- 如果项目存在测试体系，应继续补齐单元测试、静态检查和构建命令。 -- 所有命令都应替换成当前项目的真实入口，不要保留模板占位。 +- 至少填写一个最小冒烟命令。 +- 如果项目存在测试体系，应继续填写单元测试、静态检查和构建命令。 +- 所有命令都应替换成本项目的真实入口，不要保留模板占位。 最小冒烟模板： @@ -123,7 +123,7 @@ sh scripts/format.sh sh scripts/build.sh ``` -成功信号也必须补齐为真实规则，例如退出码、关键输出或产物路径。 +成功信号也必须写成真实规则，例如退出码、关键输出或产物路径。 ### 失败处理约定（必填） diff --git a/rulesets/tsl/index.md b/rulesets/tsl/index.md index 378de56a..d7f5011f 100644 --- a/rulesets/tsl/index.md +++ b/rulesets/tsl/index.md @@ -1,57 +1,141 @@ -# TSL 代理规则集 +# TSL 智能体规则 -本规则集定义 AI/自动化代理在处理 TSL 代码时必须遵守的核心约束。 +文档类型：高优先级智能体决策规则 +是否可直接用于生成代码：否 +作用：控制智能体在阅读、修改、生成 TSL 代码前的判断顺序、文档路由、禁止行为和自检流程。 + +本文件不是 TSL 语法手册，也不是完整教程。智能体必须先按本文件判断任务类型，再进入对应的 `docs/tsl/` 页面查阅语法、函数库或模块集成信息。 + +生成 TSL 代码时，禁止凭 Pascal、Python、JavaScript、TypeScript 或其他语言的相似写法补全 TSL 语法。文档没有给出结论时，必须向用户确认、记录文档缺口，或改用文档已经写明的可照写示例，不得发明语法。 ## 范围与优先级 -- 作为仓库级基线规则集使用；更靠近代码目录的规则更具体并可覆盖基线。 -- 当代理规则与 docs 冲突：安全/合规优先，其次保持仓库一致性。 +- 本文件是仓库级 TSL 智能体高优先级规则。 +- 更靠近代码目录的本地规则可以增加更严格的约束，但不能削弱本文件中的安全、文档事实和禁止发明语法规则。 +- 本文件控制智能体行为和判断顺序，不替代 `docs/tsl/` 下的语法、函数库、模块集成或项目执行文档。 +- 当本文件与 `docs/tsl/**` 冲突时，按以下顺序处理： + 1. 安全与凭据处理规则。 + 2. 用户明确指令中关于目标、交付物、文件路径和风格偏好的部分。 + 3. 本地目录规则中更具体且不削弱本文件安全、文档事实和禁止发明语法规则的部分。 + 4. 本智能体规则集。 + 5. TSL 语法/函数库事实文档。 + 6. 现有项目代码模式。 +- 用户明确指令不能覆盖安全规则、文档事实使用规则、禁止发明语法规则或 TSL 事实。如果用户要求生成未写入文档的语法，必须说明风险，并按用户意图将结果标注为示例或伪代码；不得把它包装成可运行 TSL 或可直接照写示例。 +- 如果两个权威来源对 TSL 语法结论不一致，不要猜测。必须说明冲突，优先采用 `代码块身份：可直接照写示例`；当差异会影响生成代码正确性时，先向用户确认。 -## 代理工作原则（铁律） +## 代码生成协议 -1. 先理解目标与上下文，再动手改代码 -2. 修改要小而清晰；避免无关重构 -3. 发现安全问题（明文密钥/鉴权漏洞）立即标注或修复 -4. 不引入新依赖或工具，除非明确要求 +生成或修改 TSL 代码前，智能体必须执行以下流程： -## TSL 核心约定（不可违反） +1. 识别用户交付目标：可执行脚本、可复用模块、语法解释、缺陷修复、重构、业务逻辑、函数查询或集成任务。 +2. 识别文件模型： + - 用户要求可执行脚本或入口流程时，使用 `.tsl`。 + - 用户要求可复用函数、过程、类、模块或扩展代码时，使用 `.tsf`。 + - 文件模型会影响正确性且需求不明确时，生成代码前向用户确认。 +3. 路由到 `docs/tsl/` 下最小且最相关的权威文档。 +4. 生成代码外形时，优先参考 `代码块身份：可直接照写示例`。 +5. 避开任何标记为 `代码块身份：反例 / 不可照写` 的代码块。 +6. 除非文档明确说明组合方式，否则不要把多个页面的片段拼成新的语法外形。 +7. 没有文档结论时，不要发明语法；改为向用户确认或记录文档缺口。 +8. 生成代码后，执行本文件中的最终 TSL 自检。 -- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，再根据用户交付目标判断。 -- `.tsl` 是可执行脚本：语句区按顺序执行；如果需要函数/类，放在脚本语句后的函数/类声明区。 -- `.tsf` 是模块/函数扩展文件：部署到解释器 `funcext` 后，脚本可直接调用其中暴露的顶层函数。 -- 格式：4 空格缩进；关键字小写；多语句用 `begin/end` -- 命名：类型/函数/property `PascalCase`；变量/参数 `snake_case`；私有 `snake_case_`；常量 `kPascalCase` +## TSL 核心事实 -## agent 判断流程 +以下只保留高优先级提醒。完整文件模型看 `docs/tsl/syntax/02_core_model.md`；完整语法细节从 `docs/tsl/syntax/index.md` 分流。 -1. 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。 -2. 用户未给后缀时，先判断交付目标是可执行代码还是通用模块；可执行代码对应 `.tsl`，通用模块对应 `.tsf`。 -3. 交付目标仍不明确时向用户确认，不要替用户发明文件形态。 -4. 写 `.tsl` 时，先生成顺序执行的语句区；调用本脚本内函数时，函数声明写在语句区之后。 -5. 写 `.tsf` 时，只生成模块/扩展声明；顶层函数部署到解释器 `funcext` 后才可被脚本直接调用。 -6. 如果关键词命中业务、函数库、模块集成或项目执行信息，按 `docs/tsl/index.md` 分流，不把所有问题都当语法问题。 -7. 不确定时先找已验证可执行示例、反例页和对应专题页；没有文档结论时不要发明语法，改为向用户确认或记录文档缺口。 +- `.tsl` 在通用 TSL 规则中表示可执行脚本；如果项目把 `.tsl` 另作它用，必须先确认项目约定，不能反推为通用事实。 +- `.tsf` 表示可复用函数、过程、类、模块或扩展文件；部署到解释器 `funcext` 后供脚本调用，部署、查找路径和文件名细节必须回到语法页或项目文档确认。 +- 用户明确给出 `.tsl` 或 `.tsf` 后缀时，后缀是主要文件模型信号；未给后缀时先按交付目标初判，影响正确性且不明确就先确认。 +- 入口流程、脚本任务或一次性任务默认 `.tsl`；可复用函数、过程、类、模块或扩展默认 `.tsf`；脚本内部封装函数或类不自动升级为 `.tsf`。 +- 在 `.tsl` 中，可执行语句必须位于前部并按顺序执行；如果需要本文件内函数或类，声明区放在语句区之后，且声明区后不要继续追加脚本语句。 +- 在 `.tsf` 中，只生成可复用顶层声明或 `unit`；不要写成顺序执行入口。 +- 创建对象有两种方式：`new ClassName()` 最常用，`createObject(...)` 作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`。 +- 不要因为 Pascal、Python、JavaScript 或 TypeScript 支持某种写法，就假设 TSL 也支持。 -## 安全红线（不可触碰） +## 任务路由 -- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key -- 修改鉴权/权限逻辑必须说明动机与风险 -- 不确定是否敏感时按敏感信息处理 +先路由任务，再阅读详细文档。不要把所有 TSL 相关请求都当成语法请求。 -## 权威来源 +- 如果用户询问语言语法怎么写，先读 `docs/tsl/syntax/index.md`。 +- 如果用户要求最短可运行骨架，先读 `docs/tsl/syntax/01_quickstart.md`。 +- 如果用户询问某个语法形式是否有效，先读 `docs/tsl/syntax/index.md`，再进入最小匹配专题页。 +- 如果用户询问常见误写、反例或不安全假设，先读 `docs/tsl/syntax/11_pitfalls.md`。 +- 如果用户询问行情、财务、板块、选股等金融函数，先读 `docs/tsl/reference/catalog/datawarehouse.md`。 +- 如果用户询问 Python 调 TSL 服务器函数、批量取数或异步取数，先读 `docs/tsl/modules/pytsl_api.md`。 +- 如果用户询问回测框架、组合回测、交易流程或回测结果读取，先读 `docs/tsl/modules/tsbacktesting.md`。 +- 如果用户询问某个内置函数或函数库函数怎么用，先读 `docs/tsl/reference/index.md`。 +- 如果用户询问模块、集成、pyTSL、微信消息或回测模块，先读 `docs/tsl/modules/index.md`。 +- 如果用户询问账户体系、真实服务端点、部署、脚本入口、环境变量、CI 或验证命令，把问题视为项目执行上下文；优先查项目文档、`scripts/*` 和 CI 配置，不要从通用 TSL 语法文档里猜。 -- TSL 总入口：`docs/tsl/index.md` -- 语法手册：`docs/tsl/syntax/index.md` -- 金融业务入口：`docs/tsl/finance/index.md` -- 模块与集成入口：`docs/tsl/modules/index.md` -- 函数检索入口：`docs/tsl/reference/index.md` -- 代码风格：`docs/tsl/code_style.md` -- 命名规范：`docs/tsl/naming.md` +### 路由冲突处理 -## Skills（按需加载） +- 如果一个任务同时涉及业务和语法，按用户的主要目标路由。 +- 如果主要目标是业务行为，先读模块文档、函数事实页或项目实际接口文档，语法文档只做辅助。 +- 如果主要目标是语言有效性，先读语法文档，业务或模块文档只作为示例和上下文。 +- 如果任务依赖真实凭据、账户、部署或环境行为，不要发明项目事实；必须询问用户或检查项目专属文件。 -- `$commit-message` +## 文档入口 -## 与开发规范的关系 +按目的选择来源，不要默认通读全部文档。 -- 规范文档：`docs/tsl/` 与 `docs/common/` +| 目的 | 来源 | 性质 | +| ----------------------------- | --------------------------------------------- | ---------- | +| 顶层路由 | `docs/tsl/index.md` | 决策入口 | +| 语法判断 | `docs/tsl/syntax/index.md` | 语法入口 | +| 最短可运行骨架与核心事实 | `docs/tsl/syntax/01_quickstart.md` | 语法入口 | +| 高频误写与反例 | `docs/tsl/syntax/11_pitfalls.md` | 语法入口 | +| 数据仓库金融函数 | `docs/tsl/reference/catalog/datawarehouse.md` | 函数事实 | +| pyTSL / 服务器函数 / 批量取数 | `docs/tsl/modules/pytsl_api.md` | 模块 API | +| 回测框架与结果接口 | `docs/tsl/modules/tsbacktesting.md` | 模块 API | +| 模块与集成任务 | `docs/tsl/modules/index.md` | 集成入口 | +| 函数库查询 | `docs/tsl/reference/index.md` | 函数库入口 | +| 本仓库格式偏好 | `docs/tsl/code_style.md` | 非语法事实 | +| 本仓库/作者命名偏好 | `docs/tsl/naming.md` | 非语法事实 | + +## 文档事实使用策略 + +- 页面级元数据只是粗粒度信号。生成代码时，优先看代码块级别的 `代码块身份`。 +- 优先参考标记为 `代码块身份：可直接照写示例` 的代码块。 +- 永远不要复制标记为 `代码块身份：反例 / 不可照写` 的代码块作为可运行代码。 +- `代码块身份：配置片段 / 概念骨架` 只能作为结构提示，不能当作可直接运行代码。 +- `代码块身份：输出片段` 只能作为输出形态，不能当作源码。 +- 模板、错误示例和输出片段都不是可独立编译代码。 +- 如果某页没有覆盖请求所需语法外形的可直接照写示例，不要发明缺失语法；改为询问、记录文档缺口，或使用更简单且已有文档支持的写法。 +- `code_style.md` 与 `naming.md` 只表达本仓库或作者风格偏好，不代表 TSL 语法事实。 + +## 安全规则 + +- 不得把明文密钥、密码、token、API key、cookie、私钥或真实凭据写入代码、日志、注释、示例、测试或文档。 +- 如果用户提供真实敏感信息，不要复述；替换为 ``、`` 或 `` 等占位符。 +- 如果现有代码中出现疑似敏感信息，必须明确标注风险，并避免把它复制到新代码或解释中。 +- 修改鉴权、授权、权限检查、账户处理、交易权限、下单或生产执行路径时，必须说明动机和风险。 +- 不确定某个值是否敏感时，按敏感信息处理。 +- 不要发明账户 ID、服务端点、生产路径或凭据名称；必须使用项目专属文档，或向用户确认。 +- 金融或交易任务中，除非用户明确要求且项目文档确认执行路径，否则不要生成会静默真实下单、改变账户状态或使用生产凭据的代码。 +- 当任务可能影响真实交易或外部系统时，优先使用 dry-run、仿真、回测或显式确认流程。 + +## 修改纪律 + +- 改动必须小而聚焦，只服务于用户当前请求。 +- 避免无关重构、格式刷屏或文档大改。 +- 除非用户明确要求，不要新增依赖、工具、脚本或执行要求。 +- 引入新模式前，先遵循现有项目风格、文件布局和命名习惯。 +- 编辑 TSL 文档时，保留元数据字段和 `代码块身份` 标签，因为智能体路由依赖这些信息。 +- 不要声称生成或修改后的代码已经验证，除非确实运行了对应命令或已有项目执行记录。 + +## 最终 TSL 自检 + +展示生成或修改后的 TSL 代码前，必须检查： + +1. 任务是否路由到正确层：语法、函数库、模块集成或项目执行。 +2. 文件模型是否正确：`.tsl` 用于可执行脚本，`.tsf` 用于可复用函数、过程、类、模块或扩展。 +3. 对 `.tsl`，可执行语句是否位于本文件函数/类声明之前。 +4. 对 `.tsl`，声明区之后是否没有继续追加可执行脚本语句。 +5. 对 `.tsf`，代码是否是可复用顶层声明；文件名已知时，是否尊重文件基名与声明名关系。 +6. 代码外形是否基于文档事实或 `代码块身份：可直接照写示例`。 +7. 是否没有把 `反例 / 不可照写`、输出片段或概念骨架当作可运行代码复制。 +8. 是否没有从其它语言家族发明 TSL 语法。 +9. 是否没有猜测内置名、函数库函数、模块行为或项目事实。 +10. 如果任务要求遵循本仓库风格，是否只把 `code_style.md` 和 `naming.md` 当作本仓库/作者偏好，而不是语法事实。 +11. 是否没有引入密钥、凭据、生产端点或不安全的交易/账户行为。 +12. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。 diff --git a/tests/cli/test_playbook_cli.py b/tests/cli/test_playbook_cli.py index 78566227..d57b531c 100644 --- a/tests/cli/test_playbook_cli.py +++ b/tests/cli/test_playbook_cli.py @@ -214,7 +214,7 @@ langs = ["tsl"] text = docs_index.read_text(encoding="utf-8") self.assertIn("`tsl/index.md`", text) self.assertIn("`tsl/syntax/index.md`", text) - self.assertIn("`tsl/finance/index.md`", text) + self.assertIn("`tsl/reference/catalog/datawarehouse.md`", text) self.assertIn("`tsl/modules/index.md`", text) self.assertIn("`tsl/reference/index.md`", text) self.assertNotIn("`tsl/syntax_book/index.md`", text) diff --git a/tests/test_tsl_entrypoints_consistency.py b/tests/test_tsl_entrypoints_consistency.py index 9136edb9..28a9d8b1 100644 --- a/tests/test_tsl_entrypoints_consistency.py +++ b/tests/test_tsl_entrypoints_consistency.py @@ -1,15 +1,23 @@ +import re import unittest from pathlib import Path ROOT = Path(__file__).resolve().parents[1] RULESET_TSL = ROOT / "rulesets" / "tsl" / "index.md" -TSL_INTRODUCTION = ROOT / "docs" / "tsl" / "syntax" / "01_introduction.md" -TSL_QUICKSTART = ROOT / "docs" / "tsl" / "syntax" / "02_quickstart.md" -TSL_CORE_MODEL = ROOT / "docs" / "tsl" / "syntax" / "03_core_model.md" -TSL_VALUES = ROOT / "docs" / "tsl" / "syntax" / "04_values_and_literals.md" -TSL_VARIABLES = ROOT / "docs" / "tsl" / "syntax" / "05_variables_and_constants.md" -TSL_FUNCTIONS = ROOT / "docs" / "tsl" / "syntax" / "06_functions_and_calls.md" -TSL_EXPRESSIONS = ROOT / "docs" / "tsl" / "syntax" / "07_expressions_and_operators.md" +TSL_QUICKSTART = ROOT / "docs" / "tsl" / "syntax" / "01_quickstart.md" +TSL_CORE_MODEL = ROOT / "docs" / "tsl" / "syntax" / "02_core_model.md" +TSL_VALUES = ROOT / "docs" / "tsl" / "syntax" / "03_values_and_literals.md" +TSL_VARIABLES = ROOT / "docs" / "tsl" / "syntax" / "04_variables_and_constants.md" +TSL_FUNCTIONS = ROOT / "docs" / "tsl" / "syntax" / "05_functions_and_calls.md" +TSL_EXPRESSIONS = ROOT / "docs" / "tsl" / "syntax" / "06_expressions_and_operators.md" +TSL_CONTROL_FLOW = ROOT / "docs" / "tsl" / "syntax" / "07_control_flow.md" +TSL_TS_SQL = ROOT / "docs" / "tsl" / "syntax" / "14_ts_sql.md" +TSL_TYPES = ROOT / "docs" / "tsl" / "syntax" / "17_types_and_conversions.md" +TSL_EXTERNAL = ROOT / "docs" / "tsl" / "syntax" / "18_external_calls_and_threads.md" +TSL_MATRIX_DEEP_DIVE = ROOT / "docs" / "tsl" / "syntax" / "22_matrix_deep_dive.md" +TSL_FMARRAY = ROOT / "docs" / "tsl" / "syntax" / "23_fmarray.md" +TSL_OBJECT_RUNTIME = ROOT / "docs" / "tsl" / "syntax" / "20_object_runtime_and_introspection.md" +TSL_BUILTIN_RUNTIME_OBJECTS = ROOT / "docs" / "tsl" / "syntax" / "21_builtin_runtime_objects.md" README = ROOT / "README.md" PLAYBOOK_EXAMPLE = ROOT / "playbook.toml.example" SKILLS_DOC = ROOT / "SKILLS.md" @@ -17,47 +25,68 @@ TEMPLATES_CI_README = ROOT / "templates" / "ci" / "README.md" TEMPLATES_README = ROOT / "templates" / "README.md" REMOVED_TSL_GUIDE = ROOT / "skills" / "tsl-guide" TSL_REFERENCE_INDEX = ROOT / "docs" / "tsl" / "reference" / "index.md" -TSL_REFERENCE_CATALOG_INDEX = ROOT / "docs" / "tsl" / "reference" / "catalog" / "index.md" -TSL_REFERENCE_VERIFIED_INDEX = ROOT / "docs" / "tsl" / "reference" / "verified" / "index.md" -TSL_REFERENCE_VERIFIED_CORE = ROOT / "docs" / "tsl" / "reference" / "verified" / "core.md" TSL_REFERENCE_UNAVAILABLE = ROOT / "docs" / "tsl" / "reference" / "unavailable_methods.md" -TSL_FINANCE_INDEX = ROOT / "docs" / "tsl" / "finance" / "index.md" TSL_MODULES_INDEX = ROOT / "docs" / "tsl" / "modules" / "index.md" TSL_REMAINING_SYNTAX_AGENT_SECTIONS = { - "08_control_flow.md": "Agent 控制流判断流程", - "09_objects_and_classes.md": "Agent 对象/类判断流程", - "10_units_and_scope.md": "Agent unit/作用域判断流程", - "11_runtime_context_and_with.md": "Agent 运行时上下文判断流程", - "12_pitfalls.md": "Agent 常见误写判断流程", - "13_matrix_and_collections.md": "Agent 矩阵/集合判断流程", - "14_resultset_and_filters.md": "Agent 结果集/过滤判断流程", - "15_ts_sql.md": "Agent TS-SQL 判断流程", - "16_debug_and_profiler.md": "Agent 调试/Profiler 判断流程", - "18_lexical_structure_and_compile_options.md": "Agent 词法/编译选项判断流程", - "19_types_and_conversions.md": "Agent 类型/转换判断流程", - "20_strings_and_text.md": "Agent 字符串/文本判断流程", - "21_external_calls_and_threads.md": "Agent 外部调用/线程判断流程", - "22_namespace_libpath_and_unit_runtime.md": "Agent 命名空间/Libpath 判断流程", - "23_object_runtime_and_introspection.md": "Agent 对象运行时/反射判断流程", - "24_builtin_runtime_objects.md": "Agent 内置运行时对象判断流程", - "25_set_operations.md": "Agent 集合运算判断流程", - "26_matrix_deep_dive.md": "Agent 矩阵深水判断流程", - "27_fmarray.md": "Agent FMArray 判断流程", - "28_ts_sql_core.md": "Agent TS-SQL Core 判断流程", - "29_ts_sql_advanced.md": "Agent TS-SQL Advanced 判断流程", - "30_runtime_services_and_global_cache.md": "Agent 运行时服务/全局缓存判断流程", - "31_complex_and_weakref.md": "Agent 复数/弱引用判断流程", - "32_object_overloads_and_iteration.md": "Agent 对象重载/迭代判断流程", + "07_control_flow.md": "智能体控制流判断流程", + "08_objects_and_classes.md": "智能体对象/类判断流程", + "09_units_and_scope.md": "智能体 unit/作用域判断流程", + "10_runtime_context_and_with.md": "智能体运行时上下文判断流程", + "11_pitfalls.md": "智能体常见误写判断流程", + "12_matrix_and_collections.md": "智能体数组/矩阵样数据判断流程", + "13_resultset_and_filters.md": "智能体结果集/过滤判断流程", + "14_ts_sql.md": "智能体 TS-SQL 判断流程", + "15_debug_and_profiler.md": "智能体调试/性能分析器判断流程", + "16_lexical_structure_and_compile_options.md": "智能体词法/编译选项判断流程", + "17_types_and_conversions.md": "智能体类型/转换判断流程", + "18_external_calls_and_threads.md": "智能体外部调用/线程判断流程", + "19_namespace_libpath_and_unit_runtime.md": "智能体命名空间/Libpath 判断流程", + "20_object_runtime_and_introspection.md": "智能体对象运行时/反射判断流程", + "21_builtin_runtime_objects.md": "智能体内置运行时对象判断流程", + "22_matrix_deep_dive.md": "智能体矩阵深水判断流程", + "23_fmarray.md": "智能体 FMArray 判断流程", + "24_object_overloads_and_iteration.md": "智能体对象重载/迭代判断流程", } +TSL_SYNTAX_MAINLINE_FILES = [ + "01_quickstart.md", + "02_core_model.md", + "03_values_and_literals.md", + "04_variables_and_constants.md", + "05_functions_and_calls.md", + "06_expressions_and_operators.md", + "07_control_flow.md", + "08_objects_and_classes.md", + "09_units_and_scope.md", + "10_runtime_context_and_with.md", + "12_matrix_and_collections.md", + "13_resultset_and_filters.md", + "14_ts_sql.md", + "15_debug_and_profiler.md", +] + +TSL_SYNTAX_DEEP_DIVE_FILES = [ + "16_lexical_structure_and_compile_options.md", + "17_types_and_conversions.md", + "18_external_calls_and_threads.md", + "19_namespace_libpath_and_unit_runtime.md", + "20_object_runtime_and_introspection.md", + "21_builtin_runtime_objects.md", + "22_matrix_deep_dive.md", + "23_fmarray.md", + "24_object_overloads_and_iteration.md", +] + class TslEntrypointsConsistencyTests(unittest.TestCase): def test_ruleset_lists_canonical_tsl_layers(self): text = RULESET_TSL.read_text(encoding="utf-8") self.assertIn("docs/tsl/index.md", text) self.assertIn("docs/tsl/syntax/index.md", text) - self.assertIn("docs/tsl/finance/index.md", text) + self.assertIn("docs/tsl/reference/catalog/datawarehouse.md", text) + self.assertIn("docs/tsl/modules/pytsl_api.md", text) + self.assertIn("docs/tsl/modules/tsbacktesting.md", text) self.assertIn("docs/tsl/modules/index.md", text) self.assertIn("docs/tsl/reference/index.md", text) @@ -108,31 +137,43 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): self.assertNotIn("tsl-guide", SKILLS_DOC.read_text(encoding="utf-8")) self.assertNotIn("$tsl-guide", RULESET_TSL.read_text(encoding="utf-8")) - def test_tsl_ruleset_describes_agent_first_file_model(self): + def test_tsl_ruleset_describes_agent_decision_router(self): text = RULESET_TSL.read_text(encoding="utf-8") - self.assertIn("agent 判断流程", text) - self.assertIn("用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据", text) - self.assertIn("`.tsl` 是可执行脚本", text) - self.assertIn("语句区按顺序执行", text) - self.assertIn("函数/类声明区", text) - self.assertIn("`.tsf` 是模块/函数扩展文件", text) + self.assertIn("# TSL 智能体规则", text) + self.assertIn("高优先级智能体决策规则", text) + self.assertIn("代码生成协议", text) + self.assertIn("TSL 核心事实", text) + self.assertIn("任务路由", text) + self.assertIn("文档事实使用策略", text) + self.assertIn("最终 TSL 自检", text) + self.assertIn("`.tsl` 在通用 TSL 规则中表示可执行脚本", text) + self.assertIn("可执行语句必须位于前部", text) + self.assertIn("声明区", text) + self.assertIn("`.tsf` 表示可复用函数、过程、类、模块或扩展文件", text) self.assertIn("funcext", text) - self.assertIn("仍不明确时向用户确认", text) + self.assertIn("创建对象有两种方式：`new ClassName()` 最常用", text) + self.assertIn("生成代码前向用户确认", text) + self.assertIn("不要因为 Pascal", text) + self.assertIn("代码块身份：可直接照写示例", text) + self.assertIn("不代表 TSL 语法事实", text) + self.assertNotIn("Style Snapshot", text) + self.assertNotIn("## Skills", text) + self.assertNotIn("## 与开发规范的关系", text) self.assertNotIn("`.tsl` 仅 `function`", text) self.assertNotIn("脚本优先 `.tsl`，可复用扩展优先 `.tsf`", text) def test_tsl_syntax_docs_keep_script_then_declarations_model(self): - quickstart = (ROOT / "docs/tsl/syntax/02_quickstart.md").read_text( + quickstart = (ROOT / "docs/tsl/syntax/01_quickstart.md").read_text( encoding="utf-8" ) - core_model = (ROOT / "docs/tsl/syntax/03_core_model.md").read_text( + core_model = (ROOT / "docs/tsl/syntax/02_core_model.md").read_text( encoding="utf-8" ) - functions = (ROOT / "docs/tsl/syntax/06_functions_and_calls.md").read_text( + functions = (ROOT / "docs/tsl/syntax/05_functions_and_calls.md").read_text( encoding="utf-8" ) - pitfalls = (ROOT / "docs/tsl/syntax/12_pitfalls.md").read_text( + pitfalls = (ROOT / "docs/tsl/syntax/11_pitfalls.md").read_text( encoding="utf-8" ) @@ -170,48 +211,75 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): for phrase in forbidden_phrases: self.assertNotIn(phrase, text, msg=f"{phrase!r} found in {path}") - def test_tsl_index_requires_maintainer_verified_examples_before_publication(self): + def test_tsl_docs_use_compact_uncertain_header(self): + docs_root = ROOT / "docs" / "tsl" + + for path in docs_root.rglob("*.md"): + with self.subTest(path=path.relative_to(ROOT)): + text = path.read_text(encoding="utf-8") + self.assertNotIn("遇到不确定时跳转到", text) + + def test_tsl_index_uses_documented_generation_facts(self): text = (ROOT / "docs/tsl/index.md").read_text(encoding="utf-8") - self.assertIn("维护者入文档前验证", text) - self.assertIn("代码库样例", text) - self.assertIn("环境验证通过", text) - self.assertIn("不能写成语法事实", text) - self.assertIn("验证过程不写进语法页", text) - self.assertIn("agent 不需要自行执行验证", text) + self.assertIn("语法事实使用规则", text) + self.assertIn("写成语法事实的内容就是生成依据", text) + self.assertIn("智能体自行证明", text) + self.assertIn("文档没有覆盖的写法不能生成", text) + self.assertIn("执行环境细节不写进语法页", text) - def test_tsl_introduction_is_agent_first_decision_model(self): - text = TSL_INTRODUCTION.read_text(encoding="utf-8") + def test_tsl_syntax_docs_do_not_keep_stale_manual_sequence_metadata(self): + self.assertFalse((ROOT / "docs/tsl/syntax/01_introduction.md").exists()) - self.assertIn("agent", text) - self.assertIn("后缀就是判断依据", text) - self.assertIn("用户未给后缀", text) - self.assertIn("可执行代码对应 `.tsl`", text) - self.assertIn("通用模块对应 `.tsf`", text) - self.assertIn("`.tsl` 可执行脚本第一印象", text) - self.assertIn("`.tsf` 通用模块第一印象", text) - self.assertIn("不要发明语法", text) - self.assertIn("test();", text) - self.assertIn("function test();", text) - self.assertIn("function Test1();", text) + forbidden_phrases = [ + "01_introduction.md", + "手册位置：", + "共 32 篇", + "上一篇：", + "下一篇：", + "完整吸收原 8 个", + "原 8 章", + "编号说明", + ] - self.assertNotIn("先看顶层主体", text) - self.assertNotIn("顶层主体优先收敛成四类", text) + syntax_paths = sorted((ROOT / "docs" / "tsl" / "syntax").glob("*.md")) + numbered_paths = [path for path in syntax_paths if path.name != "index.md"] + numbers = [] + for path in numbered_paths: + match = re.match(r"^(\d{2})_", path.name) + self.assertIsNotNone(match, msg=f"missing two-digit prefix: {path.name}") + numbers.append(int(match.group(1))) + + self.assertEqual(list(range(1, len(numbered_paths) + 1)), numbers) + self.assertEqual("01_quickstart.md", numbered_paths[0].name) + + for path in syntax_paths: + text = path.read_text(encoding="utf-8") + for phrase in forbidden_phrases: + self.assertNotIn(phrase, text, msg=f"{phrase!r} found in {path}") def test_tsl_quickstart_is_agent_coding_gate(self): text = TSL_QUICKSTART.read_text(encoding="utf-8") - self.assertIn("Agent 快速落代码流程", text) + self.assertIn("智能体快速落代码流程", text) self.assertIn("先看用户有没有指定 `.tsl` / `.tsf` 后缀", text) self.assertIn("再根据交付目标判断 `.tsl` 或 `.tsf`", text) - self.assertIn("只从 `代码块身份：已验证可执行示例` 的骨架起手", text) + self.assertIn("入口流程、脚本任务或一次性执行逻辑用 `.tsl`", text) + self.assertIn("可复用交付物（函数、过程、类、模块或扩展文件）用 `.tsf`", text) + self.assertIn("如果只是脚本内部封装函数或类，仍按 `.tsl` 处理", text) + self.assertIn("只从 `代码块身份：可直接照写示例` 的骨架起手", text) self.assertIn("不要发明语法", text) + self.assertIn("`procedure` 头后不允许写返回类型", text) self.assertIn("不要在声明区后面继续追加脚本语句", text) + self.assertIn("普通对象创建默认优先 `new ClassName()`", text) + self.assertIn("`createObject(...)` 也是对象创建方式", text) + self.assertIn("obj := new MyClass();", text) + self.assertNotIn('obj := createObject("MyClass");', text) def test_tsl_quickstart_labels_observable_outputs(self): text = TSL_QUICKSTART.read_text(encoding="utf-8") - self.assertIn("代码块身份：已验证输出片段", text) + self.assertIn("代码块身份：输出片段", text) self.assertIn("```text\ntest\n```", text) self.assertIn("```text\n5\n```", text) self.assertIn("```text\ntest1\n```", text) @@ -233,10 +301,18 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): def test_tsl_core_model_is_agent_file_model_decision_page(self): text = TSL_CORE_MODEL.read_text(encoding="utf-8") - self.assertIn("Agent 文件模型判断流程", text) + self.assertIn("智能体文件模型判断流程", text) self.assertIn("后缀是第一证据", text) - self.assertIn("可执行交付", text) - self.assertIn("可复用扩展交付", text) + self.assertIn("入口流程、脚本任务或一次性执行逻辑", text) + self.assertIn("可复用交付物（函数、过程、类、模块或扩展文件）", text) + self.assertIn("只是脚本内部封装函数或类时，仍按 `.tsl` 处理", text) + self.assertIn("`.tsf` 顶层类声明", text) + self.assertIn("因为 `.tsl` 脚本内部需要函数或类，就自动改成 `.tsf`", text) + self.assertIn("类声明必须使用 `type Name = class ... end;`", text) + self.assertIn("普通对象创建默认优先 `new ClassName()`", text) + self.assertIn("`createObject(...)` 也是对象创建方式", text) + self.assertIn("obj := new MyClass();", text) + self.assertNotIn('obj := createObject("MyClass");', text) self.assertIn("不要把 `.tsl` 写成只有顶层函数的模块", text) self.assertIn("不要把 `.tsf` 写成会直接执行脚本语句的入口", text) self.assertIn("没有文档证据时不要发明文件模型", text) @@ -245,7 +321,7 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): def test_tsl_core_model_examples_have_verified_outputs(self): text = TSL_CORE_MODEL.read_text(encoding="utf-8") - self.assertIn("代码块身份：已验证输出片段", text) + self.assertIn("代码块身份：输出片段", text) self.assertIn("```text\ntest\n```", text) self.assertIn("```text\n5\n```", text) self.assertIn("```text\n1\n```", text) @@ -264,27 +340,141 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): ]: self.assertNotIn(phrase, text) + def test_tsl_object_docs_prefer_new_for_plain_construction(self): + text = (ROOT / "docs/tsl/syntax/08_objects_and_classes.md").read_text( + encoding="utf-8" + ) + + self.assertIn("创建对象有两种方式：`new ClassName()` 最常用", text) + self.assertIn("[02_core_model.md](02_core_model.md)（优先）", text) + self.assertNotIn("[09_units_and_scope.md](09_units_and_scope.md)（优先）", text) + self.assertIn("命中对象反射 / 运行时状态、内置运行时对象、对象重载 / 迭代时", text) + self.assertIn("21_builtin_runtime_objects.md", text) + self.assertIn("24_object_overloads_and_iteration.md", text) + self.assertIn("`createObject(...)` 作为次选", text) + self.assertIn("普通本地类创建默认用 `new ClassName()`", text) + self.assertIn("普通本地类实例化默认生成 `new ClassName()`", text) + self.assertIn("普通类成员默认显式写 `public` 段", text) + self.assertIn("生成代码默认显式写 `public`", text) + self.assertIn("跨 `unit` 类路径创建和继承属于多文件边界", text) + self.assertIn("跨 `unit` 类路径骨架", text) + self.assertIn("跨 `unit` 父类路径骨架", text) + self.assertIn("type Class1 = class\npublic\n type Class2 = class", text) + self.assertNotIn("多文件文档事实", text) + self.assertNotIn("已在多文件环境下验证", text) + self.assertNotIn("`createObject(\"Unit1.Class1.Class2\")` 可以创建对象", text) + self.assertNotIn("`type MyNewClass = class(Unit1.Class1.Class2)` 可以通过", text) + self.assertIn("字段可以写类型注解", text) + self.assertIn("类方法参数和返回值可以写类型注解", text) + self.assertIn("类的声明和实现可以分离", text) + self.assertIn("类内可以只声明方法签名", text) + self.assertIn("类外实现属于声明区", text) + self.assertIn("字段和类方法类型注解", text) + self.assertIn("name_: string;", text) + self.assertIn("value_: any;", text) + self.assertIn("function create(_name: string; _value: any);", text) + self.assertIn("function ReadName(): string;", text) + self.assertIn("property Value: any read value_ write value_;", text) + self.assertIn("```text\nabc\n7\nabc\n```", text) + self.assertIn("类内声明、类外实现的带类型重载方法", text) + self.assertIn("function PairBox.create(_left: string); overload;", text) + self.assertIn( + "function PairBox.create(_left: string; _right: any); overload;", text + ) + self.assertIn("function PairBox.ReadLeft(): string;", text) + self.assertIn("create(_left, nil);", text) + self.assertIn("```text\nleft\n\nleft\n2\nleft\n```", text) + self.assertIn("成员读写为了性能不加 `self` 前缀", text) + self.assertIn("普通成员访问仍直接写成员名，不加 `self` 前缀", text) + self.assertIn("字段、方法和 `new`", text) + self.assertIn("return new Person();", text) + self.assertIn("obj := new MyClass();", text) + self.assertIn("static mCount;", text) + self.assertIn("单个静态字段默认写成 `static mCount;`", text) + self.assertIn("上述声明顺序可以编译通过", text) + self.assertLess( + text.index("a := new Person(22, c:99);"), + text.index('b := createObject("Person", 11);'), + ) + self.assertNotIn("score_value", text) + self.assertNotIn("slot_type", text) + self.assertNotIn("裸 `class Person`", text) + self.assertNotIn("没有任何类声明证据", text) + self.assertNotIn("把普通当前实例成员访问写成带 `self` 前缀", text) + self.assertIn("不把裸类名成员访问当成文档事实", text) + self.assertIn("MathBox.Add(1, 2);\nTHuman.mCount := 7;", text) + self.assertIn("上面这种裸类名成员访问不作为可写事实", text) + self.assertNotIn("上面这种裸类名静态字段访问不作为可写事实", text) + self.assertNotIn("字段、方法和 `createObject`", text) + self.assertNotIn('obj := createObject("MyClass");', text) + self.assertNotIn("static\n mCount;", text) + self.assertNotIn("self.", text) + self.assertNotIn("上述 `.tsf` 例子", text) + self.assertNotIn("当前解释器", text) + self.assertNotIn("文档明确运行结果", text) + self.assertNotIn("文档结果", text) + self.assertNotIn("当前已记录验证", text) + self.assertNotIn("已做双文件运行验证", text) + + def test_tsl_syntax_docs_do_not_use_self_member_access(self): + for path in (ROOT / "docs" / "tsl" / "syntax").glob("*.md"): + text = path.read_text(encoding="utf-8") + self.assertNotIn("self.", text, msg=f"self. found in {path}") + def test_tsl_values_page_is_agent_value_decision_page(self): text = TSL_VALUES.read_text(encoding="utf-8") - self.assertIn("Agent 值写法判断流程", text) + self.assertIn("智能体值写法判断流程", text) self.assertIn("普通值优先从整数、实数、普通字符串、布尔和 `array(...)` 起手", text) self.assertIn("字符串默认用普通字符串", text) - self.assertIn("`L\"\"` / `U\"\"` 只在编码或宽串场景", text) + self.assertIn("只有编码、宽串、UTF8、原始字符串、字符码或 ASCII `0` 需求明确时", text) self.assertIn("先判断要顺序数组还是字符串键表", text) self.assertIn("顺序数组和二进制缓冲区下标从 `0` 开始", text) self.assertIn("字符串下标从 `1` 开始", text) - self.assertIn("没有已验证代码块时不要发明值写法", text) + self.assertIn("矩阵、集合扩展", text) + self.assertIn("12_matrix_and_collections.md", text) + self.assertIn("普通示例默认按 `.tsl` 脚本语句区书写", text) + self.assertIn("没有对应代码块时不要发明值写法", text) + self.assertNotIn("20_strings_and_text.md", text) def test_tsl_values_key_examples_have_verified_output_snippets(self): text = TSL_VALUES.read_text(encoding="utf-8") - self.assertIn("代码块身份：已验证输出片段", text) + self.assertIn("代码块身份：输出片段", text) self.assertIn("```text\n1\n12.5\nABC\n1\n0\n2\n```", text) self.assertIn("```text\n10\n20\n0001\nA\nB\nC\n```", text) self.assertIn("```text\nBCD\n```", text) + self.assertIn("```text\nABC\n```", text) self.assertIn("```text\nString index out of bounds\n```", text) + def test_tsl_values_page_owns_string_boundaries(self): + text = TSL_VALUES.read_text(encoding="utf-8") + + self.assertFalse((ROOT / "docs/tsl/syntax/20_strings_and_text.md").exists()) + self.assertIn("字符串边界规则", text) + self.assertIn("宽串 / UTF8 前缀", text) + self.assertIn("原始字符串", text) + self.assertIn("字符码拼接", text) + self.assertIn("ASCII `0` 字符不会截断字符串", text) + self.assertIn("普通字符串里的 `\\uXXXX` 不要直接按“单字符宽串”理解", text) + self.assertIn("`U\"\"` 不是宽串", text) + self.assertIn("`#number` 可以直接把字符码拼进字符串", text) + self.assertIn("`\\0` 和 `#0` 都能把 ASCII `0` 放进字符串", text) + + def test_tsl_values_string_boundary_examples_have_verified_output_snippets(self): + text = TSL_VALUES.read_text(encoding="utf-8") + + self.assertIn("代码块身份：输出片段", text) + self.assertIn("```text\nABC\nA\"B'C\nA\nB\n```", text) + self.assertIn("writeLn(length(\"\\u0041\"));", text) + self.assertIn("writeLn(length(L\"\\u0041\"));", text) + self.assertIn("writeLn(length(U\"\\u0041\"));", text) + self.assertIn("依次输出 `2`、`1`、`1`", text) + self.assertIn("writeLn(ifWString(utf8_s));", text) + self.assertIn("依次输出 `0`、`1`、`1`、`1`", text) + self.assertIn('s2 := "A"#0"B";', text) + self.assertIn("依次输出 `3`、`3`、`1`、`1`", text) + def test_tsl_values_omits_environment_verification_details(self): text = TSL_VALUES.read_text(encoding="utf-8") @@ -301,22 +491,47 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): def test_tsl_variables_page_is_agent_binding_decision_page(self): text = TSL_VARIABLES.read_text(encoding="utf-8") - self.assertIn("Agent 变量/常量判断流程", text) + self.assertIn("智能体变量/常量判断流程", text) self.assertIn("普通变量默认直接用 `:=` 首次赋值", text) - self.assertIn("只有用户要求显式声明或遇到 `{$Explicit+}` 时才优先写 `var`", text) - self.assertIn("顶层脚本常量优先用 `const name := value;`", text) - self.assertIn("`const Name = value;` 优先放在函数 `const` 段、`unit` 接口或类成员里", text) + self.assertIn("只有用户要求显式声明或遇到 `{$explicit+}` 时才优先写 `var`", text) + self.assertIn("常量声明必须同时初始化", text) + self.assertIn("默认只生成 `const name = value;`", text) self.assertIn("单变量拆包必须写成 `[name, ] := array(...)`", text) - self.assertIn("没有已验证代码块时不要发明变量/常量写法", text) + self.assertIn("06_expressions_and_operators.md", text) + self.assertIn("16_lexical_structure_and_compile_options.md", text) + self.assertIn("普通示例默认按 `.tsl` 脚本语句区书写", text) + self.assertIn("复制常量示例时只使用 `const name = value;`", text) + self.assertIn("没有对应代码块时不要发明变量/常量写法", text) + self.assertIn("运行时类型 / 转换", text) + self.assertIn("17_types_and_conversions.md", text) + self.assertNotIn("const name :=", text) + self.assertNotIn("语法设计兼容边界", text) + self.assertNotIn("兼容通过", text) + self.assertNotRegex(text, r"const\s+[A-Za-z_][A-Za-z0-9_]*\s*:=") + + def test_tsl_types_page_does_not_own_declaration_rules(self): + text = TSL_TYPES.read_text(encoding="utf-8") + + self.assertIn("智能体类型/转换判断流程", text) + self.assertIn("运行时值会变成什么类型", text) + self.assertIn("默认值是什么", text) + self.assertIn("怎样显式转换", text) + self.assertIn("`var` / `const` 声明选择回看", text) + self.assertIn("16_lexical_structure_and_compile_options.md", text) + self.assertNotIn("显式声明边界", text) + self.assertNotIn("怎样受编译选项影响", text) def test_tsl_variables_key_examples_have_verified_output_snippets(self): text = TSL_VARIABLES.read_text(encoding="utf-8") - self.assertIn("代码块身份：已验证输出片段", text) + self.assertIn("代码块身份：输出片段", text) self.assertIn("```text\n1\n2\n```", text) self.assertIn("```text\n7\n```", text) self.assertIn("```text\n1\n3\n```", text) self.assertIn("```text\n1\n1\n```", text) + self.assertIn("```text\n1\n2\n3\n4\n```", text) + self.assertIn("```text\n0\n7\n```", text) + self.assertIn("```text\n6\n```", text) self.assertIn("```text\nvariable not defined\n```", text) def test_tsl_variables_omits_environment_verification_details(self): @@ -335,22 +550,47 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): def test_tsl_functions_page_is_agent_function_decision_page(self): text = TSL_FUNCTIONS.read_text(encoding="utf-8") - self.assertIn("Agent 函数/调用判断流程", text) - self.assertIn("先判断当前文件是 `.tsl` 还是 `.tsf`", text) + self.assertIn("智能体函数/调用判断流程", text) + self.assertIn("先判断目标文件是 `.tsl` 还是 `.tsf`", text) self.assertIn("`.tsl` 中先写语句区，再把 `function` / `procedure` 声明放在后面", text) - self.assertIn("需要返回值时用 `function`，不需要返回值时用 `procedure`", text) + self.assertIn("用户只说“写一个函数”且没有指定 `procedure` 时，默认用 `function`", text) + self.assertIn("即使任务没有返回值，也默认用 `function`", text) + self.assertIn("不要因为没有返回值就自动改用 `procedure`", text) + self.assertIn("用户提示词里的“函数”默认对应 `function`", text) self.assertIn("命名参数只写 `name: value`", text) self.assertIn("不要把 `name = value` 当成命名参数", text) - self.assertIn("没有已验证代码块时不要发明函数/调用写法", text) + self.assertIn("函数头后默认保留分号", text) + self.assertIn("16_lexical_structure_and_compile_options.md", text) + self.assertIn("普通运行示例默认按 `.tsl` 脚本语句区书写", text) + self.assertIn("`.tsf` 函数 / 过程示例只按可复用顶层声明理解", text) + self.assertIn("`procedure` 示例只在用户明确要求 `procedure` / 过程时复制", text) + self.assertIn("默认从 `function` 骨架起步", text) + self.assertIn("跨 `unit` 声明边界", text) + self.assertIn("默认参数先按普通函数规则处理", text) + self.assertIn("匿名函数和 TSL 函数值", text) + self.assertIn("原生函数指针包装", text) + self.assertIn("C 回调", text) + self.assertIn("只按本页明确的 `call(f, ...)` / `##f(...)` 生成", text) + self.assertIn("没有对应代码块时不要发明函数/调用写法", text) self.assertNotIn("在我于", text) + self.assertNotIn("LIBPATH", text) + self.assertNotIn("tsl .\\main.tsl", text) + self.assertNotIn("command", text) + self.assertNotIn("function MissingSemi()", text) + self.assertNotIn("input_value", text) + self.assertNotIn("handler): result_type", text) + self.assertNotIn("命名参数可以调换顺序", text) + self.assertNotIn("命名参数也可以和位置参数混用", text) def test_tsl_functions_key_examples_have_verified_output_snippets(self): text = TSL_FUNCTIONS.read_text(encoding="utf-8") - self.assertIn("代码块身份：已验证输出片段", text) + self.assertIn("代码块身份：输出片段", text) self.assertIn("```text\ntest\n```", text) self.assertIn("```text\n2\n```", text) + self.assertIn("```text\n9\n1\n7\n```", text) self.assertIn("```text\n12\n```", text) + self.assertIn("```text\n888\n123\n```", text) self.assertIn("```text\ninvalid statement\n```", text) def test_tsl_functions_omits_environment_verification_details(self): @@ -368,25 +608,79 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): def test_tsl_expressions_page_is_agent_expression_decision_page(self): text = TSL_EXPRESSIONS.read_text(encoding="utf-8") + text = text.replace("|", "|") - self.assertIn("Agent 表达式/运算符判断流程", text) - self.assertIn("先判断要写赋值、比较、条件求值、表达式对象、空安全访问还是链式比较", text) + self.assertIn("智能体表达式/运算符判断流程", text) + self.assertIn("先判断要写基础表达式运算符，还是集合、矩阵、对象重载、运行时调用或 TS-SQL 这类专题运算符", text) + self.assertIn("本页直接生成的运算符", text) + self.assertIn("专题运算符入口", text) + self.assertIn("默认生成规则", text) + self.assertIn("按需生成规则", text) + self.assertIn("边界规则", text) self.assertIn("赋值只能用 `:=`", text) self.assertIn("比较才用 `=`", text) + self.assertIn("`const name = value;` 是常量初始化规则", text) + self.assertIn("常量初始化不按普通赋值判断", text) + self.assertIn("函数签名里的默认参数 `name = value` 不是比较表达式", text) + self.assertIn("不要把函数签名里的 `name = value` 当成比较表达式", text) + self.assertIn("04_variables_and_constants.md", text) + self.assertIn("05_functions_and_calls.md", text) + self.assertIn("03_values_and_literals.md", text) + self.assertIn("12_matrix_and_collections.md", text) + self.assertIn("16_lexical_structure_and_compile_options.md", text) + self.assertNotIn("20_strings_and_text.md", text) + self.assertIn("`{$ifdef ...}` 只作为能力探测", text) self.assertIn("条件求值优先用 `flag ? true_value : false_value`", text) self.assertIn("`if condition then true_value else false_value` 必须带 `else`", text) - self.assertIn("没有已验证代码块时不要发明表达式/运算符写法", text) + self.assertIn("需要延迟求值或动态表达式对象时，才用 `@expr` 或 `&\"...\"`", text) + self.assertIn("数组逐元素链式比较才用 `::>`", text) + self.assertIn("本页是 TSL 表达式与运算符的生成规则页", text) + self.assertIn("只使用本页或对应专题页明确记录的运算符", text) + self.assertIn("`div`、`mod`、`^`", text) + self.assertIn("一元倒数", text) + self.assertIn("`!x`", text) + self.assertIn("整型、实型输入返回实型倒数", text) + self.assertIn("`+`、`$`", text) + self.assertIn("`and`、`or`、`not`、`&&`、||", text) + self.assertIn("`.&`、`.|`、`.^`", text) + self.assertIn("`^=`、`.&=`、`.|=`、`.^=`", text) + self.assertIn("`a++`、`a--`、`++a`、`--a`", text) + self.assertIn("`union2`、`intersect`、`minus`、`outersect`", text) + self.assertIn("`union`、|、`:|`", text) + self.assertIn("矩阵并右方", text) + self.assertIn("`->`、`!matrix`", text) + self.assertIn("矩阵逆/广义逆", text) + self.assertIn("反引号转置", text) + self.assertIn("`operator +`", text) + self.assertIn("`select` / `sselect` / `vselect` / `mselect`", text) + self.assertIn("没有文档事实的运算符", text) + self.assertIn("不要生成猜测写法", text) + self.assertNotIn("`. ^`", text) + self.assertNotIn("补证", text) + self.assertNotIn("待确认", text) + self.assertNotIn("不是完整运算符支持清单", text) + self.assertNotIn("未列运算符不等于语法不支持", text) + self.assertNotIn("未列出的运算符不要直接判为不支持", text) + self.assertNotIn("直接写成该运算符不支持", text) self.assertNotIn("当前环境里", text) def test_tsl_expressions_key_examples_have_verified_output_snippets(self): text = TSL_EXPRESSIONS.read_text(encoding="utf-8") - self.assertIn("代码块身份：已验证输出片段", text) + self.assertIn("代码块身份：输出片段", text) self.assertIn("```text\n3\n```", text) + self.assertIn("```text\n3\n3\n12\n4\n1\n2\n1\n8\n2\n3\n```", text) + self.assertIn("```text\n1\n1\n1\n1\n1\n1\n```", text) + self.assertIn("```text\n0.5\n0.25\n1\n1\n```", text) + self.assertIn("```text\n1\n1\n1\n1\n1\n```", text) + self.assertIn("```text\n2\n5\n5\n```", text) + self.assertIn("```text\n8\n2\n5\n5\n```", text) self.assertIn("```text\nAB\n```", text) self.assertIn("```text\n222888\n1\n1\n1\n1\n```", text) self.assertIn("```text\n1\n0\n```", text) self.assertIn("```text\n2\n```", text) + self.assertIn("++a;", text) + self.assertIn("--a;", text) self.assertIn("```text\n6\n```", text) self.assertIn("```text\n1\n7\n1\n```", text) self.assertIn("```text\ninvalid statement\n```", text) @@ -404,6 +698,416 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): ]: self.assertNotIn(phrase, text) + def test_tsl_control_flow_page_routes_function_and_debug_boundaries(self): + text = TSL_CONTROL_FLOW.read_text(encoding="utf-8") + + self.assertIn("智能体控制流判断流程", text) + self.assertIn("05_functions_and_calls.md", text) + self.assertIn("函数里的控制流只按控制流语法处理", text) + self.assertIn("15_debug_and_profiler.md", text) + self.assertIn("默认写成块式分支", text) + self.assertIn("控制流块的 `end` 默认不加分号", text) + self.assertIn("只按语句形态生成", text) + self.assertIn("begin\n value := 1;\nend\nelse\nbegin\n value := 0;\nend", text) + self.assertNotIn("begin\n value := 1;\nend\nelse\nbegin\n value := 0;\nend;", text) + self.assertIn("不要在 `else` 前提前加分号", text) + self.assertNotIn("then\n value := 1\nelse", text) + self.assertNotIn("b := case", text) + self.assertNotIn("b := @case", text) + self.assertNotIn("@case", text) + self.assertNotIn("case 表达式形态", text) + self.assertNotIn("当前解释器", text) + self.assertNotIn("文档明确运行结果", text) + self.assertNotIn("文档明确支持", text) + + def test_tsl_control_flow_key_examples_have_verified_output_snippets(self): + text = TSL_CONTROL_FLOW.read_text(encoding="utf-8") + + self.assertIn("代码块身份：输出片段", text) + self.assertIn("```text\n1\n0\n```", text) + self.assertIn("```text\n3\n```", text) + self.assertIn("```text\n10\n120\n230\n```", text) + self.assertIn("```text\n6\n4\n```", text) + self.assertIn("```text\ntwo\n```", text) + self.assertIn("```text\nbefore\ncaught\nraise: boom\nafter\n```", text) + self.assertIn("```text\nbefore\nbody\nfinally\n```", text) + + def test_tsl_units_page_omits_environment_and_orders_uses_before_statements(self): + text = (ROOT / "docs/tsl/syntax/09_units_and_scope.md").read_text( + encoding="utf-8" + ) + + self.assertIn("多文件结构骨架", text) + self.assertIn("[02_core_model.md](02_core_model.md)（优先）", text) + self.assertNotIn("[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)（优先）", text) + self.assertIn("命中 `unit` 生命周期、命名空间、查找路径、`tsl.conf` 或命令行查找路径参数", text) + self.assertIn("没有对应代码块时不要发明 unit/作用域写法", text) + self.assertIn( + "interface\n\nfunction Ping();\n\nimplementation\n\nfunction Ping();", + text, + ) + self.assertIn("`implementation` 前保留空行", text) + self.assertIn("`unit` 允许接口声明与实现段分离", text) + self.assertIn("类方法放在 `implementation` 段实现", text) + self.assertIn("### 接口声明与实现段分离", text) + self.assertIn("function UnitBox.create(_value);", text) + self.assertIn("function UnitBox.ReadValue();", text) + self.assertIn("只写在 `implementation` 段，对 `unit` 外部不可见", text) + self.assertIn("uses PrivateDemo;\nwriteLn(PublicFunc());\n```", text) + self.assertIn("代码块身份：反例 / 不可照写\n\n```text\nuses PrivateDemo;\nwriteLn(PrivateFunc());", text) + self.assertNotIn("interface\n function Ping();", text) + self.assertNotIn("implementation\n function Ping();", text) + self.assertNotIn("## 生成代码排版规则", text) + self.assertIn("type Worker = class\n uses DemoUnit;\npublic", text) + self.assertIn("// main.tsl\n\nuses UnitA;", text) + self.assertIn("// main.tsl\n\nuses PrivateDemo;", text) + self.assertIn("type TBox = class\npublic", text) + self.assertIn("type Box = class\npublic", text) + self.assertIn("function Box.create();", text) + self.assertIn("合并成单条 `uses UnitA, UnitB;`", text) + self.assertIn("失败点是“第二条 `uses`”", text) + self.assertIn("只生成单条逗号合并写法", text) + self.assertIn("连续多条顶层 `uses` 不再作为文档明确生成形态", text) + self.assertIn("uses UnitA, UnitB;", text) + self.assertIn("多个 `unit` 默认写成 `uses UnitA, UnitB;`", text) + self.assertNotIn("当前解释器", text) + self.assertNotIn("文档结果", text) + self.assertNotIn("已在多文件环境下验证", text) + self.assertNotIn("// command", text) + self.assertNotIn("LIBPATH", text) + self.assertNotIn("tsl .", text) + + def test_tsl_runtime_context_page_omits_environment_process_details(self): + text = (ROOT / "docs/tsl/syntax/10_runtime_context_and_with.md").read_text( + encoding="utf-8" + ) + + self.assertIn("系统参数优先用本页明确的", text) + self.assertIn("运行时上下文、服务与全局缓存", text) + self.assertIn("本地函数后缀 `with` 属于反例", text) + self.assertIn("网格调用返回的不是最终值；需要最终结果时继续写 `dupvalue(...)`", text) + self.assertIn("全局缓存读写要成对出现", text) + self.assertIn("多文件结构骨架", text) + self.assertIn("依赖函数文件查找路径", text) + self.assertIn("结果说明：", text) + self.assertIn('r := #TestDo() with array("a": 101, "b": 202);', text) + self.assertIn("writeLn(dupvalue(#AddOne(5)));", text) + self.assertIn("writeLn(dupvalue(#AddOne(5) timeout 3000));", text) + self.assertIn('writeLn(setGlobalCache("PB_TEST_GC_BASIC", v1));', text) + self.assertIn("writeLn(checkGlobalCacheExpired(v));", text) + self.assertIn("对缓存值做 `select` 可以正常执行", text) + self.assertIn("这种“本地函数后缀 `with`”写法不作为可写事实", text) + self.assertFalse((ROOT / "docs/tsl/syntax/30_runtime_services_and_global_cache.md").exists()) + self.assertNotIn("30_runtime_services_and_global_cache.md", text) + self.assertNotIn("当前解释器", text) + self.assertNotIn("文档明确运行结果", text) + self.assertNotIn("当前已做双文件运行验证", text) + + def test_tsl_external_page_owns_native_pointer_and_callback_boundaries(self): + text = TSL_EXTERNAL.read_text(encoding="utf-8") + + self.assertIn("智能体外部调用/线程判断流程", text) + self.assertIn("原生函数指针包装", text) + self.assertIn("C 回调", text) + self.assertIn("包装原生函数指针", text) + self.assertIn("生成 C 回调", text) + self.assertIn("makeInstance(thisFunction(Func), \"cdecl\", 0)", text) + self.assertIn("makeInstance(..., \"cdecl\", 1)", text) + self.assertIn("函数指针包装", text) + self.assertNotIn("普通函数怎么写已经清楚后，外部 DLL、函数指针、多线程", text) + self.assertNotIn("// command", text) + self.assertNotIn("LIBPATH", text) + self.assertNotIn("tsl .", text) + + def test_tsl_pitfalls_page_uses_stable_boundary_language(self): + text = (ROOT / "docs/tsl/syntax/11_pitfalls.md").read_text( + encoding="utf-8" + ) + + self.assertIn("## 反例索引", text) + self.assertIn("必须跳回对应语法页找可直接照写示例", text) + self.assertIn("只有已经有明确反例边界的误写", text) + self.assertIn("细节型边界放回对应专题页", text) + self.assertIn("最容易诱导智能体写错的高频误写", text) + self.assertIn("只针对函数体和类定义体里的 `uses`", text) + self.assertIn("默认回到顶层写成单条 `uses UnitA, UnitB;`", text) + self.assertIn("类定义体里出现了第二条 `uses`", text) + self.assertIn("可用写法是先拿到类类型", text) + self.assertIn("不要把反例边界写成可用语法", text) + self.assertNotIn("当前解释器", text) + self.assertNotIn("当前命令行解释器", text) + self.assertNotIn("实测", text) + self.assertNotIn("当前文档明确", text) + self.assertNotIn("对应代码块", text) + self.assertNotIn("## 不可照写反例索引", text) + self.assertNotIn("LIBPATH", text) + self.assertNotIn("在同一作用域里重复写第二个 `uses`", text) + self.assertNotIn('writeLn(length("\\u0041"));', text) + self.assertNotIn('writeLn(ifWString(U"\\u5929\\u8F6F"));', text) + self.assertNotIn('s := "A"#0"B";', text) + self.assertNotIn("const value = 1;", text) + self.assertNotIn("unit UnitConst;", text) + self.assertNotIn("TickFromExpr", text) + self.assertNotIn("文件就在当前目录", text) + self.assertNotIn("DemoUnit.UnitCounter", text) + + def test_tsl_matrix_collections_page_uses_entry_language(self): + text = ( + ROOT / "docs/tsl/syntax/12_matrix_and_collections.md" + ).read_text(encoding="utf-8") + + self.assertIn("本页明确的矩阵样比较", text) + self.assertIn("本页文档明确形态", text) + self.assertIn("14_ts_sql.md", text) + self.assertIn("[14_ts_sql.md](14_ts_sql.md)", text) + self.assertIn("没有对应代码块时不要发明数组/矩阵样数据/集合关系写法", text) + self.assertIn("结果说明：", text) + self.assertIn("矩阵链式比较 `::>`、`::<`、`::<>`、`::==`、`::>=`、`::<=`", text) + self.assertIn("`in` / `not in` 处理的是元素存在关系", text) + self.assertIn("`sqlin` / `not sqlin` 处理的是行存在关系", text) + self.assertIn("`union2`、`intersect`、`minus`、`outersect` 都按“行”运算", text) + self.assertIn("集合运算结果会折叠重复行", text) + self.assertIn("writeLn(1 not in array(0, 2));", text) + self.assertIn("writeLn(array(5, 6) not sqlin array((1, 2), (3, 4)));", text) + self.assertIn("union_rows := left_rows union2 right_rows;", text) + self.assertIn("outersect_rows := left_rows outersect right_rows;", text) + self.assertNotIn("25_set_operations.md", text) + self.assertNotIn("当前解释器", text) + self.assertNotIn("文档明确运行结果", text) + self.assertNotIn("文档明确运行结果对应关系", text) + self.assertNotIn("稳定验证", text) + self.assertNotIn("稳定通过", text) + + def test_tsl_resultset_filters_page_uses_complete_examples(self): + text = ( + ROOT / "docs/tsl/syntax/13_resultset_and_filters.md" + ).read_text(encoding="utf-8") + + self.assertIn("字段访问优先照本页明确的", text) + self.assertIn("复杂查询需求优先跳转到 [14_ts_sql.md](14_ts_sql.md)", text) + self.assertIn("金融数据筛选要先确认数据来源", text) + self.assertIn("[../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)", text) + self.assertIn("没有对应代码块时不要发明结果集/过滤写法", text) + self.assertIn("结果说明：", text) + self.assertIn('writeLn(keep_rows[0]["Code"]);', text) + self.assertIn('writeLn(drop_rows[1]["Code"]);', text) + self.assertIn('rows := array(\n ("Code": "0001"),\n ("Code": "0002")\n);', text) + self.assertIn('code_arr := array("0001");\nkeep_rows := filterIn(rows, code_arr, "Code");', text) + self.assertIn("本页只把显式写出 `nil` 作为可靠规则", text) + self.assertNotIn("文档明确运行结果", text) + self.assertNotIn("当前手册", text) + self.assertNotIn("当前解释器", text) + + def test_tsl_ts_sql_page_uses_entry_and_route_language(self): + text = (ROOT / "docs/tsl/syntax/14_ts_sql.md").read_text( + encoding="utf-8" + ) + + self.assertIn("没有对应代码块时不要发明 TS-SQL 写法", text) + self.assertIn("基础查询文档骨架", text) + self.assertIn("文档字段访问写法", text) + self.assertIn("在一维数组上做 TS-SQL 时，优先使用", text) + self.assertIn("只想按已有结果集保留/排除行时跳到", text) + self.assertIn("13_resultset_and_filters.md", text) + self.assertIn("12_matrix_and_collections.md", text) + self.assertIn("23_fmarray.md", text) + self.assertIn("这一篇是 TS-SQL 的唯一语法入口", text) + self.assertIn("多表 `join` 时，字段访问应写成", text) + self.assertIn("结果说明：", text) + self.assertNotIn("当前的稳定骨架", text) + self.assertNotIn("当前稳定字段访问", text) + self.assertNotIn("当前应优先", text) + self.assertNotIn("文档明确运行结果", text) + + def test_tsl_debug_profiler_page_uses_entry_language(self): + text = (ROOT / "docs/tsl/syntax/15_debug_and_profiler.md").read_text( + encoding="utf-8" + ) + + self.assertIn("本页明确的调试、计时、性能分析器", text) + self.assertIn("没有对应代码块时不要发明调试/性能分析器写法", text) + self.assertIn("只照文档最小调用写", text) + self.assertIn("普通控制流优先回到 [07_control_flow.md](07_control_flow.md)", text) + self.assertIn("属于文档明确写法", text) + self.assertIn("本页正向边界只覆盖", text) + self.assertIn("跨函数跳转不作为可写事实", text) + self.assertIn("目标 `label` 单独成行不作为可写事实", text) + self.assertIn("不作为本页输出事实", text) + self.assertIn("结果说明：", text) + self.assertIn("不要把调试客户端副作用写成普通输出事实", text) + self.assertNotIn("当前", text) + self.assertNotIn("当前解释器", text) + self.assertNotIn("文档明确运行结果", text) + self.assertNotIn("文档结果", text) + self.assertNotIn("未验证参数", text) + self.assertNotIn("当前命令行环境", text) + self.assertNotIn("命令行环境不可直接观察", text) + + def test_tsl_runtime_context_routes_function_query_and_runtime_boundaries(self): + text = (ROOT / "docs/tsl/syntax/10_runtime_context_and_with.md").read_text( + encoding="utf-8" + ) + + self.assertIn("智能体运行时上下文判断流程", text) + self.assertIn("05_functions_and_calls.md", text) + self.assertIn("14_ts_sql.md", text) + self.assertIn("普通函数调用回到 [05_functions_and_calls.md](05_functions_and_calls.md)", text) + self.assertIn("缓存值参与 `select` 时，查询语法仍回到 [14_ts_sql.md](14_ts_sql.md)", text) + self.assertIn("内置运行时对象", text) + + def test_tsl_complex_and_weakref_content_is_split_by_owner_page(self): + self.assertFalse((ROOT / "docs/tsl/syntax/31_complex_and_weakref.md").exists()) + + types_text = TSL_TYPES.read_text(encoding="utf-8") + object_text = TSL_OBJECT_RUNTIME.read_text(encoding="utf-8") + + self.assertIn("复数类型", types_text) + self.assertIn("复数字面量可以直接写成 `a + bj`", types_text) + self.assertIn("z1 := 4 + 3j;", types_text) + self.assertIn("z2 := complex(5, -2);", types_text) + self.assertIn("`dataType(z)` 对复数返回 `41`", types_text) + self.assertIn("complex(array(1, 2, 3), 5.5)", types_text) + self.assertIn("complex(fmarray[1, 2, 3], 5.5)", types_text) + + self.assertIn("弱引用与自动弱引用", object_text) + self.assertIn("访问弱引用前先做 `checkWeakRef(...)` 判定", object_text) + self.assertIn("弱引用能力的条件编译宏是 `weakptr`", object_text) + self.assertIn("自动弱引用相关宏是 `autoWeak`", object_text) + self.assertIn("w := weakRef(a);", object_text) + self.assertIn("s := weakref_get(w);", object_text) + self.assertIn("[weakRef] owner1;", object_text) + self.assertIn("[autoRef] owner2;", object_text) + self.assertIn("invalid class definition", object_text) + + self.assertNotIn("31_complex_and_weakref.md", types_text) + self.assertNotIn("31_complex_and_weakref.md", object_text) + + def test_tsl_syntax_examples_do_not_use_unterminated_if_else_branches(self): + pattern = re.compile(r"if[^\n]*then\s*\n\s*[^\n;]+\n\s*else") + + for path in (ROOT / "docs" / "tsl" / "syntax").glob("*.md"): + text = path.read_text(encoding="utf-8") + self.assertIsNone(pattern.search(text), msg=f"裸 if/else 分支缺分号: {path}") + + def test_tsl_matrix_deep_dive_documents_inverse_operator(self): + text = TSL_MATRIX_DEEP_DIVE.read_text(encoding="utf-8") + + self.assertIn("矩阵逆/广义逆", text) + self.assertIn("`!A` 是一元倒数运算符作用于矩阵的形态", text) + self.assertIn("inverse_value := !matrix_value;", text) + self.assertIn("不要把它改写成 `1 / matrix_value`", text) + self.assertIn("`!` 不表示逻辑非", text) + self.assertIn("```text\n2\n2\n-2\n1\n1.5\n-0.5\n```", text) + self.assertIn( + "```text\n" + "3\n" + "2\n" + "-0.944444444444444\n" + "0.444444444444444\n" + "-0.111111111111111\n" + "0.111111111111111\n" + "0.722222222222222\n" + "-0.222222222222222\n" + "```", + text, + ) + + def test_tsl_fmarray_documents_right_matrix_merge_operator(self): + text = TSL_FMARRAY.read_text(encoding="utf-8") + + self.assertIn("矩阵连接 / 矩阵并右方：`union`、`|`、`:|`", text) + self.assertIn("`|` 和 `:|` 都可做矩阵并右方（按列连接）", text) + self.assertIn("`|` 和 `:|` 会执行矩阵并右方，也就是按列拼接", text) + self.assertIn( + "```text\n" + "27\n" + "3\n" + "4\n" + "1,2,3,4\n" + "3,4,7,8\n" + "5,5,6,9\n" + "1,2,3,4\n" + "3,4,7,8\n" + "5,5,6,9\n" + "```", + text, + ) + self.assertIn( + "```text\n" + "1,2,3,4\n" + "3,4,0,0\n" + "5,5,0,0\n" + "3,4,1,2\n" + "0,0,3,4\n" + "0,0,5,5\n" + "```", + text, + ) + + def test_tsl_deep_dive_pages_avoid_process_verification_language(self): + syntax_root = ROOT / "docs" / "tsl" / "syntax" + forbidden_phrases = [ + "当前", + "当前解释器", + "当前命令行", + "文档明确运行结果", + "文档结果", + "文档明确支持", + "实测", + "补证", + "待确认", + "没有文档明确", + "未验证", + "// command", + ] + + for filename in TSL_SYNTAX_DEEP_DIVE_FILES: + with self.subTest(filename=filename): + text = (syntax_root / filename).read_text(encoding="utf-8") + for phrase in forbidden_phrases: + self.assertNotIn(phrase, text) + + def test_tsl_object_runtime_prefers_new_for_normal_object_creation(self): + text = TSL_OBJECT_RUNTIME.read_text(encoding="utf-8") + + self.assertIn("obj := new RuntimeBox();", text) + self.assertIn("type RuntimeBox = class", text) + self.assertIn('t := findOverLoad(2, "fun", new TestClass());', text) + self.assertNotIn("new TStringList()", text) + self.assertNotIn('obj := createObject("TStringList");', text) + self.assertNotIn('findOverLoad(2, "fun", createObject("TestClass"))', text) + + def test_tsl_builtin_runtime_objects_default_to_new_syntax(self): + text = TSL_BUILTIN_RUNTIME_OBJECTS.read_text(encoding="utf-8") + + self.assertIn("`TStringList` 可以直接用 `new TStringList()` 创建", text) + self.assertIn("obj := new TStringList();", text) + self.assertIn("mem := new TMemoryStream();", text) + self.assertIn("cipher := new TCipher(2);", text) + self.assertIn("bad := new TCipher();", text) + self.assertIn("`new TStream()`", text) + self.assertIn("New Class TCipher Error.", text) + self.assertNotIn('createObject("TStringList")', text) + self.assertNotIn('createObject("TMemoryStream")', text) + self.assertNotIn('createObject("TCipher"', text) + + def test_tsl_ts_sql_page_documents_thisrow_field_order(self): + text = TSL_TS_SQL.read_text(encoding="utf-8") + + self.assertIn("第一行 `Value=20, Idx=1`，第二行 `Value=30, Idx=2`", text) + self.assertNotIn("`(1,20)`、`(2,30)`", text) + + def test_tsl_ts_sql_has_single_authoritative_syntax_page(self): + syntax_root = ROOT / "docs" / "tsl" / "syntax" + text = TSL_TS_SQL.read_text(encoding="utf-8") + + self.assertFalse((syntax_root / "28_ts_sql_core.md").exists()) + self.assertFalse((syntax_root / "29_ts_sql_advanced.md").exists()) + self.assertIn("这一篇是 TS-SQL 的唯一语法入口", text) + self.assertIn("多表 `join` 时，字段访问应写成 `[表序号].[\"字段名\"]`", text) + self.assertIn("`thisGroup` 不是普通值，而是分组后的子结果集", text) + self.assertIn("`refMaxOf(...)` 和 `refMinOf(...)` 可与", text) + def test_remaining_tsl_syntax_pages_are_agent_decision_pages(self): syntax_root = ROOT / "docs" / "tsl" / "syntax" @@ -411,9 +1115,68 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): with self.subTest(filename=filename): text = (syntax_root / filename).read_text(encoding="utf-8") self.assertIn(section, text) - self.assertIn("agent", text.lower()) + self.assertIn("智能体", text) self.assertIn("不要发明", text) + def test_tsl_syntax_pages_label_mainline_and_deep_dive_roles(self): + syntax_root = ROOT / "docs" / "tsl" / "syntax" + + for filename in TSL_SYNTAX_MAINLINE_FILES: + with self.subTest(filename=filename): + text = (syntax_root / filename).read_text(encoding="utf-8") + self.assertIn("文档类型：语法主线", text) + + text = (syntax_root / "11_pitfalls.md").read_text(encoding="utf-8") + self.assertIn("文档类型：反例索引页", text) + + for filename in TSL_SYNTAX_DEEP_DIVE_FILES: + with self.subTest(filename=filename): + text = (syntax_root / filename).read_text(encoding="utf-8") + self.assertIn("文档类型：语法深水专题", text) + + def test_tsl_syntax_uncertain_routes_have_center_fallbacks(self): + syntax_root = ROOT / "docs" / "tsl" / "syntax" + + for path in syntax_root.glob("*.md"): + with self.subTest(filename=path.name): + text = path.read_text(encoding="utf-8") + self.assertNotIn("遇到不确定时跳转到", text) + self.assertNotIn("补证", text) + self.assertNotIn("待确认", text) + self.assertIn("遇到不确定时：", text) + self.assertIn("TSL 总入口 [../index.md](../index.md)", text) + + if path.name == "index.md": + self.assertIn("按任务跳转", text) + continue + + self.assertIn("继续判断", text) + self.assertIn("语法路由中心 [index.md](index.md)", text) + + def test_tsl_syntax_examples_do_not_use_program_test_shell(self): + syntax_root = ROOT / "docs" / "tsl" / "syntax" + + for path in syntax_root.glob("*.md"): + with self.subTest(filename=path.name): + text = path.read_text(encoding="utf-8") + self.assertNotIn("program test;", text) + self.assertNotIn("`program test; begin ... end.` 只是自包含示例外壳", text) + + def test_tsl_syntax_code_block_identity_labels_are_fixed(self): + syntax_root = ROOT / "docs" / "tsl" / "syntax" + allowed_labels = { + "可直接照写示例", + "输出片段", + "反例 / 不可照写", + "配置片段 / 概念骨架", + } + + for path in syntax_root.glob("*.md"): + text = path.read_text(encoding="utf-8") + for match in re.finditer(r"^代码块身份：(.+)$", text, re.MULTILINE): + with self.subTest(filename=path.name, label=match.group(1)): + self.assertIn(match.group(1), allowed_labels) + def test_remaining_tsl_syntax_pages_have_verified_output_snippets(self): syntax_root = ROOT / "docs" / "tsl" / "syntax" @@ -421,10 +1184,10 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): with self.subTest(filename=filename): text = (syntax_root / filename).read_text(encoding="utf-8") if ( - "代码块身份：已验证可执行示例" in text + "代码块身份：可直接照写示例" in text or "代码块身份：反例 / 不可照写" in text ): - self.assertIn("代码块身份：已验证输出片段", text) + self.assertIn("代码块身份：输出片段", text) def test_remaining_tsl_syntax_pages_omit_personal_and_environment_details(self): syntax_root = ROOT / "docs" / "tsl" / "syntax" @@ -445,70 +1208,226 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): for phrase in forbidden_phrases: self.assertNotIn(phrase, text) - def test_tsl_reference_index_requires_verified_function_workflow(self): + def test_tsl_reference_index_requires_function_fact_workflow(self): text = TSL_REFERENCE_INDEX.read_text(encoding="utf-8") - self.assertIn("Agent 函数使用规则", text) - self.assertIn("只从 verified 函数页读取参数类型", text) - self.assertIn("catalog 只是候选函数索引", text) - self.assertIn("确认每个方法的参数类型", text) - self.assertIn("verified/index.md", text) - self.assertIn("verified/core.md", text) - self.assertIn("unavailable_methods.md", text) - self.assertIn("不能把 catalog 里的函数名直接当成可调用事实", text) + self.assertIn("智能体函数使用规则", text) + self.assertIn("进入 catalog 分类页后按函数事实条目生成调用", text) + self.assertIn("只从带完整参数表的函数事实条目读取签名", text) + self.assertIn("catalog 使用推荐大小写展示函数名", text) + self.assertIn("以函数事实条目的函数名拼写为准", text) + self.assertIn("没在 catalog 正式条目里的函数，不要根据函数名猜调用", text) + self.assertIn("函数名属于哪个模块", text) + self.assertIn("模块目录", text) + self.assertIn("catalog/base.md", text) + self.assertIn("catalog/math.md", text) + self.assertIn("catalog/resource.md", text) + self.assertNotIn("函数参数事实", text) + self.assertNotIn("catalog 里的裸函数名只是候选名", text) + self.assertNotIn("裸函数名仍只表示候选名", text) + self.assertNotIn("catalog/index.md", text) + self.assertNotIn("core.md", text) + self.assertNotIn("functions/", text) + self.assertNotIn("verified", text) + self.assertNotIn("unavailable_methods.md", text) + self.assertNotIn("不可用方法", text) self.assertNotIn("verification_failures", text) self.assertNotIn("函数入库验证流程", text) self.assertNotIn("验证过程", text) self.assertNotIn("代码块身份", text) - self.assertNotIn("已验证输出片段", text) + self.assertNotIn("输出片段", text) self.assertNotIn("验证失败", text) - def test_tsl_reference_catalog_is_candidate_index_not_callable_fact(self): - catalog_index = TSL_REFERENCE_CATALOG_INDEX.read_text(encoding="utf-8") + def test_tsl_reference_index_contains_function_fact_catalog(self): + catalog_index = TSL_REFERENCE_INDEX.read_text(encoding="utf-8") - self.assertIn("候选函数索引", catalog_index) - self.assertIn("候选名没有进入 verified 函数页前不能当成可调用事实", catalog_index) - self.assertIn("../verified/index.md", catalog_index) - self.assertIn("../verified/core.md", catalog_index) - self.assertIn("只从 verified 函数页读取参数类型", catalog_index) + self.assertIn("函数模块目录", catalog_index) + self.assertIn("进入分类页后，按函数事实条目的参数表生成调用", catalog_index) + self.assertIn("函数事实数", catalog_index) + self.assertIn("catalog/base.md", catalog_index) + self.assertIn("catalog/math.md", catalog_index) + self.assertIn("catalog/system.md", catalog_index) + self.assertIn("catalog/third_party.md", catalog_index) + self.assertIn("catalog 使用推荐大小写展示函数名", catalog_index) + self.assertIn("以函数事实条目的函数名拼写为准", catalog_index) + self.assertNotIn("catalog/index.md", catalog_index) + self.assertNotIn("core.md", catalog_index) + self.assertNotIn("functions/", catalog_index) + self.assertNotIn("verified", catalog_index) self.assertNotIn("错误参数组合", catalog_index) self.assertNotIn("参数验证", catalog_index) - for path in (ROOT / "docs" / "tsl" / "reference" / "catalog").glob("*.md"): + catalog_root = ROOT / "docs" / "tsl" / "reference" / "catalog" + route_pages = { + "base.md", + "math.md", + "datawarehouse.md", + "system.md", + "resource.md", + "graphics.md", + } + for path in catalog_root.rglob("*.md"): text = path.read_text(encoding="utf-8") - self.assertIn("候选函数索引", text, msg=f"{path.name} missing candidate warning") - self.assertIn("只从 verified 函数页读取参数类型", text) + if path.parent == catalog_root and path.name in route_pages: + self.assertIn("文档类型：函数事实路由页", text) + self.assertIn("分类目录", text) + self.assertNotIn("### `", text) + continue + self.assertIn("文档类型：函数事实页", text) + self.assertIn("参数位置", text, msg=f"{path.name} missing parameter facts") + self.assertNotIn("候选函数索引", text) + self.assertIn("../index.md", text) - def test_tsl_reference_verified_index_routes_to_parameter_fact_pages(self): - text = TSL_REFERENCE_VERIFIED_INDEX.read_text(encoding="utf-8") + def test_tsl_reference_catalog_function_names_start_lowercase(self): + catalog_root = ROOT / "docs" / "tsl" / "reference" / "catalog" - self.assertIn("文档类型：agent 参数事实索引", text) - self.assertIn("core.md", text) - self.assertIn("Abs", text) - self.assertIn("ifInt", text) - self.assertIn("DateToStr", text) - self.assertIn("Length", text) - self.assertIn("只从具体函数页读取接收类型", text) - self.assertNotIn("验证过程", text) + for path in catalog_root.rglob("*.md"): + if path.name == "index.md": + continue + text = path.read_text(encoding="utf-8") + for match in re.finditer(r"^(?:- |#{3,6} )`([^`(]+)", text, re.MULTILINE): + with self.subTest(path=path.relative_to(ROOT), name=match.group(1)): + name = match.group(1) + self.assertFalse(name[0].isupper(), msg=f"{name} starts uppercase") + + def test_tsl_reference_completed_catalog_pages_record_parameter_facts(self): + catalog_root = ROOT / "docs" / "tsl" / "reference" / "catalog" + completed_pages = { + "base.md": [ + "dateToStr", + "dateTimeToStr", + "formatDateTime", + "time", + "now", + "date", + "currentYear", + "dayOfWeek", + "encodeDate", + "encodeTime", + "strToDate", + "strToTime", + "strToDateTime", + "strToDateDef", + "strToTimeDef", + "timeToStr", + "dateToInt", + "intToDate", + "today", + "yesterday", + "tomorrow", + "format", + "setLength", + "copy", + "upperCase", + "lowerCase", + "trim", + "trimLeft", + "trimRight", + "pos", + "strToIntDef", + "floatToStr", + "strToInt", + "intToStr", + "length", + ], + "compression.md": [ + "zipCompress", + "zipExtract", + "rarExtract", + "unicompress", + "uniuncompress", + ], + "digest_encoding.md": [ + "getMsgDigest", + "strToBase64", + "base64ToStr", + "encodeRadixstr", + "decodeRadixstr", + "encoderadixwstr", + "decoderadixwstr", + ], + "system.md": [ + "dataType", + "ifInt", + "ifInt64", + "ifReal", + "ifNumber", + "ifString", + "ifArray", + "ifNil", + "ifExp", + "ifGraph", + "ifGraphGroup", + "ifBinary", + "ifMatrix", + "ifObj", + "createMatrix", + "matrixToArray", + "getMatrixFields", + "createBinary", + "convertDataToBuf", + "convertBufToData", + "integer", + "int64", + "real", + "string", + "wideString", + "binary", + "setPrecision", + "toSTM", + "toSTN", + "exportCsv", + "importCsv", + "dupValue", + "randomize", + "random", + "randomFrom", + "ifThen", + "eval", + "call", + "callInArray", + "invoke", + "invokeinarray", + "setProfiler", + "getProfilerInfo", + "sysgettsllibpath", + "syssettsllibpath", + ], + } + + for filename, signatures in completed_pages.items(): + path = catalog_root / filename + text = path.read_text(encoding="utf-8") + if "文档类型：函数事实路由页" in text: + text = "\n".join( + detail.read_text(encoding="utf-8") + for detail in sorted((catalog_root / path.stem).glob("*.md")) + ) + with self.subTest(filename=filename): + self.assertIn("文档类型：函数事实页", text) + self.assertIn("参数个数：", text) + self.assertIn("返回值：", text) + self.assertRegex( + text, + r"\|\s*参数位置\s*\|\s*参数名\s*\|\s*必填\s*\|\s*接收类型\s*\|\s*说明\s*\|", + ) + for name in signatures: + self.assertRegex(text, rf"(?m)^### `{re.escape(name)}\(", msg=name) + + def test_tsl_reference_index_records_parameter_facts(self): + text = TSL_REFERENCE_INDEX.read_text(encoding="utf-8") + + self.assertIn("函数事实路由页", text) + self.assertIn("查可调用函数参数类型", text) + self.assertIn("带完整参数表的函数事实条目", text) + self.assertIn("函数事实数", text) + self.assertIn("catalog/base.md", text) + self.assertIn("catalog/system.md", text) + self.assertNotIn("## 函数参数事实", text) + self.assertNotIn("`abs(value)`", text) + self.assertNotIn("verified", text) self.assertNotIn("代码块身份", text) - - def test_tsl_reference_verified_core_records_agent_parameter_facts(self): - text = TSL_REFERENCE_VERIFIED_CORE.read_text(encoding="utf-8") - - self.assertIn("文档类型：agent 参数事实表", text) - self.assertIn("接收类型", text) - self.assertIn("返回", text) - self.assertIn("`Abs(value)`", text) - self.assertIn("`ifInt(value)`", text) - self.assertIn("`DateToStr(value)`", text) - self.assertIn("`Length(value)`", text) - self.assertIn("整数", text) - self.assertIn("实数", text) - self.assertIn("字符串", text) - self.assertIn("数组", text) - self.assertIn("日期时间", text) - self.assertNotIn("代码块身份", text) - self.assertNotIn("已验证输出片段", text) + self.assertNotIn("输出片段", text) self.assertNotIn("Function Abs execution error", text) self.assertNotIn("错误参数", text) @@ -519,25 +1438,25 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): self.assertNotIn("验证过程", text) self.assertNotIn("函数入库验证流程", text) self.assertNotIn("代码块身份", text) - self.assertNotIn("已验证输出片段", text) + self.assertNotIn("输出片段", text) self.assertNotIn("Function Abs execution error", text) - def test_tsl_reference_unavailable_records_only_unavailable_methods(self): - text = TSL_REFERENCE_UNAVAILABLE.read_text(encoding="utf-8") + def test_tsl_reference_does_not_ship_verified_or_unavailable_layers(self): + reference_root = ROOT / "docs" / "tsl" / "reference" - self.assertIn("文档类型：当前测试环境不支持的方法清单", text) - self.assertIn("当前测试环境不支持的方法", text) - self.assertIn("暂无已入档记录", text) - self.assertNotIn("failure", text.lower()) - self.assertNotIn("失败", text) - self.assertNotIn("验证过程", text) - self.assertNotIn("参数类型错误", text) - self.assertNotIn("`Abs(\"-3\")`", text) - self.assertNotIn("`Abs()`", text) - self.assertNotIn("`DateToStr(\"2011-12-31\")`", text) - self.assertNotIn("`DateToStr()`", text) - self.assertNotIn("`Length(123)`", text) - self.assertNotIn("Function Abs execution error", text) + self.assertFalse((reference_root / "verified").exists()) + self.assertFalse((reference_root / "functions").exists()) + self.assertFalse((reference_root / "core.md").exists()) + self.assertFalse((reference_root / "catalog" / "index.md").exists()) + self.assertFalse(TSL_REFERENCE_UNAVAILABLE.exists()) + + for path in reference_root.rglob("*.md"): + text = path.read_text(encoding="utf-8") + with self.subTest(path=path.relative_to(ROOT)): + self.assertNotIn("verified", text) + self.assertNotIn("unavailable_methods", text) + self.assertNotIn("不可用方法", text) + self.assertNotIn("已写入文档", text) def test_tsl_reference_docs_do_not_name_valid_parameter_mismatches_as_failures(self): reference_root = ROOT / "docs" / "tsl" / "reference" @@ -551,29 +1470,14 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): self.assertNotIn("Abs(\"-3\")", text) self.assertNotIn("DateToStr(\"2011-12-31\")", text) self.assertNotIn("Length(123)", text) + self.assertNotIn("abs(\"-3\")", text) + self.assertNotIn("dateToStr(\"2011-12-31\")", text) + self.assertNotIn("length(123)", text) - def test_tsl_finance_docs_are_agent_business_decision_pages(self): + def test_tsl_finance_directory_is_removed(self): finance_root = ROOT / "docs" / "tsl" / "finance" - for path in finance_root.glob("*.md"): - text = path.read_text(encoding="utf-8") - with self.subTest(path=path.name): - self.assertIn("Agent", text) - self.assertIn("不要发明", text) - self.assertIn("项目实际接口", text) - self.assertNotIn("是否含已验证", text) - self.assertNotIn("代码块身份", text) - self.assertNotIn("验证过程", text) - - def test_tsl_finance_index_routes_all_finance_pages(self): - text = TSL_FINANCE_INDEX.read_text(encoding="utf-8") - - self.assertIn("Agent Finance 路由规则", text) - self.assertIn("entry_decision.md", text) - self.assertIn("market_data_context.md", text) - self.assertIn("series_and_indicator_model.md", text) - self.assertIn("selection_and_signal_patterns.md", text) - self.assertIn("backtest_and_trade_flow.md", text) + self.assertFalse(finance_root.exists()) def test_tsl_modules_docs_are_agent_integration_boundary_pages(self): modules_root = ROOT / "docs" / "tsl" / "modules" @@ -581,22 +1485,21 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): for path in modules_root.glob("*.md"): text = path.read_text(encoding="utf-8") with self.subTest(path=path.name): - self.assertIn("Agent", text) + self.assertIn("智能体", text) self.assertIn("不要发明", text) - self.assertNotIn("是否含已验证", text) + self.assertNotIn("是否含文档明确", text) self.assertNotIn("代码块身份", text) self.assertNotIn("验证过程", text) def test_tsl_modules_index_routes_all_module_pages(self): text = TSL_MODULES_INDEX.read_text(encoding="utf-8") - self.assertIn("Agent Modules 路由规则", text) + self.assertIn("智能体模块路由规则", text) self.assertIn("tsbacktesting.md", text) - self.assertIn("tsl_python_interop.md", text) self.assertIn("wechat_message.md", text) self.assertIn("pytsl_api.md", text) - def test_tsl_finance_and_modules_omit_environment_verification_details(self): + def test_tsl_modules_omit_environment_verification_details(self): forbidden_phrases = [ "Docker", "docker exec", @@ -608,11 +1511,10 @@ class TslEntrypointsConsistencyTests(unittest.TestCase): "实测", ] - for root_name in ("finance", "modules"): - for path in (ROOT / "docs" / "tsl" / root_name).glob("*.md"): - text = path.read_text(encoding="utf-8") - for phrase in forbidden_phrases: - self.assertNotIn(phrase, text, msg=f"{phrase!r} found in {path}") + for path in (ROOT / "docs" / "tsl" / "modules").glob("*.md"): + text = path.read_text(encoding="utf-8") + for phrase in forbidden_phrases: + self.assertNotIn(phrase, text, msg=f"{phrase!r} found in {path}") if __name__ == "__main__":