powertom 0.2.5 → 0.2.7

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.
@@ -1,6 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require "set"
4
3
  require_relative "scanner"
5
4
  require_relative "table_loop"
6
5
  require_relative "grid_value"
@@ -13,6 +12,7 @@ module PowerTom
13
12
 
14
13
  # 校验结果与人话报告(§7):每条问题给出"第 X 页、形状 Y、标签 Z、期望的数据路径"。
15
14
  class CheckResult
15
+ # @return [Array<PowerTom::CheckEntry>] all entries, errors and warnings.
16
16
  attr_reader :entries
17
17
 
18
18
  def initialize(template_name, entries)
@@ -20,14 +20,19 @@ module PowerTom
20
20
  @entries = entries
21
21
  end
22
22
 
23
+ # @return [Array<PowerTom::CheckEntry>] entries that block rendering.
23
24
  def errors = entries.select { |e| e.level == :error }
24
25
 
26
+ # @return [Array<PowerTom::CheckEntry>] non-blocking entries.
25
27
  def warnings = entries.select { |e| e.level == :warning }
26
28
 
29
+ # @return [Boolean] true when there is no error.
27
30
  def ok? = errors.empty?
28
31
 
32
+ # @return [Integer] 0 when valid, 1 otherwise (for CI).
29
33
  def exit_code = ok? ? 0 : 1
30
34
 
35
+ # @return [String] human-readable, one line per entry.
31
36
  def report
32
37
  lines = ["PowerTom 模板校验 — #{@template_name}"]
33
38
  entries.each do |e|
@@ -35,7 +40,7 @@ module PowerTom
35
40
  body = head.empty? ? e.message : "#{head} #{e.message}"
36
41
  lines << format("[%-7s] %s", e.level, body)
37
42
  end
38
- lines << "-" * 48
43
+ lines << ("-" * 48)
39
44
  summary = "#{errors.size} 个 error,#{warnings.size} 个 warning"
40
45
  summary += "(error 阻断渲染,修正后再调用 PowerTom.render)" unless ok?
41
46
  lines << summary
@@ -73,7 +78,7 @@ module PowerTom
73
78
  # notes: [{slide_no:, text:}]
74
79
  # pictures: [{slide_no:, shape:, field:}](powertom:image 占位)
75
80
  # data: Hash 或 nil(nil → 跳过字段对账,只做语法与结构检查)
76
- def check(contexts:, notes:, data:, pictures: [], tables: [], table_structures: [],
81
+ def check(contexts:, notes:, data:, pictures: [], charts: [], tables: [], table_structures: [],
77
82
  template_name: "template.pptx")
78
83
  entries = []
79
84
  used_roots = Set.new
@@ -88,6 +93,7 @@ module PowerTom
88
93
  nil
89
94
  end
90
95
  next unless directive
96
+
91
97
  directives[note[:slide_no]] = directive
92
98
  used_roots << root_of(directive[:path])
93
99
  end
@@ -115,9 +121,7 @@ module PowerTom
115
121
  end
116
122
  labels.each do |l|
117
123
  labels_by_page[ctx[:slide_no]] << l
118
- if ctx[:table_shape]
119
- labels_by_table_row[[ctx[:slide_no], ctx[:table_shape], ctx[:row_index]]] << l
120
- end
124
+ labels_by_table_row[[ctx[:slide_no], ctx[:table_shape], ctx[:row_index]]] << l if ctx[:table_shape]
121
125
  end
122
126
  end
123
127
 
@@ -141,8 +145,10 @@ module PowerTom
141
145
  labels_by_page.each_value do |labels|
142
146
  labels.each do |l|
143
147
  next unless l[:spec]
148
+
144
149
  name = l[:spec].split(".").first
145
150
  next if Formatter.registered?(name)
151
+
146
152
  entries << error_entry(l[:context][:slide_no], l[:context][:shape], l[:path],
147
153
  "未注册的 formatter '#{name}'" \
148
154
  "(可用:#{Formatter.registered_names.join(', ')})")
@@ -182,7 +188,7 @@ module PowerTom
182
188
  labels.each do |l|
183
189
  next if l[:path].include?("[]")
184
190
  next if block_row_stacks.dig([l[:context][:slide_no], l[:context][:table_shape]],
185
- l[:context][:row_index])
191
+ l[:context][:row_index])
186
192
  next if block_band_cell?(table_plans, l[:context])
187
193
  next if grid_plan_for(table_plans, l[:context]) && grid_variable_path?(l[:path])
188
194
 
@@ -196,8 +202,9 @@ module PowerTom
196
202
  labels.each do |l|
197
203
  directive = directives[l[:context][:slide_no]]
198
204
  next if directive && directive[:kind] == :each
205
+
199
206
  if block_row_stacks.dig([l[:context][:slide_no], l[:context][:table_shape]],
200
- l[:context][:row_index])
207
+ l[:context][:row_index])
201
208
  used_roots << root_of(l[:path]) unless grid_variable_path?(l[:path])
202
209
  next
203
210
  end
@@ -234,11 +241,20 @@ module PowerTom
234
241
  notes.each do |note|
235
242
  Scanner.scan_notes(note[:text], note[:slide_no]).each do |found|
236
243
  next if found[:tag] =~ /\{\{\s*#/
244
+
237
245
  entries << CheckEntry.new(level: :warning, slide_no: note[:slide_no], shape: "(备注)",
238
246
  label: nil, message: "备注含标签 #{found[:tag]},v0 不渲染备注,已忽略")
239
247
  end
240
248
  end
241
249
 
250
+ # 5. 图表不绑定数据:保留标签并告警,而不是静默忽略
251
+ charts.each do |chart|
252
+ entries << CheckEntry.new(
253
+ level: :warning, slide_no: chart[:slide_no], shape: chart[:shape], label: nil,
254
+ message: "图表含标签 #{chart[:tags].join('、')}:v0 不绑定图表数据,会原样保留"
255
+ )
256
+ end
257
+
242
258
  CheckResult.new(template_name, entries)
243
259
  end
244
260
 
@@ -279,16 +295,15 @@ module PowerTom
279
295
  return # 指令级 error 已单独报告
280
296
  end
281
297
  return unless items.is_a?(Array)
298
+
282
299
  items.each_with_index do |item, k|
283
- begin
284
- PathResolver.resolve(item, path)
285
- rescue MissingDataError => e
286
- entries << error_entry(
287
- ctx[:slide_no], ctx[:shape], path,
288
- "数组 '#{directive[:path]}' 第 #{k + 1} 项:#{e.message}" \
289
- "(期望:#{directive[:path]}[#{k}].#{path})"
290
- )
291
- end
300
+ PathResolver.resolve(item, path)
301
+ rescue MissingDataError => e
302
+ entries << error_entry(
303
+ ctx[:slide_no], ctx[:shape], path,
304
+ "数组 '#{directive[:path]}' 第 #{k + 1} 项:#{e.message}" \
305
+ "(期望:#{directive[:path]}[#{k}].#{path})"
306
+ )
292
307
  end
293
308
  else
294
309
  begin
@@ -303,11 +318,15 @@ module PowerTom
303
318
  def overflow_check(label, directive, data, entries)
304
319
  ctx = label[:context]
305
320
  # 多项循环的标签取首项检查,避免同类警告刷屏
306
- source = directive && directive[:kind] == :each ? begin
307
- PathResolver.resolve(data, directive[:path])[0]
308
- rescue MissingDataError
309
- nil
310
- end : data
321
+ source = if directive && directive[:kind] == :each
322
+ begin
323
+ PathResolver.resolve(data, directive[:path])[0]
324
+ rescue MissingDataError
325
+ nil
326
+ end
327
+ else
328
+ data
329
+ end
311
330
  return unless source
312
331
 
313
332
  value = begin
@@ -341,6 +360,7 @@ module PowerTom
341
360
  return # 指令级 error 已单独报告
342
361
  end
343
362
  return unless items.is_a?(Array)
363
+
344
364
  items.each_with_index do |item, k|
345
365
  value = begin
346
366
  PathResolver.resolve(item, path)
@@ -367,6 +387,7 @@ module PowerTom
367
387
 
368
388
  def check_image_value(value, ctx, path, entries, item_index = nil)
369
389
  return if value.nil?
390
+
370
391
  where = item_index ? "第 #{item_index + 1} 项:" : ""
371
392
  unless value.is_a?(String) && !value.empty?
372
393
  entries << error_entry(ctx[:slide_no], ctx[:shape], path,
@@ -374,6 +395,7 @@ module PowerTom
374
395
  return
375
396
  end
376
397
  return if File.file?(value)
398
+
377
399
  entries << error_entry(ctx[:slide_no], ctx[:shape], path,
378
400
  "#{where}图片文件不存在:#{value}")
379
401
  end
@@ -511,6 +533,7 @@ module PowerTom
511
533
  blocks.each do |block|
512
534
  items = block_array(block, parent_item, ctx, data, entries)
513
535
  next if items.nil?
536
+
514
537
  if items.empty?
515
538
  entries << CheckEntry.new(level: :warning, slide_no: ctx[:slide_no], shape: ctx[:shape],
516
539
  label: block[:path],
@@ -526,7 +549,7 @@ module PowerTom
526
549
  if_node = block[:ifs].find { |n| n[:open] == row }
527
550
  if if_node
528
551
  if block_condition_true?(if_node[:path], item, scope, ctx, data, entries, where)
529
- (if_node[:open] + 1...if_node[:close]).each do |r|
552
+ ((if_node[:open] + 1)...if_node[:close]).each do |r|
530
553
  labels_by_row[[ctx[:slide_no], ctx[:shape], r]].each do |label|
531
554
  reconcile_block_label(label, scope, item, cols, band, where, data, entries)
532
555
  end
@@ -1,6 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module PowerTom
4
- # 设计文档 §6:v0.2.5 文档结构与元数据打磨
5
- VERSION = "0.2.5"
4
+ # 设计文档 §6:v0.2.7 文档语言统一
5
+ VERSION = "0.2.7"
6
6
  end
data/lib/powertom.rb CHANGED
@@ -20,31 +20,52 @@ require_relative "powertom/validator"
20
20
 
21
21
  module PowerTom
22
22
  class << self
23
- # §3.4 注册自定义 formatter:proc 收到 (value, arg),返回值 to_s 后落盘。
23
+ # Register a custom formatter.
24
+ #
25
+ # @param name [String] formatter name used after the colon in a tag.
26
+ # @yieldparam value [Object] value resolved from the data.
27
+ # @yieldparam arg [String, nil] argument after the dot in the formatter spec.
28
+ # @yieldreturn [Object] converted value (sent through +to_s+ when written).
29
+ # @return [void]
30
+ # @example
24
31
  # PowerTom.register_formatter("rmb") { |value, _arg| "人民币#{value}元" }
25
- def register_formatter(name, &block)
26
- Formatter.register(name, &block)
32
+ def register_formatter(name, &)
33
+ Formatter.register(name, &)
27
34
  end
28
35
 
36
+ # Remove a previously registered formatter.
37
+ #
38
+ # @param name [String]
39
+ # @return [void]
29
40
  def unregister_formatter(name)
30
41
  Formatter.unregister_formatter(name)
31
42
  end
32
- # §2.1 渲染入口。
33
- # result = PowerTom.render("templates/x.pptx", data: "data.toml", strict: true)
34
- # result.save("out/x.pptx")
35
- # result.warnings # 未使用字段、缺失字段降级、备注标签等
43
+
44
+ # Render a template with the given data.
36
45
  #
37
- # data 支持 Hash 或 .toml 文件路径(TOML 是 gem 的默认数据格式)。
38
- # v0 覆盖:单页多标签、跨 run 标签、{{#each}} 页面克隆、{{#if}} 页面删除(§3.3)。
46
+ # @param template_path [String] path to a +.pptx+ template.
47
+ # @param data [Hash, String] a Hash or a +.toml+ file path.
48
+ # @param strict [Boolean] raise on missing fields when true; fill blanks and warn when false.
49
+ # @return [PowerTom::RenderResult]
50
+ # @raise [PowerTom::MissingDataError] a field is missing in strict mode.
51
+ # @raise [PowerTom::TemplateSyntaxError] an invalid tag, directive or table block.
52
+ # @raise [PowerTom::InvalidTemplateError] the file is not a readable +.pptx+.
53
+ # @example
54
+ # result = PowerTom.render("template.pptx", data: "data.toml")
55
+ # result.save("out.pptx")
56
+ # result.warnings.each { |warning| warn warning }
39
57
  def render(template_path, data:, strict: true)
40
58
  Render.new(template_path, data: DataLoading.coerce(data), strict: strict).call
41
59
  end
42
60
 
43
- # §7 模板校验器:对账模板标签 vs 样例数据,报告问题而不抛异常
44
- # (语法错误也作为 error 条目输出)。返回 CheckResult:
45
- # result.ok? / result.errors / result.warnings / result.exit_code / result.report
61
+ # Validate a template against optional sample data without raising.
46
62
  #
47
- # data 支持 Hash 或 .toml 路径;缺省时只做语法与结构检查。
63
+ # @param template_path [String] path to a +.pptx+ template.
64
+ # @param data [Hash, String, nil] sample data Hash or +.toml+ path.
65
+ # @return [PowerTom::CheckResult]
66
+ # @example
67
+ # result = PowerTom.check("template.pptx", data: "sample.toml")
68
+ # puts result.report
48
69
  def check(template_path, data: nil)
49
70
  data = DataLoading.coerce(data) if data
50
71
  adapter = Adapter::RubyPptxAdapter.new
@@ -55,6 +76,7 @@ module PowerTom
55
76
  table_structures: adapter.table_contexts(prs),
56
77
  notes: adapter.notes_texts(prs),
57
78
  pictures: adapter.picture_contexts(prs),
79
+ charts: adapter.chart_tags(prs),
58
80
  data: data,
59
81
  template_name: File.basename(template_path)
60
82
  )
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: powertom
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.5
4
+ version: 0.2.7
5
5
  platform: ruby
6
6
  authors:
7
7
  - PowerTom contributors
@@ -37,18 +37,17 @@ dependencies:
37
37
  - - "~>"
38
38
  - !ruby/object:Gem::Version
39
39
  version: '3.0'
40
- description: |-
41
- PowerTom is a PowerPoint template engine for Ruby. Designers keep the template in PowerPoint; engineers pass a Ruby Hash or a TOML file and get a finished deck. Layout, fonts, colours, masters and theme stay under the designer's control.
42
-
43
- PowerTom est un moteur de modèles PowerPoint pour Ruby. Les designers conservent le modèle dans PowerPoint ; les ingénieurs passent un Hash Ruby ou un fichier TOML et obtiennent un deck finalisé. La mise en page, les polices, les couleurs, les masques et le thème restent sous le contrôle du designer.
44
-
45
- 设计师在 PowerPoint 里维护模板,工程师传一个 Ruby Hash 或 TOML 文件,产出成品 deck。排版、字体、配色、母版和主题完全由设计工具掌控。
40
+ description: PowerTom is a PowerPoint template engine for Ruby. Designers keep the
41
+ template in PowerPoint; engineers pass a Ruby Hash or a TOML file and get a finished
42
+ deck. Layout, fonts, colours, masters and theme stay under the designer's control.
46
43
  executables: []
47
44
  extensions: []
48
45
  extra_rdoc_files:
46
+ - CHANGELOG.md
49
47
  - LICENSE
50
48
  - README.md
51
49
  files:
50
+ - CHANGELOG.md
52
51
  - LICENSE
53
52
  - README.md
54
53
  - lib/powertom.rb
@@ -72,7 +71,9 @@ metadata:
72
71
  homepage_uri: https://github.com/ixepet/powertom
73
72
  source_code_uri: https://github.com/ixepet/powertom
74
73
  bug_tracker_uri: https://github.com/ixepet/powertom/issues
74
+ changelog_uri: https://github.com/ixepet/powertom/blob/main/CHANGELOG.md
75
75
  documentation_uri: https://github.com/ixepet/powertom/blob/main/docs/usage.md
76
+ rubygems_mfa_required: 'true'
76
77
  rdoc_options: []
77
78
  require_paths:
78
79
  - lib