# playground

Ein kleiner PDA — Kontakte, Taschenrechner, Notizen, Dateiexplorer — als
Übungsprojekt für die Bau- und Projektstruktur, die dahintersteht.

Aufgeteilt nach [P1204R0 „Canonical Project
Structure"](https://wg21.link/p1204r0) in **zwei eigenständige Projekte**:

```
playground/                    Superprojekt, kein eigener Quellcode
├── libpda/                    die Bibliothek        -> libpda.a
│   ├── libpda/
│   │   ├── textfile.h/.c        C: Datei-I/O und Feld-Escaping
│   │   ├── calculator.hpp/.cpp   Ausdrucksparser (Recursive Descent)
│   │   ├── contact.hpp/.cpp      Kontaktverwaltung mit Persistenz
│   │   ├── editor.hpp/.cpp       zeilenorientierter Textpuffer
│   │   ├── explorer.hpp/.cpp     Verzeichnisnavigation
│   │   ├── *.test.c/.cpp         Unit-Tests, direkt neben dem Modul
│   │   └── details/              Implementation Details
│   └── tests/basics/          Integrationstest, nur öffentliche API
├── pda/                       die Anwendung         -> bin/pda
│   ├── pda/shell.hpp/.cpp       Kommandoverarbeitung, ohne Ein-/Ausgabe
│   ├── pda/main.cpp             REPL und Stapelbetrieb
│   └── tests/session/         Integrationstest einer ganzen Sitzung
├── examples/consumer/         fremdes Projekt, benutzt find_package(pda)
├── cmake/                     ProjectDefaults, Warnings, Sanitizers, Config-Vorlage
├── third_party/               vendortes Unity + doctest, nie editieren
├── tools/check-install.sh     prüft die Export-Kette Ende-zu-Ende
└── docs/                      CMAKE.md, CONVENTIONS.md, ADRs
```

**Warum getrennte Projekte:** P1204R0 verlangt es, und der praktische Grund
ist, dass die Bibliothek ohne die Anwendung baubar, testbar und installierbar
sein muss — sonst ist sie keine Bibliothek, sondern ein Unterverzeichnis.

## Bauen

```sh
cmake --preset debug
cmake --build --preset debug
ctest --preset debug
./build/debug/bin/pda
```

Presets: `debug`, `release`, `asan-ubsan`, `apple-clang`, `homebrew-gcc`,
`linux-gcc`.

## Benutzen

Interaktiv:

```
$ pda
pda 0.1.0 -- 'help' zeigt die Kommandos, 'quit' beendet.
playground> contact add "Anna Schmidt" 0151 anna@example.org meine Schwester
'Anna Schmidt' angelegt (1 Kontakte)
playground> calc (2+3)*4 - 10/2
15
playground> note add Anna anrufen
Zeile 1 angelegt
playground> contact save kontakte.tsv
1 Kontakte nach kontakte.tsv geschrieben
```

Im Stapelbetrieb — ein Kommando, dann Ende:

```sh
pda calc "2^10"          # 1024
pda contact list
```

Der Exit-Code ist 1, wenn das Kommando scheitert. Fehler gehen nach stderr.

## Als Bibliothek benutzen

```sh
cmake -S libpda -B build/lib -DCMAKE_INSTALL_PREFIX=/pfad
cmake --build build/lib && cmake --install build/lib
```

Dann im eigenen Projekt:

```cmake
find_package(pda 0.1 REQUIRED)
target_link_libraries(mein_programm PRIVATE pda::pda)
```

```cpp
#include <libpda/calculator.hpp>

const auto value = pda::evaluate("(1 + 2) * 3 ^ 2");
if (value) std::println("{}", *value);
```

Ein vollständiges Beispiel steht in [examples/consumer/](examples/consumer/);
`tools/check-install.sh` baut es gegen eine frisch installierte Bibliothek und
ist damit der Test für den Export-Mechanismus.

## Dokumentation

- **[docs/CMAKE.md](docs/CMAKE.md)** — CMake an diesem Projekt erklärt:
  Target-Modell, `PUBLIC`/`PRIVATE`/`INTERFACE`, Generator-Ausdrücke,
  install/export, Symbolsichtbarkeit, „wann mache ich was?"
- [docs/CONVENTIONS.md](docs/CONVENTIONS.md) — Stil- und Strukturregeln
- [docs/adr/](docs/adr/) — Architekturentscheidungen mit Begründung

## Stand

71 Tests (Unity für C, doctest für C++, zwei Integrationstreiber ohne
Framework). Grün unter Homebrew-clang 22, Apple clang und GCC 16, jeweils
statisch und als Shared Library, mit und ohne ASan/UBSan.