@optique/man 0.10.0-dev.0

package/dist/roff-i3JSYqke.js

@@ -0,0 +1,122 @@
+//#region src/roff.ts
+/**
+* Escapes backslashes in text for roff.
+* This is an internal helper that only handles backslash escaping.
+*
+* @param text The text to escape.
+* @returns The text with backslashes escaped.
+*/
+function escapeBackslashes(text) {
+	return text.replace(/\\/g, "\\\\");
+}
+/**
+* Escapes period and single quote at line starts.
+* In roff, these characters have special meaning when at the start of a line.
+*
+* @param text The text to process.
+* @returns The text with line-start special characters escaped.
+*/
+function escapeLineStarts(text) {
+	if (text === "") return "";
+	let result = text;
+	if (result.startsWith(".") || result.startsWith("'")) result = "\\&" + result;
+	result = result.replace(/\n([.'])/g, "\n\\&$1");
+	return result;
+}
+/**
+* Escapes special roff characters in plain text.
+*
+* This function handles the following escapes:
+* - Backslash (`\`) → `\\`
+* - Period (`.`) at line start → `\&.`
+* - Single quote (`'`) at line start → `\&'`
+*
+* @param text The plain text to escape.
+* @returns The escaped text safe for use in roff documents.
+* @since 0.10.0
+*/
+function escapeRoff(text) {
+	if (text === "") return "";
+	return escapeLineStarts(escapeBackslashes(text));
+}
+/**
+* Escapes hyphens in option names to prevent line breaks.
+*
+* In roff, a regular hyphen (`-`) can be used as a line break point.
+* For option names like `--verbose`, we want to use `\-` which prevents
+* line breaks and renders as a proper minus sign.
+*
+* @param text The text containing hyphens to escape.
+* @returns The text with hyphens escaped as `\-`.
+* @since 0.10.0
+*/
+function escapeHyphens(text) {
+	return text.replace(/-/g, "\\-");
+}
+/**
+* Formats a single {@link MessageTerm} as roff markup.
+* Note: This does NOT escape line-start characters (. and ') because
+* these terms may be concatenated with other terms. Line-start escaping
+* is done in formatMessageAsRoff after all terms are joined.
+*
+* @param term The message term to format.
+* @returns The roff-formatted string.
+*/
+function formatTermAsRoff(term) {
+	switch (term.type) {
+		case "text": return escapeBackslashes(term.text);
+		case "optionName": return `\\fB${escapeHyphens(term.optionName)}\\fR`;
+		case "optionNames": return term.optionNames.map((name) => `\\fB${escapeHyphens(name)}\\fR`).join(", ");
+		case "metavar": return `\\fI${escapeBackslashes(term.metavar)}\\fR`;
+		case "value": return `"${escapeBackslashes(term.value)}"`;
+		case "values":
+			if (term.values.length === 0) return "";
+			return term.values.map((v) => `"${escapeBackslashes(v)}"`).join(" ");
+		case "envVar": return `\\fB${escapeBackslashes(term.envVar)}\\fR`;
+		case "commandLine": return `\\fB${escapeHyphens(escapeBackslashes(term.commandLine))}\\fR`;
+		default: {
+			const _exhaustive = term;
+			throw new TypeError(`Unknown message term type: ${_exhaustive.type}.`);
+		}
+	}
+}
+/**
+* Formats a {@link Message} as roff markup for use in man pages.
+*
+* This function converts Optique's structured message format into roff
+* markup suitable for man pages. Each message term type is converted
+* to appropriate roff formatting:
+*
+* | Term Type | Roff Output |
+* |-----------|-------------|
+* | `text` | Plain text (escaped) |
+* | `optionName` | `\fB--option\fR` (bold) |
+* | `optionNames` | `\fB--opt1\fR, \fB-o\fR` (comma-separated bold) |
+* | `metavar` | `\fIFILE\fR` (italic) |
+* | `value` | `"value"` (quoted) |
+* | `values` | `"a" "b" "c"` (space-separated quoted) |
+* | `envVar` | `\fBVAR\fR` (bold) |
+* | `commandLine` | `\fBcmd\fR` (bold) |
+*
+* @example
+* ```typescript
+* import { formatMessageAsRoff } from "@optique/man/roff";
+* import { message, optionName, metavar } from "@optique/core/message";
+*
+* const msg = message`Use ${optionName("--config")} ${metavar("FILE")}`;
+* const roff = formatMessageAsRoff(msg);
+* // => "Use \\fB\\-\\-config\\fR \\fIFILE\\fR"
+* ```
+*
+* @param msg The message to format.
+* @returns The roff-formatted string.
+* @since 0.10.0
+*/
+function formatMessageAsRoff(msg) {
+	const joined = msg.map(formatTermAsRoff).join("");
+	const escaped = escapeLineStarts(joined);
+	return escaped.replace(/\n\n+/g, "\n.PP\n");
+}
+
+//#endregion
+export { escapeHyphens, escapeRoff, formatMessageAsRoff };

package/dist/roff.cjs

@@ -0,0 +1,5 @@
+const require_roff = require('./roff-DzxoXJIL.cjs');
+
+exports.escapeHyphens = require_roff.escapeHyphens;
+exports.escapeRoff = require_roff.escapeRoff;
+exports.formatMessageAsRoff = require_roff.formatMessageAsRoff;

package/dist/roff.d.cts

@@ -0,0 +1,2 @@
+import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-Cs3_UBG5.cjs";
+export { escapeHyphens, escapeRoff, formatMessageAsRoff };

package/dist/roff.d.ts

@@ -0,0 +1,2 @@
+import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-CK3-yKaY.js";
+export { escapeHyphens, escapeRoff, formatMessageAsRoff };

package/dist/roff.js

@@ -0,0 +1,3 @@
+import { escapeHyphens, escapeRoff, formatMessageAsRoff } from "./roff-i3JSYqke.js";
+
+export { escapeHyphens, escapeRoff, formatMessageAsRoff };

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@optique/man",
+  "version": "0.10.0-dev.0",
+  "description": "Man page generator for Optique CLI parsers",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "man",
+    "manpage",
+    "documentation",
+    "roff",
+    "groff"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/man/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./roff": {
+      "types": {
+        "import": "./dist/roff.d.ts",
+        "require": "./dist/roff.d.cts"
+      },
+      "import": "./dist/roff.js",
+      "require": "./dist/roff.cjs"
+    },
+    "./man": {
+      "types": {
+        "import": "./dist/man.d.ts",
+        "require": "./dist/man.d.cts"
+      },
+      "import": "./dist/man.js",
+      "require": "./dist/man.cjs"
+    },
+    "./cli": {
+      "types": {
+        "import": "./dist/cli.d.ts",
+        "require": "./dist/cli.d.cts"
+      },
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.cjs"
+    }
+  },
+  "sideEffects": false,
+  "bin": {
+    "optique-man": "./dist/cli.js"
+  },
+  "dependencies": {
+    "@optique/core": "",
+    "@optique/run": ""
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test 'src/**/*.test.ts'",
+    "test:bun": "tsdown && bun test src/",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --experimental-transform-types --test 'src/**/*.test.ts' && bun test src/ && deno test"
+  }
+}