Parsing options

When you set options from the CLI options, the commands, or the libf3d options string API, F3D parses the values according to their type. If parsing fails, the value is not changed.

The following types are supported:

• bool: A boolean, true or false.
• int: A signed integer.
• double: A floating point number.
• ratio: A double dividend over a double divisor, stored in a double.
• string: A string of characters.
• path: A path to a local file.
• color: A RGB color.
• direction: A 3D vector representing a direction.
• transform2d: A 9D vector representing a 3x3 matrix.

F3D also supports lists for bool, int, double, ratio, and string, noted as:

• vector<type>

Bool

F3D supports the following formats when parsing a bool, case insensitive:

• true/false
• yes/no
• on/off
• 1/0

When formatting a bool into a string, F3D uses true/false.

Int

F3D parses ints using std::stoi and checks that the whole string is parsed.

When formatting an int into a string, F3D uses std::to_string.

Double

F3D parses doubles using std::stod and checks that the whole string is parsed.

When formatting a double into a string, F3D uses std::ostringstream with removing the point and precision when the value is exactly an integer.

Ratio

F3D supports the following formats when parsing a string into a ratio:

• percent% where percent is a double
• dividend:divisor where both are doubles
• dividend/divisor where both are doubles
• double

Percent, dividend, divisor are then parsed as double.

When formatting a ratio into a string, F3D formats it as a double.

String

F3D trims strings of leading and trailing space when parsing them. F3D formats strings as is.

Path

F3D collapses paths and supports tilda (~).

Vectors

Vector tokens are separated by ,. F3D then parses tokens using their respective types.

When formatting a vector into a string, F3D formats individual tokens according to their type and separates them using ,.

Color

F3D supports the following formats when parsing a color, case insensitive:

• R,G,B where R, G, B are doubles >= 0
• #RRGGBB where RR, GG, BB are hexadecimal values. Shortened format #RGB is also valid.
• rgb(R, G, B) where R, G and B are integer [0, 255]
• hsl(H, S%, L%) where H is integer [0, 360], S and L are integer [0, 100]
• hsv(H, S%, V%) where H is integer [0, 360], S and V are integer [0, 100]
• hwb(H, W%, B%) where H is integer [0, 360], W and B are integer [0, 100]
• cmyk(C%, M%, Y%, K%) where C, M, Y, K are integer [0, 100]
• color name

See the W3C RGB color format documentation for more details on these formats.

When formatting a color into a string, F3D formats it as #RRGGBB if values are multiple of 255. Otherwise, F3D formats it as vector of doubles.

Quote the entire option when your shell treats parenthesis specially, eg: "--background-color=rgb(84, 84, 84)".

All colors are expressed in sRGB color space.

Direction

F3D supports the following formats when parsing a string into a direction:

• [[+|-]X][[+|-]Y][[+|-]Z] (case insensitive), for example +X or X for 1,0,0, -y+z for 0,-1,1
• vector of three doubles, for example 1,2,3.4

When formatting a direction into a string, F3D formats it in the ±XYZ form if possible or as a vector of doubles otherwise.

Colormap

F3D supports the following formats when parsing a string into a colormap:

• val, red, green, blue, ...
• val, color, ...

When formatting a colormap into a string, F3D formats it as val, color, ....

Transform2D

F3D supports the following formats when parsing a string into a transform2D:

• A 9D double vector
• At least one of the following: scale: val, val, translation: val, val, angle: val in any order, semicolon-separated. Use one scale value to apply it to both the x and y axes of the matrix. angle is expressed in degrees.

When formatting a transform2d into a string, F3D formats it as a 9D double vector.