class RemiLib::Args::ArgParser

Overview

The main class for parsing command line arguments.

Defined in:

remilib/args/arg-parsing.cr

Constructors

Class Method Summary

Instance Method Summary

Constructor Detail

def self.new(progName : String, progVersion : String, *, helpLongName : String = "--help", helpShortName : Char = 'h', verLongName : String = "--version", verShortName : Char = 'V', newProgBinName : String = PROGRAM_NAME, newArgv0 : String = PROGRAM_NAME) #

Creates a new ArgParser instance. A help argument and a version argument will always be added as FlagArguments.


[View source]

Class Method Detail

def self.defaultHelpPrinter(parser : ArgParser) : Nil #

The default printer for help arguments (e.g. "--help"/"-h").

The default output looks something like this (depending on the values of #preHelpText and #postHelpText:

Usage: /path/to/binary [options]
General Options
================================================================================
--help     / -h   : Show this help text
--version  / -V   : Show version information
--foo  x   / -f x : Adds a foo

[View source]
def self.defaultVerPrinter(parser : ArgParser) : Nil #

The default printer for version arguments (e.g. "--version"/"-V"). The default output looks something like this (depending on the values of #preVerText and #postVerText:

My Program v0.1.0

[View source]

Instance Method Detail

def [](name : String) : Argument #

Returns the Argument that has the given Argument#longName. The "--" prefix is optional.


[View source]
def [](name : Char) : Argument #

Returns the Argument that has the given Argument#shortName.


[View source]
def addArg(arg : Argument) #

Adds a new Argument to this parser. The argument must have a Argument#longName. Arguments with duplicate Argument#longNames and Argument#shortNames will raise an Exception.


[View source]
def addFlag(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "") : FlagArgument #

Adds a new FlagArgument.


[View source]
def addFlag(longName : String, shortName : Char | Nil = nil, &) : Nil #

Adds a new FlagArgument.


[View source]
def addFloat(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Float64 = 0.0, minimum : Float64 = Float64::MIN, maximum : Float64 = Float64::MAX) : FloatArgument #

Adds a new FloatArgument.


[View source]
def addFloat(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Float64 = 0.0, minimum : Float64 = Float64::MIN, maximum : Float64 = Float64::MAX, &) : Nil #

Adds a new FloatArgument.


[View source]
def addInt(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Int = 0, minimum : Int = Int64::MIN, maximum : Int = Int64::MAX) : IntArgument #

Adds a new IntArgument.


[View source]
def addInt(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Int = 0, minimum : Int = Int64::MIN, maximum : Int = Int64::MAX, &) : Nil #

Adds a new IntArgument.


[View source]
def addMultiFlag(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "") : MultiFlagArgument #

Adds a new MultiFlagArgument.


[View source]
def addMultiFlag(longName : String, shortName : Char | Nil = nil, &) : Nil #

Adds a new MultiFlagArgument.


[View source]
def addMultiFloat(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Array(Float64) = [] of Float64) : MultiIntArgument #

Adds a new MultiIntArgument.


[View source]
def addMultiInt(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Array(Int64) = [] of Int64) : MultiIntArgument #

Adds a new MultiIntArgument.


[View source]
def addMultiInt(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Array(Float64) = [] of Float64, &) : Nil #

Adds a new MultiIntArgument.


[View source]
def addMultiString(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : Array(String) = [] of String, constraints : Array(String) | Nil = nil) : MultiStringArgument #

Adds a new MultiStringArgument.


[View source]
def addMultiString(longName : String, shortName : Char | Nil = nil, *, group : String = "", &) : Nil #

Adds a new MultiStringArgument.


[View source]
def addString(longName : String, shortName : Char | Nil = nil, *, group : String = "", help : String = "", default : String = "", constraints : Array(String) | Nil = nil) : StringArgument #

Adds a new StringArgument.


[View source]
def addString(longName : String, shortName : Char | Nil = nil, *, group : String = "", &) : Nil #

Adds a new StringArgument.


[View source]
def allArgGroups : Array(String) #

Returns an array of Strings containing all fo the argument groups. Note that the default argument group is an empty string.


[View source]
def allArgsInGroup(group : String) : Array(Argument) #

Returns an array of Arguments that are in the given group.


[View source]
def args : Hash(String, Argument) #

The Arguments defined for this parser. Do not add arguments directly to this field - use one of the add* methods instead.


[View source]
def detectHelp=(detectHelp : Bool) #

When true, the help argument (e.g. "--help"/"-h") will be processed. Otherwise it is ignored.


[View source]
def detectHelp? : Bool #

When true, the help argument (e.g. "--help"/"-h") will be processed. Otherwise it is ignored.


[View source]
def detectVer=(detectVer : Bool) #

When true, the version argument (e.g. "--version"/"-V") will be processed. Otherwise it is ignored.


[View source]
def detectVer? : Bool #

When true, the version argument (e.g. "--version"/"-V") will be processed. Otherwise it is ignored.


[View source]
def doubleDashPositional=(doubleDashPositional : Bool) #

When true, the double dash -- will be treated as a positional argument.


[View source]
def doubleDashPositional? : Bool #

When true, the double dash -- will be treated as a positional argument.


[View source]
def each(&) : Nil #

Executes a block on every argument.


[View source]
def eachCalled(&) : Nil #

Executes a block on every argument that was Argument#called.


[View source]
def helpPrinter : HelpPrinterFunc #

This will be called when a help argument (e.g. "--help"/"-h") is found on the command line.


[View source]
def helpPrinter=(helpPrinter : HelpPrinterFunc) #

This will be called when a help argument (e.g. "--help"/"-h") is found on the command line.


[View source]
def longestArgName : Int32 #

Returns the length of the longest Argument#longName found in #args.


[View source]
def parse(theseArgs : Array(String)) : Nil #

Parses an array containing command line arguments.

If a help argument or version argument is found on the command line, and #detectHelp/#detectVer is true, then the corresponding #helpPrinter/#verPrinter will be called.

If a help argument or version argument is found on the command line, and #quitOnHelp/#quitOnVer is true, then exit(0) will be called after executing the corresponding method.

After parsing, any argument that has a Argument#callback method will have that method executed.


[View source]
def parse : Nil #

Parses ARGV.

If a help argument or version argument is found on the command line, and #detectHelp/#detectVer is true, then the corresponding #helpPrinter/#verPrinter will be called.

If a help argument or version argument is found on the command line, and #quitOnHelp/#quitOnVer is true, then exit(0) will be called after executing the corresponding method.

After parsing, any argument that has a Argument#callback method will have that method executed.


[View source]
def positionalArgs : Array(String) #

Any non-argument strings left on the command line after parsing.


[View source]
def positionalArgs=(positionalArgs : Array(String)) #

Any non-argument strings left on the command line after parsing.


[View source]
def postHelpText : String #

A string that is to be printed after the list of arguments when a help argument (e.g. "--help"/"-h") is found on the command line. A newline will be appended automatically.


[View source]
def postHelpText=(postHelpText : String) #

A string that is to be printed after the list of arguments when a help argument (e.g. "--help"/"-h") is found on the command line. A newline will be appended automatically.


[View source]
def postVerText : String #

A string that is to be printed after the version information when a version argument (e.g. "--version"/"-V") is found on the command line. A newline will be appended automatically.


[View source]
def postVerText=(postVerText : String) #

A string that is to be printed after the version information when a version argument (e.g. "--version"/"-V") is found on the command line. A newline will be appended automatically.


[View source]
def preHelpText : String #

A string that is to be printed after the "Usage:" line but before the list of arguments when a help argument (e.g. "--help"/"-h") is found on the command line. A newline will be appended automatically.


[View source]
def preHelpText=(preHelpText : String) #

A string that is to be printed after the "Usage:" line but before the list of arguments when a help argument (e.g. "--help"/"-h") is found on the command line. A newline will be appended automatically.


[View source]
def preVerText : String #

A string that is to be printed before version information when a version argument (e.g. "--version"/"-V") is found on the command line. A newline will be appended automatically.


[View source]
def preVerText=(preVerText : String) #

A string that is to be printed before version information when a version argument (e.g. "--version"/"-V") is found on the command line. A newline will be appended automatically.


[View source]
def progBinName : String #

The name of the binary using this ArgParser.


[View source]
def progBinName=(newName : String) #

Sets the name of the binary using this ArgParser.


[View source]
def progName : String #

The name of the program using this parser. Used when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def progName=(progName : String) #

The name of the program using this parser. Used when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def progVersion : String #

The version of the program using this parser. Used when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def progVersion=(progVersion : String) #

The version of the program using this parser. Used when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def quitOnHelp=(quitOnHelp : Bool) #

When true, #parse will call exit(0) after printing help when a help argument (e.g. "--help"/"-h") is found on the command line.


[View source]
def quitOnHelp? : Bool #

When true, #parse will call exit(0) after printing help when a help argument (e.g. "--help"/"-h") is found on the command line.


[View source]
def quitOnVer=(quitOnVer : Bool) #

When true, #parse will call exit(0) after printing version information when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def quitOnVer? : Bool #

When true, #parse will call exit(0) after printing version information when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def singleDashPositional=(singleDashPositional : Bool) #

When true, a single dash - will be and stored as a positional argument.


[View source]
def singleDashPositional? : Bool #

When true, a single dash - will be and stored as a positional argument.


[View source]
def usageLine : String | Nil #

When non-nil, this will be used for the "Usage:" line instead of the generated one.


[View source]
def usageLine=(usageLine : String | Nil) #

When non-nil, this will be used for the "Usage:" line instead of the generated one.


[View source]
def verPrinter : VerPrinterFunc #

This will be called when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def verPrinter=(verPrinter : VerPrinterFunc) #

This will be called when a version argument (e.g. "--version"/"-V") is found on the command line.


[View source]
def withCalledArg(name : String, &) #

If an argument named name was called, then this yields that argument to the block. Otherwise this does nothing. This returns either the result of the block, or nil if it wasn't called.


[View source]
def withCalledFloatArg(name : String, &) #

Looks up the argument named name, casts it to a FloatArgument. If the argument was called, this yields it to the block, otherwise it does nothing. If the argument is not a FloatArgument, this raises an exception. This returns either the result of the block, or nil if it wasn't called.


[View source]
def withCalledIntArg(name : String, &) #

Looks up the argument named name, casts it to an IntArgument. If the argument was called, this yields it to the block, otherwise it does nothing. If the argument is not an IntArgument, this raises an exception. This returns either the result of the block, or nil if it wasn't called.


[View source]
def withCalledMultiFloatArg(name : String, &) #

Looks up the argument named name, casts it to a MultiFloatArgument. If the argument was called, this yields it to the block, otherwise it does nothing. If the argument is not a MultiFloatArgument, this raises an exception. This returns either the result of the block, or nil if it wasn't called.


[View source]
def withCalledMultiIntArg(name : String, &) #

Looks up the argument named name, casts it to a MultiIntArgument. If the argument was called, this yields it to the block, otherwise it does nothing. If the argument is not a MultiIntArgument, this raises an exception. This returns either the result of the block, or nil if it wasn't called.


[View source]
def withCalledMultiStringArg(name : String, &) #

Looks up the argument named name, casts it to an MultiStringArgument. If the argument was called, this yields it to the block, otherwise it does nothing. If the argument is not an MultiStringArgument, this raises an exception. This returns either the result of the block, or nil if it wasn't called.


[View source]
def withCalledStringArg(name : String, &) #

Looks up the argument named name, casts it to an StringArgument. If the argument was called, this yields it to the block, otherwise it does nothing. If the argument is not an StringArgument, this raises an exception. This returns either the result of the block, or nil if it wasn't called.


[View source]
def withFlagArg(name : String, &) #

Looks up the argument named name, casts it to an FlagArgument, then yields it to the block. If the argument is not an FlagArgument, this raises an exception. Returns the last value of the block.


[View source]
def withFloatArg(name : String, &) #

Looks up the argument named name, casts it to a FloatArgument, then yields it to the block. If the argument is not a FloatArgument, this raises an exception. Returns the last value of the block.


[View source]
def withIntArg(name : String, &) #

Looks up the argument named name, casts it to an IntArgument, then yields it to the block. If the argument is not an IntArgument, this raises an exception. Returns the last value of the block.


[View source]
def withMultiFlagArg(name : String, &) #

Looks up the argument named name, casts it to an MultiFlagArgument, then yields it to the block. If the argument is not an MultiFlagArgument, this raises an exception. Returns the last value of the block.


[View source]
def withMultiFloatArg(name : String, &) #

Looks up the argument named name, casts it to a MultiFloatArgument, then yields it to the block. If the argument is not a MultiFloatArgument, this raises an exception. Returns the last value of the block.


[View source]
def withMultiIntArg(name : String, &) #

Looks up the argument named name, casts it to a MultiIntArgument, then yields it to the block. If the argument is not a MultiIntArgument, this raises an exception. Returns the last value of the block.


[View source]
def withMultiStringArg(name : String, &) #

Looks up the argument named name, casts it to an MultiStringArgument, then yields it to the block. If the argument is not an MultiStringArgument, this raises an exception. Returns the last value of the block.


[View source]
def withStringArg(name : String, &) #

Looks up the argument named name, casts it to an StringArgument, then yields it to the block. If the argument is not an StringArgument, this raises an exception. Returns the last value of the block.


[View source]