Skip to content
FutureBlitz

    Install

    Import std.os.args

    std.os.args

    Args: a program's command line, read into a Struct or Class. Args.Parse<T>() reads T's Fields' attributes, @Positional, @Option, and @Flag, and @Program on T itself, into an ArgsParser, which reads the arguments into a Value that Load<T> makes the T from, with the help and errors they make. An ArgsParser can be built at run time too, for options a program only knows then.

    std/os/args.fb

    Types

    Program attribute 

    Public Attribute Program(Name: String = "", About: String = "", Version: String = "")

    The program a Struct or Class reads the command line of: its name, which is otherwise its executable's, what it does, and its version, which --version and -V print.

    std/os/args.fb, line 17

    Positional attribute 

    Public Attribute Positional(Help: String = "", Name: String = "", Optional: Bool = False)

    A Field an argument goes to by its place, after any before it. One that's a T[] takes the rest, and one that's a T? or Optional can be left out, when it keeps its default.

    std/os/args.fb, line 20

    Option attribute 

    Public Attribute Option(Help: String = "", Short: String = "", Long: String = "", Name: String = "", Required: Bool = False)

    A Field that "--name value", "--name=value", or "-s value" sets, its long name the Field's in kebab case unless Long says otherwise. One that's a T[] takes each time it's given. Name is what its value is called in the help.

    std/os/args.fb, line 24

    Flag attribute 

    Public Attribute Flag(Help: String = "", Short: String = "", Long: String = "")

    A Bool Field that "--name" or "-s" sets, or an integer one that counts how many times it's given, as -vvv is 3.

    std/os/args.fb, line 28

    Subcommand attribute 

    Public Attribute Subcommand(Help: String = "", Name: String = "")

    A T? Field of a Struct or Class that its command fills from the rest of the command line, as "git commit -m x" fills a Commit's. Its command is its name in kebab case unless Name says otherwise. One of them, or none, is given; the others stay Null.

    std/os/args.fb, line 32

    ArgsHelp class 

    Public Class ArgsHelp Extends ArgumentError

    What --help or --version asks for, which isn't an error: its text, which Args.Parse<T>() prints before the program ends with 0.

    std/os/args.fb, line 96

    • Public New(text: String) constructor #

      An ArgsHelp of text, the help or version that was asked for.

    ArgsError class 

    Public Class ArgsError Extends ArgumentError

    A command line an ArgsParser can't read, with the usage of the command it was reading.

    std/os/args.fb, line 104

    • Public ReadOnly Field Usage: String field #

      The usage of the command it was reading.

    • Public New(kind: ArgumentErrorKind, message: String, usage: String, name: String? = Null, cause: Error? = Null) constructor #

      An ArgsError of kind that says message, with the command's usage, about the argument name.

    ArgsParser class 

    Public Class ArgsParser

    Reads a command line into a Value's Object: each flag's Bool or count, each option's and positional argument's String, or Array of them, and a command's Object, by their keys. Its methods give the ArgsParser back, so they chain.

    std/os/args.fb, line 120

    • Public New(name: String, about: String = "", version: String = "") constructor #

      A new ArgsParser for the program name, which --help describes by about and --version shows version for.

    • @PanicsAtCaller Public Method Flag(key: String, long: String = "", short: String = "", help: String = "", counts: Bool = False): ArgsParser method #

      A flag, "--long" or "-s", which is True once given, or with counts, how many times it was. Panics for a key, long name, or short name another has, a short name that isn't one ASCII letter or digit, or neither name.

    • @PanicsAtCaller Public Method Option(key: String, long: String = "", short: String = "", help: String = "", valueName: String = "", required: Bool = False, repeated: Bool = False, shownDefault: String = ""): ArgsParser method #

      An option that takes a value, "--long value", "--long=value", "-s value", or "-svalue", which can be given once, or with repeated, any number of times. Panics as Flag does.

    • @PanicsAtCaller Public Method Positional(key: String, help: String = "", valueName: String = "", required: Bool = True, rest: Bool = False): ArgsParser method #

      The next argument by its place, which with rest takes all that are left. Panics for one after one that takes the rest, a required one after one that isn't, or one beside commands.

    • @PanicsAtCaller Public Method Command(name: String, key: String, parser: ArgsParser, help: String = "", optional: Bool = False): ArgsParser method #

      A command, which reads the rest of the command line after its name, into an Object at its key. One of the commands has to be given, unless every one is optional. Panics beside positional arguments, or for a name another command has.

    • Public Method Parse(arguments: String[]): Value Throws ArgumentError method #

      Reads arguments into an Object. Throws an ArgsHelp for --help or -h, or --version or -V where there's a version, and an ArgsError for what it can't read, which says why.

    • Public Method Usage(): String method #

      How the program is run, as the help's first line has it.

    • Public Method Help(): String method #

      What --help prints: what the program does, how it's run, and each argument, option, and command, with what it does.

    Args struct 

    Public Struct Args

    Args' Static Methods.

    std/os/args.fb, line 574

    • Public Static Method Parse<T>(): T static method #

      Reads the program's command line into a T. --help, -h, --version, and -V print what they ask for, and a command line it can't read prints why, with how the program is run, to stderr; either way the program then ends, with 0 or 2.

    • Public Static Method Parse<T>(arguments: String[]): T Throws ArgumentError static method #

      Reads arguments into a T. Throws an ArgsHelp for --help, -h, --version, and -V, and an ArgsError for what it can't read, which says why.

    • Public Static Method Parser<T>(): ArgsParser static method #

      The ArgsParser that Parse<T> reads with, made from T's Fields' attributes.

    • Public Static Method Help<T>(): String static method #

      What --help prints for a T.

    Report an issue with this page or with FutureBlitz on GitHub.