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,558 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "fileutils"
4
+ require "tempfile"
5
+ require_relative "scanner"
6
+ require_relative "binder"
7
+ require_relative "path_resolver"
8
+ require_relative "grid_value"
9
+ require_relative "run_merge"
10
+ require_relative "table_loop"
11
+ require_relative "data_loading"
12
+ require_relative "adapter/ruby_pptx_adapter"
13
+ require_relative "adapter/page_surgery"
14
+
15
+ module PowerTom
16
+ # §2.1 渲染入口。
17
+ # result = PowerTom.render("templates/x.pptx", data: "data.toml", strict: true)
18
+ # result.save("out/x.pptx")
19
+ # result.warnings # 未使用字段、缺失字段降级、备注标签等
20
+ #
21
+ # data 支持 Hash 或 .toml 文件路径(TOML 是 gem 的默认数据格式)。
22
+ # v0 覆盖:单页多标签、跨 run 标签、{{#each}} 页面克隆、{{#if}} 页面删除(§3.3)。
23
+ def self.render(template_path, data:, strict: true)
24
+ Render.new(template_path, data: DataLoading.coerce(data), strict: strict).call
25
+ end
26
+
27
+ class RenderResult
28
+ attr_reader :warnings
29
+
30
+ def initialize(adapter, prs, warnings, temp_path: nil)
31
+ @adapter = adapter
32
+ @prs = prs
33
+ @warnings = warnings
34
+ @temp_path = temp_path
35
+ end
36
+
37
+ def save(path)
38
+ @adapter.save(@prs, path)
39
+ FileUtils.remove_entry(@temp_path, true) if @temp_path
40
+ path
41
+ end
42
+
43
+ # 成品页数(埋点与断言用;克隆/删页之后的结果)
44
+ def slide_count
45
+ @prs.slides.size
46
+ end
47
+ end
48
+
49
+ # 渲染管线(§4):扫描(标签+指令,语法校验)→ 编辑计划 → 结构手术(克隆/删页)
50
+ # → 绑定(#each 页取迭代作用域)→ 保存。
51
+ # 任何抛错都发生在写盘之前:产物要么完整要么不存在。
52
+ class Render
53
+ def initialize(template_path, data:, strict:)
54
+ @template_path = template_path
55
+ @data = data
56
+ @strict = strict
57
+ end
58
+
59
+ def call
60
+ adapter = Adapter::RubyPptxAdapter.new
61
+ prs = adapter.open(@template_path)
62
+ warnings = []
63
+
64
+ contexts = adapter.paragraph_contexts(prs)
65
+ # 正文与表格单元格的标签语法校验,手术前失败
66
+ Scanner.scan(contexts + adapter.table_cell_contexts(prs))
67
+ notes = adapter.notes_texts(prs)
68
+ directives = Scanner.scan_directives(notes)
69
+ binder = Binder.new(@data, strict: @strict, warnings: warnings)
70
+
71
+ if directives.empty?
72
+ work_prs = prs
73
+ page_scopes = Hash.new { |_h, _k| { scope: nil, scope_root: nil } }
74
+ else
75
+ pages = build_page_plan(directives, binder, prs.slides.size)
76
+ run_surgery(adapter, pages)
77
+ work_prs = adapter.open(@work_path) # 手术产物重新打开,按新页序绑定
78
+ # pages 与输出页一一对应(手术按计划顺序展开,不重排)
79
+ page_scopes = {}
80
+ pages.each_with_index do |p, i|
81
+ page_scopes[i] = { scope: p[:scope], scope_root: p[:scope_root] }
82
+ end
83
+ page_scopes.default = { scope: nil, scope_root: nil }
84
+ end
85
+
86
+ # 表格行循环:按数组长度展开模板行,再采集单元格段落做绑定
87
+ table_scopes = expand_table_rows(adapter, work_prs, page_scopes, binder)
88
+
89
+ contexts = adapter.paragraph_contexts(work_prs) + adapter.table_cell_contexts(work_prs)
90
+ contexts.each do |ctx|
91
+ page = page_scopes[ctx[:slide_no] - 1]
92
+ row_scopes = row_scopes_for(table_scopes, ctx)
93
+ grid_scope = grid_scope_for(table_scopes, ctx)
94
+ row_item = row_item_for(table_scopes, ctx)
95
+ bctx = ctx.merge(scope: page[:scope], scope_root: page[:scope_root],
96
+ row_scopes: row_scopes, grid_scope: grid_scope,
97
+ row_item: row_item)
98
+ new_texts = RunMerge.merge(
99
+ ctx[:run_texts],
100
+ ->(path, spec) { binder.render_label(path, bctx, spec: spec) }
101
+ )
102
+ adapter.write_paragraph_runs(ctx[:paragraph], new_texts) if new_texts
103
+ end
104
+
105
+ replace_images(adapter, work_prs, page_scopes, binder)
106
+
107
+ report_unused_fields(binder, warnings)
108
+ report_notes_labels(notes, warnings)
109
+
110
+ RenderResult.new(adapter, work_prs, warnings,
111
+ temp_path: directives.empty? ? nil : @work_path)
112
+ end
113
+
114
+ private
115
+
116
+ # §3.3:#each 按数组克隆(K=数组长度,空数组整组删除);#if 为假删页。
117
+ # 返回 [{source:, iteration:, scope:, scope_root:}] 按输出顺序。
118
+ def build_page_plan(directives, binder, slide_count)
119
+ pages = []
120
+ (1..slide_count).each do |no|
121
+ directive = directives[no]
122
+ ctx = { slide_no: no, shape: "(备注指令)" }
123
+ if directive.nil?
124
+ pages << { source: no, iteration: nil, scope: nil, scope_root: nil }
125
+ elsif directive[:kind] == :if
126
+ value = binder.value_at(directive[:path], ctx)
127
+ pages << { source: no, iteration: nil, scope: nil, scope_root: nil } if truthy?(value)
128
+ else
129
+ value = binder.value_at(directive[:path], ctx)
130
+ if value.nil?
131
+ raise MissingDataError,
132
+ "第 #{no} 页备注 {{#each #{directive[:path]}}}:数据缺少 #{directive[:path]},无法确定循环次数"
133
+ end
134
+ unless value.is_a?(Array)
135
+ raise PowerTom::Error,
136
+ "第 #{no} 页备注 {{#each #{directive[:path]}}}:取到 #{value.class},必须为数组"
137
+ end
138
+ root = directive[:path].split(".").first[/\A[A-Za-z0-9_]+/]
139
+ value.each_with_index do |item, k|
140
+ pages << { source: no, iteration: k, scope: item, scope_root: root }
141
+ end
142
+ end
143
+ end
144
+ pages
145
+ end
146
+
147
+ def truthy?(value)
148
+ !(value.nil? || value == false)
149
+ end
150
+
151
+ # 结构手术走字节级包操作:模板原文件 → 手术后的临时文件 → 重新打开绑定
152
+ def run_surgery(adapter, pages)
153
+ tmp = Tempfile.create(["powertom_surgery", ".pptx"])
154
+ tmp.close
155
+ @work_path = tmp.path
156
+ Adapter::PageSurgery.execute(@template_path, @work_path, pages)
157
+ end
158
+
159
+ # §5.3 图片替换:powertom:image:字段名 占位 → 数据里的图片文件。
160
+ # 与文本一样作用域感知:#each 克隆页各自取本项的图片;缺字段(strict: false)
161
+ # 时保留占位图并记 warning。
162
+ def replace_images(adapter, prs, page_scopes, binder)
163
+ adapter.picture_contexts(prs).each do |pctx|
164
+ page = page_scopes[pctx[:slide_no] - 1]
165
+ ctx = { slide_no: pctx[:slide_no], shape: pctx[:shape],
166
+ scope: page[:scope], scope_root: page[:scope_root] }
167
+ value = binder.value_at(pctx[:field], ctx, purpose: "图片占位,保留占位图")
168
+ next if value.nil? # 缺失(non-strict):保留占位图
169
+ unless value.is_a?(String) && !value.empty?
170
+ raise PowerTom::Error,
171
+ "第 #{pctx[:slide_no]} 页 图片字段 '#{pctx[:field]}' 需要 String 文件路径," \
172
+ "得到 #{value.class}"
173
+ end
174
+ unless File.file?(value)
175
+ raise PowerTom::Error,
176
+ "第 #{pctx[:slide_no]} 页 图片字段 '#{pctx[:field]}' 的文件不存在:#{value}"
177
+ end
178
+ adapter.replace_image(pctx[:slide], pctx[:picture], value)
179
+ end
180
+ end
181
+
182
+ # 表格循环:单级行 / 两级嵌套行 / 动态列;页级 #each 与表格循环不叠加
183
+ def expand_table_rows(adapter, prs, page_scopes, binder)
184
+ scopes = {}
185
+ adapter.table_contexts(prs).each do |table|
186
+ plan = table_plan(table)
187
+ next unless plan
188
+
189
+ page = page_scopes[table[:slide_no] - 1]
190
+ if page[:scope]
191
+ raise PowerTom::Error,
192
+ "第 #{table[:slide_no]} 页 表格'#{table[:shape]}':" \
193
+ "页级 #each 与表格行循环暂不支持叠加(只支持一层循环)"
194
+ end
195
+
196
+ scopes[[table[:slide_no], table[:shape]]] = case plan[:kind]
197
+ when :simple
198
+ expand_simple_rows(adapter, table, plan, binder)
199
+ when :nested
200
+ expand_nested_rows(adapter, table, plan, binder)
201
+ when :blocks
202
+ expand_block_rows(adapter, table, plan, binder)
203
+ else
204
+ expand_grid_rows(adapter, table, plan, binder)
205
+ end
206
+ end
207
+ scopes
208
+ end
209
+
210
+ # 结构错误(表内行号)补上页码与形状名,方便设计师定位
211
+ def table_plan(table)
212
+ TableLoop.plan(table[:rows], merged_rows: table[:merged_rows],
213
+ columns: table[:columns])
214
+ rescue TemplateSyntaxError => e
215
+ raise TemplateSyntaxError, "第 #{table[:slide_no]} 页 表格'#{table[:shape]}':#{e.message}"
216
+ end
217
+
218
+ def expand_simple_rows(adapter, table, plan, binder)
219
+ ctx = { slide_no: table[:slide_no], shape: table[:shape] }
220
+ items = fetch_loop_array(binder, plan[:root], table, ctx)
221
+ adapter.expand_table_row(table[:element], table[:frame], plan[:row], items.size)
222
+ { kind: :simple, start: plan[:row], count: items.size,
223
+ items: items, root: plan[:root] }
224
+ end
225
+
226
+ def expand_nested_rows(adapter, table, plan, binder)
227
+ ctx = { slide_no: table[:slide_no], shape: table[:shape] }
228
+ parents = fetch_loop_array(binder, plan[:parent][:path], table, ctx)
229
+ children = parents.each_with_index.map do |parent, index|
230
+ fetch_child_array(parent, plan[:child][:relative], table, ctx, index)
231
+ end
232
+ adapter.expand_table_rows_nested(table[:element], table[:frame], plan,
233
+ children.map(&:size))
234
+
235
+ rows = []
236
+ children.each_with_index do |items, parent_index|
237
+ rows << { parent: parent_index, child: nil }
238
+ items.each_index { |child_index| rows << { parent: parent_index, child: child_index } }
239
+ end
240
+
241
+ { kind: :nested, start: plan[:parent][:marker], rows: rows,
242
+ parents: parents, children: children,
243
+ parent_prefix: plan[:parent][:prefix], child_prefix: plan[:child][:prefix] }
244
+ end
245
+
246
+ # 动态列(#grid):列按 cols 克隆(每一行),行按 rows 克隆;首列固定为行标题
247
+ def expand_grid_rows(adapter, table, plan, binder)
248
+ ctx = { slide_no: table[:slide_no], shape: table[:shape] }
249
+ grid = plan[:grid]
250
+ rows = fetch_loop_array(binder, grid[:rows_path], table, ctx)
251
+ cols = fetch_loop_array(binder, grid[:cols_path], table, ctx)
252
+ check_grid_columns!(cols, table, ctx)
253
+
254
+ adapter.expand_grid_columns(table[:element], table[:frame], cols.size)
255
+ adapter.strip_grid_marker(table[:element], grid[:header], 0)
256
+ adapter.expand_table_row(table[:element], table[:frame], grid[:content], rows.size)
257
+
258
+ { kind: :grid, header: grid[:header], content_start: grid[:content],
259
+ rows: rows, cols: cols, value_path: grid[:value_path] }
260
+ end
261
+
262
+ # 列键提前校验:不要等渲染到一半才发现某列缺 key
263
+ def check_grid_columns!(cols, table, ctx)
264
+ cols.each_with_index do |col, index|
265
+ GridValue.column_key(col)
266
+ rescue MissingDataError => e
267
+ raise MissingDataError,
268
+ "第 #{ctx[:slide_no]} 页 表格'#{table[:shape]}':" \
269
+ "列数据第 #{index + 1} 项#{e.message}"
270
+ end
271
+ end
272
+
273
+ # v0.2.0 区块:配对行区块(多行记录、最多 3 级)+ 单列带(可写在区块内)
274
+ def expand_block_rows(adapter, table, plan, binder)
275
+ ctx = { slide_no: table[:slide_no], shape: table[:shape] }
276
+ band = plan[:cols]
277
+ cols = []
278
+ if band
279
+ cols = fetch_loop_array(binder, band[:path], table, ctx)
280
+ check_grid_columns!(cols, table, ctx)
281
+ # 先剥离标记,再复制列:否则标记会被复制到每一列
282
+ adapter.strip_column_markers(table[:element], band[:row], band[:first_col], band[:last_col])
283
+ adapter.expand_column_band(table[:element], table[:frame],
284
+ band[:first_col], band[:last_col], cols.size)
285
+ end
286
+
287
+ # 行索引在列克隆后不变,先捕获顶层区块的开闭行元素
288
+ roots = plan[:blocks].map do |block|
289
+ { block: block,
290
+ open_el: adapter.table_row_element(table[:element], block[:open]),
291
+ close_el: adapter.table_row_element(table[:element], block[:close]),
292
+ items: fetch_loop_array(binder, block[:path], table, ctx) }
293
+ end
294
+ roots.each do |node|
295
+ node[:children_by_item] = resolve_block_children(node[:block], {}, node[:items], table, ctx)
296
+ node[:if_values_by_item] = node[:items].map do |item|
297
+ block_if_values(node[:block], item, {})
298
+ end
299
+ end
300
+
301
+ records = build_block_row_records(roots, table[:rows].size)
302
+ roots.each do |node|
303
+ node[:groups] = adapter.clone_table_row_range(
304
+ table[:element], node[:open_el], node[:close_el], node[:items].size
305
+ )
306
+ expand_block_children(adapter, table, node)
307
+ end
308
+ adapter.refresh_table_height(table[:element], table[:frame])
309
+
310
+ { kind: :blocks, records: records, cols: cols, band: band }
311
+ end
312
+
313
+ # 子区块的数组依赖父项:按每个父项解析一次,供行计划与展开复用
314
+ def resolve_block_children(block, parent_scope, items, table, ctx)
315
+ items.each_with_index.map do |item, index|
316
+ scope = parent_scope.merge(block[:prefix] => item)
317
+ block[:children].map do |child|
318
+ child_items = fetch_child_array(item, child[:relative], table, ctx, index)
319
+ {
320
+ block: child,
321
+ items: child_items,
322
+ if_values_by_item: child_items.map { |ci| block_if_values(child, ci, scope) },
323
+ children_by_item: resolve_block_children(child, scope, child_items, table, ctx)
324
+ }
325
+ end
326
+ end
327
+ end
328
+
329
+ def block_if_values(block, item, parent_scope)
330
+ scope = parent_scope.merge(block[:prefix] => item)
331
+ block[:ifs].to_h do |node|
332
+ [node, condition_truthy?(node[:path], item, scope)]
333
+ end
334
+ end
335
+
336
+ # #if 求值:含 [] 时按作用域栈;否则先看当前记录,再看整页数据
337
+ def condition_truthy?(path, item, scope)
338
+ value = if path.include?("[]")
339
+ prefix = scope.keys.select { |key| path == key || path.start_with?("#{key}.") }
340
+ .max_by(&:length)
341
+ raise PowerTom::Error, "{{#if #{path}}} 不在当前行区块作用域内" unless prefix
342
+
343
+ remainder = path.delete_prefix(prefix).delete_prefix(".")
344
+ remainder.empty? ? scope[prefix] : PathResolver.resolve(scope[prefix], remainder)
345
+ else
346
+ begin
347
+ PathResolver.resolve(item, path)
348
+ rescue MissingDataError
349
+ PathResolver.resolve(@data, path)
350
+ end
351
+ end
352
+ !(value.nil? || value == false)
353
+ rescue MissingDataError => e
354
+ raise MissingDataError, "{{#if #{path}}} 无法求值:#{e.message}"
355
+ end
356
+
357
+ # 展开后的行作用域计划:下标与最终行号一一对应;静态行为 nil
358
+ def build_block_row_records(roots, row_count)
359
+ records = []
360
+ cursor = 0
361
+ roots.each do |node|
362
+ (cursor...node[:block][:open]).each { records << nil }
363
+ append_block_records(node, {}, records)
364
+ cursor = node[:block][:close] + 1
365
+ end
366
+ (cursor...row_count).each { records << nil }
367
+ records
368
+ end
369
+
370
+ def append_block_records(node, parent_scope, records)
371
+ block = node[:block]
372
+ node[:items].each_with_index do |item, index|
373
+ scope = parent_scope.merge(block[:prefix] => item)
374
+ record = { scopes: scope, row_item: item }
375
+ append_block_template_records(block, node[:children_by_item][index], scope, records, record,
376
+ node[:if_values_by_item][index])
377
+ end
378
+ end
379
+
380
+ # 区块内:条件范围按真假取舍,子区块范围由子区块计划替代,其余行各输出一条记录
381
+ def append_block_template_records(block, children, scope, records, record, if_values)
382
+ row = block[:open] + 1
383
+ while row < block[:close]
384
+ if_node = block[:ifs].find { |node| node[:open] == row }
385
+ if if_node
386
+ (if_node[:open] + 1...if_node[:close]).each { records << record } if if_values[if_node]
387
+ row = if_node[:close] + 1
388
+ next
389
+ end
390
+
391
+ child = children.find { |node| node[:block][:open] == row }
392
+ if child
393
+ append_block_records(child, scope, records)
394
+ row = child[:block][:close] + 1
395
+ else
396
+ records << record
397
+ row += 1
398
+ end
399
+ end
400
+ end
401
+
402
+ # 递归展开子区块:先裁剪条件范围,再按模板相对偏移展开子区块
403
+ def expand_block_children(adapter, table, node)
404
+ block = node[:block]
405
+ node[:items].each_index do |index|
406
+ group = node[:groups][index]
407
+ prune_block_ifs(adapter, table, group, block, node[:if_values_by_item][index])
408
+
409
+ block[:children].each do |child|
410
+ child_node = node[:children_by_item][index].find { |cn| cn[:block] == child }
411
+ open_el = group[child[:open] - block[:open] - 1]
412
+ close_el = group[child[:close] - block[:open] - 1]
413
+ child_node[:groups] = adapter.clone_table_row_range(
414
+ table[:element], open_el, close_el, child_node[:items].size
415
+ )
416
+ expand_block_children(adapter, table, child_node)
417
+ end
418
+ end
419
+ end
420
+
421
+ def prune_block_ifs(adapter, table, group, block, if_values)
422
+ block[:ifs].each do |node|
423
+ open_el = group[node[:open] - block[:open] - 1]
424
+ close_el = group[node[:close] - block[:open] - 1]
425
+ adapter.prune_table_row_range(table[:element], open_el, close_el,
426
+ keep_content: if_values[node])
427
+ end
428
+ end
429
+
430
+ def fetch_loop_array(binder, path, table, ctx)
431
+ items = binder.value_at(path, ctx)
432
+ return items if items.is_a?(Array)
433
+
434
+ raise PowerTom::Error,
435
+ "第 #{table[:slide_no]} 页 表格'#{table[:shape]}':" \
436
+ "{{#{path}}} 需要数组,得到 #{items.nil? ? '空值' : items.class}"
437
+ end
438
+
439
+ def fetch_child_array(parent, relative, table, ctx, index)
440
+ value = PathResolver.resolve(parent, relative)
441
+ return value if value.is_a?(Array)
442
+
443
+ raise PowerTom::Error,
444
+ "第 #{ctx[:slide_no]} 页 表格'#{table[:shape]}':父级第 #{index + 1} 项的" \
445
+ "'#{relative}' 需要数组,得到 #{value.class}"
446
+ rescue MissingDataError => e
447
+ raise MissingDataError,
448
+ "第 #{ctx[:slide_no]} 页 表格'#{table[:shape]}':父级第 #{index + 1} 项" \
449
+ "缺少子数组 '#{relative}'(#{e.message})"
450
+ end
451
+
452
+ # 该段落属于哪一行作用域:返回 {"groups[]" => 父项, "groups[].items[]" => 子项}
453
+ def row_scopes_for(scopes, ctx)
454
+ return nil unless ctx[:table_shape]
455
+
456
+ scope = scopes[[ctx[:slide_no], ctx[:table_shape]]]
457
+ return nil unless scope
458
+
459
+ if scope[:kind] == :blocks
460
+ record = scope[:records][ctx[:row_index]]
461
+ return record ? record[:scopes] : nil
462
+ end
463
+ return nil if scope[:kind] == :grid
464
+
465
+ offset = ctx[:row_index] - scope[:start]
466
+ return nil if offset.negative?
467
+
468
+ if scope[:kind] == :simple
469
+ return nil if offset >= scope[:count]
470
+
471
+ { "#{scope[:root]}[]" => scope[:items][offset] }
472
+ else
473
+ row = scope[:rows][offset]
474
+ return nil unless row
475
+
476
+ result = { scope[:parent_prefix] => scope[:parents][row[:parent]] }
477
+ if row[:child]
478
+ result[scope[:child_prefix]] = scope[:children][row[:parent]][row[:child]]
479
+ end
480
+ result
481
+ end
482
+ end
483
+
484
+ # #grid / 区块列带的单元格作用域:{col: 列项, row: 行项, cell: 行列交叉值}
485
+ def grid_scope_for(scopes, ctx)
486
+ return nil unless ctx[:table_shape]
487
+
488
+ scope = scopes[[ctx[:slide_no], ctx[:table_shape]]]
489
+ return nil unless scope
490
+ return block_grid_scope(scope, ctx) if scope[:kind] == :blocks
491
+ return nil unless scope[:kind] == :grid
492
+
493
+ col_index = ctx[:col_index].to_i
494
+ col = col_index.positive? ? scope[:cols][col_index - 1] : nil
495
+ offset = ctx[:row_index] - scope[:content_start]
496
+ row = offset >= 0 && offset < scope[:rows].size ? scope[:rows][offset] : nil
497
+
498
+ grid = {}
499
+ grid[:col] = col if col
500
+ grid[:row] = row if row
501
+ if row && col
502
+ grid[:cell] = -> { GridValue.cell_value(row, col, scope[:value_path]) }
503
+ end
504
+ grid.empty? ? nil : grid
505
+ end
506
+
507
+ def block_grid_scope(scope, ctx)
508
+ band = scope[:band]
509
+ return nil unless band
510
+
511
+ col_index = ctx[:col_index].to_i
512
+ start = band[:first_col]
513
+ width = band[:last_col] - start + 1
514
+ return nil if col_index < start || col_index >= start + width * scope[:cols].size
515
+
516
+ col = scope[:cols][(col_index - start) / width]
517
+ template_index = (col_index - start) % width
518
+ value_path = GridValue.band_value_path(band[:value_paths], template_index)
519
+ record = scope[:records][ctx[:row_index]]
520
+ row = record && record[:row_item]
521
+
522
+ grid = { col: col }
523
+ if row
524
+ grid[:row] = row
525
+ grid[:cell] = -> { GridValue.cell_value(row, col, value_path) }
526
+ end
527
+ grid
528
+ end
529
+
530
+ # 行区块里的当前记录(供 {{row.*}} 使用)
531
+ def row_item_for(scopes, ctx)
532
+ return nil unless ctx[:table_shape]
533
+
534
+ scope = scopes[[ctx[:slide_no], ctx[:table_shape]]]
535
+ return nil unless scope && scope[:kind] == :blocks
536
+
537
+ record = scope[:records][ctx[:row_index]]
538
+ record && record[:row_item]
539
+ end
540
+
541
+ # §2.3 数据有模板未使用的字段 → warning(v0 只追踪顶层字段)
542
+ def report_unused_fields(binder, warnings)
543
+ return unless @data.is_a?(Hash)
544
+ unused = @data.keys.map(&:to_s) - binder.used_root_keys.to_a
545
+ unused.each { |key| warnings << "数据字段 '#{key}' 未被模板使用" }
546
+ end
547
+
548
+ # §3.3 备注里的普通文本标签 v0 不渲染,记 warning(页级指令除外)
549
+ def report_notes_labels(notes, warnings)
550
+ notes.each do |note|
551
+ Scanner.scan_notes(note[:text], note[:slide_no]).each do |found|
552
+ next if found[:tag] =~ /\{\{\s*#/
553
+ warnings << "第 #{found[:slide_no]} 页备注含标签 #{found[:tag]},v0 不渲染备注,已忽略"
554
+ end
555
+ end
556
+ end
557
+ end
558
+ end
@@ -0,0 +1,26 @@
1
+ # frozen_string_literal: true
2
+
3
+ module PowerTom
4
+ # §5.1 段落级 run 合并替换(纯 Ruby,不碰 XML)。
5
+ #
6
+ # PowerPoint 会把 {{title}} 存成多个 run(输入法组合、拼写检查、反复编辑都会触发)。
7
+ # 解法:把段落内所有 run 的文本拼接成完整字符串,匹配标签做替换,
8
+ # 结果写回首个 run,其余 run 清空文本但保留节点本身(样式引用不破坏)。
9
+ module RunMerge
10
+ module_function
11
+
12
+ # run_texts: [String];resolver: path(String), spec(String|nil) → 渲染后的文本
13
+ # 返回新的 run 文本数组;段落里没有可替换标签时返回 nil(调用方跳过写入)
14
+ def merge(run_texts, resolver)
15
+ return nil if run_texts.nil? || run_texts.empty?
16
+ joined = run_texts.join
17
+ return nil unless joined.include?("{{")
18
+ return nil unless joined.match?(PowerTom::Scanner::LABEL_RE)
19
+
20
+ replaced = joined.gsub(PowerTom::Scanner::LABEL_RE) do
21
+ resolver.call(Regexp.last_match(1), Regexp.last_match(2))
22
+ end
23
+ [replaced] + Array.new(run_texts.size - 1, "")
24
+ end
25
+ end
26
+ end