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.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 78b836be78ce3eb57f1ee656d4a73ffdd307c60bf12bfa11e332800dcda43ece
4
- data.tar.gz: 5c0ea72ff17fa162c17c265d6a850b0c4b7ff5d16665a1ea418cc9467f5a8a9d
3
+ metadata.gz: 4cc6fd7b427f0d9d1a6ec2104fa51c807251cca9f438fd65e968b5eb1a8433f4
4
+ data.tar.gz: '087886b3c039a9b57dd9ba0f31e94cd148a217c9fe94c5f4be77a87542085927'
5
5
  SHA512:
6
- metadata.gz: 827c7c32494ffe34e928e33be2eeec447cae486d67cd7fe718e61ead3bd590730ab30824e4ed4a073016ebe7577591f86c0e32ec73b6587a6658a2ea7bb9c99d
7
- data.tar.gz: e79d9d9bca6fc0b15367cf8d28d4e5ff789374a4b807648e14897281f268b433c653f7165349677009a214685e8501e2d4ce8d970bfd031ccacd472798c4a5b0
6
+ metadata.gz: 7fadce8fac1c479d74521f0e653ec69486a9731cb63ad44aa5efb5d4b0c5edeab6f6450d7f8507afdd1241387277c2a92ce81b356e50e48170b49d249a20c980
7
+ data.tar.gz: 47c4e71b4f7160bf2c564837dd8ec1d3d92b8df49c7c443ff9ee28d24760da9bb9bc912420f5e8a8aa16c2caf88d7b1225980895f3a699c59e419ebac2c6bb76
data/CHANGELOG.md ADDED
@@ -0,0 +1,81 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here.
4
+ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
5
+ and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ ## [0.2.7] - 2026-11-17
8
+
9
+ ### Changed
10
+
11
+ - All documentation is now English-only: the designer guide, template production spec,
12
+ dogfooding plan, table loop design and project design document were translated from Chinese.
13
+ - Documentation files renamed to English kebab-case names:
14
+ `docs/template-guide.md`, `docs/score-report-template-spec.md`, `docs/dogfooding-plan.md`,
15
+ `docs/table-loop-design.md`, `docs/project-design.md`.
16
+ - `README.md` is English-only again; the French translation was removed and remaining French
17
+ comments were translated.
18
+ - The gemspec description is English-only.
19
+ - Cross-links between the README and the guides point at the new file names.
20
+
21
+ ### Note
22
+
23
+ - 0.2.6 was tagged and never published to RubyGems; 0.2.7 supersedes it.
24
+
25
+ ## [0.2.6] - 2026-11-17
26
+
27
+ ### Added
28
+
29
+ - RuboCop and YARD in the development toolchain, plus CI jobs for style and docs.
30
+ - A public fidelity CI job that runs the LibreOffice checks on committed scaffolds,
31
+ so contributors can run the full pipeline without private fixtures.
32
+ - Render warnings when a chart contains template tags (charts are not data-bound).
33
+ - Render warnings when an image aspect ratio differs significantly from its placeholder
34
+ (replacement always fills and centre-crops).
35
+
36
+ ### Changed
37
+
38
+ - Added this changelog and `changelog_uri` metadata to the gemspec.
39
+ - Public API entry points now carry YARD tags.
40
+ - Documented fixture policy: private gold samples stay local; committed scaffolds are public.
41
+
42
+ ## [0.2.5] - 2026-11-17
43
+
44
+ ### Changed
45
+
46
+ - Gemspec metadata now explicitly includes `homepage_uri`, `source_code_uri`,
47
+ `bug_tracker_uri` and `documentation_uri`.
48
+ - `README.md` and `LICENSE` are included in both `spec.files` and `spec.extra_rdoc_files`.
49
+ - English README comments translated from French.
50
+ - Engineering design document moved to `docs/project-design.md`.
51
+
52
+ ## [0.2.4] - 2026-11-17
53
+
54
+ ### Added
55
+
56
+ - Column-level `{{#if path}} ... {{/if}}` inside `#cols` bands: the wrapped template
57
+ columns are removed per column item, across all rows.
58
+ - English, French and Chinese description on the RubyGems page.
59
+
60
+ ## [0.2.3] - 2026-11-17
61
+
62
+ ### Added
63
+
64
+ - `docs/usage.md`, a full tag and data reference.
65
+ - RubyGems version badge and a 5-line quick-start example in the README.
66
+
67
+ ## [0.2.2] - 2026-11-17
68
+
69
+ ### Added
70
+
71
+ - Paired row blocks `{{#rows path}} ... {{/rows}}` with multi-row records, up to 3 levels.
72
+ - Multi-column column bands `{{#cols path value: a,b}} ... {{/cols}}`.
73
+ - Row-level `{{#if path}} ... {{/if}}` conditional blocks.
74
+ - Backward compatible with L0/L1/L2 table loops.
75
+
76
+ ## [0.1.0] - 2026-11-17
77
+
78
+ ### Added
79
+
80
+ - Initial release: text tags, split-run handling, formatters, page directives,
81
+ image placeholders, single-level table row loops, `PowerTom.check`, TOML data.
data/README.md CHANGED
@@ -134,16 +134,16 @@ result = PowerTom.render("templates/report.pptx", data: {
134
134
  - **Pictures**: name the shape or its alt text `powertom:image:cover` and pass a file path in the data. Replacement always fills the shape and crops from the centre.
135
135
  - One directive per notes page, maximum.
136
136
  - TOML dates are written unquoted (`report_date = 2026-01-20`), normalised to Ruby `Date`, and can be formatted with `{{report_date:date.cn}}`.
137
- - Full guide for designers (Chinese): [docs/模板制作规范.md](https://github.com/ixepet/powertom/blob/main/docs/模板制作规范.md).
138
- - Full usage reference (English): [docs/usage.md](https://github.com/ixepet/powertom/blob/main/docs/usage.md).
137
+ - Full guide for designers: [docs/template-guide.md](https://github.com/ixepet/powertom/blob/main/docs/template-guide.md).
138
+ - Full usage reference: [docs/usage.md](https://github.com/ixepet/powertom/blob/main/docs/usage.md).
139
139
 
140
140
  Built-in formatters: `currency`, `percent`, `number`, `date` (with `.year_month` / `.cn` / `.short`).
141
141
  Register your own:
142
142
 
143
143
  ```ruby
144
- # Formateur personnalisé — reçoit (value, arg) et renvoie le texte à écrire
144
+ # Custom formatter — receives (value, arg) and returns the text to write
145
145
  PowerTom.register_formatter("rmb") { |value, _arg| "#{value} RMB" }
146
- # Utilisation dans le modèle : {{amount:rmb}}
146
+ # Use in a template: {{amount:rmb}}
147
147
  ```
148
148
 
149
149
  ## Template checker
@@ -169,12 +169,12 @@ PowerTom 模板校验 — report.pptx
169
169
  Programmatic API:
170
170
 
171
171
  ```ruby
172
- # Vérifie sans rendre ; les erreurs sont rapportées, pas levées
172
+ # Validate without rendering; errors are reported, not raised
173
173
  result = PowerTom.check("templates/report.pptx", data: "data/sample.toml")
174
174
  result.ok? # => false
175
- result.errors # chaque entrée porte slide_no / shape / label / message
176
- result.report # le rapport lisible ci-dessus
177
- result.exit_code # 0 ou 1 — utilisable en CI
175
+ result.errors # each entry carries slide_no / shape / label / message
176
+ result.report # the human-readable report shown above
177
+ result.exit_code # 0 or 1 — usable in CI
178
178
  ```
179
179
 
180
180
  Checks: missing fields (including each item of an `#each` array), unregistered formatters, directive syntax, more than one directive per page, picture fields and missing files, placeholder overflow warnings, unused data fields, leftover tags in notes.
@@ -194,20 +194,22 @@ Output is **all or nothing**: every check runs before anything is written to dis
194
194
 
195
195
  | Limitation | Notes |
196
196
  | --- | --- |
197
- | Tables support row loops, paired row blocks, nesting and dynamic columns; charts are not bound | `{{classes[].name}}` clones one row; `{{#rows ...}} ... {{/rows}}` clones multi-row records (3 levels); `{{#grid ...}}` / `{{#cols ...}}` clone columns; merged cells inside loops are rejected |
198
- | Notes are not rendered | Notes are only read for page directives |
197
+ | Tables support row loops, paired row blocks, nesting and dynamic columns; charts are not bound | `{{classes[].name}}` clones one row; `{{#rows ...}} ... {{/rows}}` clones multi-row records (3 levels); `{{#grid ...}}` / `{{#cols ...}}` clone columns; merged cells inside loops are rejected. Tags found inside charts are preserved and reported as warnings |
198
+ | Notes are not rendered | Notes are only read for page directives; ordinary tags in notes produce a warning |
199
199
  | Tags on masters/layouts are ignored | Only shapes on slides are processed |
200
200
  | No PPT → PDF | Use LibreOffice headless |
201
201
  | `.pptx` only | No legacy 97-2003 binary format |
202
202
  | TOML or Hash only | No YAML / JSON loader |
203
- | Fixed picture cropping | Always fill the shape and crop from the centre |
203
+ | Fixed picture cropping | Always fill the shape and crop from the centre; a warning is emitted when the image aspect differs by more than 20% |
204
204
  | Messages are Chinese-only | Localisation is planned; the report format is language-neutral |
205
205
 
206
206
  ## Development
207
207
 
208
208
  ```bash
209
209
  bundle install
210
- bundle exec rspec
210
+ bundle exec rspec # full suite (private-fixture examples skip if absent)
211
+ bundle exec rubocop # style
212
+ bundle exec yard doc --no-output # API docs check
211
213
  ```
212
214
 
213
215
  The golden-sample template used by the end-to-end tests (split runs, cloning, picture replacement, fidelity) is not committed, because of size and ownership; only its structural snapshot `spec/fixtures/hai_mate/manifest.toml` is. With the original template at hand:
@@ -217,7 +219,7 @@ bundle exec rake fixtures:generate TEMPLATE=/path/to/template.pptx OUT=spec/fixt
217
219
  bundle exec rake fixtures:check OUT=spec/fixtures/hai_mate
218
220
  ```
219
221
 
220
- Without `template.pptx`, fixture-dependent examples are skipped and the unit suite still runs. Fidelity tests need LibreOffice (`soffice`).
222
+ Without `template.pptx`, fixture-dependent examples are skipped and the unit suite still runs. The committed scaffolds (`examples/score_report/*.pptx`) and the public fidelity job cover the full render/PDF pipeline without private assets. Fidelity tests need LibreOffice (`soffice`).
221
223
 
222
224
  ## License
223
225
 
@@ -226,230 +228,3 @@ MIT.
226
228
  ## Why PowerTom
227
229
 
228
230
  The Tom in PowerTom is a dedication — left unexplained, on purpose.
229
-
230
- Le Tom de PowerTom est une dédicace — laissée sans explication, à dessein.
231
-
232
- ---
233
- ---
234
-
235
- # PowerTom — moteur de modèles PowerPoint pour Ruby
236
-
237
- > Les designers maintiennent le modèle dans PowerPoint. Les développeurs passent un Hash Ruby (ou un fichier TOML) et obtiennent une présentation finalisée.
238
- > La mise en page, les polices, les couleurs, les masques et le thème restent sous le contrôle du designer ; le code se contente de scanner les balises, de lier les données et de dupliquer les diapositives.
239
-
240
- <sub>Non affilié à Microsoft ni à TomTom.</sub>
241
-
242
- ---
243
-
244
- ## En 30 secondes
245
-
246
- ```text
247
- Designer Développeur
248
- ┌──────────────────────────┐ ┌──────────────────────────┐
249
- │ Un pptx ordinaire dans │ │ report.toml │
250
- │ PowerPoint : │ │ title = "Examens" │
251
- │ corps : {{title}} │ ─────────▶ │ [[classes]] │
252
- │ notes : {{#each classes}}│ │ name = "8e (3)" │
253
- │ image nommée │ │ avg = 82.4 │
254
- │ powertom:image:cover │ │ │
255
- └──────────────────────────┘ └──────────────────────────┘
256
- │ │
257
- └──────────────┬───────────────────┘
258
- ▼
259
- PowerTom.render("template.pptx", data: "report.toml")
260
- ▼
261
- Présentation finale : balises liées, pages dupliquées
262
- ou supprimées, images remplacées — s'ouvre dans
263
- PowerPoint sans message de réparation.
264
- ```
265
-
266
- ## Pourquoi un nouveau moteur
267
-
268
- Ruby propose aujourd'hui deux façons de produire des PPTX, et aucune ne convient à la réutilisation d'un actif de design :
269
-
270
- | Approche | Exemples | Problème |
271
- | --- | --- | --- |
272
- | Génération pilotée par le code | `powerpoint`, `ruby_slides` | La mise en page est codée en dur ; changer une taille de police exige un développeur |
273
- | Bibliothèque OOXML bas niveau | `ruby_pptx`, `rbpptx` | Des briques XML, pas de couche modèle ; inutilisable par un designer |
274
-
275
- PowerTom occupe la couche intermédiaire : un **moteur de modèles au-dessus de [`ruby_pptx`](https://rubygems.org/gems/ruby_pptx)**, sans analyser OOXML lui-même. L'équivalent Ruby de Carbone / Docxtemplater — sans dépendance Node, sans service externe, une ligne dans le Gemfile.
276
-
277
- ## Installation
278
-
279
- ```ruby
280
- # Gemfile
281
- gem "powertom"
282
- ```
283
-
284
- Nécessite Ruby >= 3.3 ; dépend de `ruby_pptx ~> 0.2.0` (lecture/écriture) et de `tomlrb ~> 3.0` (fichiers de données).
285
-
286
- ## Démarrage rapide
287
-
288
- **1. Le designer construit le modèle** — un pptx normal, les balises dans le corps, les directives de page dans les notes :
289
-
290
- ```text
291
- Corps : Bienvenue sur {{product_name}}
292
- Taux d'adoption {{kpis[0].value}}
293
- Notes : {{#each scenarios}}
294
- ```
295
-
296
- **2. Le développeur prépare les données** — TOML est le format de données par défaut :
297
-
298
- ```toml
299
- # TOML — format de données par défaut
300
- product_name = "Espace de travail enseignant"
301
- show_compare = true
302
-
303
- [[kpis]]
304
- name = "Taux d'adoption"
305
- value = "29.7%"
306
-
307
- [[scenarios]]
308
- headline = "Pack de lecture du matin"
309
- detail = "Prêt automatiquement chaque dimanche"
310
- ```
311
-
312
- **3. Rendu :**
313
-
314
- ```ruby
315
- require "powertom"
316
-
317
- # Lecture du modèle, liaison des balises, duplication/suppression de pages,
318
- # remplacement des images
319
- result = PowerTom.render("templates/report.pptx", data: "data/report.toml")
320
- result.save("out/report.pptx")
321
- result.warnings.each { |w| warn w } # champs inutilisés, valeurs de repli…
322
- ```
323
-
324
- Ou passez directement un Hash quand les données viennent d'une base ou d'une API :
325
-
326
- ```ruby
327
- # Même appel avec des données en mémoire
328
- result = PowerTom.render("templates/report.pptx", data: {
329
- product_name: "Espace de travail enseignant",
330
- kpis: [{ name: "Taux d'adoption", value: "29.7%" }],
331
- scenarios: [{ headline: "Pack de lecture", detail: "Prêt chaque dimanche" }]
332
- })
333
- ```
334
-
335
- ## Syntaxe des modèles
336
-
337
- > Référence complète : [docs/usage.md](https://github.com/ixepet/powertom/blob/main/docs/usage.md) — données, balises, blocs de tableaux, formateurs, images et erreurs.
338
-
339
- | Syntaxe | Emplacement | Signification |
340
- | --- | --- | --- |
341
- | `{{title}}` | corps | Lier un champ |
342
- | `{{kpis[0].value}}` | corps | Chemin pointé + indice de tableau |
343
- | `{{classes[].name}}` | cellule de tableau | Boucle de lignes : duplique la ligne pour chaque élément |
344
- | `{{#rows groups}}` | ligne de tableau | Marqueur de boucle imbriquée : déclare le tableau parent (la ligne de marqueur n'est pas imprimée) |
345
- | `{{#rows groups[].items}}` | ligne de tableau | Marqueur de boucle imbriquée : déclare le tableau enfant |
346
- | `{{#grid rows: .. cols: ..}}` | en-tête de tableau | Colonnes dynamiques : duplique la colonne modèle pour chaque élément de `cols` |
347
- | `{{#rows groups}} ... {{/rows}}` | lignes de tableau | Bloc de lignes apparié : duplique toutes les lignes entre les marqueurs par élément (3 niveaux max) |
348
- | `{{#cols subjects}} ... {{/cols}}` | ligne de tableau | Bande de colonnes : une ou plusieurs colonnes modèles ; peut être déclarée dans l'en-tête ou dans un bloc de lignes |
349
- | `{{#if groups[].flag}} ... {{/if}}` | lignes de tableau | Bloc de lignes conditionnel à l'intérieur d'un bloc `#rows` |
350
- | `{{price:currency}}` | corps | Formateur : `¥1,234.56` |
351
- | `{{ratio:percent.1}}` | corps | Formateur : `29.7%` |
352
- | `{{day:date.year_month}}` | corps | Formateur : 2026年11月 |
353
- | `{{#each scenarios}}` | notes | Duplique la page pour chaque élément (tableau vide = groupe supprimé) |
354
- | `{{#if show_compare}}` | notes | Supprime la page si la valeur est fausse |
355
-
356
- - **Les runs fractionnés sont gérés** : si PowerPoint découpe `{{title}}` en plusieurs runs, le moteur fusionne le paragraphe et remplace correctement ; le résultat hérite du style du premier run.
357
- - **Lignes de tableau imbriquées** : `{{#rows groups}}` occupe une ligne entière (première cellule uniquement), et la ligne suivante est la ligne de contenu parent ; `{{#rows groups[].items}}` suivie de sa propre ligne de contenu ajoute un niveau. Deux niveaux maximum ; les balises parent et enfant utilisent le chemin complet (`{{groups[].name}}`, `{{groups[].items[].name}}`).
358
- - **Colonnes dynamiques** : placez `{{#grid rows: distribution cols: bands value: counts}}` dans la première cellule de l'en-tête. La deuxième cellule de l'en-tête est le modèle de colonne (`{{col.label}}`), et la ligne suivante est le modèle de ligne (`{{row.name}}` dans la première cellule, `{{cell}}` dans les colonnes de données). Exactement deux colonnes ; `value:` est facultatif (par défaut `row[col.key]`).
359
- - **Blocs de lignes (v0.2.x)** : `{{#rows groups}} ... {{/rows}}` occupent chacun une ligne entière ; tout ce qui se trouve entre eux est le modèle d'un enregistrement, dupliqué par élément. Jusqu'à 3 niveaux ; `{{row.name}}` désigne l'enregistrement courant. Une bande `{{#cols ...}}` peut être déclarée dans l'en-tête ou directement dans un bloc de lignes, et couvrir plusieurs colonnes modèles ; `value: scores,rates` associe un champ à chaque colonne modèle (un seul champ est partagé par toutes). Un bloc `{{#if ...}} ... {{/if}}` dans un bloc de lignes supprime toutes ses lignes pour les éléments dont la condition est fausse.
360
- - **Images** : nommez la forme ou son texte de remplacement `powertom:image:cover` et fournissez un chemin de fichier dans les données. Le remplacement remplit toujours la forme et recadre depuis le centre.
361
- - Une seule directive par page de notes, au maximum.
362
- - Les dates TOML s'écrivent sans guillemets (`report_date = 2026-01-20`), sont normalisées en `Date` Ruby et peuvent être formatées avec `{{report_date:date.cn}}`.
363
- - Guide complet pour les designers (en chinois) : [docs/模板制作规范.md](https://github.com/ixepet/powertom/blob/main/docs/模板制作规范.md).
364
-
365
- Formateurs intégrés : `currency`, `percent`, `number`, `date` (avec `.year_month` / `.cn` / `.short`).
366
- Ajoutez les vôtres :
367
-
368
- ```ruby
369
- # Formateur personnalisé — reçoit (value, arg) et renvoie le texte à écrire
370
- PowerTom.register_formatter("rmb") { |value, _arg| "#{value} RMB" }
371
- # Utilisation dans le modèle : {{amount:rmb}}
372
- ```
373
-
374
- ## Vérificateur de modèles
375
-
376
- La plupart des outils traitent la validation comme un effet de bord des logs. PowerTom en fait une étape de premier ordre : un modèle défectueux échoue en CI avant tout rendu.
377
-
378
- ```bash
379
- bundle exec rake powertom:check TEMPLATE=templates/report.pptx DATA=data/sample.toml
380
- ```
381
-
382
- Exemple de rapport (les messages sont actuellement en chinois) :
383
-
384
- ```text
385
- PowerTom 模板校验 — report.pptx
386
- [warning] 第 9 页 形状'(备注)' {{scenarios}} 数组 'scenarios' 为空(0 项):渲染时该组页面将被整组删除
387
- [error ] 第 2 页 形状'圆角矩形 4' {{workload}} 数据里没有字段 'workload'
388
- [error ] 第 5 页 形状'powertom:image:banner' {{banner}} 图片文件不存在:/tmp/a.png
389
- [warning] 数据字段 'unused_field' 未被模板使用
390
- ------------------------------------------------
391
- 2 个 error,2 个 warning(error 阻断渲染,修正后再调用 PowerTom.render)
392
- ```
393
-
394
- API programmatique :
395
-
396
- ```ruby
397
- # Vérifie sans rendre ; les erreurs sont rapportées, pas levées
398
- result = PowerTom.check("templates/report.pptx", data: "data/sample.toml")
399
- result.ok? # => false
400
- result.errors # chaque entrée porte slide_no / shape / label / message
401
- result.report # le rapport lisible ci-dessus
402
- result.exit_code # 0 ou 1 — utilisable en CI
403
- ```
404
-
405
- Contrôles : champs manquants (y compris chaque élément d'un tableau `#each`), formateurs non enregistrés, syntaxe des directives, plus d'une directive par page, champs d'image et fichiers absents, avertissements de débordement de texte, champs de données inutilisés, balises oubliées dans les notes.
406
-
407
- ## Modèle d'erreurs
408
-
409
- | Situation | Comportement |
410
- | --- | --- |
411
- | Champ manquant | `PowerTom::MissingDataError` par défaut, avec numéro de diapositive, nom de forme et balise ; avec `strict: false`, remplit par du vide et enregistre un avertissement |
412
- | Syntaxe de balise invalide | `PowerTom::TemplateSyntaxError` avant le rendu |
413
- | Fichier pptx invalide | `PowerTom::InvalidTemplateError` |
414
- | Chemin `#each` manquant | Lève toujours — aucune page n'est supprimée silencieusement |
415
-
416
- La sortie est **tout ou rien** : tous les contrôles ont lieu avant la moindre écriture sur disque.
417
-
418
- ## Limites (v0.1)
419
-
420
- | Limite | Précision |
421
- | --- | --- |
422
- | Tableaux : boucles de lignes, blocs appariés, imbrication et colonnes dynamiques ; graphiques non liés | `{{classes[].name}}` duplique une ligne ; `{{#rows ...}} ... {{/rows}}` duplique des enregistrements multi-lignes (3 niveaux) ; `{{#grid ...}}` / `{{#cols ...}}` dupliquent des colonnes ; les cellules fusionnées dans une boucle sont refusées |
423
- | Les notes ne sont pas rendues | Elles servent uniquement aux directives de page |
424
- | Les balises sur les masques/dispositions sont ignorées | Seules les formes des diapositives sont traitées |
425
- | Pas de PPT → PDF | Utilisez LibreOffice en mode headless |
426
- | `.pptx` uniquement | Pas de format binaire 97-2003 |
427
- | TOML ou Hash uniquement | Pas de chargeur YAML / JSON |
428
- | Recadrage d'image fixe | Toujours remplir la forme et recadrer depuis le centre |
429
- | Messages en chinois uniquement | La localisation est prévue ; le format du rapport est neutre |
430
-
431
- ## Développement
432
-
433
- ```bash
434
- bundle install
435
- bundle exec rspec
436
- ```
437
-
438
- Le modèle de référence utilisé par les tests de bout en bout (runs fractionnés, duplication, remplacement d'images, fidélité) n'est pas versionné, pour des raisons de taille et de propriété ; seule son empreinte structurelle `spec/fixtures/hai_mate/manifest.toml` l'est. Avec le modèle d'origine :
439
-
440
- ```bash
441
- bundle exec rake fixtures:generate TEMPLATE=/chemin/vers/modele.pptx OUT=spec/fixtures/hai_mate
442
- bundle exec rake fixtures:check OUT=spec/fixtures/hai_mate
443
- ```
444
-
445
- Sans `template.pptx`, les exemples qui en dépendent sont ignorés et la suite unitaire s'exécute normalement. Les tests de fidélité nécessitent LibreOffice (`soffice`).
446
-
447
- ## Licence
448
-
449
- MIT.
450
-
451
- ## Pourquoi PowerTom
452
-
453
- The Tom in PowerTom is a dedication — left unexplained, on purpose.
454
-
455
- Le Tom de PowerTom est une dédicace — laissée sans explication, à dessein.
@@ -38,6 +38,7 @@ module PowerTom
38
38
  outputs = @plan.map do |p|
39
39
  src = order[p[:source] - 1]
40
40
  raise Error, "页码越界:#{p[:source]}(共 #{order.size} 页)" unless src
41
+
41
42
  { src_slide: src, src_notes: notes_part_for(parts, p[:source]) }
42
43
  end
43
44
 
@@ -60,6 +61,7 @@ module PowerTom
60
61
  Zip::File.open(@template_path) do |zip|
61
62
  zip.entries.each do |entry|
62
63
  next if entry.directory?
64
+
63
65
  parts[entry.name] = entry.get_input_stream.read
64
66
  end
65
67
  end
@@ -78,6 +80,7 @@ module PowerTom
78
80
  rid_attr = sld_id.attributes.get_attribute("r:id")
79
81
  target = rid_target[rid_attr&.value]
80
82
  raise Error, "presentation.xml 的 sldId 引用了未知关系" unless target
83
+
81
84
  "ppt/#{target}"
82
85
  end
83
86
  end
@@ -85,10 +88,12 @@ module PowerTom
85
88
  def notes_part_for(parts, old_slide_no)
86
89
  rels_name = "ppt/slides/_rels/slide#{old_slide_no}.xml.rels"
87
90
  return nil unless parts[rels_name]
91
+
88
92
  rel = REXML::XPath.match(REXML::Document.new(parts[rels_name]), "//Relationship").find do |r|
89
93
  r.attributes["Type"].to_s.end_with?("/notesSlide")
90
94
  end
91
95
  return nil unless rel
96
+
92
97
  "ppt/notesSlides/#{File.basename(rel.attributes['Target'])}"
93
98
  end
94
99
 
@@ -108,6 +113,7 @@ module PowerTom
108
113
 
109
114
  notes_parts = outputs.each_with_index.filter_map do |out, i|
110
115
  next nil unless out[:src_notes]
116
+
111
117
  {
112
118
  "ppt/notesSlides/#{notes_name(i)}" => parts.fetch(out[:src_notes]),
113
119
  "ppt/notesSlides/_rels/#{notes_name(i)}.rels" =>
@@ -128,8 +134,8 @@ module PowerTom
128
134
  def allocate_slide_rids(parts, count)
129
135
  rels = REXML::Document.new(parts.fetch("ppt/_rels/presentation.xml.rels"))
130
136
  max = REXML::XPath.match(rels, "//Relationship")
131
- .filter_map { |r| r.attributes["Id"].to_s[/\ArId(\d+)\z/, 1] }
132
- .map(&:to_i).max || 0
137
+ .filter_map { |r| r.attributes["Id"].to_s[/\ArId(\d+)\z/, 1] }
138
+ .map(&:to_i).max || 0
133
139
  (1..count).map { |i| "rId#{max + i}" }
134
140
  end
135
141
 
@@ -139,6 +145,7 @@ module PowerTom
139
145
  unless xml.sub!(%r{<p:sldIdLst>.*?</p:sldIdLst>}m, "<p:sldIdLst>#{entries}</p:sldIdLst>")
140
146
  raise Error, "presentation.xml 中未找到 sldIdLst"
141
147
  end
148
+
142
149
  xml.force_encoding(Encoding::BINARY)
143
150
  end
144
151
 
@@ -146,9 +153,9 @@ module PowerTom
146
153
  xml = parts.fetch("ppt/_rels/presentation.xml.rels").dup.force_encoding(Encoding::UTF_8)
147
154
  xml = xml.gsub(%r{<Relationship\b[^>]*Target="slides/slide\d+\.xml"[^>]*/>}, "")
148
155
  new_rels = (0...count).map do |i|
149
- %(<Relationship Id="#{new_rids[i]}" ) +
150
- %(Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" ) +
151
- %(Target="slides/#{slide_name(i)}"/>)
156
+ "<Relationship Id=\"#{new_rids[i]}\" " \
157
+ "Type=\"http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide\" " \
158
+ "Target=\"slides/#{slide_name(i)}\"/>"
152
159
  end
153
160
  xml.sub!(%r{</Relationships>}, "#{new_rels.join}</Relationships>")
154
161
  xml.force_encoding(Encoding::BINARY)
@@ -204,6 +211,7 @@ module PowerTom
204
211
  parts.each do |name, data|
205
212
  next if name == "[Content_Types].xml"
206
213
  next if SKIP_PATTERNS.any? { |re| name.match?(re) }
214
+
207
215
  zos.put_next_entry(name)
208
216
  zos.write(data)
209
217
  end
@@ -23,6 +23,7 @@ module PowerTom
23
23
  shape.text_frame.paragraphs.each do |paragraph|
24
24
  runs = paragraph.runs
25
25
  next if runs.empty?
26
+
26
27
  contexts << {
27
28
  slide_no: slide_no,
28
29
  shape: shape.name,
@@ -39,9 +40,8 @@ module PowerTom
39
40
  # run 节点本身不动(保留 rPr 样式引用)。
40
41
  def write_paragraph_runs(paragraph, texts)
41
42
  runs = paragraph.runs
42
- if texts.size != runs.size
43
- raise Error, "写回失败:run 数量不匹配(现有 #{runs.size},传入 #{texts.size})"
44
- end
43
+ raise Error, "写回失败:run 数量不匹配(现有 #{runs.size},传入 #{texts.size})" if texts.size != runs.size
44
+
45
45
  runs.each_with_index { |run, i| run.text = texts[i] }
46
46
  end
47
47
 
@@ -63,8 +63,10 @@ module PowerTom
63
63
  prs.slides.each_with_index do |slide, i|
64
64
  walk_shapes(slide.shapes) do |shape|
65
65
  next unless shape.is_a?(Pptx::Picture)
66
+
66
67
  field = image_field(shape)
67
68
  next unless field
69
+
68
70
  contexts << { slide_no: i + 1, shape: shape.name, field: field,
69
71
  slide: slide, picture: shape }
70
72
  end
@@ -72,6 +74,45 @@ module PowerTom
72
74
  contexts
73
75
  end
74
76
 
77
+ # 图片比例与占位形状差异(超过阈值时返回比例信息,用于温和告警)
78
+ def image_aspect_mismatch(picture, image_path, threshold: 0.2)
79
+ image = Pptx::Image.from_file(image_path)
80
+ return nil if image.vector?
81
+
82
+ native = image.native_size
83
+ image_width = native[0].emu
84
+ image_height = native[1].emu
85
+ shape_width = picture.width&.emu
86
+ shape_height = picture.height&.emu
87
+ return nil unless image_width && image_height && shape_width && shape_height
88
+ return nil unless shape_width.positive? && shape_height.positive?
89
+
90
+ image_ratio = image_width.to_f / image_height
91
+ shape_ratio = shape_width.to_f / shape_height
92
+ diff = (image_ratio - shape_ratio).abs / shape_ratio
93
+ return nil if diff <= threshold
94
+
95
+ { image_ratio: image_ratio, shape_ratio: shape_ratio, diff: diff }
96
+ end
97
+
98
+ # 图表里的模板标签(v0 不绑定图表数据,只用于温和告警)
99
+ def chart_tags(prs)
100
+ list = []
101
+ prs.slides.each_with_index do |slide, i|
102
+ walk_shapes(slide.shapes) do |shape|
103
+ next unless shape.respond_to?(:chart?) && shape.chart?
104
+
105
+ tags = shape.chart.element.to_xml.to_s.scan(/\{\{[^{}]*\}\}/).uniq
106
+ next if tags.empty?
107
+
108
+ list << { slide_no: i + 1, shape: shape.name, tags: tags }
109
+ end
110
+ end
111
+ list
112
+ rescue StandardError
113
+ []
114
+ end
115
+
75
116
  # §5.3 图片替换:get_or_add 新 image part(按内容 sha1 去重,扩展名/content type
76
117
  # 由 ruby_pptx 按真实图片类型维护),repoint blip 引用,再按"填满形状、居中裁切"
77
118
  # 设置 srcRect。SVG 等矢量图不做裁切。
@@ -204,7 +245,7 @@ module PowerTom
204
245
  def strip_column_markers(table_element, row_index, first_col, last_col)
205
246
  cells = table_element.tr_list[row_index].tc_list
206
247
  (first_col..last_col).each do |c|
207
- strip_tags_in_cell(cells[c], /\{\{\s*(?:#cols\b[^{}]*|\/cols|#if\b[^{}]*|\/if)\s*\}\}/)
248
+ strip_tags_in_cell(cells[c], %r{\{\{\s*(?:#cols\b[^{}]*|/cols|#if\b[^{}]*|/if)\s*\}\}})
208
249
  end
209
250
  true
210
251
  end
@@ -219,11 +260,9 @@ module PowerTom
219
260
  trs = table_element.tr_list
220
261
  open_index = trs.index { |tr| tr.node == open_element.node }
221
262
  close_index = trs.index { |tr| tr.node == close_element.node }
222
- unless open_index && close_index && close_index > open_index
223
- raise PowerTom::Error, "行区块标记定位失败(区块可能已被展开)"
224
- end
263
+ raise PowerTom::Error, "行区块标记定位失败(区块可能已被展开)" unless open_index && close_index && close_index > open_index
225
264
 
226
- templates = (open_index + 1...close_index).map { |i| trs[i] }
265
+ templates = ((open_index + 1)...close_index).map { |i| trs[i] }
227
266
  groups = Array.new(count) do
228
267
  templates.map { |template| open_element.add_previous_sibling(table_element.import(template)) }
229
268
  end
@@ -236,11 +275,9 @@ module PowerTom
236
275
  trs = table_element.tr_list
237
276
  open_index = trs.index { |tr| tr.node == open_element.node }
238
277
  close_index = trs.index { |tr| tr.node == close_element.node }
239
- unless open_index && close_index && close_index > open_index
240
- raise PowerTom::Error, "条件区块标记定位失败(区块可能已被展开)"
241
- end
278
+ raise PowerTom::Error, "条件区块标记定位失败(区块可能已被展开)" unless open_index && close_index && close_index > open_index
242
279
 
243
- content = (open_index + 1...close_index).map { |i| trs[i] }
280
+ content = ((open_index + 1)...close_index).map { |i| trs[i] }
244
281
  content.each { |tr| table_element.remove(tr) } unless keep_content
245
282
  table_element.remove(open_element)
246
283
  table_element.remove(close_element)
@@ -348,6 +385,7 @@ module PowerTom
348
385
  def find_shape(prs, slide_no, name)
349
386
  slide = prs.slides[slide_no - 1]
350
387
  return nil unless slide
388
+
351
389
  found = nil
352
390
  walk_shapes(slide.shapes) { |shape| found ||= shape if shape.name == name }
353
391
  found
@@ -378,8 +416,10 @@ module PowerTom
378
416
  def image_field(shape)
379
417
  name = shape.name.to_s
380
418
  return name.delete_prefix(IMAGE_FIELD_PREFIX) if name.start_with?(IMAGE_FIELD_PREFIX)
419
+
381
420
  descr = alt_text_of(shape)
382
421
  return descr.delete_prefix(IMAGE_FIELD_PREFIX) if descr&.start_with?(IMAGE_FIELD_PREFIX)
422
+
383
423
  nil
384
424
  end
385
425
 
@@ -417,8 +457,10 @@ module PowerTom
417
457
  end
418
458
  walk_shapes(container.shapes) do |shape|
419
459
  next unless shape.text_frame?
460
+
420
461
  text = shape.text_frame.text.to_s
421
462
  next unless text.include?("{{")
463
+
422
464
  entries << { container: label, shape: shape.name, text: text }
423
465
  end
424
466
  end