core/flags

flags

Types

Custom_Flag_Checker :: proc(model: rawptr, name: string, value: any, args_tag: string) -> (error: string)Source

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.

Custom_Type_Setter :: proc(data: rawptr, data_type: typeid, unparsed_value: string, args_tag: string) -> (error: string, handled: bool, alloc_error: runtime.Allocator_Error)

Source

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.

Error :: union {
	Parse_Error,
	Open_File_Error,
	Help_Request,
	Validation_Error,
}

Source

Help_Request :: boolSource

Raised during parsing.

Open_File_Error :: struct {
	filename: string,
	errno:    os.Error,
	flags:    os.File_Flags,
	perms:    os.Permissions,
}

Source

Raised during parsing. Provides more granular information than what just a string could hold.

Parse_Error :: struct {
	reason:  Unified_Parse_Error_Reason,
	message: string,
}

Source

Raised during parsing, naturally.

Parse_Error_Reason :: enum int {
	None             = 0,
	// An extra positional argument was given, and there is no `overflow` field.
	Extra_Positional = 1,
	// The underlying type does not support the string value it is being set to.
	Bad_Value        = 2,
	// No flag was given by the user.
	No_Flag          = 3,
	// No value was given by the user.
	No_Value         = 4,
	// The flag on the struct is missing.
	Missing_Flag     = 5,
	// The type itself isn't supported.
	Unsupported_Type = 6,
}

Source

Parser :: struct {
	// `fields_set` tracks which arguments have been set.
	// It uses their struct field index.
	fields_set: bit_array.Bit_Array,
	// `filled_pos` tracks which arguments have been filled into positional
	// spots, much like how `fmt` treats them.
	filled_pos: bit_array.Bit_Array,
}

Source

Used to group state together.

Parsing_Style :: enum int {
	// Odin-style: `-flag`, `-flag:option`, `-map:key=value`
	Odin = 0,
	// UNIX-style: `-flag` or `--flag`, `--flag=argument`, `--flag argument (manifold-argument)`
	Unix = 1,
}

Source

Unified_Parse_Error_Reason :: union {
	Parse_Error_Reason,
	runtime.Allocator_Error,
	net.Parse_Endpoint_Error,
}

Source

Validation_Error :: struct {
	message: string,
}

Source

Raised after parsing, during validation.

Constants

IMPORTING_NET :: _ = #config(ODIN_CORE_FLAGS_USE_NET, ODIN_OS == .Windows || ODIN_OS == .Linux || ODIN_OS == .Darwin || ODIN_OS == .FreeBSD || ODIN_OS == .NetBSD || ODIN_OS == .OpenBSD)

Source

Override support for parsing net types.

IMPORTING_TIME :: _ = #config(ODIN_CORE_FLAGS_USE_TIME, time.IS_SUPPORTED)Source

Override support for parsing time types.

INTERNAL_OVERFLOW_FLAG :: _ = #config(ODIN_CORE_FLAGS_OVERFLOW_FLAG, "overflow")Source

NO_CORE_NAMED_TYPES :: _ = #config(ODIN_CORE_FLAGS_NO_CORE_NAMED_TYPES, false)Source

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 :: 16Source

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 :: "help"Source

RESERVED_HELP_FLAG_SHORT :: "h"Source

SUBTAG_FILE :: "file"Source

SUBTAG_HIDDEN :: "hidden"Source

SUBTAG_INDISTINCT :: "indistinct"Source

SUBTAG_MANIFOLD :: "manifold"Source

SUBTAG_NAME :: "name"Source

SUBTAG_PERMS :: "perms"Source

SUBTAG_POS :: "pos"Source

SUBTAG_REQUIRED :: "required"Source

TAG_ARGS :: "args"Source

TAG_USAGE :: "usage"Source

UNDOCUMENTED_FLAG :: "<This flag has not been documented yet.>"Source

Procedures

get_field_by_name :: proc(model: ^T, name: string) -> (result: reflect.Struct_Field, index: int, error: Error)Source

Get a struct field by its field name or name subtag.

get_field_by_pos :: proc(model: ^T, pos: int) -> (result: reflect.Struct_Field, index: int, ok: bool)Source

Get a struct field by its pos subtag.

get_field_name :: proc(field: reflect.Struct_Field) -> (string)Source

get_field_pos :: proc(field: reflect.Struct_Field) -> (bool, int)Source

get_struct_subtag :: proc(tag: string, id: string) -> (value: string, ok: bool)Source

get_subtag :: proc(tag: string, id: string) -> (value: string, ok: bool)Source

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"

get_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)
}

Output:

precision = "3", true
signed = "", true

parse :: proc(
	model:         ^T,
	args:          []string,
	style:         Parsing_Style,
	validate_args: bool,
	strict:        bool,
	allocator:     mem.Allocator = context.allocator,
	loc:           _ = #caller_location,
) -> (error: Error)

Source

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_and_set_pointer_by_base_type :: proc(ptr: rawptr, str: string, type_info: ^runtime.Type_Info) -> (bool)Source

parse_and_set_pointer_by_named_type :: proc(ptr: rawptr, str: string, data_type: typeid, arg_tag: string, out_error: ^Error)

Source

This proc exists to make error handling easier, since everything in the base type one above works on booleans. It's a simple parsing error if it's false.

However, here we have to be more careful about how we handle errors, especially with files.

We want to provide as informative as an error as we can.

parse_and_set_pointer_by_type :: proc(ptr: rawptr, str: string, type_info: ^runtime.Type_Info, arg_tag: string) -> (error: Error)

Source

parse_one_odin_arg :: proc(model: ^T, parser: ^Parser, arg: string) -> (error: Error)Source

parse_one_unix_arg :: proc(model: ^T, parser: ^Parser, arg: string) -> (future_args: int, current_flag: string, error: Error)

Source

parse_or_exit :: proc(model: ^T, program_args: []string, style: Parsing_Style, allocator: mem.Allocator = context.allocator, loc = #caller_location)

Source

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)

parse_requirements :: proc(str: string) -> (minimum: int, maximum: int, ok: bool)Source

Parse a number of requirements specifier.

Examples:

min <max min<max

print_errors :: proc(data_type: typeid, error: Error, program: string, style: Parsing_Style)Source

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.

push_positional :: proc(model: ^T, parser: ^Parser, arg: string) -> (error: Error)Source

Push a positional argument onto a data struct, checking for specified positionals first before adding it to a fallback field.

register_field :: proc(parser: ^Parser, field: reflect.Struct_Field, index: int)Source

register_flag_checker :: proc(checker: Custom_Flag_Checker)Source

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 :: proc(setter: Custom_Type_Setter)Source

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.

set_key_value :: proc(model: ^T, parser: ^Parser, name: string, key: string, value: string) -> (error: Error)Source

Set a -map:key=value argument.

set_odin_flag :: proc(model: ^T, parser: ^Parser, name: string) -> (error: Error)Source

Set a -flag argument, Odin-style.

set_option :: proc(model: ^T, parser: ^Parser, name: string, option: string) -> (error: Error)Source

Set a -flag:option argument.

set_unbounded_integer_by_type :: proc(ptr: rawptr, value: T, data_type: typeid)Source

set_unix_flag :: proc(model: ^T, parser: ^Parser, name: string) -> (future_args: int, error: Error)Source

Set a -flag argument, UNIX-style.

validate_arguments :: proc(model: ^T, parser: ^Parser) -> (Error)Source

Validate that all the required arguments are set and that the set arguments are up to the program's expectations.

validate_structure :: proc(model_type: T, style: Parsing_Style, loc = #caller_location)Source

This proc is used to assert that T meets the expectations of the library.

write_usage :: proc(out: io.Writer, data_type: typeid, program: string, style: Parsing_Style)Source

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.

flags

Types

Constants

Procedures

Example:

Output:

Find anything

Settings