b30918af41
Importer for ProPresenter's protobuf-encoded `Macros` document. Exposes each macro's UUID and name plus the collections that group them. - src/MacroLibrary.php: top-level wrapper indexed by UUID and name - src/Macro.php, src/MacroCollection.php: per-entry wrappers - src/MacrosFileReader.php: file -> MacroLibrary entry point - bin/parse-macros.php: CLI listing macros and collections - tests/MacrosFileReaderTest.php: 10 tests against reference sample - doc/api/macros.md: API reference, plus INDEX/keywords updates
152 lines
4.3 KiB
Markdown
152 lines
4.3 KiB
Markdown
# Macros Library API
|
|
|
|
> PHP module for reading the global ProPresenter `Macros` file (raw protobuf,
|
|
> no extension) and exposing each macro's name, UUID, and collection
|
|
> membership.
|
|
|
|
## Quick Reference
|
|
|
|
```php
|
|
use ProPresenter\Parser\MacrosFileReader;
|
|
|
|
$library = MacrosFileReader::read('/path/to/Macros');
|
|
|
|
foreach ($library->getMacros() as $macro) {
|
|
$macro->getName(); // "Gottesdienst START"
|
|
$macro->getUuid(); // "FA0602E4-EDA2-4457-BB62-68AA17184217"
|
|
|
|
foreach ($library->getCollectionsForMacro($macro) as $collection) {
|
|
$collection->getName(); // "Ablauf"
|
|
$collection->getUuid(); // "8D02FC57-83F8-4042-9B90-81C229728426"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## File Layout
|
|
|
|
The `Macros` file is the protobuf-serialised
|
|
[`MacrosDocument`](../../proto/macros.proto):
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `application_info` | message | ProPresenter version + flags that wrote the file |
|
|
| `macros` | repeated `Macro` | Definitions: UUID, name, color, actions, icon, startup flag |
|
|
| `macro_collections` | repeated `MacroCollection` | UUID, name, ordered list of `macro_id` references |
|
|
|
|
Macros and collections live at the document root. Membership is by UUID
|
|
reference — a macro may appear in zero, one, or multiple collections.
|
|
|
|
---
|
|
|
|
## Reading
|
|
|
|
```php
|
|
use ProPresenter\Parser\MacrosFileReader;
|
|
|
|
$library = MacrosFileReader::read('/Users/me/.../Macros');
|
|
```
|
|
|
|
Throws `InvalidArgumentException` for missing files and `RuntimeException` for
|
|
empty / unreadable files.
|
|
|
|
---
|
|
|
|
## MacroLibrary
|
|
|
|
Top-level wrapper around `Rv\Data\MacrosDocument`. Indexes macros and
|
|
collections for fast lookup.
|
|
|
|
```php
|
|
$library->getMacros(); // Macro[]
|
|
$library->getMacroByUuid('FA06...'); // ?Macro (case-insensitive)
|
|
$library->getMacroByName('Lied 1.Folie'); // ?Macro
|
|
|
|
$library->getCollections(); // MacroCollection[]
|
|
$library->getCollectionByUuid('8D02...'); // ?MacroCollection (case-insensitive)
|
|
$library->getCollectionByName('Ablauf'); // ?MacroCollection
|
|
|
|
// Cross-reference helpers
|
|
$library->getMacrosForCollection($collection); // Macro[] in declared order
|
|
$library->getCollectionsForMacro($macro); // MacroCollection[] (membership)
|
|
|
|
$library->getDocument(); // \Rv\Data\MacrosDocument (raw protobuf)
|
|
```
|
|
|
|
---
|
|
|
|
## Macro
|
|
|
|
```php
|
|
$macro->getUuid(); // "FA0602E4-..."
|
|
$macro->getName(); // "Gottesdienst START"
|
|
$macro->getColor(); // ['r'=>..,'g'=>..,'b'=>..,'a'=>..] | null
|
|
$macro->getTriggerOnStartup(); // bool
|
|
$macro->getActionCount(); // int — number of attached Action entries
|
|
$macro->getImageType(); // int — see Rv\Data\MacrosDocument\Macro\ImageType
|
|
$macro->getProto(); // \Rv\Data\MacrosDocument\Macro
|
|
```
|
|
|
|
Action payloads are not unwrapped by this library; reach for `getProto()` and
|
|
walk `getActions()` directly when needed.
|
|
|
|
---
|
|
|
|
## MacroCollection
|
|
|
|
```php
|
|
$collection->getUuid(); // "8D02FC57-..."
|
|
$collection->getName(); // "Ablauf"
|
|
$collection->getMacroUuids(); // string[] — referenced macro UUIDs in order
|
|
$collection->getProto(); // \Rv\Data\MacrosDocument\MacroCollection
|
|
```
|
|
|
|
Items use a protobuf `oneof ItemType`; only `macro_id` is currently defined.
|
|
Items without a populated reference are skipped.
|
|
|
|
---
|
|
|
|
## CLI Tool
|
|
|
|
```bash
|
|
php bin/parse-macros.php /path/to/Macros
|
|
```
|
|
|
|
Output:
|
|
|
|
```
|
|
Macros (24):
|
|
[1] Gottesdienst START :: FA0602E4-EDA2-4457-BB62-68AA17184217 (1 action) [in: Ablauf]
|
|
...
|
|
|
|
Collections (3):
|
|
[1] Ablauf :: 8D02FC57-83F8-4042-9B90-81C229728426 (12 macros)
|
|
1. Gottesdienst START :: FA0602E4-EDA2-4457-BB62-68AA17184217
|
|
...
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/MacroLibrary.php` | Document-level wrapper with lookup helpers |
|
|
| `src/Macro.php` | Single macro wrapper |
|
|
| `src/MacroCollection.php` | Collection wrapper |
|
|
| `src/MacrosFileReader.php` | Reads the `Macros` file |
|
|
| `bin/parse-macros.php` | CLI tool |
|
|
| `proto/macros.proto` | Protobuf schema |
|
|
| `generated/Rv/Data/MacrosDocument.php` | Generated message classes |
|
|
|
|
---
|
|
|
|
## Scope Notes
|
|
|
|
This module is read-only by design. Action editing, slide-side macro
|
|
references on `.pro` files (see `Slide::getMacroUuid()` /
|
|
`Slide::setMacro()`), and writing the `Macros` file back are not implemented
|
|
here. Add them by mirroring the `ProFileWriter` / `ProFileGenerator` pattern
|
|
when needed.
|