⌂ Modules nupp nupp.cli nupp.cli
Command-line arguments, from raw tokens up to a whole application.
The usual way in is a record: the types decide the conversion, the doc comments become the help text.
local cli = require ( "nupp.cli" )
@ derive ( cli . Arguments )
local record Options
@ cli ( short = "v" )
verbose : boolean = false
@ cli ( short = "o" , value = "PATH" )
output : string ?
@ cli ( positional = "FILE" )
files : { string } = { }
end
const options , problem = Options . fromCLI ( arg )
assert ( options ~= nil , problem and problem . message )
@derive(cli.Command) goes further and adds metadata, help, and shell completion, with a parent naming its children in subcommands so the tree reads from the top down. Underneath both, optParser and getopt are the syntax-only foundation: a token stream with no types attached, for when the shape of the command line is not a record.
This module also holds the terminal side of a command-line program -- color modes, styles, and tables -- so what a command prints lines up with what it parsed.
See Command-line applications .
Module contents Types Type Kind Description Alignmenttype How a cell sits in its column. Applicationrecord A finite tree of derived command types. ApplicationOptionstype Runtime-only settings for a CLI application. ArgumentRecordinterface Marker implemented by a record deriving Arguments. Cellrecord One cell. ColorModetype How terminal styling is selected. Columnrecord One column. CommandTypetype A record type deriving Command. Completerinterface A lazily invoked source of dynamic values for one CLI field. CompletionCandidaterecord One shell-neutral completion candidate. CompletionRequestrecord Context supplied to a dynamic field completion provider. DecodeErrortype Invocationrecord A command type resolved and decoded without executing it. OptParserrecord An incremental command-line option parser. OptParserConfigtype Syntax policy supplied to optParser. Patterntype One whole-word option form, such as -O2. Runnableinterface The instance contract of a derived executable command. Stylerecord Generic terminal styles shared by CLI applications and their commands. SyntaxErrorrecord A syntax failure found while consuming argv. TableOptionsrecord What to render. TokenKindtype The kind of one classified argv word. ValueAritytype How an option obtains a value.
Functions
Types
Alignmenttype
type Alignment = "left" | "right"
How a cell sits in its column.
Applicationrecord
A finite tree of derived command types.
Members Name Kind Description rootfield commandsfield byParentfield optionsfield resolvemethod Resolves and decodes argv, without writing output or invoking run. helpmethod Renders the application's top-level help. commandHelpmethod Renders help for a command path, or returns nil when it is unknown. completemethod Produces shell-neutral candidates for one cursor position. completionmethod Renders a Bash, Zsh, or Fish completion script from this schema. mainmethod Handles framework options, renders failures, and invokes a typed command.
byParentfield
byParent : { [ any ] : { [ string ] : Descriptor } }
@private
resolvemethod
resolve : function resolve ( self , argv : { string } ) : Invocation ? , any ?
Resolves and decodes argv, without writing output or invoking run.
Arguments Name Type Description selfany argv{ string }
Returns
helpmethod
help : function help ( self ) : string
Renders the application's top-level help.
Arguments Name Type Description selfany
Returns
commandHelpmethod
commandHelp : function commandHelp ( self , path : { string } ) : string ?
Renders help for a command path, or returns nil when it is unknown.
Arguments Name Type Description selfany path{ string }
Returns
completemethod
complete : function complete ( self , request : any ) : { any } , string ?
Produces shell-neutral candidates for one cursor position.
The second result is "files" or "dirs" when the slot is a path the shell should complete itself.
Arguments Name Type Description selfany requestany
Returns Type Description { any } string ?
completionmethod
completion : function completion ( self , shell : "bash" | "zsh" | "fish" ) : string
Renders a Bash, Zsh, or Fish completion script from this schema.
The script asks the program itself, through the hidden __complete command, so what it offers depends on where the cursor is: one command's options rather than every command's, and a value's choices rather than every word the grammar knows. A reply whose first line is :files or :dirs hands the word to the shell's own path completion.
Arguments Name Type Description selfany shell"bash" | "zsh" | "fish"
Returns
mainmethod
main : function main ( self , argv : { string } ) : integer
Handles framework options, renders failures, and invokes a typed command.
Arguments Name Type Description selfany argv{ string }
Returns
ApplicationOptionstype
type ApplicationOptions = {
name : string ? ,
version : string ? ,
stdout : LuaFile ? ,
stderr : LuaFile ? ,
cwd : string ? ,
environment : { [ string ] : string } ? ,
width : integer ? ,
indent : string ? ,
labelLimit : integer ?
}
Runtime-only settings for a CLI application.
ArgumentRecordinterface
Marker implemented by a record deriving Arguments.
Cellrecord
One cell.
Members Name Kind Description textfield What the cell says. paintfield Paints the text, overriding the column's painter for this cell alone. notefield An aside after the text, in its own color: a default a project moved off, a unit, a "(default)" beside the name it... notePaintfield Paints the note.
textfield
What the cell says.
paintfield
paint : ( function ( string ) : string ) ?
Paints the text, overriding the column's painter for this cell alone. How one row reports a level in its own severity color while its neighbors do not.
notefield
An aside after the text, in its own color: a default a project moved off, a unit, a "(default)" beside the name it belongs to. Written separately because it is painted separately, and measured with the text rather than after it, so a column carrying one still lines up with the column beside it.
notePaintfield
notePaint : ( function ( string ) : string ) ?
Paints the note. Defaults to the style's faint, which is what an aside is.
ColorModetype
type ColorMode = "auto" | "always" | "never"
How terminal styling is selected.
Columnrecord
One column.
Members Name Kind Description headingfield What prints above it. alignfield Which side the padding goes on. paintfield Paints every cell in this column that does not paint itself. minimumWidthfield A floor on the width, for a column whose contents are shorter than what they will be once a row appears that fills it.
headingfield
What prints above it. An empty heading still reserves the column's width.
alignfield
Which side the padding goes on. Numbers read as a column when they are right aligned and as noise when they are not.
paintfield
paint : ( function ( string ) : string ) ?
Paints every cell in this column that does not paint itself.
minimumWidthfield
A floor on the width, for a column whose contents are shorter than what they will be once a row appears that fills it.
CommandTypetype
A record type deriving Command.
Completerinterface
A lazily invoked source of dynamic values for one CLI field.
completemethod
Arguments
Returns
CompletionCandidaterecord
One shell-neutral completion candidate.
kindfield
kind : "value" | "file" | "directory" ?
CompletionRequestrecord
Context supplied to a dynamic field completion provider.
environmentfield
environment : { [ string ] : string }
DecodeErrortype
type DecodeError = {
@ readonly kind : string ,
@ readonly message : string ,
@ readonly index : integer ? ,
@ readonly raw : string ? ,
@ readonly option : string ? ,
@ readonly field : string ? ,
@ readonly destination : string ?
}
Invocationrecord
A command type resolved and decoded without executing it.
OptParserrecord
An incremental command-line option parser.
currentKindfield
@private
currentValuefield
@private
currentIndexfield
@private
currentAttachedfield
@private
currentPatternfield
@private
nextmethod
Advances to the next token and returns its kind, or a syntax error.
Token data remains on this parser until the next call to next.
Arguments Name Type Description selfany
Returns
kindmethod
Returns the current token kind.
Arguments Name Type Description selfany
Returns
Raises Type Condition string when the parser has no current token
keymethod
key : function key ( self ) : string
Returns the current option's normalized key.
Arguments Name Type Description selfany
Returns
Raises Type Condition string when the parser has no current token or it is not an option
valuemethod
value : function value ( self ) : string ?
Returns the current option's value, when it has one.
Arguments Name Type Description selfany
Returns
Raises Type Condition string when the parser has no current token or it is not an option
rawmethod
raw : function raw ( self ) : string
Returns the original argv word for the current token.
Arguments Name Type Description selfany
Returns
Raises Type Condition string when the parser has no current token
indexmethod
index : function index ( self ) : integer
Returns the one-based argv index of the current token.
Arguments Name Type Description selfany
Returns
Raises Type Condition string when the parser has no current token
attachedmethod
attached : function attached ( self ) : boolean
Reports whether the current option carried an attached value.
Arguments Name Type Description selfany
Returns
Raises Type Condition string when the parser has no current token or it is not an option
patternmethod
pattern : function pattern ( self ) : boolean
Reports whether the current option matched a configured whole-word form.
Arguments Name Type Description selfany
Returns
Raises Type Condition string when the parser has no current token or it is not an option
remainingmethod
remaining : function remaining ( self ) : { string }
Returns the unclassified suffix in its original order.
Arguments Name Type Description selfany
Returns
originalmethod
original : function original ( self ) : { string }
Returns the original argv table.
Arguments Name Type Description selfany
Returns
OptParserConfigtype
type OptParserConfig = {
arity : { [ string ] : ValueArity } ? ,
patterns : { Pattern } ? ,
stopAtFirstArgument : boolean ? ,
exposeTerminator : boolean ?
}
Syntax policy supplied to optParser.
Patterntype
type Pattern = {
pattern : string ,
key : string
}
One whole-word option form, such as -O2.
Runnableinterface
The instance contract of a derived executable command.
Members Name Kind Description runmethod
runmethod
run : function ( self ) : integer
Arguments
Returns
Stylerecord
Generic terminal styles shared by CLI applications and their commands.
strongmethod
strong : function ( string ) : string
Arguments Name Type Description ?string
Returns
faintmethod
faint : function ( string ) : string
Arguments Name Type Description ?string
Returns
headingmethod
heading : function ( string ) : string
A column heading, a section title: text that names what is beneath it rather than saying anything itself. Named as a role rather than as a colour so the one decision lives here instead of at every table that prints one.
Arguments Name Type Description ?string
Returns
redmethod
red : function ( string ) : string
Arguments Name Type Description ?string
Returns
yellowmethod
yellow : function ( string ) : string
Arguments Name Type Description ?string
Returns
greenmethod
green : function ( string ) : string
Arguments Name Type Description ?string
Returns
cyanmethod
cyan : function ( string ) : string
Arguments Name Type Description ?string
Returns
bluemethod
blue : function ( string ) : string
Arguments Name Type Description ?string
Returns
pathmethod
path : function ( string ) : string
Arguments Name Type Description ?string
Returns
guttermethod
gutter : function ( string ) : string
Arguments Name Type Description ?string
Returns
severityfield
severity : { [ string ] : function ( string ) : string }
SyntaxErrorrecord
A syntax failure found while consuming argv.
kindfield
kind : "missingValue" | "needsAttachedValue"
TableOptionsrecord
What to render.
Members Name Kind Description columnsfield rowsfield Rows, each as many cells as there are columns. stylefield Where the heading color and any cell colors come from. headingPaintfield Paints the heading row. gapfield Printed between columns. indentfield Printed before every line, heading included. showHeadingfield Whether to print the heading row at all. widthfield Columns available on screen.
rowsfield
Rows, each as many cells as there are columns. A short row is padded with blanks rather than refused, so a caller may leave a trailing cell out.
stylefield
Where the heading color and any cell colors come from. Supply the style selected for the stream being written to; omit it and nothing is painted.
headingPaintfield
headingPaint : ( function ( string ) : string ) ?
Paints the heading row. Defaults to the style's heading role.
gapfield
Printed between columns. Two spaces unless a caller says otherwise.
indentfield
Printed before every line, heading included.
showHeadingfield
Whether to print the heading row at all.
widthfield
Columns available on screen. The last column is cut to fit rather than left to wrap. Nil cuts nothing, which is what a pipe wants.
TokenKindtype
type TokenKind = "shortOption" | "longOption" | "argument" | "terminator"
The kind of one classified argv word.
ValueAritytype
type ValueArity = "none" | "required" | "optionalAttached" | "attachedOnly"
How an option obtains a value.
Functions
cliModule.annotatedCellfunction
function cliModule . annotatedCell ( value : string , note : string , paint : ( function ( string ) : string ) ? ) : cliModule . Cell
A table cell carrying an aside, measured with the cell and painted apart from it.
Arguments Name Type Description valuestring notestring paint( function ( string ) : string ) ?
Returns Type Description cliModule . Cell
cliModule.applicationfunction
Builds an application from a command type and its subcommands tree.
Type parameters
Arguments
Returns
cliModule.Argumentscomptime function
@comptime
Derives typed argv decoding for a record.
Arguments
Returns
cliModule.cellfunction
A plain table cell.
Arguments Name Type Description valuestring
Returns Type Description cliModule . Cell
cliModule.colorEnabledfunction
Reports whether escapes should be written to one stream.
Arguments
Returns
cliModule.columnsfunction
Reports how many columns one stream's terminal has, when it has one.
Arguments
Returns
cliModule.Commandcomptime function
@comptime
Derives typed argv decoding and a self-describing executable command.
Arguments
Returns
cliModule.commandfunction
Returns the descriptor generated for a command type.
Type parameters
Arguments Name Type Description subjectType < T >
Returns Type Description table ? string ?
cliModule.decodeAsfunction
Decodes argv as a record deriving Arguments or Command.
Type parameters
Arguments Name Type Description subjectType < T > argv{ string }
Returns
cliModule.isTerminalfunction
Reports whether one stream is connected to a terminal.
Arguments
Returns
cliModule.paintedCellfunction
A table cell that paints itself, whatever its column says.
Arguments Name Type Description valuestring paintfunction ( string ) : string
Returns Type Description cliModule . Cell
cliModule.schemafunction
Returns the CLI schema carried by a derived type.
Type parameters
Arguments Name Type Description subjectType < T >
Returns
cliModule.setColorModefunction
Sets the process-wide default color policy.
Arguments
Returns
cliModule.severityfunction
function cliModule . severity ( styles : cliModule . Style , name : string ? ) : function ( string ) : string
Selects the color associated with a diagnostic severity.
Arguments Name Type Description stylescliModule . Style namestring ?
Returns Type Description function ( string ) : string
cliModule.stylefunction
Returns the generic styles selected for one stream.
Arguments
Returns Type Description cliModule . Style
cliModule.tablefunction
Renders aligned columns, painting each cell after it is padded.
Arguments
Returns
cliModule.withColorModefunction
Runs a body under one color policy and restores the previous policy.
Arguments Name Type Description wantedcliModule . ColorMode bodyfunction ( ) : nil
Returns
cliModule.writeTablefunction
Renders aligned columns straight to a stream.
Arguments
Returns
← Previous nupp.checksum.spi Next → nupp.codec