// SPDX-License-Identifier: GPL-3.0-only // (c) Hare authors // Note: ast::ident should never have to be escaped use encoding::utf8; use fmt; use hare::ast; use hare::lex; use hare::parse::doc; use hare::unparse; use io; use memio; use net::ip; use net::uri; use os; use path; use strings; // Prints a string to an output handle, escaping any of HTML's reserved // characters. fn html_escape(out: io::handle, in: str) (size | io::error) = { let z = 0z; let iter = strings::iter(in); for (let rn => strings::next(&iter)) { z += fmt::fprint(out, switch (rn) { case '&' => yield "&"; case '<' => yield "<"; case '>' => yield ">"; case '"' => yield """; case '\'' => yield "'"; case => yield strings::fromutf8(utf8::encoderune(rn))!; })?; }; return z; }; @test fn html_escape() void = { let sink = memio::dynamic(); defer io::close(&sink)!; html_escape(&sink, "hello world!")!; assert(memio::string(&sink)! == "hello world!"); let sink = memio::dynamic(); defer io::close(&sink)!; html_escape(&sink, "\"hello world!\"")!; assert(memio::string(&sink)! == ""hello world!""); let sink = memio::dynamic(); defer io::close(&sink)!; html_escape(&sink, "")!; assert(memio::string(&sink)! == "<hello & 'world'!>"); }; // Formats output as HTML export fn emit_html(ctx: *context) (void | error) = { const decls = ctx.summary; const ident = unparse::identstr(ctx.ident); defer free(ident); if (ctx.template) { head(ctx.ident)?; }; if (len(ident) == 0) { fmt::fprintf(ctx.out, "

The Hare standard library ")?; } else { fmt::fprintf(ctx.out, "

{}", ident)?; }; for (let tag .. ctx.tags) { fmt::fprintf(ctx.out, "+{} ", tag)?; }; fmt::fprintln(ctx.out, "

")?; match (ctx.readme) { case void => void; case let f: io::file => fmt::fprintln(ctx.out, "
")?; markup_html(ctx, f, lex::location { path = "README", // XXX: this is meh line = 1, col = 1, off = 0, })?; fmt::fprintln(ctx.out, "
")?; }; let identpath = strings::join("/", ctx.ident...)!; defer free(identpath); if (len(ctx.submods) != 0) { if (len(ctx.ident) == 0) { fmt::fprintln(ctx.out, "

Modules

")?; } else { fmt::fprintln(ctx.out, "

Submodules

")?; }; fmt::fprintln(ctx.out, "")?; }; if (len(decls.types) == 0 && len(decls.errors) == 0 && len(decls.constants) == 0 && len(decls.globals) == 0 && len(decls.funcs) == 0) { return; }; fmt::fprintln(ctx.out, "

Index

")?; tocentries(ctx.out, decls.types, "Types", "types")?; tocentries(ctx.out, decls.errors, "Errors", "Errors")?; tocentries(ctx.out, decls.constants, "Constants", "constants")?; tocentries(ctx.out, decls.globals, "Globals", "globals")?; tocentries(ctx.out, decls.funcs, "Functions", "functions")?; if (len(decls.types) != 0) { fmt::fprintln(ctx.out, "

Types

")?; for (let t &.. decls.types) { details(ctx, t)?; }; }; if (len(decls.errors) != 0) { fmt::fprintln(ctx.out, "

Errors

")?; for (let e &.. decls.errors) { details(ctx, e)?; }; }; if (len(decls.constants) != 0) { fmt::fprintln(ctx.out, "

Constants

")?; for (let c &.. decls.constants) { details(ctx, c)?; }; }; if (len(decls.globals) != 0) { fmt::fprintln(ctx.out, "

Globals

")?; for (let g &.. decls.globals) { details(ctx, g)?; }; }; if (len(decls.funcs) != 0) { fmt::fprintln(ctx.out, "

Functions

")?; for (let f &.. decls.funcs) { details(ctx, f)?; }; }; }; fn tocentries( out: io::handle, decls: []ast::decl, name: str, lname: str, ) (void | error) = { if (len(decls) == 0) { return; }; fmt::fprintfln(out, "

{}

", name)?; fmt::fprintln(out, "
")?;
	let undoc = false;
	for (let i = 0z; i < len(decls); i += 1) {
		if (!undoc && decls[i].docs == "") {
			fmt::fprintfln(
				out,
				"{}// Undocumented {}:",
				if (i == 0) "" else "\n",
				lname)?;
			undoc = true;
		};

		match (&decls[i].decl) {
		case let d: *ast::decl_func =>
			free(d.symbol);
			d.symbol = "";
		case => void;
		};

		const decl = &decls[i];
		match (decl.decl) {
		case let t: ast::decl_type =>
			// Print summarized types in the TOC
			fmt::fprintf(out, "type ")?;
			fmt::fprintf(out, "")?;
			unparse::ident(out, decl_ident(decl))?;
			fmt::fprintf(out, ";")?;
		case =>
			unparse::decl(out, &syn_centry, &decls[i])?;
		};

		fmt::fprintln(out)?;
	};
	fmt::fprint(out, "
")?; return; }; fn details(ctx: *context, decl: *ast::decl) (void | error) = { fmt::fprintln(ctx.out, "
")?; fmt::fprint(ctx.out, "

")?; fmt::fprintf(ctx.out, "{} ", match (decl.decl) { case ast::decl_func => yield "fn"; case ast::decl_type => yield "type"; case ast::decl_const => yield "def"; case ast::decl_global => yield "let"; case ast::assert_expr => abort(); })?; unparse::ident(ctx.out, decl_ident(decl))?; // TODO: Add source URL fmt::fprint(ctx.out, "[permalink]")?; match (os::getenv("HAREDOC_HTML_SRC")) { case let fmt: str => const url = fmt::asprintf(fmt, cwdpath(decl.loc.start.path), decl.loc.start.line)!; defer free(url); fmt::fprint(ctx.out, " [source]")?; case void => yield; }; fmt::fprint(ctx.out, "")?; fmt::fprintln(ctx.out, "

")?; if (len(decl.docs) == 0) { fmt::fprintln(ctx.out, "
")?; fmt::fprintln(ctx.out, "Show undocumented member")?; }; fmt::fprintln(ctx.out, "
")?;
	unparse::decl(ctx.out, &syn_html, decl)?;
	fmt::fprintln(ctx.out, "
")?; if (len(decl.docs) != 0) { const trimmed = trim_comment(decl.docs); defer free(trimmed); const buf = strings::toutf8(trimmed); markup_html(ctx, &memio::fixed(buf), decl.loc.start)?; } else { fmt::fprintln(ctx.out, "
")?; }; fmt::fprintln(ctx.out, "
")?; return; }; // Returns the relative path from the current module to a target module path. // The caller is responsible for freeing the allocated string. fn relpath(from: ast::ident, to: []str) str = { let common = 0z; // Length of common prefix. for (common < len(from) && common < len(to); common += 1) { if (from[common] != to[common]) { break; }; }; let parts: []str = []; for (let i = common; i < len(from); i += 1) { append(parts, "..")!; }; for (let i = common; i < len(to); i += 1) { append(parts, to[i])!; }; if (len(parts) == 0) { return strings::dup(".")!; }; return strings::join("/", parts...)!; }; @test fn relpath_sibling() void = { const from1: []str = ["strings"]; const to1: []str = ["strconv"]; const result1 = relpath(from1, to1); defer free(result1); assert(result1 == "../strconv"); }; @test fn relpath_shared_prefix() void = { const from2: []str = ["fakeone"]; const to2: []str = ["faketwo"]; const result2 = relpath(from2, to2); defer free(result2); assert(result2 == "../faketwo"); }; @test fn relpath_nested_to_top() void = { const from3: []str = ["encoding", "base64"]; const to3: []str = ["strings"]; const result3 = relpath(from3, to3); defer free(result3); assert(result3 == "../../strings"); }; @test fn relpath_top_to_nested() void = { const from4: []str = ["strings"]; const to4: []str = ["encoding", "base64"]; const result4 = relpath(from4, to4); defer free(result4); assert(result4 == "../encoding/base64"); }; fn html_decl_ref(ctx: *context, ref: ast::ident) (void | error) = { const ik = match (resolve(ctx, ref)?) { case let ik: (ast::ident, symkind) => yield ik; case void => const ident = unparse::identstr(ref); fmt::errorfln("Warning: Unresolved reference: {}", ident)?; fmt::fprintf(ctx.out, "{}", ident)?; free(ident); return; }; // TODO: The reference is not necessarily in the stdlib const kind = ik.1, id = ik.0; const ident = unparse::identstr(id); switch (kind) { case symkind::LOCAL => fmt::fprintf(ctx.out, "{0}", ident)?; case symkind::MODULE => let rpath = relpath(ctx.ident, id); defer free(rpath); fmt::fprintf(ctx.out, "{}::", rpath, ident)?; case symkind::SYMBOL => let rpath = relpath(ctx.ident, id[..len(id) - 1]); defer free(rpath); fmt::fprintf(ctx.out, "{}", rpath, id[len(id) - 1], ident)?; case symkind::ENUM_LOCAL => fmt::fprintf(ctx.out, "{}", id[len(id) - 2], ident)?; case symkind::ENUM_REMOTE => let rpath = relpath(ctx.ident, id[..len(id) - 2]); defer free(rpath); fmt::fprintf(ctx.out, "{}", rpath, id[len(id) - 2], ident)?; }; free(ident); }; fn html_mod_ref(ctx: *context, ref: ast::ident) (void | error) = { const ident = unparse::identstr(ref); defer free(ident); let rpath = relpath(ctx.ident, ref); defer free(rpath); fmt::fprintf(ctx.out, "{}::", rpath, ident)?; }; fn html_paragraph(ctx: *context, p: doc::paragraph) (void | error) = { for (let elem .. p) { match (elem) { case let s: str => match (uri::parse(s)) { case let uri: uri::uri => defer uri::finish(&uri); if (uri.host is ip::addr || len(uri.host as str) > 0) { fmt::fprint(ctx.out, "")?; html_escape(ctx.out, s)?; fmt::fprint(ctx.out, "")?; } else { html_escape(ctx.out, s)?; }; case uri::invalid => html_escape(ctx.out, s)?; }; case let d: doc::decl_ref => html_decl_ref(ctx, d)?; case let m: doc::mod_ref => html_mod_ref(ctx, m)?; }; }; }; fn markup_html( ctx: *context, in: io::handle, loc: lex::location, ) (void | error) = { const doc = match (doc::parse(in, loc)) { case let doc: doc::doc => yield doc; case let err: lex::syntax => const err = lex::strerror(err); fmt::errorln("Warning:", err)?; fmt::fprint(ctx.out, "

Can't parse docs: ")?; html_escape(ctx.out, err)?; fmt::fprintln(ctx.out)?; return; }; defer doc::freeall(doc); for (let elem .. doc) { match (elem) { case let p: doc::paragraph => fmt::fprint(ctx.out, "

")?; html_paragraph(ctx, p)?; fmt::fprintln(ctx.out)?; case let l: doc::list => fmt::fprintln(ctx.out, "

    ")?; for (let entry .. l) { fmt::fprint(ctx.out, "
  • ")?; html_paragraph(ctx, entry)?; fmt::fprintln(ctx.out)?; }; fmt::fprintln(ctx.out, "
")?; case let c: doc::code_sample => fmt::fprint(ctx.out, "
")?;
			html_escape(ctx.out, c)?;
			fmt::fprintln(ctx.out, "
")?; }; }; }; fn syn_centry( ctx: *unparse::context, s: str, kind: unparse::synkind, ) (size | io::error) = { let z = 0z; switch (kind) { case unparse::synkind::CONSTANT, unparse::synkind::FUNCTION, unparse::synkind::GLOBAL, unparse::synkind::TYPEDEF => z += fmt::fprint(ctx.out, "")?; z += html_escape(ctx.out, s)?; z += fmt::fprint(ctx.out, "")?; ctx.linelen += len(s); return z; case => return syn_html(ctx, s, kind); }; }; fn syn_html( ctx: *unparse::context, s: str, kind: unparse::synkind, ) (size | io::error) = { let z = 0z; const span = switch (kind) { case unparse::synkind::COMMENT => const stack = ctx.stack as *unparse::stack; if (stack.cur is *ast::decl) { // doc comment is unparsed separately later return 0z; }; z += fmt::fprint(ctx.out, "")?; yield true; case unparse::synkind::KEYWORD => z += fmt::fprint(ctx.out, "")?; yield true; case unparse::synkind::TYPE => z += fmt::fprint(ctx.out, "")?; yield true; case => yield false; }; z += html_escape(ctx.out, s)?; ctx.linelen += len(s); if (span) { z += fmt::fprint(ctx.out, "")?; }; return z; }; fn breadcrumb(ident: ast::ident) str = { if (len(ident) == 0) { return ""; }; let buf = memio::dynamic(); let root_parts: []str = []; for (let i = 0z; i < len(ident); i += 1) { append(root_parts, "..")!; }; let root_path = strings::join("/", root_parts...)!; defer free(root_path); fmt::fprintf(&buf, "stdlib » ", root_path)!; for (let i = 0z; i < len(ident) - 1; i += 1) { let rpath = relpath(ident, ident[..i+1]); defer free(rpath); fmt::fprintf(&buf, "{}::", rpath, ident[i])!; }; fmt::fprint(&buf, ident[len(ident) - 1])!; return memio::string(&buf)!; }; const harriet_b64 = "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"; fn head(ident: ast::ident) (void | error) = { const id = unparse::identstr(ident); defer free(id); let breadcrumb = breadcrumb(ident); defer free(breadcrumb); const title = if (len(id) == 0) fmt::asprintf("Hare documentation")! else fmt::asprintf("{} — Hare documentation", id)!; defer free(title); // TODO: Move bits to +embed? fmt::printfln(" {} ", title, harriet_b64)?; fmt::println("")?; fmt::printfln("
")?; return; };