podlit-literate-programming

name	podlit-literate-programming
description	Guide for AI agents to write, weave, tangle, mangle, and stitch literate programs in PodLit for the Raptor language and runtime.

PodLit Literate Programming Guide for AI Agents

1. Overview & Academic Foundations

PodLit is Raptor's built-in Literate Programming subsystem, combining Knuth's classical literate programming with modern bi-directional synchronization:

• Donald E. Knuth (1984): Literate Programming, The Computer Journal. Established the paradigm of decomposing software into named macros and explanatory prose (weave and tangle).
• Johan Hidding (2023): Entangled, a Bidirectional System for Sustainable Literate Programming, IEEE e-Science 2023 (DOI: 10.1109/e-Science58273.2023.10254816). Formulated the grammar for bidirectional round-trip literate programming, providing the theoretical basis for Raptor's pod_stitch / raptor stitch engine.

PodLit provides five primary workflows:

1. Weave: Generates GitHub-Flavored Markdown (.md) formatted for humans from narrative prose and code chunks (raptor weave).
2. Tangle: Extracts source code files (.rp, .raptor, .c) by recursively assembling named code chunks (<<chunk-name>>) (raptor tangle).
3. Mangle: Applies macro transformation filters (:mangle(...)) during assembly.
4. Stitch: Synchronizes external source code edits back into the .pod document without disturbing narrative prose (raptor stitch).
5. Direct Execution: Directly executes .pod literate documents in memory without writing intermediate files to disk (raptor run <file.pod>).

2. PodLit Directives & Syntax

Literate documents use the .pod file extension.

2.1 Block Directives

Directive	Purpose	Description
=pod	Document Start	Begins a POD documentation block
=head1 .. =head6 <title>	Headings	Markdown-compatible section headings (Level 1 to 6)
=item <text>	Bullet List Item	Adds a list element
=chunk <name> [:file "path"] [:mangle(...)]	Code Chunk Declaration	Declares a named code fragment
=end chunk	Chunk Terminator	Concludes a code chunk declaration
=cut	Documentation End	Ends a POD block and returns to raw text/code

2.2 Inline Formatting Codes

Formatting Code	Output in Woven Markdown	Example
B<text>	Bold (**text**)	B<Vector2> -> **Vector2**
I<text>	Italic (*text*)	I<delta_time> -> *delta_time*
C<text>	Monospace Inline Code (`text`)	C<$count> -> `$count`
L<url>	Markdown Link ([url](url))	L<https://raptor.dev>

3. Tangling & Chunk Expansion (<<chunk>>)

Chunks are named fragments of code that can be embedded into other chunks using <<chunk-name>>.

3.1 Recursive Decomposition Pattern

=pod

=head1 1. Particle Types

We define the particle data structure:

=chunk <particle-types> :file "lib/Types.rp"
struct Particle {
    num32 $x;
    num32 $y;
    num32 $vx;
    num32 $vy;
}
=end chunk

=head1 2. Movement Logic

=chunk <particle-physics>
sub update_particle($p, $dt) {
    $p.x = $p.x + $p.vx * $dt;
    $p.y = $p.y + $p.vy * $dt;
    <<boundary-check>>
}
=end chunk

=chunk <boundary-check>
if $p.x < 0.0 || $p.x > 800.0 { $p.vx = -$p.vx; }
if $p.y < 0.0 || $p.y > 600.0 { $p.vy = -$p.vy; }
=end chunk

=head1 3. Main Executable Entrypoint

=chunk <main> :file "bin/app.rp"
<<particle-types>>

<<particle-physics>>

my $p = Particle.new();
$p.x = 100.0; $p.y = 100.0;
$p.vx = 50.0; $p.vy = 25.0;

update_particle($p, 0.016);
say "Particle Position: (", $p.x, ", ", $p.y, ")";
=end chunk

=cut

3.2 Indentation Preservation & Cycle Detection

• Indentation: When <<boundary-check>> is expanded within update_particle, PodLit automatically prepends the caller's indentation level (e.g., 4 spaces) to every line of the embedded chunk.
• Cycle Detection: Cyclic chunk dependencies (e.g., chunk A including chunk B which includes chunk A) are detected and fail gracefully with an error report.

4. Mangle Transformations

You can attach processing filters to any chunk using the :mangle(...) attribute:

Mangle Filter	Effect
:mangle(indent(N))	Indents every line in the chunk by N spaces
:mangle(strip_comments)	Strips # single-line comments from the emitted chunk
:mangle(prefix("str"))	Prepends a prefix string to the beginning of each line

Example:

=chunk <secure-config> :mangle(strip_comments)
# Development keys - stripped in tangled output
my $apiKey = "SECRET_12345";
my $dbHost = "127.0.0.1";
=end chunk

5. Reverse-Stitching (Round-Trip Synchronization)

When source code files generated by raptor tangle are edited in an IDE or external editor, Stitch parses the modified code and updates the corresponding chunk bodies inside the original .pod document without altering any prose or headings:

# 1. Tangle code to disk
raptor tangle app.pod -o src/

# 2. Modify src/lib/Types.rp in your editor
# (e.g. adding a new field to struct Particle)

# 3. Stitch modified code back into the literate document
raptor stitch app.pod src/lib/Types.rp

# 4. Or stitch an entire directory tree with output to a new file:
raptor stitch app.pod src/ -o app_updated.pod

6. Command Line Interface (CLI)

Raptor provides dedicated subcommands for PodLit:

# 1. Weave: Render .pod to Markdown (.md)
raptor weave doc.pod -o doc.md

# 2. Tangle: Extract source files defined by :file attributes
raptor tangle doc.pod -o ./src/

# 3. Stitch: Reverse-sync modified source files back into .pod
raptor stitch doc.pod ./src/lib/Types.rp

# 4. Direct Literate Execution: Run .pod directly
raptor doc.pod
raptor run doc.pod

7. In-Language Runtime Builtins

Raptor scripts can also invoke the PodLit engine programmatically:

my $podSource = q[=pod
=head1 Literate Math Engine

<<add-func>>
=chunk <add-func>
sub add($a, $b) { return $a + $b; }
=end chunk
=cut];

# 1. Weave to Markdown string
my Str $markdown = pod_weave($podSource);

# 2. Tangle to Hash of { filename => code }
my %files = pod_tangle($podSource);

# 3. Stitch updated code hash back into POD string
my %updates = { "add-func" => "sub add($a, $b) { return $a + $b + 0; }" };
my Str $newPod = pod_stitch($podSource, %updates);

8. Agent Guidelines for Authoring Literate Programs

When authoring new literate programs:

1. Explain First, Code Second: Begin each section with human-readable prose explaining why a particular design decision or algorithm was chosen.
2. Define Data Models Early: Place C-ABI struct definitions in early named chunks tagged with :file "lib/Types.rp".
3. Decompose Complex Logic: Break large subroutines into smaller named chunks (e.g., <<validation>>, <<core-loop>>, <<cleanup>>).
4. Provide a Clean <main> Chunk: Tag the top-level assembly chunk with :file "bin/app.rp" or :file "main.rp".
5. Verify with Direct Execution: Execute the .pod file using raptor run file.pod to verify that all recursive chunk expansions compile and run cleanly.

AI credit

The first prototype was written by Gemini. Library bindings and PodLit were written by Gemini 3.7. Later work was modified by Grok.