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 +4 -4
- data/CHANGELOG.md +81 -0
- data/README.md +15 -240
- data/lib/powertom/adapter/page_surgery.rb +13 -5
- data/lib/powertom/adapter/ruby_pptx_adapter.rb +54 -12
- data/lib/powertom/binder.rb +10 -14
- data/lib/powertom/formatter.rb +5 -3
- data/lib/powertom/path_resolver.rb +4 -5
- data/lib/powertom/render.rb +38 -12
- data/lib/powertom/run_merge.rb +1 -0
- data/lib/powertom/scanner.rb +20 -15
- data/lib/powertom/table_loop.rb +36 -58
- data/lib/powertom/validator.rb +46 -23
- data/lib/powertom/version.rb +2 -2
- data/lib/powertom.rb +35 -13
- metadata +8 -7
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 4cc6fd7b427f0d9d1a6ec2104fa51c807251cca9f438fd65e968b5eb1a8433f4
|
|
4
|
+
data.tar.gz: '087886b3c039a9b57dd9ba0f31e94cd148a217c9fe94c5f4be77a87542085927'
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
|
138
|
-
- Full usage reference
|
|
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
|
-
#
|
|
144
|
+
# Custom formatter — receives (value, arg) and returns the text to write
|
|
145
145
|
PowerTom.register_formatter("rmb") { |value, _arg| "#{value} RMB" }
|
|
146
|
-
#
|
|
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
|
-
#
|
|
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 #
|
|
176
|
-
result.report #
|
|
177
|
-
result.exit_code # 0
|
|
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
|
-
|
|
132
|
-
|
|
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
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
-
|
|
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],
|
|
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
|