@optique/core 0.10.0-dev.327 → 0.10.0-dev.328

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/dist/doc.cjs +42 -2
  2. package/dist/doc.d.cts +15 -0
  3. package/dist/doc.d.ts +15 -0
  4. package/dist/doc.js +42 -2
  5. package/dist/facade.cjs +10 -1
  6. package/dist/facade.d.cts +19 -1
  7. package/dist/facade.d.ts +19 -1
  8. package/dist/facade.js +10 -1
  9. package/dist/program.d.cts +1 -1
  10. package/dist/program.d.ts +1 -1
  11. package/package.json +1 -1
package/dist/doc.cjs CHANGED
@@ -46,7 +46,8 @@ function formatDocPage(programName, page, options = {}) {
46
46
  output += "\n";
47
47
  }
48
48
  if (page.usage != null) {
49
- output += "Usage: ";
49
+ const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
50
+ output += usageLabel;
50
51
  output += indentLines(require_usage.formatUsage(programName, page.usage, {
51
52
  colors: options.colors,
52
53
  maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
@@ -67,7 +68,10 @@ function formatDocPage(programName, page, options = {}) {
67
68
  for (const section of sections) {
68
69
  if (section.entries.length < 1) continue;
69
70
  output += "\n";
70
- if (section.title != null) output += `${section.title}:\n`;
71
+ if (section.title != null) {
72
+ const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
73
+ output += sectionLabel;
74
+ }
71
75
  for (const entry of section.entries) {
72
76
  const term = require_usage.formatUsageTerm(entry.term, {
73
77
  colors: options.colors,
@@ -92,6 +96,42 @@ function formatDocPage(programName, page, options = {}) {
92
96
  output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)} ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
93
97
  }
94
98
  }
99
+ if (page.examples != null) {
100
+ output += "\n";
101
+ const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
102
+ output += examplesLabel;
103
+ const examplesContent = require_message.formatMessage(page.examples, {
104
+ colors: options.colors,
105
+ maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
106
+ quotes: !options.colors
107
+ });
108
+ output += " " + indentLines(examplesContent, 2);
109
+ output += "\n";
110
+ }
111
+ if (page.author != null) {
112
+ output += "\n";
113
+ const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
114
+ output += authorLabel;
115
+ const authorContent = require_message.formatMessage(page.author, {
116
+ colors: options.colors,
117
+ maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
118
+ quotes: !options.colors
119
+ });
120
+ output += " " + indentLines(authorContent, 2);
121
+ output += "\n";
122
+ }
123
+ if (page.bugs != null) {
124
+ output += "\n";
125
+ const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
126
+ output += bugsLabel;
127
+ const bugsContent = require_message.formatMessage(page.bugs, {
128
+ colors: options.colors,
129
+ maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
130
+ quotes: !options.colors
131
+ });
132
+ output += " " + indentLines(bugsContent, 2);
133
+ output += "\n";
134
+ }
95
135
  if (page.footer != null) {
96
136
  output += "\n";
97
137
  output += require_message.formatMessage(page.footer, {
package/dist/doc.d.cts CHANGED
@@ -43,6 +43,21 @@ interface DocPage {
43
43
  readonly usage?: Usage;
44
44
  readonly description?: Message;
45
45
  readonly sections: readonly DocSection[];
46
+ /**
47
+ * Usage examples for the program.
48
+ * @since 0.10.0
49
+ */
50
+ readonly examples?: Message;
51
+ /**
52
+ * Author information.
53
+ * @since 0.10.0
54
+ */
55
+ readonly author?: Message;
56
+ /**
57
+ * Information about where to report bugs.
58
+ * @since 0.10.0
59
+ */
60
+ readonly bugs?: Message;
46
61
  readonly footer?: Message;
47
62
  }
48
63
  /**
package/dist/doc.d.ts CHANGED
@@ -43,6 +43,21 @@ interface DocPage {
43
43
  readonly usage?: Usage;
44
44
  readonly description?: Message;
45
45
  readonly sections: readonly DocSection[];
46
+ /**
47
+ * Usage examples for the program.
48
+ * @since 0.10.0
49
+ */
50
+ readonly examples?: Message;
51
+ /**
52
+ * Author information.
53
+ * @since 0.10.0
54
+ */
55
+ readonly author?: Message;
56
+ /**
57
+ * Information about where to report bugs.
58
+ * @since 0.10.0
59
+ */
60
+ readonly bugs?: Message;
46
61
  readonly footer?: Message;
47
62
  }
48
63
  /**
package/dist/doc.js CHANGED
@@ -46,7 +46,8 @@ function formatDocPage(programName, page, options = {}) {
46
46
  output += "\n";
47
47
  }
48
48
  if (page.usage != null) {
49
- output += "Usage: ";
49
+ const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
50
+ output += usageLabel;
50
51
  output += indentLines(formatUsage(programName, page.usage, {
51
52
  colors: options.colors,
52
53
  maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
@@ -67,7 +68,10 @@ function formatDocPage(programName, page, options = {}) {
67
68
  for (const section of sections) {
68
69
  if (section.entries.length < 1) continue;
69
70
  output += "\n";
70
- if (section.title != null) output += `${section.title}:\n`;
71
+ if (section.title != null) {
72
+ const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
73
+ output += sectionLabel;
74
+ }
71
75
  for (const entry of section.entries) {
72
76
  const term = formatUsageTerm(entry.term, {
73
77
  colors: options.colors,
@@ -92,6 +96,42 @@ function formatDocPage(programName, page, options = {}) {
92
96
  output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)} ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
93
97
  }
94
98
  }
99
+ if (page.examples != null) {
100
+ output += "\n";
101
+ const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
102
+ output += examplesLabel;
103
+ const examplesContent = formatMessage(page.examples, {
104
+ colors: options.colors,
105
+ maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
106
+ quotes: !options.colors
107
+ });
108
+ output += " " + indentLines(examplesContent, 2);
109
+ output += "\n";
110
+ }
111
+ if (page.author != null) {
112
+ output += "\n";
113
+ const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
114
+ output += authorLabel;
115
+ const authorContent = formatMessage(page.author, {
116
+ colors: options.colors,
117
+ maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
118
+ quotes: !options.colors
119
+ });
120
+ output += " " + indentLines(authorContent, 2);
121
+ output += "\n";
122
+ }
123
+ if (page.bugs != null) {
124
+ output += "\n";
125
+ const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
126
+ output += bugsLabel;
127
+ const bugsContent = formatMessage(page.bugs, {
128
+ colors: options.colors,
129
+ maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
130
+ quotes: !options.colors
131
+ });
132
+ output += " " + indentLines(bugsContent, 2);
133
+ output += "\n";
134
+ }
95
135
  if (page.footer != null) {
96
136
  output += "\n";
97
137
  output += formatMessage(page.footer, {
package/dist/facade.cjs CHANGED
@@ -419,6 +419,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
419
419
  ...options,
420
420
  brief: options.brief ?? program.metadata.brief,
421
421
  description: options.description ?? program.metadata.description,
422
+ examples: options.examples ?? program.metadata.examples,
423
+ author: options.author ?? program.metadata.author,
424
+ bugs: options.bugs ?? program.metadata.bugs,
422
425
  footer: options.footer ?? program.metadata.footer
423
426
  };
424
427
  } else {
@@ -429,7 +432,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
429
432
  }
430
433
  const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
431
434
  throw new RunParserError("Failed to parse command line arguments.");
432
- }, stderr = console.error, stdout = console.log, brief, description, footer } = options;
435
+ }, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
433
436
  const helpMode = options.help?.mode ?? "option";
434
437
  const onHelp = options.help?.onShow ?? (() => ({}));
435
438
  const versionMode = options.version?.mode ?? "option";
@@ -530,6 +533,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
530
533
  ...doc,
531
534
  brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
532
535
  description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
536
+ examples: !isMetaCommandHelp ? examples ?? doc.examples : doc.examples,
537
+ author: !isMetaCommandHelp ? author ?? doc.author : doc.author,
538
+ bugs: !isMetaCommandHelp ? bugs ?? doc.bugs : doc.bugs,
533
539
  footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
534
540
  };
535
541
  stdout(require_doc.formatDocPage(programName, augmentedDoc, {
@@ -557,6 +563,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
557
563
  ...doc,
558
564
  brief: brief ?? doc.brief,
559
565
  description: description ?? doc.description,
566
+ examples: examples ?? doc.examples,
567
+ author: author ?? doc.author,
568
+ bugs: bugs ?? doc.bugs,
560
569
  footer: footer ?? doc.footer
561
570
  };
562
571
  stderr(require_doc.formatDocPage(programName, augmentedDoc, {
package/dist/facade.d.cts CHANGED
@@ -178,6 +178,24 @@ interface RunOptions<THelp, TError> {
178
178
  * @since 0.4.0
179
179
  */
180
180
  readonly description?: Message;
181
+ /**
182
+ * Usage examples for the program.
183
+ *
184
+ * @since 0.10.0
185
+ */
186
+ readonly examples?: Message;
187
+ /**
188
+ * Author information.
189
+ *
190
+ * @since 0.10.0
191
+ */
192
+ readonly author?: Message;
193
+ /**
194
+ * Information about where to report bugs.
195
+ *
196
+ * @since 0.10.0
197
+ */
198
+ readonly bugs?: Message;
181
199
  /**
182
200
  * Footer text shown at the bottom of help text.
183
201
  *
@@ -214,7 +232,7 @@ interface RunOptions<THelp, TError> {
214
232
  * callbacks.
215
233
  * @throws {RunParserError} When parsing fails and no `onError` callback is
216
234
  * provided.
217
- * @since 0.11.0 Added support for {@link Program} objects.
235
+ * @since 0.10.0 Added support for {@link Program} objects.
218
236
  */
219
237
  declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
220
238
  declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
package/dist/facade.d.ts CHANGED
@@ -178,6 +178,24 @@ interface RunOptions<THelp, TError> {
178
178
  * @since 0.4.0
179
179
  */
180
180
  readonly description?: Message;
181
+ /**
182
+ * Usage examples for the program.
183
+ *
184
+ * @since 0.10.0
185
+ */
186
+ readonly examples?: Message;
187
+ /**
188
+ * Author information.
189
+ *
190
+ * @since 0.10.0
191
+ */
192
+ readonly author?: Message;
193
+ /**
194
+ * Information about where to report bugs.
195
+ *
196
+ * @since 0.10.0
197
+ */
198
+ readonly bugs?: Message;
181
199
  /**
182
200
  * Footer text shown at the bottom of help text.
183
201
  *
@@ -214,7 +232,7 @@ interface RunOptions<THelp, TError> {
214
232
  * callbacks.
215
233
  * @throws {RunParserError} When parsing fails and no `onError` callback is
216
234
  * provided.
217
- * @since 0.11.0 Added support for {@link Program} objects.
235
+ * @since 0.10.0 Added support for {@link Program} objects.
218
236
  */
219
237
  declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
220
238
  declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;
package/dist/facade.js CHANGED
@@ -419,6 +419,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
419
419
  ...options,
420
420
  brief: options.brief ?? program.metadata.brief,
421
421
  description: options.description ?? program.metadata.description,
422
+ examples: options.examples ?? program.metadata.examples,
423
+ author: options.author ?? program.metadata.author,
424
+ bugs: options.bugs ?? program.metadata.bugs,
422
425
  footer: options.footer ?? program.metadata.footer
423
426
  };
424
427
  } else {
@@ -429,7 +432,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
429
432
  }
430
433
  const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
431
434
  throw new RunParserError("Failed to parse command line arguments.");
432
- }, stderr = console.error, stdout = console.log, brief, description, footer } = options;
435
+ }, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
433
436
  const helpMode = options.help?.mode ?? "option";
434
437
  const onHelp = options.help?.onShow ?? (() => ({}));
435
438
  const versionMode = options.version?.mode ?? "option";
@@ -530,6 +533,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
530
533
  ...doc,
531
534
  brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
532
535
  description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
536
+ examples: !isMetaCommandHelp ? examples ?? doc.examples : doc.examples,
537
+ author: !isMetaCommandHelp ? author ?? doc.author : doc.author,
538
+ bugs: !isMetaCommandHelp ? bugs ?? doc.bugs : doc.bugs,
533
539
  footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
534
540
  };
535
541
  stdout(formatDocPage(programName, augmentedDoc, {
@@ -557,6 +563,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
557
563
  ...doc,
558
564
  brief: brief ?? doc.brief,
559
565
  description: description ?? doc.description,
566
+ examples: examples ?? doc.examples,
567
+ author: author ?? doc.author,
568
+ bugs: bugs ?? doc.bugs,
560
569
  footer: footer ?? doc.footer
561
570
  };
562
571
  stderr(formatDocPage(programName, augmentedDoc, {
package/dist/program.d.cts CHANGED
@@ -6,7 +6,7 @@ import { Mode, Parser } from "./parser.cjs";
6
6
  /**
7
7
  * Metadata for a CLI program.
8
8
  *
9
- * @since 0.11.0
9
+ * @since 0.10.0
10
10
  */
11
11
  interface ProgramMetadata {
12
12
  /**
package/dist/program.d.ts CHANGED
@@ -6,7 +6,7 @@ import { Mode, Parser } from "./parser.js";
6
6
  /**
7
7
  * Metadata for a CLI program.
8
8
  *
9
- * @since 0.11.0
9
+ * @since 0.10.0
10
10
  */
11
11
  interface ProgramMetadata {
12
12
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optique/core",
3
- "version": "0.10.0-dev.327+76d21ea0",
3
+ "version": "0.10.0-dev.328+4e5f40d5",
4
4
  "description": "Type-safe combinatorial command-line interface parser",
5
5
  "keywords": [
6
6
  "CLI",