Files
R8Forge/tests/macro_docs_test.cc
T
dsh 56ea288cd6 Tidy the standard library's macro docs, and check them by machine
Audited all 30 %macro in asm/.  The format was already followed almost
everywhere -- the doc block sits above the %macro, or above the %synth block
that generates its body -- but four things were wrong:

  raw_and.r8asm  the two doc blocks still carried the old names (bit_and, and)
  raw_xor.r8asm  raw_xor's first two parameters were typed Unit, not Cell
  lib.r8asm      step / back / output had no type at all ("%1: step_count")

and two files still repeated the retracted claim that set_0 only converges on 0
and 1 (raw_add_nc.r8asm, raw_add_nc4.r8asm).  Those now say what set_0 really
does -- it clears the low bit -- and stay on the point that matters for a bit
level slice: A, B and the carry must be single bits because the searched
program only tracks the low K bits.

Parameter types are now a closed set: Cell, CellBit, Unit, UnitBit, Count
(Count is for step/back's repeat count).  It is written down in AGENTS.md
together with the format, so the next macro has something to copy.

New r8forge_macro_docs_test checks the format instead of trusting review: a doc
block must exist, its ";   Macro <name>" line must match the macro, the number
of documented parameters must equal argc, and every type must be one of the
five.  Negative tested by deleting a parameter line and by renaming a block --
it reports both and exits 1.

Also fixes a real annoyance found while running the checks: %synth writes its
generated macro to the system temp directory and imports it.  That write fails
intermittently on this machine (same directory, cmd can write, r8forge cannot;
cause unknown), which turned every assembly into "cannot open ...synth.r8asm".
The body is now built in memory and written to the temp directory or, if that
open fails, to the working directory, with one stderr line saying so.

Full suite green: test.r8asm 1666 characters, full_add 8/8, verify_raw_add_nc,
byte_op_test 65536x4 + 512, macro_docs_test 30/30, fibonacci prints its ten
numbers.
2026-11-07 00:23:28 +08:00

172 lines
5.2 KiB
C++

// Checks that every %macro in the standard library carries a doc comment in the
// house format:
//
// ; Macro bit_raw_add
// ; %1: CellBit A
// ; %2: CellBit B
// ...
//
// ; %this: CellBit operand (only for macros that work on the current cell)
//
// The comment block may sit directly above the %macro, or above the %synth
// block that generates the macro body (the library does the latter whenever the
// body is synthesised) -- this runs often enough that a missing or stale block
// is worth a machine check rather than a review.
//
// r8forge_macro_docs_test [asm dir] default: asm
//
// Parameter types are the ones the library uses: Cell, CellBit, Unit, UnitBit
// and Count (a plain number, for things like step's repeat count).
#include <algorithm>
#include <cstdio>
#include <filesystem>
#include <fstream>
#include <iostream>
#include <regex>
#include <string>
#include <vector>
namespace {
struct block {
size_t first = 0; // line index of the first ';' line
size_t last = 0; // line index of the last ';' line
};
bool is_comment(const std::string &line) {
const size_t at = line.find_first_not_of(" \t");
return at != std::string::npos && line[at] == ';';
}
const std::vector<std::string> TYPES = {"Cell", "CellBit", "Unit", "UnitBit",
"Count"};
std::vector<std::string> read_lines(const std::filesystem::path &path) {
std::vector<std::string> lines;
std::ifstream in(path);
std::string line;
while (std::getline(in, line)) {
if (!line.empty() && line.back() == '\r')
line.pop_back();
lines.push_back(line);
}
return lines;
}
} // namespace
int main(int argc, char **argv) {
const std::filesystem::path dir = argc > 1 ? argv[1] : "asm";
std::vector<std::filesystem::path> files;
std::error_code ec;
for (const auto &entry : std::filesystem::directory_iterator(dir, ec)) {
if (entry.path().extension() == ".r8asm")
files.push_back(entry.path());
}
if (ec || files.empty()) {
std::cerr << "cannot read " << dir << " (" << ec.message() << ")\n";
return 2;
}
std::sort(files.begin(), files.end());
const std::regex macro_re(R"(^[ \t]*%macro[ \t]+([A-Za-z_][A-Za-z0-9_]*)[ \t]+([0-9]+))");
const std::regex head_re(R"(^[ \t]*;[ \t]*Macro[ \t]+(\S+)[ \t]*$)");
const std::regex param_re(
R"(^[ \t]*;[ \t]*%([0-9]+):[ \t]*(\S+)[ \t]*(\S+)[ \t]*$)");
size_t macros = 0;
std::vector<std::string> problems;
for (const auto &file : files) {
const std::vector<std::string> lines = read_lines(file);
// every maximal run of ';' lines
std::vector<block> blocks;
for (size_t i = 0; i < lines.size();) {
if (!is_comment(lines[i])) {
i++;
continue;
}
block b;
b.first = i;
while (i < lines.size() && is_comment(lines[i]))
i++;
b.last = i - 1;
blocks.push_back(b);
}
for (size_t m = 0; m < lines.size(); m++) {
std::smatch match;
if (!std::regex_search(lines[m], match, macro_re))
continue;
const std::string name = match[1];
const size_t argc = std::stoul(match[2]);
macros++;
const std::string where =
file.filename().string() + ":" + std::to_string(m + 1) + ": " + name;
// the closest block that ends before this %macro
const block *doc = nullptr;
for (const block &b : blocks)
if (b.last < m)
doc = &b;
if (doc == nullptr) {
problems.push_back(where + ": no doc comment");
continue;
}
std::string doc_name;
size_t documented = 0;
bool bad_shape = false;
for (size_t i = doc->first; i <= doc->last; i++) {
std::smatch m2;
if (std::regex_search(lines[i], m2, head_re))
doc_name = m2[1];
if (!std::regex_search(lines[i], m2, param_re))
continue;
documented++;
const std::string type = m2[2];
if (std::find(TYPES.begin(), TYPES.end(), type) == TYPES.end()) {
problems.push_back(where + ":" + std::to_string(i + 1) +
": unknown parameter type '" + type + "'");
bad_shape = true;
}
if (m2[3].str().empty()) {
problems.push_back(where + ":" + std::to_string(i + 1) +
": parameter has no name");
bad_shape = true;
}
}
if (doc_name.empty()) {
problems.push_back(where + ": the comment block above has no "
"'; Macro <name>' line");
continue;
}
if (doc_name != name) {
problems.push_back(where + ": doc says Macro " + doc_name);
continue;
}
if (documented != argc) {
problems.push_back(where + ": " + std::to_string(argc) + " parameters, " +
std::to_string(documented) +
" documented");
continue;
}
(void)bad_shape;
}
std::cout << file.filename().string() << ": ok\n";
}
std::cout << macros << " macros in " << files.size() << " files\n";
if (problems.empty()) {
std::cout << "all documented in the house format\n";
return 0;
}
std::cout << problems.size() << " problem(s):\n";
for (const std::string &p : problems)
std::cout << " " << p << "\n";
return 1;
}