Template.php 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. <?php
  2. namespace App\Services\Markup\Templates;
  3. use App\Services\Markup\Dialect;
  4. use App\Services\Markup\Format;
  5. use App\Services\Markup\Ir\Call;
  6. use App\Services\Markup\Ir\Document;
  7. use App\Services\Markup\Ir\Params;
  8. use App\Services\Markup\Render\RenderContext;
  9. use App\Services\Markup\Resolve\Resolver;
  10. /**
  11. * 模板基类。一个模板一个子类,在 {@see TemplateRegistry} 登记名字。
  12. *
  13. * 生命周期:
  14. * 1. 解析:{@see Params()} 声明参数(位置、默认值、是否 markdown);markdown 参数递归解析成 slot
  15. * 2. 取数:{@see collect()} 把要查的键交给 Resolver,同类模板一次批量查完(不再逐个查库)
  16. * 3. 输出:tree 用 {@see component()} + {@see props()} + {@see children()};html / 纯文本 / markdown
  17. * 各有一个方法,默认都退回 {@see text()},只有真的不同才覆盖
  18. *
  19. * 模板实例无状态(单例),每次调用的数据都在 {@see Call} 上。
  20. */
  21. abstract class Template
  22. {
  23. /** tree 输出的组件名(前端按它分发) */
  24. protected string $component = 'unknown';
  25. /**
  26. * @return array<string, ParamSpec>
  27. */
  28. public function params(): array
  29. {
  30. return [];
  31. }
  32. /**
  33. * 参数片段 → 参数表。
  34. *
  35. * `name=value` 当命名参数的条件:名字全是小写字母(v2 口径);E2 方言下还要求名字是 {@see Params()}
  36. * 声明过的,否则整段按位置参数处理——LLM 写的 `x=y` 不会被误认成参数。
  37. *
  38. * @param list<string> $segments
  39. */
  40. public function parseParams(array $segments, Dialect $dialect): Params
  41. {
  42. $declared = $this->params();
  43. $named = [];
  44. $positional = [];
  45. foreach ($segments as $offset => $segment) {
  46. if (preg_match('/^([a-z]+)=(.*)$/s', $segment, $m) === 1
  47. && ($dialect === Dialect::Markdown || $this->acceptsAnyName() || isset($declared[$m[1]]))) {
  48. $named[$m[1]] = $m[2];
  49. } else {
  50. $positional[$offset + 1] = $segment;
  51. }
  52. }
  53. return new Params($named, $positional);
  54. }
  55. /**
  56. * 是否接受任意名字的命名参数(Tpl 模板把参数原样交给 Mustache)。
  57. */
  58. protected function acceptsAnyName(): bool
  59. {
  60. return false;
  61. }
  62. public function collect(Call $call, Resolver $resolver): void {}
  63. /**
  64. * html 输出是块级元素(目录的 nav、mermaid 的 pre):段落里只有它时不包 `<p>`。
  65. */
  66. public function block(): bool
  67. {
  68. return false;
  69. }
  70. /**
  71. * 这次调用引用到的经文段落(`{{ref}}` 据此列参考文献)。只从参数里解析,不查库。
  72. *
  73. * @return list<array{0: int, 1: int}> [book, para]
  74. */
  75. public function references(Call $call): array
  76. {
  77. return [];
  78. }
  79. /**
  80. * `book-para` 或 `book-para-start-end` 形式的坐标 → [[book, para]];不合法返回 []。
  81. *
  82. * @return list<array{0: int, 1: int}>
  83. */
  84. protected static function paragraphRef(string $id): array
  85. {
  86. $parts = explode('-', trim($id));
  87. if (count($parts) < 2 || ! ctype_digit($parts[0]) || ! ctype_digit($parts[1])) {
  88. return [];
  89. }
  90. return [[(int) $parts[0], (int) $parts[1]]];
  91. }
  92. public function component(Call $call, RenderContext $ctx): string
  93. {
  94. return $this->component;
  95. }
  96. /**
  97. * tree 输出的 props。值可以是 {@see Document},由渲染器按当前格式展开。
  98. *
  99. * @return array<string, mixed>
  100. */
  101. public function props(Call $call, RenderContext $ctx): array
  102. {
  103. return [];
  104. }
  105. /**
  106. * tree 输出的 children。
  107. */
  108. public function children(Call $call, RenderContext $ctx): ?Document
  109. {
  110. return null;
  111. }
  112. /**
  113. * 纯文本表示:text / simple / prompt / markdown / html 的默认输出都从它来。
  114. */
  115. public function text(Call $call, RenderContext $ctx): string
  116. {
  117. return '';
  118. }
  119. public function plain(Call $call, RenderContext $ctx, Format $format): string
  120. {
  121. return $this->text($call, $ctx);
  122. }
  123. public function html(Call $call, RenderContext $ctx): string
  124. {
  125. return e($this->text($call, $ctx));
  126. }
  127. public function markdown(Call $call, RenderContext $ctx): string
  128. {
  129. return $this->text($call, $ctx);
  130. }
  131. }