5.3 Functions

5.3.1 p_context_init

The p_context_init() function must be called to initialize the context structure. The input to be used for lexing/parsing is passed in when initializing the context structure.

C example:

p_context_t context;
p_context_init(&context, input, input_length);

D example:

p_context_t context;
p_context_init(&context, input);

5.3.2 p_parse

The p_parse() function is the main entry point to the parser. It must be passed a pointer to an initialized context structure.

Example:

p_context_t context;
p_context_init(&context, input, input_length);
size_t result = p_parse(&context);

5.3.3 p_position_valid

The p_position_valid() function is only generated for C targets. it is used to determine whether or not a p_position_t structure is valid.

Example:

if (p_position_valid(node->position))
{
    ....
}

For D targets, rather than using p_position_valid(), the valid property function of the p_position_t structure can be queried (e.g. if (node.position.valid)).

5.3.4 p_result

The p_result() function can be used to retrieve the final parse value after p_parse() returns a P_SUCCESS value.

Example:

p_context_t context;
p_context_init(&context, input, input_length);
size_t result = p_parse(&context);
if (p_parse(&context) == P_SUCCESS)
{
    result = p_result(&context);
}

If AST generation mode is active, then the p_result() function returns a Start * pointing to the Start AST structure.

5.3.5 p_position

The p_position() function can be used to retrieve the parser position where an error occurred.

Example:

p_context_t context;
p_context_init(&context, input, input_length);
size_t result = p_parse(&context);
if (p_parse(&context) == P_UNEXPECTED_TOKEN)
{
    p_position_t error_position = p_position(&context);
    fprintf(stderr, "Error: unexpected token at row %u column %u\n",
        error_position.row + 1, error_position.col + 1);
}

5.3.6 p_user_terminate_code

The p_user_terminate_code() function can be used to retrieve the user terminate code after p_parse() returns a P_USER_TERMINATED value. User terminate codes are arbitrary values that can be defined by the user to be returned when the user requests to terminate parsing. They have no particular meaning to Propane.

Example:

if (p_parse(&context) == P_USER_TERMINATED)
{
    size_t user_terminate_code = p_user_terminate_code(&context);
}

5.3.7 p_token

The p_token() function can be used to retrieve the current parse token. This is useful after p_parse() returns a P_UNEXPECTED_TOKEN value. terminate code after p_parse() returns a P_USER_TERMINATED value to indicate what token the parser was not expecting.

Example:

if (p_parse(&context) == P_UNEXPECTED_TOKEN)
{
    p_token_t unexpected_token = p_token(&context);
}

5.3.8 p_decode_code_point

The p_decode_code_point() function can be used to decode code points from a UTF-8 string. It does not require a lexer/parser context structure and can be used as a standalone UTF-8 decoder or from within a lexer or parser user code block.

D Example:

size_t result;
p_code_point_t code_point;
ubyte code_point_length;

result = p_decode_code_point("\xf0\x9f\xa7\xa1", &code_point, &code_point_length);
assert(result == P_SUCCESS);
assert(code_point == 0x1F9E1u);
assert(code_point_length == 4u);