🔍

lit.o

Literate programming parser for .lit files. Allows mixing documentation and code in a single file following the literate programming paradigm invented by Donald Knuth.

Main elements

Name Description / comments
lparse[<file>] Parse .lit file and return structured data
src[<parsed>] Extract source code from parsed .lit data
html[<parsed>] Generate HTML documentation from parsed .lit data

Examples

Literate program structure:

@title My Program

@h1 Introduction

This section explains what the program does.

---program.o
// Main function
main: {
    println["Hello from literate program"];
};
---

@h2 Usage

Call main[] to run the program.

Parse .lit file:

o)load[getenv[`OHOME];"lit"];
o)
o)// Parse literate program file
o)parsed: lparse[`$":/path/to/program.lit"];
o)
o)// Extract source code
o)(code;filename): src[parsed];
o)code  // Source code as string
o)filename  // Target filename (e.g., :program.o)
o)
o)// Generate HTML documentation
o)doc: html[parsed];
o)write[`$":/path/to/output.html"; "x"$doc];

.lit file format

Documentation directives:

Directive Description Example
`@title TEXT` Document title `@title My Library`
`@h1 TEXT` Heading level 1 `@h1 Introduction`
`@h2 TEXT` Heading level 2 `@h2 Implementation`
`@h3 TEXT` Heading level 3 `@h3 Details`
`@h4 TEXT` Heading level 4 `@h4 Notes`
`@h5 TEXT` Heading level 5 `@h5 Subsection`
`@table TEXT` Table marker `@table Results`

Code blocks:

---filename.o
code here
---

Code blocks must have .o extension in filename.

Include blocks:

---identifier
content
---

Include blocks can be referenced and inserted into code using @{identifier} syntax.

Ignore blocks:

---[identifier]
content to ignore
---

Content in ignore blocks is not included in the output code but may be used for examples or documentation.

Auxiliary elements

Name Description / comments
htempl HTML template for generated documentation
.space PEG parser: parse spaces
.title PEG parser: parse @title directive
.h1-.h5 PEG parser: parse heading directives
.table PEG parser: parse @table directive
.sep PEG parser: parse separator `---`
.code PEG parser: parse code blocks
.incl PEG parser: parse include blocks
.igno PEG parser: parse ignore blocks
.mark PEG parser: parse any markup
.text PEG parser: parse plain text
.entit PEG parser: parse entities
.lit PEG parser: top-level entry point

Use case

Literate programming is useful when:

  • Writing libraries with extensive documentation
  • Creating educational code examples
  • Maintaining complex algorithms where explanation is as important as implementation
  • Generating both executable code and readable documentation from single source

The .lit format allows you to write prose explanations and code together, then extract clean source code for execution and beautiful HTML documentation for reading.