Parsing Flags

Relevant source files

The following files were used as context for generating this wiki page:

• tests/parse_flags.c
• tests/parse_flags.h
• json_tokener.c
• json_object.h
• json_print.c
• json_object.c
• tests/test_parse.c

Parsing flags in libfastjson are bitmask integers used to control the behavior of the JSON tokener during input processing and the formatting of JSON objects during output serialization. These flags allow developers to toggle between strict RFC compliance and more liberal parsing, as well as to define the visual structure of the generated JSON strings.

The system is primarily divided into two categories: Tokener Flags, which affect how a string is converted into an object model, and Serialization Flags, which determine how an object model is converted back into a string representation.

Tokener Behavior Flags

Tokener flags are applied to a fjson_tokener instance to modify its state machine logic. By default, libfastjson is liberal in what it accepts (following Postel's Law), but it can be configured for strict adherence to JSON specifications.

Strict Mode and Validation

The FJSON_TOKENER_STRICT flag enforces rigid parsing rules. When this flag is set, the tokener will reject non-standard JSON features such as comments, single-quoted strings, or leading zeros in numbers.

The diagram above shows the decision logic used within the state machine when encountering characters that may be valid in liberal mode but invalid in strict mode.
Sources: json_tokener.c:266-271, json_tokener.c:303-307, tests/test_charcase.c:32-44

Key Tokener Flags

Flag Name	Description	Source
FJSON_TOKENER_STRICT	Enables strict RFC compliance; disables comments and non-standard quoting.	json_tokener.h
0 (Default)	Liberal parsing mode; allows C-style comments and single quotes.	json_tokener.c:266

Serialization and Output Flags

Serialization flags control the fjson_object_to_json_string_ext function and related file output utilities. These flags are typically combined using bitwise OR operations to achieve a specific output format.

Formatting Logic

Serialization flags guide the recursive write function, determining whether to insert newlines, indentation, or extra spaces around structural delimiters like colons and commas.

The sequence above illustrates how flags influence the internal indent and write_object functions during the stringification process.
Sources: json_print.c:269-286, json_print.c:354-358, json_object.c:215-226

Available Serialization Flags

Constant	Value	Effect
FJSON_TO_STRING_PLAIN	0	No extra whitespace or formatting.
FJSON_TO_STRING_SPACED	1<<0	Minimal whitespace for basic readability.
FJSON_TO_STRING_PRETTY	1<<1	Full hierarchical formatting with newlines and indentation.
FJSON_TO_STRING_NOZERO	1<<2	Drops trailing zeros from floating point values.
FJSON_TO_STRING_PRETTY_TAB	1<<3	Uses Tab characters instead of spaces for indentation.

Sources: json_object.h:50-84, json_print.c:269-278

Test Utility Flag Parsing

The project includes a utility function in the test suite, parse_flags, designed to convert command-line arguments into their corresponding bitmask integers. This is primarily used for validating the output of formatted JSON in test cases.

Implementation in tests/parse_flags.c

The function iterates through provided arguments and compares them against a static mapping of string literals to flag constants.

static struct {
	const char *arg;
	int flag;
} format_args[] = {
	{ "plain", FJSON_TO_STRING_PLAIN },
	{ "spaced", FJSON_TO_STRING_SPACED },
	{ "pretty", FJSON_TO_STRING_PRETTY },
};

Sources: tests/parse_flags.c:16-22, tests/parse_flags.c:29-50

Internal Object Addition Flags

While primarily used for serialization and tokenizing, libfastjson also provides flags for internal object manipulation through fjson_object_object_add_ex. These flags optimize performance during object construction.

• FJSON_OBJECT_ADD_KEY_IS_NEW: Skips the check for an existing key, assuming the key is unique.
• FJSON_OBJECT_KEY_IS_CONSTANT: Indicates the key string is in constant memory, preventing a strdup() call.

Sources: json_object.h:86-111, json_object.c:380-388

Summary

Parsing flags in libfastjson provide a granular interface for configuring the library's performance and output style. By utilizing FJSON_TOKENER_STRICT, developers ensure data integrity and compliance, while serialization flags like FJSON_TO_STRING_PRETTY facilitate debugging and human-readable logging. These flags are central to the library's flexibility in handling diverse JSON environments.

Sources: json_tokener.c:266, json_print.c:514, json_object.h:45