cli-generate(1)

✨ NAME ✨

cli-generate — bestie, this thing generates source code and documentation straight out of your CLI descriptions 💅 (it's the cli-generate(1) page from the General Commands Manual, in case you were wondering 🫶)

---

🌸 SYNOPSIS 🌸

cli-generate [ -c | -h | -m | -w ] FILENAME.cli

---

🦋 DESCRIPTION 🦋

💫 Operation

okay so here's the tea: cli-generate reads in a CLI (command line interface) description file, parses it into its various sections, and prints out one of a set of output files. In typical usage, that output would be directed to a file and later compiled or included in other sources. no cap, that's literally the whole vibe ✨

The CLI file (named PROGRAM.cli) is divided into two parts, a header (formatted much like a standard mail header) and a series of sections. Headers and sections other than those specified below are ignored. All headers and sections are optional — so yeah, nothing is mandatory, it's giving "chill, do what you want" 😌

📝 File Format

file = header "\n" *section

header = *(header-line "\n")

header-line = header-field ":" whitespace value

whitespace = *(SPACE / TAB)

section = "[" name "]" "\n" lines

lines = *( line "\n" )

🎀 Headers

• Description: — a one-line description of what the program does. short, sweet, iconic.
• Include: — add C statements to #include the given source file. Must be formatted as either <file> or file. (yes bestie, the angle brackets matter, choose wisely 🙈)
• Min: — the minimum number of allowed non-option arguments. Defaults to 0.
• Max: — the maximum number of allowed non-option arguments. Negative values mean unlimited. Defaults to -1.
• Show-Pid: — set to non-zero if the resulting program is to show its PID with every output message. Defaults to 0.
• Usage: — a one-line description of the intended usage. Defaults to empty.

🌈 Section Names

• [prefix] — the text in this section is shown in the command usage before the options description.
• [options] — the list of options this program accepts. See below for their format 👀
• [suffix] — the text in this section is shown in the command usage after the options description.
• [description]
• [return value]
• [errors]
• [examples]
• [environment]
• [files]
• [see also]
• [notes]
• [caveats]
• [diagnostics]
• [bugs]
• [restrictions]
• [author]
• [history]

These sections are formatted and copied into the man page in the standard order. periodt 📚✨

💖 Options Format

options = *(option / separator)

option = option1 "\n" option2 "\n" *(line "\n")

option1 = [shortopt] [longopt] type ["=" flag-value] variable ["=" init]

option2 = helpstr ["=" default]

separator = "-- " text "\n"

shortopt = "-" character

longopt = "--" word

type = "FLAG" / "COUNTER" / "INTEGER" / "UINTEGER" / "STRING" / "STRINGLIST" / "FUNCTION"

If not specified, flag-value and init are 0, and default is empty. (so like, defaults on defaults on defaults, we love a low-maintenance queen 👑)

🧚 Formatting

Except for [prefix], [options], and [suffix], all of the sections support formatting instructions similar to that of TeXinfo (but greatly simplified). ok so here's every single one, don't skip:

• @strong{text} — use "strong" (bold) text.
• @command{text} — indicate the name of a command.
• @option{text} — indicate a command-line option.
• @emph{text} — use "emphatic" (italicized) text.
• @var{text} — indicate a metasyntactic variable.
• @env{text} — indicate an environment variable.
• @file{text} — indicate the name of a file.
• @code{text} — indicate text that is a literal example of a piece of a program.
• @samp{text} — indicate text that is a literal example of a sequence of characters.
• @example
• @end example — the text between these two tags is indented.
• @verbatim
• @end verbatim — everything between these two tags is passed as-is (verbatim) to the output.
• @table @format
• @end table — mark up a two-column table, or "definition list".
• @item paragraph — add an item to a table. The @item starts a paragraph that will be the actual list entry. Any subsequent paragraphs will be typeset seperately.

---

💅 OPTIONS 💅

• -c — output C source code.
• -h — output C header file.
• -m — output a UNIX man page.
• -w — output HTML (web) markup.

---

🍓 EXAMPLES 🍓

Here is a sample CLI file, containing many of the described elements. (a whole main character, honestly 🌟)

Min: 1
Max: 1
Usage: PATH
Description: Create a file.
Show-Pid: 0
Include: <stdio.h>

[prefix]
If the given PATH is a directory, it is suffixed with another name.

[description]
@program generates a new random file from a variety of sources including
@command{ls} and @command{ps} output.

If the given @option{PATH} is a directory, it is suffixed with another
name of my choosing.

[options]
-v --verbose FLAG=1 opt_verbose

-t --type STRING opt_type = "type1"
The type of the file to generate. = type1
Possible types for this include @option{type1} and @option{base64}.

---

💜 AUTHOR 💜

Bruce Guenter <bruce@untroubled.org> — shoutout to the legend, we stan 🫶

---

okay that's the whole page bestie, you're officially fluent in cli-generate 💖 this was the cli-generate(1) page from the General Commands Manual, and yes, the footer said the exact same thing as the header because that's just how man pages do 😭 go forth and generate, no cap ✨🦋🎀