@optique/man 0.10.7 → 1.0.0-dev.1116

package/dist/man-BE1OY_lJ.js

@@ -0,0 +1,386 @@
+import { escapeHyphens, escapeRequestArg, escapeRoff, formatMessageAsRoff } from "./roff-CCdIQO7B.js";
+import { isDocHidden, isUsageHidden } from "@optique/core/usage";
+
+//#region src/man.ts
+/**
+* Formats a date for use in man pages.
+*
+* When a `Date` object is given, the month and year are extracted using
+* the host's local timezone (`getMonth()` / `getFullYear()`).  This means
+* the same `Date` instant may produce different output on machines in
+* different timezones.  Pass a pre-formatted string (e.g., `"January 2026"`)
+* if you need timezone-independent output.
+*
+* @param date The date to format, or undefined.
+* @returns The formatted date string, or undefined.
+* @throws {RangeError} If the given `Date` object is invalid.
+* @since 0.10.0
+*/
+function formatDateForMan(date) {
+	if (date === void 0) return void 0;
+	if (typeof date === "string") return date;
+	if (Number.isNaN(date.getTime())) throw new RangeError("Invalid Date object.");
+	const months = [
+		"January",
+		"February",
+		"March",
+		"April",
+		"May",
+		"June",
+		"July",
+		"August",
+		"September",
+		"October",
+		"November",
+		"December"
+	];
+	return `${months[date.getMonth()]} ${date.getFullYear()}`;
+}
+function formatCommandNameAsRoff(name) {
+	return `\\fB${escapeHyphens(escapeRoff(name))}\\fR`;
+}
+/**
+* Formats a single {@link UsageTerm} as roff markup for the SYNOPSIS section.
+*
+* @param term The usage term to format.
+* @returns The roff-formatted string.
+* @throws {TypeError} If the term has an unknown type.
+* @since 0.10.0
+*/
+function formatUsageTermAsRoff(term) {
+	return formatUsageTermAsRoffInternal(term, false);
+}
+/**
+* Returns whether a usage list contains exactly one visible term that
+* produces its own brackets.  When true, a parent wrapper can safely elide
+* its own brackets to avoid redundant nesting.  Multiple bracket-producing
+* siblings must keep their individual brackets for disambiguation.
+*/
+function hasSingleBracketedTerm(terms) {
+	const visible = terms.filter((t$1) => !("hidden" in t$1 && isUsageHidden(t$1.hidden)));
+	if (visible.length !== 1) return false;
+	const t = visible[0];
+	return t.type === "option" || t.type === "optional" || t.type === "multiple" && t.min < 1 || t.type === "passthrough";
+}
+/**
+* Returns whether a usage list's single visible term has the given type.
+*/
+function hasSingleVisibleTermOfType(terms, type) {
+	const visible = terms.filter((t) => !("hidden" in t && isUsageHidden(t.hidden)));
+	return visible.length === 1 && visible[0].type === type;
+}
+function formatUsageTermAsRoffInternal(term, insideBrackets) {
+	if ("hidden" in term && isUsageHidden(term.hidden)) return "";
+	switch (term.type) {
+		case "argument": return `\\fI${escapeRoff(term.metavar)}\\fR`;
+		case "option": {
+			const names = term.names.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(" | ");
+			const metavarPart = term.metavar ? ` \\fI${escapeRoff(term.metavar)}\\fR` : "";
+			if (insideBrackets) return `${names}${metavarPart}`;
+			return `[${names}${metavarPart}]`;
+		}
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "optional": {
+			const childrenBracketed = hasSingleBracketedTerm(term.terms);
+			const childIsMultiple = childrenBracketed && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const inner = formatUsageAsRoffInternal(term.terms, childrenBracketed);
+			if (inner === "") return "";
+			if (insideBrackets && childrenBracketed && !childIsMultiple) return inner;
+			return `[${inner}]`;
+		}
+		case "multiple": {
+			const wrapInBrackets = term.min < 1;
+			const childrenBracketed = hasSingleBracketedTerm(term.terms);
+			const childIsMultiple = childrenBracketed && hasSingleVisibleTermOfType(term.terms, "multiple");
+			const passInsideBrackets = wrapInBrackets && childrenBracketed && !childIsMultiple;
+			const inner = formatUsageAsRoffInternal(term.terms, passInsideBrackets);
+			if (inner === "") return "";
+			if (wrapInBrackets) {
+				if (insideBrackets && passInsideBrackets) return `${inner} ...`;
+				return `[${inner} ...]`;
+			}
+			return `${inner} ...`;
+		}
+		case "exclusive": {
+			const alternatives = term.terms.map((t) => formatUsageAsRoffInternal(t, false)).filter((s) => s !== "");
+			if (alternatives.length === 0) return "";
+			if (alternatives.length === 1) return alternatives[0];
+			return `(${alternatives.join(" | ")})`;
+		}
+		case "literal": return escapeRoff(term.value);
+		case "passthrough": return "[...]";
+		case "ellipsis": return "...";
+		default: {
+			const _exhaustive = term;
+			throw new TypeError(`Unknown usage term type: ${_exhaustive.type}.`);
+		}
+	}
+}
+/**
+* Formats a {@link Usage} array as roff markup.
+*
+* @param usage The usage terms to format.
+* @returns The roff-formatted string.
+*/
+function formatUsageAsRoff(usage) {
+	return formatUsageAsRoffInternal(usage, false);
+}
+function formatUsageAsRoffInternal(usage, insideBrackets) {
+	return usage.map((term) => formatUsageTermAsRoffInternal(term, insideBrackets)).filter((s) => s !== "").join(" ");
+}
+/**
+* Formats a {@link DocEntry}'s term for man page output.
+*
+* @param term The usage term from the entry.
+* @returns The roff-formatted term string.
+*/
+function formatDocEntryTerm(term) {
+	if ("hidden" in term && isDocHidden(term.hidden)) return "";
+	switch (term.type) {
+		case "option": {
+			const names = term.names.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
+			const metavarPart = term.metavar ? ` \\fI${escapeRoff(term.metavar)}\\fR` : "";
+			return `${names}${metavarPart}`;
+		}
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "argument": return `\\fI${escapeRoff(term.metavar)}\\fR`;
+		case "literal": return escapeRoff(term.value);
+		default: return formatDocUsageTermAsRoff(term);
+	}
+}
+/**
+* Formats a {@link UsageTerm} as roff markup for doc rendering, filtering
+* doc-hidden terms instead of usage-hidden terms.
+*
+* @throws {TypeError} If the term has an unknown type.
+*/
+function formatDocUsageTermAsRoff(term) {
+	if ("hidden" in term && isDocHidden(term.hidden)) return "";
+	switch (term.type) {
+		case "optional": {
+			const inner = formatDocUsageAsRoff(term.terms);
+			if (inner === "") return "";
+			return `[${inner}]`;
+		}
+		case "multiple": {
+			const inner = formatDocUsageAsRoff(term.terms);
+			if (inner === "") return "";
+			if (term.min < 1) return `[${inner} ...]`;
+			return `${inner} ...`;
+		}
+		case "exclusive": {
+			const alternatives = term.terms.map((t) => formatDocUsageAsRoff(t)).filter((s) => s !== "");
+			if (alternatives.length === 0) return "";
+			if (alternatives.length === 1) return alternatives[0];
+			return `(${alternatives.join(" | ")})`;
+		}
+		case "argument": return `\\fI${escapeRoff(term.metavar)}\\fR`;
+		case "option": {
+			const names = term.names.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
+			const metavarPart = term.metavar ? ` \\fI${escapeRoff(term.metavar)}\\fR` : "";
+			return `${names}${metavarPart}`;
+		}
+		case "command": return formatCommandNameAsRoff(term.name);
+		case "literal": return escapeRoff(term.value);
+		case "passthrough": return "[...]";
+		case "ellipsis": return "...";
+		default: {
+			const _exhaustive = term;
+			throw new TypeError(`Unknown usage term type: ${_exhaustive.type}.`);
+		}
+	}
+}
+/**
+* Formats a {@link Usage} array as roff markup for doc rendering,
+* filtering doc-hidden terms.
+*/
+function formatDocUsageAsRoff(usage) {
+	return usage.map(formatDocUsageTermAsRoff).filter((s) => s !== "").join(" ");
+}
+/**
+* Infers the section title from entry kinds when no explicit title is given.
+* Returns `"COMMANDS"` for command-only sections, `"ARGUMENTS"` for
+* argument-only sections, and `"OPTIONS"` otherwise.
+*
+* @param entries The entries in the section.
+* @returns The inferred section title in uppercase.
+*/
+function inferSectionTitle(entries) {
+	const kinds = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		if ("hidden" in entry.term && isDocHidden(entry.term.hidden)) continue;
+		kinds.add(entry.term.type);
+	}
+	if (kinds.size === 1) {
+		if (kinds.has("command")) return "COMMANDS";
+		if (kinds.has("argument")) return "ARGUMENTS";
+	}
+	return "OPTIONS";
+}
+/**
+* Formats a {@link DocSection} as roff markup with .TP macros.
+*
+* @param section The section to format.
+* @returns The roff-formatted section content.
+*/
+function formatDocSectionEntries(section) {
+	const lines = [];
+	for (const entry of section.entries) {
+		const termStr = formatDocEntryTerm(entry.term);
+		if (termStr === "") continue;
+		lines.push(".TP");
+		lines.push(termStr);
+		if (entry.description) {
+			let desc = formatMessageAsRoff(entry.description);
+			if (entry.default) desc += ` [${formatMessageAsRoff(entry.default)}]`;
+			if (entry.choices) desc += ` (choices: ${formatMessageAsRoff(entry.choices, { quotes: false })})`;
+			lines.push(desc);
+		} else if (entry.default || entry.choices) {
+			const parts = [];
+			if (entry.default) parts.push(`[${formatMessageAsRoff(entry.default)}]`);
+			if (entry.choices) parts.push(`(choices: ${formatMessageAsRoff(entry.choices, { quotes: false })})`);
+			lines.push(parts.join(" "));
+		}
+	}
+	return lines.join("\n");
+}
+/**
+* Formats a {@link DocPage} as a complete man page in roff format.
+*
+* This function generates a man page following the standard man(7) format,
+* including sections for NAME, SYNOPSIS, DESCRIPTION, OPTIONS, and more.
+*
+* @example
+* ```typescript
+* import { formatDocPageAsMan } from "@optique/man/man";
+* import type { DocPage } from "@optique/core/doc";
+*
+* const page: DocPage = {
+*   brief: message`A sample CLI application`,
+*   usage: [{ type: "argument", metavar: "FILE" }],
+*   sections: [],
+* };
+*
+* const manPage = formatDocPageAsMan(page, {
+*   name: "myapp",
+*   section: 1,
+*   version: "1.0.0",
+* });
+* ```
+*
+* @param page The documentation page to format.
+* @param options The man page options.
+* @returns The complete man page in roff format.
+* @throws {TypeError} If the program name is empty.
+* @throws {RangeError} If the section number or any `seeAlso` entry's section
+* number is not a valid man page section (1–8).
+* @since 0.10.0
+*/
+function formatDocPageAsMan(page, options) {
+	if (options.name === "") throw new TypeError("Program name must not be empty.");
+	if (!Number.isInteger(options.section) || options.section < 1 || options.section > 8) {
+		let repr;
+		try {
+			repr = JSON.stringify(options.section);
+		} catch {
+			repr = String(typeof options.section);
+		}
+		throw new RangeError(`Invalid man page section number (must be 1–8): ${repr}`);
+	}
+	const lines = [];
+	const thParts = [`"${escapeHyphens(escapeRequestArg(options.name.toUpperCase()))}"`, options.section.toString()];
+	const hasDate = options.date != null && options.date !== "";
+	const hasVersion = options.version != null && options.version !== "";
+	const hasManual = options.manual != null && options.manual !== "";
+	if (hasDate) thParts.push(`"${escapeRequestArg(formatDateForMan(options.date))}"`);
+	else if (hasVersion || hasManual) thParts.push("\"\"");
+	if (hasVersion) thParts.push(`"${escapeHyphens(escapeRequestArg(options.name))} ${escapeRequestArg(options.version)}"`);
+	else if (hasManual) thParts.push("\"\"");
+	if (hasManual) thParts.push(`"${escapeRequestArg(options.manual)}"`);
+	lines.push(`.TH ${thParts.join(" ")}`);
+	lines.push(".SH NAME");
+	const brief = options.brief ?? page.brief;
+	if (brief) lines.push(`${escapeHyphens(escapeRoff(options.name))} \\- ${formatMessageAsRoff(brief)}`);
+	else lines.push(escapeHyphens(escapeRoff(options.name)));
+	if (page.usage) {
+		lines.push(".SH SYNOPSIS");
+		lines.push(`.B "${escapeHyphens(escapeRequestArg(options.name))}"`);
+		const usageStr = formatUsageAsRoff(page.usage);
+		if (usageStr) lines.push(usageStr);
+	}
+	const description = options.description ?? page.description;
+	if (description) {
+		lines.push(".SH DESCRIPTION");
+		lines.push(formatMessageAsRoff(description));
+	}
+	for (const section of page.sections) {
+		if (section.entries.length === 0) continue;
+		const content = formatDocSectionEntries(section);
+		if (content === "") continue;
+		const title = section.title?.toUpperCase() ?? inferSectionTitle(section.entries);
+		lines.push(`.SH "${escapeRequestArg(title)}"`);
+		lines.push(content);
+	}
+	if (options.environment && options.environment.entries.length > 0) {
+		const content = formatDocSectionEntries(options.environment);
+		if (content !== "") {
+			lines.push(".SH ENVIRONMENT");
+			lines.push(content);
+		}
+	}
+	if (options.files && options.files.entries.length > 0) {
+		const content = formatDocSectionEntries(options.files);
+		if (content !== "") {
+			lines.push(".SH FILES");
+			lines.push(content);
+		}
+	}
+	if (options.exitStatus && options.exitStatus.entries.length > 0) {
+		const content = formatDocSectionEntries(options.exitStatus);
+		if (content !== "") {
+			lines.push(".SH EXIT STATUS");
+			lines.push(content);
+		}
+	}
+	const examples = options.examples ?? page.examples;
+	if (examples) {
+		lines.push(".SH EXAMPLES");
+		lines.push(formatMessageAsRoff(examples));
+	}
+	const bugs = options.bugs ?? page.bugs;
+	if (bugs) {
+		lines.push(".SH BUGS");
+		lines.push(formatMessageAsRoff(bugs));
+	}
+	if (options.seeAlso && options.seeAlso.length > 0) {
+		for (const ref of options.seeAlso) if (!Number.isInteger(ref.section) || ref.section < 1 || ref.section > 8) {
+			let repr;
+			try {
+				repr = JSON.stringify(ref.section);
+			} catch {
+				repr = String(typeof ref.section);
+			}
+			throw new RangeError(`Invalid man page section number for seeAlso entry ${JSON.stringify(ref.name)} (must be 1–8): ${repr}`);
+		}
+		lines.push(".SH SEE ALSO");
+		const refs = options.seeAlso.map((ref, i) => {
+			const suffix = i < options.seeAlso.length - 1 ? "," : "";
+			return `.BR "${escapeHyphens(escapeRequestArg(ref.name))}" (${ref.section})${suffix}`;
+		});
+		lines.push(refs.join("\n"));
+	}
+	const author = options.author ?? page.author;
+	if (author) {
+		lines.push(".SH AUTHOR");
+		lines.push(formatMessageAsRoff(author));
+	}
+	const footer = options.footer ?? page.footer;
+	if (footer) {
+		lines.push(".PP");
+		lines.push(formatMessageAsRoff(footer));
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+export { formatDateForMan, formatDocPageAsMan, formatUsageTermAsRoff };