Skip to content

0.1.0

Latest

Choose a tag to compare

@rasuvaeff rasuvaeff released this 21 Aug 10:39
· 2 commits to master since this release

First release.

  • Executes php doc-exec fenced code blocks from Markdown against the current
    codebase, in a child php process — never eval(), never in-process.
  • Markers on a statement's trailing comment: // => <expr>,
    // throws <FQCN>[ | <substring>], // outputs <text>, // skip[: <reason>].
  • Blocks under one Markdown heading share a variable scope, in document order.
  • Blocks are split into statements by nikic/php-parser, so closures,
    if/else, try/catch, match, anonymous classes and do/while are
    each one statement.
  • A block that is not valid PHP fails on its own, with the line inside the
    block; the other blocks of its scope group still run.
  • Each scope group runs under a wall-clock deadline (30 s by default,
    --timeout=<seconds>), so a runaway example fails the build instead of
    wedging it.
  • CLI: vendor/bin/doc-exec [--bootstrap=<file>] [--timeout=<seconds>] [--help] [file.md ...], defaulting to ./README.md. Exit 0 all passed, 1 a block
    failed, 2 a usage error.
  • Runs on Windows as well as POSIX systems: the child process communicates
    entirely through files rather than pipes, so neither the unreachable file
    descriptor 3 nor stream_select()'s behaviour on Windows pipes applies.
    Documents are read the same whether they are saved with LF, CRLF or CR line
    endings.
  • use and const declarations inside a block are emitted at file level,
    where PHP accepts them; a document's own declare(strict_types=…) is
    dropped, since the generated script declares its own first.
  • A marker keyword with no payload — // =>, // throws, // outputs —
    fails the statement with a diagnostic instead of silently reading as prose.
  • Programmatic API: DocExec::check() returning DocumentResult →
    BlockResult → StatementResult, plus StableId for tracking a block
    across edits elsewhere in the document.