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.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: feb18b4055ad1229aba28ef398e78d829e0ef427df7b1fb3462dd01a23225058
4
+ data.tar.gz: da8dfe60234ef32aa8f237d33d0539f14006d220e8f58c2c427d84a05e3e50af
5
+ SHA512:
6
+ metadata.gz: aac6b281fe867b01794e63be088a67a07f34c26f1848313491258cdf41e12315f3740f78cbffb8a8ce2870ff9218b441fab08a51c1419725df7f4dd6940ff726
7
+ data.tar.gz: 130010e8e837f4aeb6168b3ccd26378c6cce4611ec128910cd49ad9bf4084b13daa8f8161f81f1316625990f3ed0401ea689c443012171c6235e502a4f122104
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 PowerTom contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,447 @@
1
+ # PowerTom — PowerPoint template engine for Ruby
2
+
3
+ > Designers keep the template in PowerPoint. Engineers pass a Ruby Hash (or a TOML file) and get a finished deck.
4
+ > Layout, fonts, colours, masters and theme stay under the designer's control; the code only scans tags, binds data and clones slides.
5
+
6
+ <sub>Not affiliated with Microsoft or TomTom.</sub>
7
+
8
+ ---
9
+
10
+ ## In 30 seconds
11
+
12
+ ```text
13
+ Designer Engineer
14
+ ┌──────────────────────────┐ ┌──────────────────────────┐
15
+ │ A plain pptx in │ │ report.toml │
16
+ │ PowerPoint: │ │ title = "Final exams" │
17
+ │ body: {{title}} │ ─────────▶ │ [[classes]] │
18
+ │ notes: {{#each classes}}│ │ name = "Grade 8 (3)" │
19
+ │ picture named │ │ avg = 82.4 │
20
+ │ powertom:image:cover │ │ │
21
+ └──────────────────────────┘ └──────────────────────────┘
22
+ │ │
23
+ └──────────────┬───────────────────┘
24
+ ▼
25
+ PowerTom.render("template.pptx", data: "report.toml")
26
+ ▼
27
+ Finished deck: tags bound, pages cloned/removed,
28
+ pictures replaced — opens in PowerPoint without repair.
29
+ ```
30
+
31
+ ## Why another one
32
+
33
+ Ruby has two ways to produce PPTX today, and neither fits "reuse the design asset":
34
+
35
+ | Approach | Examples | Problem |
36
+ | --- | --- | --- |
37
+ | Code-driven generation | `powerpoint`, `ruby_slides` | Layout is hard-coded; changing one font size needs a developer |
38
+ | Low-level OOXML library | `ruby_pptx`, `rbpptx` | XML building blocks, no template layer; designers cannot use it directly |
39
+
40
+ PowerTom fills the middle layer: a **template engine on top of [`ruby_pptx`](https://rubygems.org/gems/ruby_pptx)**, without parsing OOXML itself. Think Carbone / Docxtemplater for Ruby — no Node dependency, no external service, one line in your Gemfile.
41
+
42
+ ## Installation
43
+
44
+ ```ruby
45
+ # Gemfile
46
+ gem "powertom"
47
+
48
+ # Chemin local tant que le gem n'est pas publié sur RubyGems
49
+ # gem "powertom", path: "/chemin/vers/PowerTom"
50
+ ```
51
+
52
+ Requires Ruby >= 3.3; depends on `ruby_pptx ~> 0.2.0` (read/write) and `tomlrb ~> 3.0` (data files).
53
+
54
+ ## Quick start
55
+
56
+ **1. The designer builds a template** — just a normal pptx, tags in the body, page directives in the notes:
57
+
58
+ ```text
59
+ Body: Welcome to {{product_name}}
60
+ Adoption rate {{kpis[0].value}}
61
+ Notes: {{#each scenarios}}
62
+ ```
63
+
64
+ **2. The engineer prepares the data** — TOML is the default data format:
65
+
66
+ ```toml
67
+ # TOML — format de données par défaut
68
+ product_name = "Student workspace"
69
+ show_compare = true
70
+
71
+ [[kpis]]
72
+ name = "Adoption rate"
73
+ value = "29.7%"
74
+
75
+ [[scenarios]]
76
+ headline = "Morning reading pack"
77
+ detail = "Ready automatically every Sunday"
78
+ ```
79
+
80
+ **3. Render:**
81
+
82
+ ```ruby
83
+ require "powertom"
84
+
85
+ # Lecture du modèle, liaison des balises, duplication/suppression de pages,
86
+ # remplacement des images
87
+ result = PowerTom.render("templates/report.pptx", data: "data/report.toml")
88
+ result.save("out/report.pptx")
89
+ result.warnings.each { |w| warn w } # champs inutilisés, valeurs de repli…
90
+ ```
91
+
92
+ Or pass a Hash directly when the data comes from a database or an API:
93
+
94
+ ```ruby
95
+ # Même appel avec des données en mémoire
96
+ result = PowerTom.render("templates/report.pptx", data: {
97
+ product_name: "Student workspace",
98
+ kpis: [{ name: "Adoption rate", value: "29.7%" }],
99
+ scenarios: [{ headline: "Morning reading pack", detail: "Ready every Sunday" }]
100
+ })
101
+ ```
102
+
103
+ ## Template syntax
104
+
105
+ | Syntax | Where | Meaning |
106
+ | --- | --- | --- |
107
+ | `{{title}}` | body | Bind a field |
108
+ | `{{kpis[0].value}}` | body | Dot path + array index |
109
+ | `{{classes[].name}}` | table cell | Table row loop: clones the row per array item |
110
+ | `{{#rows groups}}` | table row | Nested loop marker: declares the parent array (marker row itself is not printed) |
111
+ | `{{#rows groups[].items}}` | table row | Nested loop marker: declares the child array |
112
+ | `{{#grid rows: .. cols: ..}}` | table header | Dynamic columns: clones the template column per `cols` item |
113
+ | `{{#rows groups}} ... {{/rows}}` | table rows | Paired row block: clones all rows between the markers per item (up to 3 levels) |
114
+ | `{{#cols subjects}} ... {{/cols}}` | table row | Column band: one or more template columns; may be declared in the header or inside a row block |
115
+ | `{{#if groups[].flag}} ... {{/if}}` | table rows | Conditional row block inside a `#rows` block |
116
+ | `{{price:currency}}` | body | Formatter: ¥1,234.56 |
117
+ | `{{ratio:percent.1}}` | body | Formatter: 29.7% |
118
+ | `{{day:date.year_month}}` | body | Formatter: 2026年11月 |
119
+ | `{{#each scenarios}}` | notes | Clone the page per array item (empty array removes the group) |
120
+ | `{{#if show_compare}}` | notes | Remove the page when falsy |
121
+
122
+ - **Split runs are handled**: if PowerPoint stores `{{title}}` as several runs, the engine merges the paragraph and replaces correctly; the result inherits the first run's style.
123
+ - **Nested table rows**: `{{#rows groups}}` occupies a whole row (first cell only), and the next row is the parent content row; `{{#rows groups[].items}}` followed by its own content row adds one nesting level. Two levels maximum; parent and child tags use full paths (`{{groups[].name}}`, `{{groups[].items[].name}}`).
124
+ - **Dynamic columns**: put `{{#grid rows: distribution cols: bands value: counts}}` in the header row's first cell. The header row's second cell is the column template (`{{col.label}}`), and the next row is the row template (`{{row.name}}` in the first cell, `{{cell}}` in the data columns). Exactly two columns; `value:` is optional (defaults to `row[col.key]`).
125
+ - **Row blocks (v0.2.x)**: `{{#rows groups}} ... {{/rows}}` each occupy a whole row; everything between them is one record template and is cloned per item. Up to 3 nested levels; `{{row.name}}` refers to the current record. A `{{#cols ...}}` band may be declared in the header or directly inside a row block, and may span several template columns; `value: scores,rates` maps one field to each template column (a single field is shared by all). A `{{#if ...}} ... {{/if}}` block inside a row block removes all its rows for items where the condition is falsy.
126
+ - **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.
127
+ - One directive per notes page, maximum.
128
+ - TOML dates are written unquoted (`report_date = 2026-01-20`), normalised to Ruby `Date`, and can be formatted with `{{report_date:date.cn}}`.
129
+ - Full guide for designers (Chinese): [docs/模板制作规范.md](docs/模板制作规范.md).
130
+
131
+ Built-in formatters: `currency`, `percent`, `number`, `date` (with `.year_month` / `.cn` / `.short`).
132
+ Register your own:
133
+
134
+ ```ruby
135
+ # Formateur personnalisé — reçoit (value, arg) et renvoie le texte à écrire
136
+ PowerTom.register_formatter("rmb") { |value, _arg| "#{value} RMB" }
137
+ # Utilisation dans le modèle : {{amount:rmb}}
138
+ ```
139
+
140
+ ## Template checker
141
+
142
+ Most tools treat validation as a side effect of logging. PowerTom makes it a first-class step: bad templates fail in CI before anything is rendered.
143
+
144
+ ```bash
145
+ bundle exec rake powertom:check TEMPLATE=templates/report.pptx DATA=data/sample.toml
146
+ ```
147
+
148
+ Example report (messages are currently emitted in Chinese):
149
+
150
+ ```text
151
+ PowerTom 模板校验 — report.pptx
152
+ [warning] 第 9 页 形状'(备注)' {{scenarios}} 数组 'scenarios' 为空(0 项):渲染时该组页面将被整组删除
153
+ [error ] 第 2 页 形状'圆角矩形 4' {{workload}} 数据里没有字段 'workload'
154
+ [error ] 第 5 页 形状'powertom:image:banner' {{banner}} 图片文件不存在:/tmp/a.png
155
+ [warning] 数据字段 'unused_field' 未被模板使用
156
+ ------------------------------------------------
157
+ 2 个 error,2 个 warning(error 阻断渲染,修正后再调用 PowerTom.render)
158
+ ```
159
+
160
+ Programmatic API:
161
+
162
+ ```ruby
163
+ # Vérifie sans rendre ; les erreurs sont rapportées, pas levées
164
+ result = PowerTom.check("templates/report.pptx", data: "data/sample.toml")
165
+ result.ok? # => false
166
+ result.errors # chaque entrée porte slide_no / shape / label / message
167
+ result.report # le rapport lisible ci-dessus
168
+ result.exit_code # 0 ou 1 — utilisable en CI
169
+ ```
170
+
171
+ 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.
172
+
173
+ ## Error model
174
+
175
+ | Situation | Behaviour |
176
+ | --- | --- |
177
+ | Missing field | `PowerTom::MissingDataError` by default, with slide number, shape name and tag; with `strict: false`, fills in blank and records a warning |
178
+ | Invalid tag syntax | `PowerTom::TemplateSyntaxError` before rendering |
179
+ | Not a valid pptx | `PowerTom::InvalidTemplateError` |
180
+ | Missing `#each` path | Always raises — pages are never silently dropped |
181
+
182
+ Output is **all or nothing**: every check runs before anything is written to disk.
183
+
184
+ ## Limitations (v0.1)
185
+
186
+ | Limitation | Notes |
187
+ | --- | --- |
188
+ | 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 |
189
+ | Notes are not rendered | Notes are only read for page directives |
190
+ | Tags on masters/layouts are ignored | Only shapes on slides are processed |
191
+ | No PPT → PDF | Use LibreOffice headless |
192
+ | `.pptx` only | No legacy 97-2003 binary format |
193
+ | TOML or Hash only | No YAML / JSON loader |
194
+ | Fixed picture cropping | Always fill the shape and crop from the centre |
195
+ | Messages are Chinese-only | Localisation is planned; the report format is language-neutral |
196
+
197
+ ## Development
198
+
199
+ ```bash
200
+ bundle install
201
+ bundle exec rspec
202
+ ```
203
+
204
+ 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:
205
+
206
+ ```bash
207
+ bundle exec rake fixtures:generate TEMPLATE=/path/to/template.pptx OUT=spec/fixtures/hai_mate
208
+ bundle exec rake fixtures:check OUT=spec/fixtures/hai_mate
209
+ ```
210
+
211
+ Without `template.pptx`, fixture-dependent examples are skipped and the unit suite still runs. Fidelity tests need LibreOffice (`soffice`).
212
+
213
+ ## License
214
+
215
+ MIT.
216
+
217
+ ## Why PowerTom
218
+
219
+ The Tom in PowerTom is a dedication — left unexplained, on purpose.
220
+
221
+ Le Tom de PowerTom est une dédicace — laissée sans explication, à dessein.
222
+
223
+ ---
224
+ ---
225
+
226
+ # PowerTom — moteur de modèles PowerPoint pour Ruby
227
+
228
+ > 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.
229
+ > 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.
230
+
231
+ <sub>Non affilié à Microsoft ni à TomTom.</sub>
232
+
233
+ ---
234
+
235
+ ## En 30 secondes
236
+
237
+ ```text
238
+ Designer Développeur
239
+ ┌──────────────────────────┐ ┌──────────────────────────┐
240
+ │ Un pptx ordinaire dans │ │ report.toml │
241
+ │ PowerPoint : │ │ title = "Examens" │
242
+ │ corps : {{title}} │ ─────────▶ │ [[classes]] │
243
+ │ notes : {{#each classes}}│ │ name = "8e (3)" │
244
+ │ image nommée │ │ avg = 82.4 │
245
+ │ powertom:image:cover │ │ │
246
+ └──────────────────────────┘ └──────────────────────────┘
247
+ │ │
248
+ └──────────────┬───────────────────┘
249
+ ▼
250
+ PowerTom.render("template.pptx", data: "report.toml")
251
+ ▼
252
+ Présentation finale : balises liées, pages dupliquées
253
+ ou supprimées, images remplacées — s'ouvre dans
254
+ PowerPoint sans message de réparation.
255
+ ```
256
+
257
+ ## Pourquoi un nouveau moteur
258
+
259
+ Ruby propose aujourd'hui deux façons de produire des PPTX, et aucune ne convient à la réutilisation d'un actif de design :
260
+
261
+ | Approche | Exemples | Problème |
262
+ | --- | --- | --- |
263
+ | 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 |
264
+ | Bibliothèque OOXML bas niveau | `ruby_pptx`, `rbpptx` | Des briques XML, pas de couche modèle ; inutilisable par un designer |
265
+
266
+ 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.
267
+
268
+ ## Installation
269
+
270
+ ```ruby
271
+ # Gemfile
272
+ gem "powertom"
273
+
274
+ # Chemin local tant que le gem n'est pas publié sur RubyGems
275
+ # gem "powertom", path: "/chemin/vers/PowerTom"
276
+ ```
277
+
278
+ Nécessite Ruby >= 3.3 ; dépend de `ruby_pptx ~> 0.2.0` (lecture/écriture) et de `tomlrb ~> 3.0` (fichiers de données).
279
+
280
+ ## Démarrage rapide
281
+
282
+ **1. Le designer construit le modèle** — un pptx normal, les balises dans le corps, les directives de page dans les notes :
283
+
284
+ ```text
285
+ Corps : Bienvenue sur {{product_name}}
286
+ Taux d'adoption {{kpis[0].value}}
287
+ Notes : {{#each scenarios}}
288
+ ```
289
+
290
+ **2. Le développeur prépare les données** — TOML est le format de données par défaut :
291
+
292
+ ```toml
293
+ # TOML — format de données par défaut
294
+ product_name = "Espace de travail enseignant"
295
+ show_compare = true
296
+
297
+ [[kpis]]
298
+ name = "Taux d'adoption"
299
+ value = "29.7%"
300
+
301
+ [[scenarios]]
302
+ headline = "Pack de lecture du matin"
303
+ detail = "Prêt automatiquement chaque dimanche"
304
+ ```
305
+
306
+ **3. Rendu :**
307
+
308
+ ```ruby
309
+ require "powertom"
310
+
311
+ # Lecture du modèle, liaison des balises, duplication/suppression de pages,
312
+ # remplacement des images
313
+ result = PowerTom.render("templates/report.pptx", data: "data/report.toml")
314
+ result.save("out/report.pptx")
315
+ result.warnings.each { |w| warn w } # champs inutilisés, valeurs de repli…
316
+ ```
317
+
318
+ Ou passez directement un Hash quand les données viennent d'une base ou d'une API :
319
+
320
+ ```ruby
321
+ # Même appel avec des données en mémoire
322
+ result = PowerTom.render("templates/report.pptx", data: {
323
+ product_name: "Espace de travail enseignant",
324
+ kpis: [{ name: "Taux d'adoption", value: "29.7%" }],
325
+ scenarios: [{ headline: "Pack de lecture", detail: "Prêt chaque dimanche" }]
326
+ })
327
+ ```
328
+
329
+ ## Syntaxe des modèles
330
+
331
+ | Syntaxe | Emplacement | Signification |
332
+ | --- | --- | --- |
333
+ | `{{title}}` | corps | Lier un champ |
334
+ | `{{kpis[0].value}}` | corps | Chemin pointé + indice de tableau |
335
+ | `{{classes[].name}}` | cellule de tableau | Boucle de lignes : duplique la ligne pour chaque élément |
336
+ | `{{#rows groups}}` | ligne de tableau | Marqueur de boucle imbriquée : déclare le tableau parent (la ligne de marqueur n'est pas imprimée) |
337
+ | `{{#rows groups[].items}}` | ligne de tableau | Marqueur de boucle imbriquée : déclare le tableau enfant |
338
+ | `{{#grid rows: .. cols: ..}}` | en-tête de tableau | Colonnes dynamiques : duplique la colonne modèle pour chaque élément de `cols` |
339
+ | `{{#rows groups}} ... {{/rows}}` | lignes de tableau | Bloc de lignes apparié : duplique toutes les lignes entre les marqueurs par élément (3 niveaux max) |
340
+ | `{{#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 |
341
+ | `{{#if groups[].flag}} ... {{/if}}` | lignes de tableau | Bloc de lignes conditionnel à l'intérieur d'un bloc `#rows` |
342
+ | `{{price:currency}}` | corps | Formateur : `¥1,234.56` |
343
+ | `{{ratio:percent.1}}` | corps | Formateur : `29.7%` |
344
+ | `{{day:date.year_month}}` | corps | Formateur : 2026年11月 |
345
+ | `{{#each scenarios}}` | notes | Duplique la page pour chaque élément (tableau vide = groupe supprimé) |
346
+ | `{{#if show_compare}}` | notes | Supprime la page si la valeur est fausse |
347
+
348
+ - **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.
349
+ - **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}}`).
350
+ - **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]`).
351
+ - **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.
352
+ - **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.
353
+ - Une seule directive par page de notes, au maximum.
354
+ - 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}}`.
355
+ - Guide complet pour les designers (en chinois) : [docs/模板制作规范.md](docs/模板制作规范.md).
356
+
357
+ Formateurs intégrés : `currency`, `percent`, `number`, `date` (avec `.year_month` / `.cn` / `.short`).
358
+ Ajoutez les vôtres :
359
+
360
+ ```ruby
361
+ # Formateur personnalisé — reçoit (value, arg) et renvoie le texte à écrire
362
+ PowerTom.register_formatter("rmb") { |value, _arg| "#{value} RMB" }
363
+ # Utilisation dans le modèle : {{amount:rmb}}
364
+ ```
365
+
366
+ ## Vérificateur de modèles
367
+
368
+ 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.
369
+
370
+ ```bash
371
+ bundle exec rake powertom:check TEMPLATE=templates/report.pptx DATA=data/sample.toml
372
+ ```
373
+
374
+ Exemple de rapport (les messages sont actuellement en chinois) :
375
+
376
+ ```text
377
+ PowerTom 模板校验 — report.pptx
378
+ [warning] 第 9 页 形状'(备注)' {{scenarios}} 数组 'scenarios' 为空(0 项):渲染时该组页面将被整组删除
379
+ [error ] 第 2 页 形状'圆角矩形 4' {{workload}} 数据里没有字段 'workload'
380
+ [error ] 第 5 页 形状'powertom:image:banner' {{banner}} 图片文件不存在:/tmp/a.png
381
+ [warning] 数据字段 'unused_field' 未被模板使用
382
+ ------------------------------------------------
383
+ 2 个 error,2 个 warning(error 阻断渲染,修正后再调用 PowerTom.render)
384
+ ```
385
+
386
+ API programmatique :
387
+
388
+ ```ruby
389
+ # Vérifie sans rendre ; les erreurs sont rapportées, pas levées
390
+ result = PowerTom.check("templates/report.pptx", data: "data/sample.toml")
391
+ result.ok? # => false
392
+ result.errors # chaque entrée porte slide_no / shape / label / message
393
+ result.report # le rapport lisible ci-dessus
394
+ result.exit_code # 0 ou 1 — utilisable en CI
395
+ ```
396
+
397
+ 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.
398
+
399
+ ## Modèle d'erreurs
400
+
401
+ | Situation | Comportement |
402
+ | --- | --- |
403
+ | 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 |
404
+ | Syntaxe de balise invalide | `PowerTom::TemplateSyntaxError` avant le rendu |
405
+ | Fichier pptx invalide | `PowerTom::InvalidTemplateError` |
406
+ | Chemin `#each` manquant | Lève toujours — aucune page n'est supprimée silencieusement |
407
+
408
+ La sortie est **tout ou rien** : tous les contrôles ont lieu avant la moindre écriture sur disque.
409
+
410
+ ## Limites (v0.1)
411
+
412
+ | Limite | Précision |
413
+ | --- | --- |
414
+ | 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 |
415
+ | Les notes ne sont pas rendues | Elles servent uniquement aux directives de page |
416
+ | Les balises sur les masques/dispositions sont ignorées | Seules les formes des diapositives sont traitées |
417
+ | Pas de PPT → PDF | Utilisez LibreOffice en mode headless |
418
+ | `.pptx` uniquement | Pas de format binaire 97-2003 |
419
+ | TOML ou Hash uniquement | Pas de chargeur YAML / JSON |
420
+ | Recadrage d'image fixe | Toujours remplir la forme et recadrer depuis le centre |
421
+ | Messages en chinois uniquement | La localisation est prévue ; le format du rapport est neutre |
422
+
423
+ ## Développement
424
+
425
+ ```bash
426
+ bundle install
427
+ bundle exec rspec
428
+ ```
429
+
430
+ 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 :
431
+
432
+ ```bash
433
+ bundle exec rake fixtures:generate TEMPLATE=/chemin/vers/modele.pptx OUT=spec/fixtures/hai_mate
434
+ bundle exec rake fixtures:check OUT=spec/fixtures/hai_mate
435
+ ```
436
+
437
+ 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`).
438
+
439
+ ## Licence
440
+
441
+ MIT.
442
+
443
+ ## Pourquoi PowerTom
444
+
445
+ The Tom in PowerTom is a dedication — left unexplained, on purpose.
446
+
447
+ Le Tom de PowerTom est une dédicace — laissée sans explication, à dessein.