powertom 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,146 @@
1
+ # frozen_string_literal: true
2
+
3
+ module PowerTom
4
+ # §3 模板语法 v0:
5
+ # - 文本标签 {{path}} / {{path:formatter}}(§3.4),路径只支持点路径与下标
6
+ # - 页级指令 {{#each}} / {{#if}} 只允许写在幻灯片备注(§3.3),出现在正文 = 语法错误
7
+ module Scanner
8
+ # 宽松的"疑似标签"正则,用于语法校验兜底:任何 {{...}} 都必须能通过严格校验
9
+ TAG_RE = /\{\{[^{}]*\}\}/.freeze
10
+
11
+ # 严格的文本标签正则:点路径与下标 + 可选 formatter 规格(§3.4)
12
+ LABEL_RE = /\{\{\s*([A-Za-z0-9_\[\]]+(?:\.[A-Za-z0-9_\[\]]+)*)(?::([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)*))?\s*\}\}/.freeze
13
+
14
+ # 合法的路径段:字段名或 字段名[下标]
15
+ SEGMENT_RE = /\A[A-Za-z0-9_]+(?:\[\d+\])?\z/.freeze
16
+
17
+ # formatter 规格:词 + 可选 .参数(percent.1 / date.year_month)
18
+ FORMAT_SPEC_RE = /\A[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)*\z/.freeze
19
+
20
+ module_function
21
+
22
+ # 扫描段落上下文,收集标签并校验语法。
23
+ # contexts: [{slide_no:, shape:, run_texts:}]
24
+ # 返回 [{path:, spec:, context:}](同一标签出现多次会分别记录)
25
+ # {{#rows 路径}} 是表格行标记,只做语法校验,不作为可绑定标签返回。
26
+ def scan(contexts)
27
+ contexts.flat_map do |ctx|
28
+ joined = ctx[:run_texts].join
29
+ next [] unless joined.include?("{{")
30
+
31
+ joined.scan(TAG_RE).flat_map do |tag|
32
+ raw = tag[/\{\{\s*([^{}]*?)\s*\}\}/, 1].to_s
33
+ validate!(raw, tag, ctx)
34
+ next [] if raw.start_with?("#", "/")
35
+
36
+ path, spec = raw.split(":", 2)
37
+ [{ path: path, spec: spec, context: ctx }]
38
+ end
39
+ end
40
+ end
41
+
42
+ # 备注里的标签:v0 不渲染备注,发现即记 warning(§3.3)
43
+ def scan_notes(notes_text, slide_no)
44
+ return [] unless notes_text
45
+ notes_text.scan(TAG_RE).map { |tag| { tag: tag, slide_no: slide_no } }
46
+ end
47
+
48
+ # 备注页级指令(§3.3):{{#each 路径}} 按数组克隆整页;{{#if 路径}} 为假删页。
49
+ # 一页备注只允许一条指令;返回 {slide_no => {kind:, path:}}
50
+ def scan_directives(notes_texts)
51
+ notes_texts.each_with_object({}) do |note, directives|
52
+ directive = directive_for(note)
53
+ directives[note[:slide_no]] = directive if directive
54
+ end
55
+ end
56
+
57
+ # 单页备注的指令解析:无指令返回 nil,语法问题抛 TemplateSyntaxError。
58
+ # Validator 逐页调用以收集全部错误;render 走 scan_directives 一次性收集。
59
+ def directive_for(note)
60
+ slide_no = note[:slide_no]
61
+ tags = note[:text].to_s.scan(TAG_RE)
62
+ directives_in_notes = tags.select { |tag| tag[/\{\{\s*([^{}]*?)\s*\}\}/, 1].to_s.start_with?("#") }
63
+ return nil if directives_in_notes.empty?
64
+
65
+ if directives_in_notes.size > 1
66
+ raise TemplateSyntaxError,
67
+ "第 #{slide_no} 页备注含 #{directives_in_notes.size} 条页级指令 " \
68
+ "(#{directives_in_notes.join(', ')}),一页只允许一条(§3.3)"
69
+ end
70
+
71
+ raw = directives_in_notes.first[/\{\{\s*#\s*([^{}]*?)\s*\}\}/, 1].to_s
72
+ m = raw.match(/\A(each|if)\s+([A-Za-z0-9_\[\]\.]+)\z/)
73
+ unless m
74
+ raise TemplateSyntaxError,
75
+ "第 #{slide_no} 页备注指令 {{##{raw}}} 不合法,只支持 {{#each 路径}} 与 {{#if 路径}}"
76
+ end
77
+ { kind: m[1].to_sym, path: m[2] }
78
+ end
79
+
80
+ def validate!(raw, tag, ctx)
81
+ where = "第 #{ctx[:slide_no]} 页 形状'#{ctx[:shape]}'"
82
+ if raw.start_with?("#") || raw.start_with?("/")
83
+ if ctx[:in_table] && raw.match?(/\A#(rows|grid|cols|if)\b|\A\/(rows|cols|if)\z/)
84
+ validate_table_directive!(raw, tag, where)
85
+ return
86
+ end
87
+ raise TemplateSyntaxError,
88
+ "#{where}:#{tag} 是页级指令,必须写在幻灯片备注里,v0 正文不支持指令"
89
+ end
90
+ path, spec = raw.split(":", 2)
91
+ validate_path!(path, tag, where, ctx)
92
+ if spec && !spec.match?(FORMAT_SPEC_RE)
93
+ raise TemplateSyntaxError,
94
+ "#{where}:#{tag} 的 formatter 写法不合法,应为 {{路径:名字}} 或 {{路径:名字.参数}}"
95
+ end
96
+ end
97
+
98
+ # 表格指令:{{#rows 路径}} / {{#grid ...}} / {{#cols ...}} / {{/rows}} / {{/cols}}。
99
+ # 这里只做轻量语法校验,结构(层级/位置/作用域)由 TableLoop 校验。
100
+ GRID_MARKER_RE = /\A#grid\s+.+\z/.freeze
101
+ COLS_MARKER_RE = /\A#cols\s+[A-Za-z0-9_\.]+(?:\s+value:\s*[A-Za-z0-9_\.]+(?:\s*,\s*[A-Za-z0-9_\.]+)*)?\z/.freeze
102
+ IF_MARKER_RE = /\A#if\s+[A-Za-z0-9_\[\]\.]+\z/.freeze
103
+ CLOSE_MARKER_RE = /\A\/(rows|cols|if)\z/.freeze
104
+
105
+ def validate_table_directive!(raw, tag, where)
106
+ case raw
107
+ when /\A#rows\s/
108
+ validate_row_marker!(raw, tag, where)
109
+ when GRID_MARKER_RE, COLS_MARKER_RE, IF_MARKER_RE, CLOSE_MARKER_RE
110
+ nil
111
+ else
112
+ raise TemplateSyntaxError,
113
+ "#{where}:#{tag} 表格指令不合法,只支持 {{#rows 路径}} / {{#grid ...}} / " \
114
+ "{{#cols ...}} / {{#if 路径}} / {{/rows}} / {{/cols}} / {{/if}}"
115
+ end
116
+ end
117
+
118
+ # 表格行标记 {{#rows 路径}}:只校验路径写法,结构与层级由 TableLoop 校验
119
+ def validate_row_marker!(raw, tag, where)
120
+ unless raw.match?(/\A#rows\s+[A-Za-z0-9_\[\]\.]+\z/)
121
+ raise TemplateSyntaxError,
122
+ "#{where}:#{tag} 行标记不合法,应为 {{#rows 路径}}(路径只支持点路径与 [])"
123
+ end
124
+ return unless raw.match?(/\[\d+\]/)
125
+
126
+ raise TemplateSyntaxError, "#{where}:#{tag} 行标记路径不支持下标,请用数组名 + []"
127
+ end
128
+
129
+ # 路径逐段校验:字段、字段[下标]、字段[](仅表格行循环)
130
+ def validate_path!(path, tag, where, ctx)
131
+ path.split(".").each do |segment|
132
+ next if segment.match?(/\A[A-Za-z0-9_]+(?:\[\d+\])?\z/)
133
+
134
+ if segment.match?(/\A[A-Za-z0-9_]+\[\]\z/)
135
+ unless ctx[:in_table]
136
+ raise TemplateSyntaxError,
137
+ "#{where}:#{tag} 的 [] 只能在表格行里使用(表格行循环),正文/备注请用具体下标"
138
+ end
139
+ else
140
+ raise TemplateSyntaxError,
141
+ "#{where}:#{tag} 不是合法标签,路径只支持点路径与下标(如 {{kpis[0].name}})"
142
+ end
143
+ end
144
+ end
145
+ end
146
+ end