package core:flags
Overview
package flags implements a command-line argument parser.
It works by using Odin's run-time type information to determine where and how to store data on a struct provided by the program. Type conversion is handled automatically and errors are reported with useful messages.
Command-Line Syntax:
Arguments are treated differently depending on how they're formatted. The format is similar to the Odin binary's way of handling compiler flags.
type handling ------------ ------------------------ <positional> depends on struct layout -<flag> set a bool true -<flag:option> set flag to option -<flag=option> set flag to option, alternative syntax -<map>:<key>=<value> set map[key] to value
Struct Tags:
Users of the core:encoding/json
package may be familiar with using tags to
annotate struct metadata. The same technique is used here to annotate where
arguments should go and which are required.
Under the args
tag, there are the following subtags:
name=S
: set S
as the flag's name.
pos=N
: place positional argument N
into this flag.
hidden
: hide this flag from the usage documentation.
required
: cause verification to fail if this argument is not set.
variadic
: take all remaining arguments when set, UNIX-style only.
file
: for os.Handle
types, file open mode.
perms
: for os.Handle
types, file open permissions.
indistinct
: allow the setting of distinct types by their base type.
required
may be given a range specifier in the following formats:
min <max min<max
max
is not inclusive in this range, as noted by the less-than <
sign, so if
you want to require 3 and only 3 arguments in a dynamic array, you would
specify required=3<4
.
variadic
may be given a number (variadic=N
) above 1 to limit how many extra
arguments it consumes.
file
determines the file open mode for an os.Handle
.
It accepts a string of flags that can be mixed together:
r: read
w: write
c: create, create the file if it doesn't exist
a: append, add any new writes to the end of the file
t: truncate, erase the file on open
perms
determines the file open permissions for an os.Handle
.
The permissions are represented by three numbers in octal format. The first number is the owner, the second is the group, and the third is other. Read is represented by 4, write by 2, and execute by 1.
These numbers are added together to get combined permissions. For example, 644 represents read/write for the owner, read for the group, and read for other.
Note that this may only have effect on UNIX-like platforms. By default, perms
is set to 444 when only reading and 644 when writing.
indistinct
tells the parser that it's okay to treat distinct types as their
underlying base type. Normally, the parser will hand those types off to the
custom type setter (more about that later) if one is available, if it doesn't
know how to handle the type.
Usage Tag:
There is also the usage
tag, which is a plain string to be printed alongside
the flag in the usage output. If usage
contains a newline, it will be
properly aligned when printed.
All surrounding whitespace is trimmed when formatting with multiple lines.
Supported Flag Data Types:
all booleans
all integers
all floats
all enums
all complex numbers
all quaternions
all bit_sets
string
and cstring
rune
os.Handle
time.Time
datetime.DateTime
net.Host_Or_Endpoint
,
additional custom types, see Custom Types below
dynamic
arrays with element types of the above
map[string]
s or map[cstring]
s with value types of the above
Validation:
The parser will ensure required
arguments are set, if no errors occurred
during parsing. This is on by default.
Additionally, you may call register_flag_checker
to set your own argument
validation procedure that will be called after the default checker.
Strict:
The parser will return on the first error and stop parsing. This is on by default. Otherwise, all arguments that can be parsed, will be, and only the last error is returned.
Error Messages:
All error message strings are allocated using the context's temp_allocator
,
so if you need them to persist, make sure to clone the underlying message
.
Help:
By default, -h
and -help
are reserved flags which raise their own error
type when set, allowing the program to handle the request differently from
other errors.
Custom Types:
You may specify your own type setter for program-specific structs and other
named types. Call register_type_setter
with an appropriate proc before
calling any of the parsing procs.
A compliant Custom_Type_Setter
must return three values:
an error message if one occurred,
a boolean indicating if the proc handles the type, and
an Allocator_Error
if any occurred.
If the setter does not handle the type, simply return without setting any of the values.
UNIX-style:
This package also supports parsing arguments in a limited flavor of UNIX. Odin and UNIX style are mutually exclusive, and which one to be used is chosen at parse time.
--flag --flag=argument --flag argument --flag argument repeating-argument
-flag
may also be substituted for --flag
.
Do note that map flags are not currently supported in this parsing style.
For a complete example, see: core/flags/example.
Index
Constants (18)
Variables (0)
This section is empty.
Procedure Groups (0)
This section is empty.
Types
Custom_Flag_Checker ¶
Custom_Flag_Checker :: proc(model: rawptr, name: string, value: any, args_tag: string) -> (error: string)
Check a flag after parsing, during the validation stage.
Inputs:
model: A raw pointer to the data structure provided to parse
.
name: The name of the flag being checked.
value: An any
type that contains the value to be checked.
args_tag: The args
tag from within the struct.
Returns:
error: An error message, or an empty string if no error occurred.
Related Procedures With Parameters
Custom_Type_Setter ¶
Custom_Type_Setter :: proc(data: rawptr, data_type: typeid, unparsed_value: string, args_tag: string) -> (error: string, handled: bool, alloc_error: runtime.Allocator_Error)
Handle setting custom data types.
Inputs:
data: A raw pointer to the field where the data will go.
data_type: Type information on the underlying field.
unparsed_value: The unparsed string that the flag is being set to.
args_tag: The args
tag from the struct's field.
Returns:
error: An error message, or an empty string if no error occurred.
handled: A boolean indicating if the setter handles this type.
alloc_error: If an allocation error occurred, return it here.
Related Procedures With Parameters
Error ¶
Error :: union { Parse_Error, Open_File_Error, Help_Request, Validation_Error, }
Related Procedures With Parameters
Related Procedures With Returns
Open_File_Error ¶
Raised during parsing. Provides more granular information than what just a string could hold.
Parse_Error ¶
Parse_Error :: struct { reason: Unified_Parse_Error_Reason, message: string, }
Raised during parsing, naturally.
Parse_Error_Reason ¶
Parse_Error_Reason :: enum int { None, // An extra positional argument was given, and there is no `varg` field. Extra_Positional, // The underlying type does not support the string value it is being set to. Bad_Value, // No flag was given by the user. No_Flag, // No value was given by the user. No_Value, // The flag on the struct is missing. Missing_Flag, // The type itself isn't supported. Unsupported_Type, }
Parsing_Style ¶
Parsing_Style :: enum int { // Odin-style: `-flag`, `-flag:option`, `-map:key=value` Odin, // UNIX-style: `-flag` or `--flag`, `--flag=argument`, `--flag argument repeating-argument` Unix, }
Related Procedures With Parameters
Unified_Parse_Error_Reason ¶
Unified_Parse_Error_Reason :: union { Parse_Error_Reason, runtime.Allocator_Error, net.Parse_Endpoint_Error, }
Validation_Error ¶
Validation_Error :: struct { message: string, }
Raised after parsing, during validation.
Constants
IMPORTING_NET ¶
IMPORTING_NET :: #config(ODIN_CORE_FLAGS_USE_NET, ODIN_OS == .Windows || ODIN_OS == .Linux || ODIN_OS == .Darwin || ODIN_OS == .FreeBSD)
Override support for parsing net
types.
TODO: Update this when the BSDs are supported.
IMPORTING_TIME ¶
IMPORTING_TIME :: #config(ODIN_CORE_FLAGS_USE_TIME, time.IS_SUPPORTED)
Override support for parsing time
types.
INTERNAL_VARIADIC_FLAG ¶
INTERNAL_VARIADIC_FLAG :: "varg"
NO_CORE_NAMED_TYPES ¶
NO_CORE_NAMED_TYPES :: #config(ODIN_CORE_FLAGS_NO_CORE_NAMED_TYPES, false)
Set to true to compile with support for core named types disabled, as a fallback in the event your platform does not support one of the types, or you have no need for them and want a smaller binary.
ONE_LINE_FLAG_CUTOFF_COUNT ¶
ONE_LINE_FLAG_CUTOFF_COUNT :: 16
If there are more than this number of flags in total, only the required and positional flags will be shown in the one-line usage summary.
RESERVED_HELP_FLAG ¶
RESERVED_HELP_FLAG :: "help"
RESERVED_HELP_FLAG_SHORT ¶
RESERVED_HELP_FLAG_SHORT :: "h"
SUBTAG_FILE ¶
SUBTAG_FILE :: "file"
SUBTAG_HIDDEN ¶
SUBTAG_HIDDEN :: "hidden"
SUBTAG_INDISTINCT ¶
SUBTAG_INDISTINCT :: "indistinct"
SUBTAG_NAME ¶
SUBTAG_NAME :: "name"
SUBTAG_PERMS ¶
SUBTAG_PERMS :: "perms"
SUBTAG_POS ¶
SUBTAG_POS :: "pos"
SUBTAG_REQUIRED ¶
SUBTAG_REQUIRED :: "required"
SUBTAG_VARIADIC ¶
SUBTAG_VARIADIC :: "variadic"
TAG_ARGS ¶
TAG_ARGS :: "args"
TAG_USAGE ¶
TAG_USAGE :: "usage"
UNDOCUMENTED_FLAG ¶
UNDOCUMENTED_FLAG :: "<This flag has not been documented yet.>"
Variables
This section is empty.
Procedures
get_struct_subtag ¶
get_struct_subtag :: get_subtag
Get the value for a subtag.
This is useful if you need to parse through the args
tag for a struct field
on a custom type setter or custom flag checker.
Example:
import "core:flags"
import "core:fmt"
subtag_example :: proc() {
args_tag := "precision=3,signed"
precision, has_precision := flags.get_subtag(args_tag, "precision")
signed, is_signed := flags.get_subtag(args_tag, "signed")
fmt.printfln("precision = %q, %t", precision, has_precision)
fmt.printfln("signed = %q, %t", signed, is_signed)
}
precision = "3", true signed = "", true
get_subtag ¶
Get the value for a subtag.
This is useful if you need to parse through the args
tag for a struct field
on a custom type setter or custom flag checker.
Example:
import "core:flags"
import "core:fmt"
subtag_example :: proc() {
args_tag := "precision=3,signed"
precision, has_precision := flags.get_subtag(args_tag, "precision")
signed, is_signed := flags.get_subtag(args_tag, "signed")
fmt.printfln("precision = %q, %t", precision, has_precision)
fmt.printfln("signed = %q, %t", signed, is_signed)
}
precision = "3", true signed = "", true
parse ¶
parse :: proc( model: ^$T, args: []string, style: Parsing_Style = .Odin, validate_args: bool = true, strict: bool = true, allocator := context.allocator, loc := #caller_location, ) -> (error: Error) {…}
Parse a slice of command-line arguments into an annotated struct.
Allocates Using Provided Allocator
By default, this proc will only allocate memory outside of its lifetime if it has to append to a dynamic array, set a map value, or set a cstring.
The program is expected to free any allocations on model
as a result of parsing.
Inputs:
model: A pointer to an annotated struct with flag definitions.
args: A slice of strings, usually os.args[1:]
.
style: The argument parsing style.
validate_args: If true
, will ensure that all required arguments are set if no errors occurred.
strict: If true
, will return on first error. Otherwise, parsing continues.
allocator: (default: context.allocator)
loc: The caller location for debugging purposes (default: #caller_location)
Returns:
error: A union of errors; parsing, file open, a help request, or validation.
parse_or_exit ¶
parse_or_exit :: proc(model: ^$T, program_args: []string, style: Parsing_Style = .Odin, allocator := context.allocator, loc := #caller_location) {…}
Parse any arguments into an annotated struct or exit if there was an error.
Allocates Using Provided Allocator
This is a convenience wrapper over parse
and print_errors
.
Inputs:
model: A pointer to an annotated struct.
program_args: A slice of strings, usually os.args
.
style: The argument parsing style.
allocator: (default: context.allocator)
loc: The caller location for debugging purposes (default: #caller_location)
print_errors ¶
print_errors :: proc(data_type: typeid, error: Error, program: string, style: Parsing_Style = .Odin) {…}
Print out any errors that may have resulted from parsing.
All error messages print to STDERR, while usage goes to STDOUT, if requested.
Inputs:
data_type: The typeid of the data structure to describe, if usage is requested.
error: The error returned from parse
.
style: The argument parsing style, required to show flags in the proper style, when usage is shown.
register_flag_checker ¶
register_flag_checker :: proc(checker: Custom_Flag_Checker) {…}
Set the global custom flag checker.
Note that only one can be active at a time.
Inputs:
checker: The flag checker. Pass nil
to disable any previously set checker.
register_type_setter ¶
register_type_setter :: proc(setter: Custom_Type_Setter) {…}
Set the global custom type setter.
Note that only one can be active at a time.
Inputs:
setter: The type setter. Pass nil
to disable any previously set setter.
write_usage ¶
write_usage :: proc(out: io.Stream, data_type: typeid, program: string = "", style: Parsing_Style = .Odin) {…}
Write out the documentation for the command-line arguments to a stream.
Inputs:
out: The stream to write to.
data_type: The typeid of the data structure to describe.
program: The name of the program, usually the first argument to os.args
.
style: The argument parsing style, required to show flags in the proper style.
Procedure Groups
This section is empty.
Source Files
- constants.odin
- doc.odin
- errors.odin
- errors_nonbsd.odin
- internal_assignment.odin
- internal_parsing.odin
- internal_rtti.odin
- internal_rtti_nonbsd.odin
- internal_validation.odin
- parsing.odin
- rtti.odin
- usage.odin
- util.odin
- validation.odin
Generation Information
Generated with odin version dev-2024-09 (vendor "odin") Windows_amd64 @ 2024-09-07 21:12:27.311410800 +0000 UTC