propresenter-php/src/KeyMappingsLibrary.php
Thorsten Bus 9e3e719806 feat(library): add readers + writers for all ProPresenter global libraries and theme bundles
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.
2026-05-03 21:40:09 +02:00

140 lines
3.4 KiB
PHP

<?php
declare(strict_types=1);
namespace ProPresenter\Parser;
use Rv\Data\ApplicationInfo;
use Rv\Data\KeyMappingsDocument;
use Rv\Data\KeyMappingsDocument\Mapping as MappingProto;
use Rv\Data\UUID;
class KeyMappingsLibrary
{
/** @var KeyMapping[] */
private array $mappings = [];
/** @var array<string, KeyMapping> */
private array $mappingsByUuid = [];
/** @var array<string, KeyMapping> */
private array $mappingsByName = [];
public function __construct(
private readonly KeyMappingsDocument $document,
) {
$this->rebuildIndex();
}
/**
* Return key mappings in document order.
*
* @return KeyMapping[]
*/
public function getMappings(): array
{
return $this->mappings;
}
public function count(): int
{
return count($this->mappings);
}
public function getMappingByUuid(string $uuid): ?KeyMapping
{
return $this->mappingsByUuid[strtoupper($uuid)] ?? null;
}
public function getMappingByName(string $name): ?KeyMapping
{
return $this->mappingsByName[$name] ?? null;
}
public function addMapping(string $name, string $uuid, string $target = ''): KeyMapping
{
$proto = new MappingProto();
$uuidProto = new UUID();
$uuidProto->setString($uuid);
$proto->setUuid($uuidProto);
$proto->setName($name);
$proto->setTarget($target);
$existing = iterator_to_array($this->document->getMappings());
$existing[] = $proto;
$this->document->setMappings($existing);
$this->rebuildIndex();
return $this->getMappingByUuid($uuid) ?? new KeyMapping($proto);
}
public function removeMapping(string $uuid): bool
{
$needle = strtoupper($uuid);
$kept = [];
$removed = false;
foreach ($this->document->getMappings() as $proto) {
$current = strtoupper($proto->getUuid()?->getString() ?? '');
if (!$removed && $current === $needle) {
$removed = true;
continue;
}
$kept[] = $proto;
}
if (!$removed) {
return false;
}
$this->document->setMappings($kept);
$this->rebuildIndex();
return true;
}
public function getApplicationInfo(): ?ApplicationInfo
{
return $this->document->getApplicationInfo();
}
public function setApplicationInfo(?ApplicationInfo $applicationInfo): self
{
if ($applicationInfo === null) {
$this->document->clearApplicationInfo();
return $this;
}
$this->document->setApplicationInfo($applicationInfo);
return $this;
}
public function getDocument(): KeyMappingsDocument
{
return $this->document;
}
private function rebuildIndex(): void
{
$this->mappings = [];
$this->mappingsByUuid = [];
$this->mappingsByName = [];
foreach ($this->document->getMappings() as $proto) {
$mapping = new KeyMapping($proto);
$this->mappings[] = $mapping;
$uuid = strtoupper($mapping->getUuid());
if ($uuid !== '') {
$this->mappingsByUuid[$uuid] = $mapping;
}
$name = $mapping->getName();
if ($name !== '') {
$this->mappingsByName[$name] ??= $mapping;
}
}
}
}