# 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.