Project Overview

The Plywood runtime library consists of four main modules and several higher-level libraries, each consisting of a single pair of .h and .cpp files. Whenever a Plywood .h file is included in a project, its corresponding .cpp file should also be compiled and linked in.

Main Modules:

• System (ply-system.h): Memory, timers, file systems, threads and processes.
• Math (ply-math.h): Scalar and vector math suitable for games and UI layouts.
• Reflection (ply-reflect.h): Generic processing of data stored in Plywood data structures.
• Networking (ply-network.h): Client and server-side TCP and HTTP.

Higher-Level Libraries:

• Agent Harness (ply-agent.h): Spawn local agents with custom tools using remote inference providers.
• JSON Support (ply-json.h): Import and export JSON documents.
• Markdown Parser (ply-markdown.h): Import Markdown documents and export to HTML.
• C++ Parser (ply-cpp.h) (experimental): Parse C++ source code and generate syntax trees.
• Tokenizer (ply-tokenizer.h): Break input text into common token types.

Sample Applications:

• agent: Command-line agent with built-in web UI.
• agent-proxy: Protects API keys while working on agent.
• test-suite: Automated tests to validate Plywood's API-correctness.
• generate-docs: Generate the HTML version of Plywood's documentation.
• serve-docs: Serve the HTML documentation locally.
• banner-comment: Generate banner comments.

Directory Structure

The Plywood repository has the following directory structure. The build and bin folders are excluded from source control.

plywood/
├── src/                        # Library source code.
│   ├── ply-system.h
│   ├── ply-system.cpp
│   ├── ply-math.h
│   ├── ply-math.cpp
│   └── ...
├── docs/                       # Documentation.
│   ├── table-of-contents.md
│   ├── ...
│   └── build/                  # HTML output files written by generate-docs.
├── apps/                       # Sample applications.
│   ├── agent/
│   │   ├── main.cpp
│   │   ├── CMakeLists.txt
│   │   ├── build/              # Intermediate build folder.
│   │   └── ...
│   ├── test-suite/
│   ├── generate-docs/
│   ├── serve-docs/
│   └── banner-comment/
├── share/
│   ├── build-app.sh            # Sample build script.
│   ├── build-app.bat           # Sample build script (Windows).
│   └── ...
├── bin/                        # Output executables.
│   ├── agent[.exe]
│   └── ...
└── agent.json                  # Agent harness settings.

The ply Namespace

All Plywood functions and types are defined in the ply namespace. Some higher-level libraries define nested namespaces, such as ply::markdown. When possible, importing ply into the global namespace is a convenient way to simplify name lookup.

#include <ply-markdown.h>

using namespace ply;  // Import ply into global namespace.

Array<Owned<markdown::Block>> blocks = markdown::parse("Hello, *world!*");

Coding Style

These are the internal guidelines that the Plywood source code strives to follow. (Client applications can use any style they like.)

• Use C++14 language features only.
• Use the provided .clang-format for formatting.
• Type and enumerator names in PascalCase; variable and function names in camelCase.
• Every significant code block should begin with a brief comment to explain what it does.
• Use the fewest line of code possible without sacrificing readability.
• Always use this-> to refer to member functions and member variables inside the same class.
• The body of every if, else, do, while and for statement must be surrounded by { curly braces }, unless it consists of a single continue, return, or break statement, in which case curly braces must be omitted.
• Use the banner-comment sample application to generate banner comments that label significant source file sections.