9e3e719806
Add full IO support for every global ProPresenter library file plus theme folders, and extend the existing Labels/Macros readers with exporters and editable accessors so every supported document is now a round-trippable, mutable object. New library readers/writers (each: FileReader, FileWriter, Library wrapper, element wrapper where applicable, CLI tool, tests, doc/api/*.md): - Groups (ProGroupsDocument) + GroupDefinition - ClearGroups (ClearGroupsDocument) + ClearGroupDefinition - CCLI (CCLIDocument) - Messages (MessageDocument) + Message - Timers (TimersDocument + Clock) + Timer - Stage (Stage.Document) + StageLayout - Workspace (ProPresenterWorkspace) + Screen - Props (PropDocument) + Prop - TestPatterns (TestPatternDocument) - Calendar (new CalendarDocument) + CalendarEvent - KeyMappings (new KeyMappingsDocument) + KeyMapping - CommunicationDevices (JSON file) + CommunicationDevice - Theme bundles (Template.Document folder + Assets/) + ThemeBundle/Slide/Asset Extensions to existing modules: - LabelsFileWriter; Label and LabelLibrary gain setters, addLabel, removeLabel, setColor / setColorHex helpers - MacrosFileWriter; Macro/MacroCollection/MacroLibrary gain UUID, name, color, image_type, image_data, trigger_on_startup setters plus add/remove for macros and collections Two new minimal proto schemas were defined for documents that lacked upstream definitions: - proto/calendar.proto - CalendarDocument with Event entries, raw bytes for the action/macro sub-messages so the schema can evolve - proto/keyMappings.proto - KeyMappingsDocument with ApplicationInfo and a forward-looking Mapping message (sample only carries the info) The Theme file turned out to be a regular Rv\Data\Template\Document, so no new proto was required for theme content; ThemeBundle layers folder + Assets/ handling on top in the same spirit as PresentationBundle. GroupDefinition is intentionally distinct from the existing Group class (which wraps song-level CueGroup) to avoid breaking song APIs. Verified with the full PHPUnit suite: 370 tests, 9200 assertions, all green; LSP diagnostics clean across src/. The unmodified reference samples for Labels, Groups, ClearGroups, TestPatterns, Calendar and KeyMappings round-trip byte-for-byte; the others round-trip with the same byte length (PHP protobuf is not canonically deterministic but re-write-after-write stabilises). doc/INDEX.md, doc/keywords.md and AGENTS.md updated so every new module is discoverable from the top level.
116 lines
2.9 KiB
Markdown
116 lines
2.9 KiB
Markdown
# Calendar Library API
|
|
|
|
> PHP module for reading and writing the global ProPresenter `Calendar` file
|
|
> (raw protobuf, no extension) and preserving scheduled macro events.
|
|
|
|
## Quick Reference
|
|
|
|
```php
|
|
use ProPresenter\Parser\CalendarFileReader;
|
|
|
|
$library = CalendarFileReader::read('/path/to/Calendar');
|
|
|
|
foreach ($library->getEvents() as $event) {
|
|
$event->getName();
|
|
$event->getStartTimeSeconds();
|
|
$event->getActionData(); // raw bytes
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## File Layout
|
|
|
|
The `Calendar` file is the protobuf-serialised
|
|
[`CalendarDocument`](../../proto/calendar.proto):
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `events` | repeated `CalendarDocument.Event` | Scheduled events |
|
|
| `mode` | `uint32` | Opaque document mode/source flag |
|
|
|
|
Each event includes UUID, name, start/end timestamps, opaque `flags`, and two
|
|
raw bytes fields: `action_data` (field 8) and `macro_data` (field 9). Those
|
|
bytes are intentionally not decoded by this wrapper.
|
|
|
|
---
|
|
|
|
## Reading
|
|
|
|
```php
|
|
$library = CalendarFileReader::read('/Users/me/.../Calendar');
|
|
```
|
|
|
|
Throws `InvalidArgumentException` for missing files and `RuntimeException` for
|
|
empty / unreadable files.
|
|
|
|
---
|
|
|
|
## CalendarLibrary
|
|
|
|
```php
|
|
$library->getEvents(); // CalendarEvent[]
|
|
$library->count(); // int
|
|
$library->getEventByUuid($uuid); // ?CalendarEvent (case-insensitive)
|
|
$library->getEventByName($name); // ?CalendarEvent
|
|
$library->addEvent($name, $uuid); // CalendarEvent
|
|
$library->removeEvent($uuid); // bool
|
|
$library->getMode(); // int
|
|
$library->setMode(1); // void
|
|
$library->getDocument(); // \Rv\Data\CalendarDocument
|
|
```
|
|
|
|
---
|
|
|
|
## CalendarEvent
|
|
|
|
```php
|
|
$event->getUuid();
|
|
$event->setUuid($uuid);
|
|
$event->getName();
|
|
$event->setName($name);
|
|
$event->getStartTime();
|
|
$event->setStartTime($timestamp);
|
|
$event->getStartTimeSeconds();
|
|
$event->setStartTimeSeconds($seconds);
|
|
$event->getEndTime();
|
|
$event->getEndTimeSeconds();
|
|
$event->getFlags();
|
|
$event->setFlags($bytes);
|
|
$event->getActionData(); // raw protobuf bytes
|
|
$event->setActionData($bytes);
|
|
$event->getMacroData(); // raw protobuf bytes
|
|
$event->setMacroData($bytes);
|
|
$event->getProto();
|
|
```
|
|
|
|
---
|
|
|
|
## CLI Tool
|
|
|
|
```bash
|
|
php bin/parse-calendar.php /path/to/Calendar
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/CalendarLibrary.php` | Document wrapper with UUID / name indexes |
|
|
| `src/CalendarEvent.php` | Single event wrapper |
|
|
| `src/CalendarFileReader.php` | Reads the `Calendar` file |
|
|
| `src/CalendarFileWriter.php` | Writes the `Calendar` file |
|
|
| `bin/parse-calendar.php` | CLI summary tool |
|
|
| `proto/calendar.proto` | Protobuf schema |
|
|
| `generated/Rv/Data/CalendarDocument.php` | Generated document class |
|
|
|
|
---
|
|
|
|
## Scope Notes
|
|
|
|
`action_data` and `macro_data` are raw protobuf byte strings. They are exposed
|
|
directly for byte-preserving edits and round trips; semantic decoding belongs in
|
|
a future schema-specific module.
|